Práticas recomendadas para pacotes Helm

Helm é um gerenciador de pacotes para Kubernetes que ajuda a simplificar o gerenciamento do ciclo de vida do aplicativo. Os pacotes do Helm são chamados charts e consistem em arquivos de modelo e configuração YAML. Durante a execução de uma operação do Helm, os charts são renderizados em arquivos de manifesto do Kubernetes para disparar as ações apropriadas do ciclo de vida do aplicativo. Para obter a integração mais eficiente com o Gerenciador de Serviços de Operador do Azure, siga estas práticas recomendadas ao desenvolver gráficos do Helm.

Considerações sobre registryPath e imagePullSecrets

Normalmente, todos os charts do Helm exigem os parâmetros registryPath e imagePullSecrets. Na maioria das vezes, você expõe esses parâmetros no arquivo values.yaml. Inicialmente, o Gerenciador de Serviço de Operador do Azure dependia de os fornecedores gerenciarem esses valores de maneira estrita (abordagem herdada), para serem substituídos pelos valores adequados do Azure durante a implantação. Mas nem todos os fornecedores conseguiam cumprir com facilidade a gestão rigorosa desses valores. Alguns charts ocultam registryPath e/ou imagePullSecrets atrás de condicionais ou outras restrições de valor, que nem sempre eram atendidas. Alguns charts declaram registryPath e/ou imagePullSecrets como uma matriz em vez de como a cadeia de caracteres nomeada esperada.

Para reduzir as exigências regulatórias dos fornecedores, o Gerenciador de Serviço de Operador do Azure introduziu dois métodos aprimorados: injectArtifactStoreDetail e registro de cluster. Esses métodos mais recentes não dependem da presença de registryPath ou imagePullSecrets no pacote do Helm. Em vez disso, esses métodos usam um webhook para injetar valores adequados do Azure diretamente em operações de pod.

Resumo dos métodos para registryPath e imagePullSecrets

Atualmente, os três métodos têm suporte, conforme descrito neste artigo. Escolha a melhor opção para sua função de rede (NF) e caso de uso.

Herdado:

  • Exige que você parametrize registryPath e imagePullSecrets nos valores do Helm e nos modelos de implantação para substituição.
  • Hospeda imagens no Registro de Contêiner do Azure.

InjectArtifactStoreDetail:

  • Usa um webhook para injetar registryPath e imagePullSecrets diretamente nas operações de pod, com dependências mínimas no Helm.
  • Hospeda imagens no Registro de Contêiner do Azure.

Registro do cluster:

  • Usa um webhook para injetar registryPath e imagePullSecrets diretamente nas operações de pod, sem dependência do Helm.
  • Hospeda imagens na extensão do operador de função de rede local (NFO).

Nos três casos, o Gerenciador de Serviço de Operador do Azure substitui os valores do Azure por quaisquer valores que você expuser em modelos. A única diferença é o método de substituição.

Requisitos herdados para registryPath e imagePullSecrets

O Gerenciador de Serviço de Operador do Azure usa o serviço Gerenciador de Funções de Rede do Azure para implantar funções de rede conteinerizadas (CNFs). Com o método herdado, o Gerenciador de Funções de Rede do Azure substitui os valores registryPath e imagePullSecrets do contêiner do Gerenciador de Serviço de Operador do Azure na operação do Helm durante a implantação de funções de rede.

Exemplo do método herdado

O modelo de implantação do Helm a seguir mostra um exemplo de como expor registryPath e 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

O modelo values.yaml a seguir mostra um exemplo de como fornecer os valores registryPath e imagePullSecrets:

global: 
   imagePullSecrets: [] 
   registryPath: ""

O arquivo values.schema.json a seguir mostra um exemplo de como definir os valores registryPath e 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" ], 
      } 
   } 
}

O payload de solicitação da versão de definição de função de rede (NFDV) a seguir mostra um exemplo de como fornecer os valores registryPath e imagePullSecrets na implantação:

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

