Mejores prácticas del paquete de Helm

Helm es un administrador de paquetes para Kubernetes que ayuda a simplificar la administración del ciclo de vida de las aplicaciones. Los paquetes de Helm se denominan gráficos y constan de archivos de plantilla y configuración de YAML. Tras la ejecución de una operación de Helm, los gráficos se representan en archivos de manifiesto de Kubernetes para desencadenar las acciones adecuadas del ciclo de vida de la aplicación. Para la integración más eficaz con Azure Operator Service Manager, siga estos procedimientos recomendados al desarrollar gráficos de Helm.

Consideraciones para RegistryPath e imagePullSecrets

Por lo general, todos los gráficos de Helm requieren parámetros registryPath y imagePullSecrets. Normalmente, estos parámetros se exponen en el values.yaml archivo. Al principio, Azure Operator Service Manager dependía de los publicadores que administran estos valores de forma estricta (enfoque heredado), que se sustituyen por los valores de Azure adecuados durante la implementación. Pero no todos los publicadores podrían cumplir fácilmente la estricta administración de estos valores. Algunos gráficos ocultan registryPath o imagePullSecrets detrás de condicionales u otras restricciones de valor, que no siempre se cumplen. Algunos gráficos declaran registryPath o imagePullSecrets como una matriz en lugar de como la cadena con nombre esperada.

Para reducir los requisitos de cumplimiento de los publicadores, Azure Operator Service Manager introdujo dos métodos mejorados: injectArtifactStoreDetail y el registro de clústeres. Estos métodos más recientes no dependen registryPath ni imagePullSecrets aparecen en el paquete de Helm. En su lugar, estos métodos usan un webhook para insertar valores de Azure adecuados directamente en operaciones de pod.

Resumen del método para RegistryPath e ImagePullSecrets

Los tres métodos se admiten actualmente como se describe en este artículo. Elija la mejor opción para la función de red (NF) y el caso de uso.

Legado:

• Requiere parametrizar registryPath y imagePullSecrets en valores de Helm y plantillas de implementación para la sustitución.
• Hospeda imágenes en Azure Container Registry.

InjectArtifactStoreDetail:

• Usa un webhook para insertar registryPath y imagePullSecrets directamente en operaciones de pod, con dependencias mínimas en Helm.
• Hospeda imágenes en Azure Container Registry.

Registro de clúster:

• Usa un webhook para insertar registryPath y imagePullSecrets directamente en operaciones de pod, sin ninguna dependencia en Helm.
• Hospeda imágenes en la extensión del operador de función de red local (NFO).

En los tres casos, Azure Operator Service Manager sustituye los valores de Azure por los valores que exponga en las plantillas. La única diferencia es el método de sustitución.

Requisitos heredados para registryPath e imagePullSecrets

Azure Operator Service Manager usa el servicio Azure Network Function Manager para implementar funciones de red en contenedor (CNF). Con el método heredado, Azure Network Function Manager sustituye el operador de Azure Service Manager contenedor registryPath y imagePullSecrets los valores en la operación de Helm durante la implementación de funciones de red.

Ejemplo del método heredado

La siguiente plantilla de implementación de Helm muestra un ejemplo de cómo debe exponer registryPath y imagePullSecrets:

apiVersion: apps/v1 
kind: Deployment 
metadata: 
  name: nginx-deployment 
  labels: 
    app: nginx 
spec: 
  replicas: 3 
  selector: 
    matchLabels: 
      app: nginx 
  template: 
    metadata: 
      labels: 
        app: nginx 
    spec: 
      {{- if .Values.global.imagePullSecrets }} 
      imagePullSecrets: {{ toYaml .Values.global.imagePullSecrets | nindent 8 }} 
      {{- end }} 
      containers: 
      - name: contosoapp 
        image:{{ .Values.global.registryPath }}/contosoapp:1.14.2 
        ports: 
        - containerPort: 80 

En la plantilla siguiente values.yaml se muestra un ejemplo de cómo puede proporcionar los valores registryPath y imagePullSecrets:

global: 
   imagePullSecrets: [] 
   registryPath: "" 

En el archivo siguiente values.schema.json se muestra un ejemplo de cómo puede definir los valores registryPath y imagePullSecrets:

{ 
  "$schema": "http://json-schema.org/draft-07/schema#", 
  "title": "StarterSchema", 
  "type": "object", 
  "required": ["global"], 
  "properties": { 
      "global" : {
          "type": "object",
          "properties": {
              "registryPath": {"type": "string"}, 
              "imagePullSecrets": {"type": "string"}, 
          }
          "required": [ "registryPath", "imagePullSecrets" ], 
      } 
   } 
} 

La siguiente carga de solicitud de la versión de definición de función de red (NFDV) muestra un ejemplo de cómo puede proporcionar los valores registryPath y imagePullSecrets en la implementación:

"registryValuesPaths": [ "global.registryPath" ], 
"imagePullSecretsValuesPaths": [ "global.imagePullSecrets" ], 

En los ejemplos anteriores:

• El registryPath valor se establece sin ningún prefijo como https:// o oci://. Si es necesario, defina un prefijo en el paquete de Helm.
• imagePullSecrets y registryPath deben proporcionarse durante la incorporación de NFDV.

Otras consideraciones

Tenga en cuenta las siguientes recomendaciones cuando use el método heredado.

Evitar referencias a un registro externo

Las referencias a un registro externo pueden causar problemas de validación. Por ejemplo, si deployment.yaml usa una ruta de acceso del Registro codificada de forma rígida o referencias externas del registro, se produce un error en la validación.

Realizar validaciones de forma manual

Revise las imágenes y las especificaciones de contenedor para asegurarse de que las imágenes tienen un prefijo de registryPath y que imagePullSecrets se rellenan con secretName:

 helm template --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryPath>" <release-name> <chart-name> --dry-run

Este es otro ejemplo:

 helm install --set "global.imagePullSecrets[0].name=<secretName>" --set "global.registry.url=<registryPath>" <release-name> <chart-name> --dry-run
 kubectl create secret <secretName> regcred --docker-server=<registryPath> --dockerusername=<regusername> --docker-password=<regpassword>

Uso de etiquetas y repositorios de imágenes estáticas

Cada gráfico de Helm debe contener un repositorio de imágenes estáticas y etiquetas. Los valores estáticos se establecen mediante uno de los métodos siguientes:

• En la image línea
• En values.yaml, sin exponer estos valores en NFDV

Un NFDV debe asignarse a un conjunto estático de gráficos e imágenes de Helm. Solo se actualizan los gráficos e imágenes mediante la publicación de un nuevo NFDV, como se muestra en los ejemplos siguientes:

 image: "{{ .Values.global.registryPath }}/contosoapp:1.14.2"

 image: "{{ .Values.global.registryPath }}/{{ .Values.image.repository }}:{{ .Values.image.tag}}"
 
YAML values.yaml
image:
  repository: contosoapp
  tag: 1.14.2

 image: http://myUrl/{{ .Values.image.repository }}:{{ .Values.image.tag}}

requisitos de injectArtifactStoreDetails para registryPath e imagePullSecrets

En algunos casos, es posible que los gráficos de Helm de terceros no sean totalmente compatibles con los requisitos de Azure Operator Service Manager para registryPath. En estos casos, puede usar injectArtifactStoreDetails para evitar realizar cambios de cumplimiento en los paquetes de Helm.

Con injectArtifactStoreDetails habilitado, se usa un método de webhook para insertar el adecuado registryPath y imagePullSecrets dinámicamente durante las operaciones del pod. Este método invalida los valores configurados en el paquete de Helm. Todavía debe usar valores ficticios legales en los que se hace referencia a registryPath y imagePullSecrets, normalmente en la global sección de values.yaml.

En el ejemplo siguiente values.yaml se muestra cómo puede proporcionar los valores registryPath y imagePullSecrets para la compatibilidad con el injectArtifactStoreDetails enfoque:

global: 
   registryPath: "azure.io"
   imagePullSecrets: ["abc123"] 

Uso del método injectArtifactStoreDetails

Para habilitar injectArtifactStoreDetails, establezca el installOptions parámetro en la roleOverridessección del true recurso NF en, como se muestra en el ejemplo siguiente:

resource networkFunction 'Microsoft.HybridNetwork/networkFunctions@2023-09-01' = {
  name: nfName
  location: location
  properties: {
    nfviType: 'AzureArcKubernetes'
    networkFunctionDefinitionVersionResourceReference: {
      id: nfdvId
      idType: 'Open'
    }
    allowSoftwareUpdate: true
    nfviId: nfviId
    deploymentValues: deploymentValues
    configurationType: 'Open'
    roleOverrideValues: [
      // Use inject artifact store details feature on test app 1
      '{"name":"testapp1", "deployParametersMappingRuleProfile":{"helmMappingRuleProfile":{"options":{"installOptions":{"atomic":"false","wait":"false","timeout":"60","injectArtifactStoreDetails":"true"},"upgradeOptions": {"atomic": "false", "wait": "true", "timeout": "100", "injectArtifactStoreDetails": "true"}}}}}'
    ]
  }
}

Requisitos del Registro de clúster para registryPath e imagePullSecrets

Con un registro de clúster, las imágenes se copian de Azure Container Registry a un repositorio de Docker local en el clúster de Kubernetes de Nexus. Use un método de webhook para insertar los valores adecuados registryPath y imagePullSecrets dinámicamente durante las operaciones del pod. Este método invalida los valores configurados en el paquete de Helm. Todavía debe usar valores ficticios legales en los que se hace referencia a registryPath y imagePullSecrets, normalmente en la global sección de values.yaml.

En el ejemplo siguiente values.yaml se muestra cómo puede proporcionar los registryPath valores y imagePullSecrets para la compatibilidad con el enfoque del registro de clúster:

global: 
   registryPath: "azure.io"
   imagePullSecrets: ["abc123"] 

Para más información sobre el uso de un registro de clúster, consulte la documentación del concepto.

Recomendaciones para restricciones de inmutabilidad

Las restricciones de inmutabilidad impiden los cambios en un archivo o directorio. Por ejemplo, no se puede cambiar ni renombrar un archivo inmutable. Debe evitar el uso de etiquetas mutables como latest, dev, o stable. Por ejemplo, si deployment.yaml usa latest para .Values.image.tag, se produce un error en la implementación.

 image: "{{ .Values.global.registryPath }}/{{ .Values.image.repository }}:{{ .Values.image.tag}}"

Recomendaciones para la declaración de CRD y división de uso

Se recomienda dividir la declaración y el uso de definiciones de recursos de cliente (CRD) en gráficos de Helm independientes para admitir actualizaciones. Para obtener información detallada, consulte la documentación de Helm sobre cómo separar gráficos.

Recomendaciones para el etiquetado de versiones de imagen

Para garantizar implementaciones coherentes y predecibles, se recomienda lo siguiente para todas las imágenes de contenedor:

• Evite el uso :latest en entornos de producción.
  • El uso de más reciente puede provocar un comportamiento inesperado porque la imagen real detrás de la versión más reciente puede cambiar sin previo aviso.
  • En una configuración del registro de clúster, si el valor de etiqueta cambia, pero el nombre de etiqueta permanece igual, el registro de clúster no volverá a descargar la imagen actualizada.
  • Esto puede provocar la ejecución de imágenes obsoletas o incoherentes.
• En su lugar, use siempre etiquetas inmutables como :1.4.2
• Asegúrese de que cada compilación genera una etiqueta única, no sobrescriba las etiquetas existentes.

Estas prácticas ayudan a evitar problemas de implementación y a mejorar la rastreabilidad, la seguridad de reversión y el cumplimiento de la seguridad.

Recomendaciones para la secuencial ordenación de nfApplication

De forma predeterminada, las aplicaciones CNF se instalan o actualizan en función del orden en que aparecen en NFDV. Para la operación de eliminación, las aplicaciones CNF se eliminan en el orden inverso especificado. Si necesita definir un orden específico de las aplicaciones CNF que son diferentes de la predeterminada, use dependsOnProfile para definir una secuencia única para las operaciones de instalación, actualización y eliminación.

Cómo usar dependsOnProfile

Puede usar dependsOnProfile en NFDV para controlar la secuencia de ejecuciones de Helm para aplicaciones CNF. En el ejemplo siguiente:

• Durante una operación de instalación, las aplicaciones CNF se implementan en el orden siguiente: dummyApplication1, dummyApplication2, dummyApplication.
• Durante una operación de actualización, las aplicaciones CNF se actualizan en el orden siguiente: dummyApplication2, dummyApplication1, dummyApplication.
• Durante una operación de eliminación, las aplicaciones CNF se eliminan en el orden siguiente: dummyApplication2, dummyApplication1, dummyApplication.

{
    "location": "eastus",
    "properties": {
        "networkFunctionTemplate": {
            "networkFunctionApplications": [
                {
                  "dependsOnProfile": {
                        "installDependsOn": [
                            "dummyApplication1",
                            "dummyApplication2"
                        ],
                        "uninstallDependsOn": [
                            "dummyApplication1"
                        ],
                        "updateDependsOn": [
                            "dummyApplication1"
                        ]
                    },
                    "name": "dummyApplication"
                },
                {
                  "dependsOnProfile": {
                        "installDependsOn": [
                        ],
                        "uninstallDependsOn": [
                            "dummyApplication2"
                        ],
                        "updateDependsOn": [
                            "dummyApplication2"
                        ]
                    },
                    "name": "dummyApplication1"
                },
                {
                    "dependsOnProfile": null,
                    "name": "dummyApplication2"
                }
            ],
            "nfviType": "AzureArcKubernetes"
        },
        "networkFunctionType": "ContainerizedNetworkFunction"
    }
}

Errores comunes con dependsOnProfile

Actualmente, si el código de dependsOnProfile proporcionado en NFDV no es válido, la operación NF produce un error de validación. El mensaje para el error de validación aparece en el recurso de estado de la operación y tiene un aspecto similar al ejemplo siguiente:

 {
  "id": "/providers/Microsoft.HybridNetwork/locations/EASTUS2EUAP/operationStatuses/ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
  "name": "ca051ddf-c8bc-4cb2-945c-a292bf7b654b*C9B39996CFCD97AB3A121AE136ED47F67BB13946C573EF90628C47628BC5EF5F",
  "resourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/xinrui-publisher/providers/Microsoft.HybridNetwork/networkfunctions/testnfDependsOn02",
  "status": "Failed",
  "startTime": "2023-07-17T20:48:01.4792943Z",
  "endTime": "2023-07-17T20:48:10.0191285Z",
  "error": {
    "code": "DependenciesValidationFailed",
    "message": "CyclicDependencies: Circular dependencies detected at hellotest."
  }
}

Procedimientos recomendados para adoptar Helm 4

Helm ha sido el administrador de paquetes estándar para Kubernetes desde su versión inicial en 2016. Su evolución ha ido muy de la mano de la de Kubernetes:

• Helm v2 (2016-2019): introdujo el empaquetado de aplicaciones basado en gráficos, pero dependía de un componente del lado del servidor (Tiller), lo que generaba problemas de seguridad y multitenencia.
• Helm v3 (2019–2025): se quitó Tiller, cambiando a un modelo de solo cliente con mayor seguridad y facilidad de uso. Esta versión se convirtió en el estándar del sector y ha acumulado mejoras incrementales al tiempo que mantiene la compatibilidad con versiones anteriores.

Después de casi seis años de Helm v3, el proyecto acumulaba deudas técnicas, limitaciones arquitectónicas y desafíos de seguridad que no podía abordar sin introducir cambios importantes. Esta situación llevó al lanzamiento de Helm v4 a finales de 2025.

Qué representa Helm 4

Helm 4 es una evolución arquitectónica significativa en lugar de una actualización incremental. Sus objetivos principales son:

• Alineación con los patrones de implementación de Kubernetes modernos
• Eliminación de comportamientos heredados de Helm v3
• Mejora de la extensibilidad, mantenimiento y seguridad

Entre los cambios clave introducidos con Helm 4 se incluyen:

• Server-Side Apply (SSA): reemplaza el enfoque heredado de fusión de tres vías y alinea los despliegues con la semántica de reconciliación nativa de Kubernetes.
• Sistema de complementos rediseñado: presenta una arquitectura más extensible, incluidos complementos opcionales basados en WebAssembly para mejorar el aislamiento y la flexibilidad.
• Seguimiento mejorado de recursos: aprovecha los mecanismos de estado de Kubernetes más recientes, como kstatus, para proporcionar informes de estado de implementación más precisos.
• Modernización interna: elimina la deuda técnica y establece la base para futuras mejoras de innovación y rendimiento.