Nos exemplos anteriores:

  • O valor registryPath é definido sem prefixo, como https:// ou oci://. Se necessário, defina um prefixo no pacote do Helm.
  • imagePullSecrets e registryPath devem ser fornecidos durante a integração da NFDV.

Outras considerações

Considere as seguintes recomendações ao usar o método herdado.

Evitar referências a um registro externo

Referências a um registro externo podem causar problemas de validação. Por exemplo, se deployment.yaml usar um caminho de registro embutido no código ou referências externas ao registro, ele falhará na validação.

Realizar validações manuais

Revise as especificações de imagens e contêineres para garantir que as imagens tenham o prefixo registryPath e que imagePullSecrets esteja preenchido com secretName:

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

Veja outro exemplo:

 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>

Usar um repositório de imagens e rótulos estáticos

Cada chart do Helm deve conter um repositório de imagens e rótulos estáticos. Defina os valores estáticos por meio de um dos seguintes métodos:

  • Na linha image
  • Em values.yaml, sem expor esses valores na NFDV

Uma NFDV deve ser mapeada para um conjunto estático de charts do Helm e imagens. Atualize os charts e as imagens apenas publicando uma nova NFDV, conforme mostrado nos exemplos a seguir:

 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

Em alguns casos, os gráficos Helm de terceiros podem não estar totalmente em conformidade com os requisitos do Gerenciador de Serviço de Operador do Azure para registryPath. Nesses casos, você pode usar injectArtifactStoreDetails para evitar alterações de conformidade em pacotes do Helm.

Com injectArtifactStoreDetails habilitado, use um método de webhook para injetar os valores registryPath e imagePullSecrets adequados dinamicamente durante as operações de pod. Esse método substitui os valores configurados no pacote do Helm. Ainda é necessário usar valores fictícios legais onde registryPath e imagePullSecrets são referenciados, geralmente na seção global de values.yaml.

O exemplo de values.yaml a seguir mostra como fornecer os valores registryPath e imagePullSecrets para compatibilidade com a abordagem injectArtifactStoreDetails:

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

Observação

Se registryPath for deixado em branco no pacote do Helm subjacente, a implantação do serviço de rede do site (SNS) falhará durante o download da imagem.

Usar o método injectArtifactStoreDetails

Para habilitar injectArtifactStoreDetails, defina o parâmetro installOptions na seção roleOverrides do recurso NF como true, conforme mostrado no exemplo a seguir:

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"}}}}}'
    ]
  }
}

Observação

O pacote de charts do Helm ainda deve expor valores registryPath e imagePullSecrets devidamente formatados.

Requisitos do registro de cluster para registryPath e imagePullSecrets

Com um registro de cluster, as imagens são copiadas do Registro de Contêiner do Azure para um repositório Docker local no cluster do Kubernetes do Nexus. Use um método de webhook para injetar dinamicamente os valores registryPath e imagePullSecrets adequados durante as operações de pod. Esse método substitui os valores configurados no pacote do Helm. Ainda é necessário usar valores fictícios legais onde registryPath e imagePullSecrets são referenciados, geralmente na seção global de values.yaml.

O exemplo de values.yaml a seguir mostra como fornecer os valores registryPath e imagePullSecrets para compatibilidade com a abordagem do registro de cluster:

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

Observação

Se registryPath for deixado em branco no pacote do Helm subjacente, a implantação do SNS falhará durante o download da imagem.

Para obter mais informações sobre como usar um registro de cluster, confira a documentação de conceitos.

Recomendações para restrições de imutabilidade

Restrições de imutabilidade impedem alterações em um arquivo ou diretório. Por exemplo, um arquivo imutável não pode ser alterado ou renomeado. Evite usar rótulos mutáveis, como latest, dev ou stable. Por exemplo, se deployment.yaml usar latest para .Values.image.tag, a implantação falhará.

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

Recomendações para declaração de CRD e divisão de uso

Recomendamos separar a declaração e o uso de definições de recursos do cliente (CRDs) em charts do Helm distintos para dar suporte a atualizações. Para obter informações detalhadas, confira a documentação do Helm sobre a separação de charts.

Recomendações para marcação de versão de imagem

Para garantir implantações consistentes e previsíveis, recomendamos o seguinte para todas as imagens de contêiner:

  • Evite usar :latest em ambientes de produção.
    • Usar a tag 'latest' pode causar um comportamento inesperado porque a imagem real associada ao 'latest' pode ser alterada sem qualquer aviso.
    • Em uma configuração do registro de cluster, se o valor da marca for alterado, mas o nome da marca permanecer o mesmo, o registro do cluster não baixará novamente a imagem atualizada.
    • Isso pode levar à execução de imagens desatualizadas ou inconsistentes.
  • Em vez disso, use sempre tags imutáveis ​​como :1.4.2
  • Verifique se cada build produz uma tag única, não sobrescreva as tags existentes.

Essas práticas ajudam a evitar problemas de implantação e melhorar a rastreabilidade, a segurança de reversão e a conformidade de segurança.

Recomendações para ordenação sequencial de nfApplication

Por padrão, os aplicativos CNF são instalados ou atualizados conforme a ordem em que aparecem no NFDV. Na operação de exclusão, os aplicativos CNF são excluídos na ordem inversa especificada. Se for necessário definir uma ordem específica de aplicativos CNF diferente da padrão, use dependsOnProfile para definir uma sequência exclusiva para as operações de instalação, atualização e exclusão.

Como usar dependsOnProfile

É possível usar dependsOnProfile no NFDV para controlar a sequência das execuções do Helm para aplicativos CNF. No exemplo a seguir:

  • Durante uma operação de instalação, os aplicativos CNF são implantados na seguinte ordem: dummyApplication1, dummyApplication2, dummyApplication.
  • Durante uma operação de atualização, os aplicativos CNF são atualizados na seguinte ordem: dummyApplication2, dummyApplication1, dummyApplication.
  • Durante uma operação de exclusão, os aplicativos CNF são excluídos na seguinte ordem: 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"
    }
}

Erros comuns com dependsOnProfile

Atualmente, se o código dependsOnProfile fornecido no NFDV for inválido, a operação NF falhará com um erro de validação. A mensagem do erro de validação aparece no recurso de status da operação e é semelhante ao exemplo a seguir:

 {
  "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."
  }
}

Práticas recomendadas para adotar o Helm 4

O Helm é o gerenciador de pacotes padrão do Kubernetes desde seu lançamento inicial em 2016. Sua evolução acompanhou de perto o próprio Kubernetes:

  • Helm v2 (2016-2019): introduziu o empacotamento de aplicativos baseado em gráfico, mas contou com um componente do lado do servidor (Tiller), que gerou preocupações com segurança e multilocação.
  • Helm v3 (2019–2025): removeu o Tiller, passando a um modelo apenas do cliente, com segurança e usabilidade aprimoradas. Essa versão tornou-se o padrão do setor e acumulou aprimoramentos incrementais, mantendo a compatibilidade com versões anteriores.

Após quase seis anos do Helm v3, o projeto acumulou dívidas técnicas, limitações arquitetônicas e desafios de segurança que não poderia enfrentar sem introduzir mudanças significativas. Essa situação levou ao lançamento do Helm v4 no final de 2025.

O que o Helm 4 representa

O Helm 4 é uma evolução arquitetônica significativa em vez de uma atualização incremental. Suas principais metas são:

  • Alinhar com padrões de implantação modernos do Kubernetes
  • Remover comportamentos herdados do Helm v3
  • Melhorar a extensibilidade, a manutenção e a segurança

As principais alterações introduzidas com o Helm 4 incluem:

  • Aplicação no lado do servidor (SSA): substitui a abordagem legada de fusão de três vias e alinha as implantações à semântica de reconciliação nativa do Kubernetes.
  • Sistema de plugins redesenhado: introduz uma arquitetura mais extensível, incluindo plugins opcionais baseados em WebAssembly para maior isolamento e flexibilidade.
  • Melhor acompanhamento de recursos: aproveita os mecanismos de status do Kubernetes mais recentes, como kstatus, para fornecer relatórios de estado de implantação mais precisos.
  • Modernização interna: remove a dívida técnica e estabelece as bases para futuras melhorias de inovação e desempenho.