Importantemente, Helm 4 mantiene la compatibilidad con los gráficos de Helm v3 existentes, lo que permite a las organizaciones adoptar Helm 4 gradualmente sin necesidad de cambios inmediatos en gráficos o artefactos de implementación.

Relevancia para los publicadores de AOSM

El equipo de AOSM tiene previsto dar soporte a Helm 4 mediante dos hitos clave:

• En primer lugar, el equipo de AOSM publica una versión NFO que incluye Helm 4.1.4 que funciona en un "modo de compatibilidad". Este modo conserva el comportamiento de Helm 3.18, por lo que los publicadores pueden adoptar Helm 4 sin modificar los gráficos o artefactos existentes.
  • Puede probar hoy esta versión preliminar de NFO en el laboratorio UKSouth.
• En segundo lugar, el equipo de AOSM publica una versión NFO que elimina las personalizaciones de compatibilidad y habilita el comportamiento completo de Helm 4. Los editores pueden adoptar esta versión cuando estén listos, entendiendo que podrían ser necesarios cambios en los gráficos y los artefactos.
  • El equipo de AOSM tiene previsto esta versión de NFO para las pruebas del publicador en el cuarto trimestre del año natural 2026.

Los publicadores siguen teniendo flexibilidad al seleccionar el comportamiento de Helm durante la instalación de NFO. NFO tiene como valor predeterminado "modo de compatibilidad", al tiempo que proporciona una opción de instalación para habilitar el comportamiento completo de Helm 4. Esta funcionalidad tiene ámbito de clúster, lo que significa que todas las implementaciones dentro de un clúster deben usar el mismo modo operativo de Helm.

Detalles del modo de compatibilidad

La siguiente configuración conserva el comportamiento de Helm 3 al ejecutar Helm 4 en "modo de compatibilidad":

• Validación de esquemas más estricta
  • Helm 4 presenta una validación más estricta que rechaza segmentos con tipo Go, como []map[string]interface{}, al validar matrices JSON. Este comportamiento puede provocar errores cuando NFO inserta valores imagePullSecrets.
  • NFO actualiza la lógica de inyección de valores para usar []interfaz{} en su lugar y audita rutas de acceso de código similares para garantizar la compatibilidad.
• Server-Side Apply (SSA) está habilitado de forma predeterminada
  • Helm 4 valida los manifiestos generados con el esquema OpenAPI del clúster antes de aplicar los recursos. Los gráficos que contienen definiciones de campo no válidas que Helm 3 toleraba anteriormente podrían producir un error en la validación.
  • El modo de compatibilidad deshabilita SSA durante las operaciones de instalación y actualización para conservar el comportamiento de Helm 3.
• Nuevo modelo de espera
  • Helm 4 tiene como valor predeterminado un modelo de espera controlado por eventos que requiere permisos de inspección de Kubernetes. Este comportamiento puede producir un error en los clústeres nexus cuando los permisos de RBAC necesarios no están disponibles.
  • El modo de compatibilidad fija el comportamiento de espera en LegacyStrategy, conservando la semántica de sondeo de Helm 3.
• Recrear lo eliminado
  • Helm 4 elimina la compatibilidad con Upgrade.Recreate. Aunque se espera que el impacto en tiempo de ejecución sea bajo, los valores configurados por el cliente en el CRD ya no tendrán ningún efecto.
  • El modo de compatibilidad conserva el campo CRD para la compatibilidad con versiones anteriores, pero lo omite al ejecutar operaciones de Helm 4.
• Validación del metaesquema del esquema
  • Helm 4 valida values.schema.json con respecto al metaesquema de JSON Schema. Los gráficos que contienen definiciones de esquema no compatibles se rechazan antes de que se produzca la validación de valores. Se sabe que este comportamiento afecta a algunos gráficos de los editores.
  • El modo de compatibilidad establece SkipSchemaValidation=true durante las operaciones de instalación y actualización.