É importante ressaltar que o Helm 4 mantém a compatibilidade com os gráficos existentes do Helm v3, permitindo que as organizações adotem o Helm 4 gradualmente sem exigir alterações imediatas em gráficos ou artefatos de implantação.

Relevância para os Editores de AOSM

A equipe da AOSM planeja oferecer suporte ao Helm 4 por meio de dois marcos importantes:

  • Primeiro, a equipe de AOSM lança uma versão de NFO que inclui o Helm 4.1.4 operando em um "modo de compatibilidade". Esse modo preserva o comportamento do Helm 3.18, para que os editores possam adotar o Helm 4 sem modificar os gráficos ou artefatos existentes.
    • Você pode testar em prévia esta versão do NFO hoje no laboratório UKSouth.
  • Em segundo lugar, a equipe de AOSM lança uma versão NFO que remove personalizações de compatibilidade e habilita o comportamento completo do Helm 4. Os publicadores podem adotar esta versão quando estiverem prontos, cientes de que alterações em gráficos e artefatos podem ser necessárias.
    • A equipe do AOSM planeja esta versão do NFO para testes da editora no 4º trimestre do ano-calendário de 2026.

Os editores continuam a ter flexibilidade ao selecionar o comportamento do Helm durante a instalação do NFO. O NFO usa como padrão o "modo de compatibilidade", ao mesmo tempo em que fornece uma opção de instalação para habilitar o comportamento completo do Helm 4. Essa funcionalidade se aplica ao escopo do cluster, o que significa que todas as implantações dentro de um cluster devem usar o mesmo modo de operação do Helm.

Detalhes do modo de compatibilidade

As seguintes configurações preservam o comportamento do Helm 3 ao executar o Helm 4 em "modo de compatibilidade":

  • Validação de esquema mais rigorosa
    • O Helm 4 apresenta uma validação mais rigorosa que rejeita fatias do tipo Go, como []map[string]interface{}, ao validar matrizes JSON. Esse comportamento pode causar falhas quando o NFO injeta valores imagePullSecrets.
    • O NFO atualiza a lógica de injeção de valor para usar []interface{} e audita trechos de código semelhantes para garantir a compatibilidade.
  • Server-Side Apply (SSA) habilitado por padrão
    • O Helm 4 valida os manifestos renderizados em relação ao esquema OpenAPI do cluster antes de aplicar os recursos. Gráficos que contêm definições de campo inválidas que o Helm 3 tolerou anteriormente podem falhar na validação.
    • O modo de compatibilidade desabilita o SSA durante operações de instalação e atualização para preservar o comportamento do Helm 3.
  • Novo modelo de espera
    • O Helm 4 usa como padrão um modelo de espera controlado por eventos que requer permissões de inspeção do Kubernetes. Esse comportamento pode falhar em clusters Nexus em que as permissões RBAC necessárias não estão disponíveis.
    • O modo de compatibilidade vincula o comportamento de aguardo à LegacyStrategy, preservando a semântica de sondagem do Helm 3.
  • Recriar o que foi removido
    • O Helm 4 remove o suporte a Upgrade.Recreate. Embora se espere que o impacto no runtime deva ser baixo, caso contrário, os valores configurados pelo cliente no CRD não teriam mais nenhum efeito.
    • O modo de compatibilidade preserva o campo CRD para compatibilidade com versões anteriores, mas o ignora ao executar operações do Helm 4.
  • Validação de metaesquema do esquema
    • O Helm 4 valida o values.schema.json em relação ao metaesquema do JSON Schema. Os gráficos que contêm definições de esquema não compatíveis são rejeitados antes que a validação de valores ocorra. Esse comportamento é conhecido por afetar alguns gráficos de editores.
    • O modo de compatibilidade define SkipSchemaValidation=true durante operações de instalação e atualização.
  • Last updated on