Compartilhar via

Enviar por push e efetuar pull de gráficos do Helm para registro de contêiner do Azure

  • Artigo

Para gerenciar e implanta rapidamente aplicativos para Kubernetes, é possível usar o gerenciador de pacotes do Helm de software livre. Com o Helm, os pacotes de aplicativos são definidos como gráficos, coletados e armazenados em um repositório de gráficos do Helm.

Este artigo mostra como hospedar repositórios de gráficos do Helm em um registro de contêiner do Azure por meio de comandos do Helm 3 e do armazenamento de gráficos como artefatos de OCI. Na maioria dos cenários, você criaria e faria upload dos seus próprios gráficos para os aplicativos que você desenvolve. Para mais informações sobre como criar seus próprios gráficos do Helm, consulte o Guia do Desenvolvedor do Modelo de Gráfico. Você também pode armazenar um gráfico Helm existente a partir de outro repositório do Helm.

Observação

Este artigo foi atualizado com comandos Helm 3. O Helm 3.7 inclui alterações nos comandos da CLI do Helm e no suporte a OCI introduzidos em versões anteriores do Helm 3. Por padrão, helm avança com as atualizações de versão. Recomendamos o uso da versão 3.7.2 ou posterior.

Importante

  • Em novembro de 2020, o Helm 2 atingiu o fim de vida. A partir de 30 de março de 2025, o Registro de Contêiner do Azure não dará mais suporte ao Helm 2. Portanto, a funcionalidade de "repositórios Helm" herdados também será desativada. Recomendamos que você faça a transição para o Helm 3 imediatamente.
  • A partir de 21 de janeiro de 2025, o comando da CLI az acr helm push será desativado para impedir o envio de novos gráficos do Helm para repositórios do Helm herdados.
  • A partir de 30 de março de 2025, o grupo de comandos da CLI az acr helm será desativado, encerrando todas as funcionalidades do repositório Helm herdadas no Registro de Contêiner do Azure.
  • Todos os gráfico do Helm que não forem armazenados como artefato OCI serão excluídos do Registro de Contêiner do Azure em 30 de março de 2025.
  • Saiba como encontrar todos os gráfico do Helms armazenados em um repositório Helm aqui: az acr helm list. Se o gráfico do Helm que você está usando estiver listado, então ele estará armazenado em um repositório Helm herdado e corre o risco de ser excluído.

Helm 3 ou Helm 2?

Para armazenar, gerenciar e instalar gráficos do Helm, use os comandos na CLI do Helm. Versões principais do Helm incluem o Helm 3 e o Helm 2. Para mais detalhes sobre as diferenças de versão, consulte as perguntas frequentes sobre a versão.

Helm 3 deve ser usado para hospedar gráficos Helm no Registro de Contêiner do Azure. Com o Helm 3, você:

  • Pode armazenar e gerenciar gráficos do Helm em repositórios em um registro de contêiner do Azure
  • Armazene gráficos do Helm no seu registro como artefatos de OCI. O Registro de Contêiner do Azure dá suporte à GA para artefatos OCI, incluindo os gráficos do Helm.
  • Autentique com o seu registro usando o comando helm registry login ou az acr login.
  • Use comandos helm para efetuar push, efetuar pull e gerenciar gráficos do Helm em um registro
  • Use helm install para instalar gráficos em um cluster Kubernetes do Registro.

Suporte a recursos

O Registro de Contêiner do Azure dá suporte a recursos específicos de gerenciamento de gráficos do Helm, dependendo de você estar usando o Helm 3 (atual) ou o Helm 2 (preterido).

Recurso Helm 2 Helm 3
Gerenciar gráficos usando os comandos az acr helm ✔️
Armazenar gráficos como artefatos de OCI ✔️
Gerenciar gráficos usando os comandos az acr repository e a folha Repositórios no portal do Azure ✔️

Compatibilidade com versões do gráfico

As versões do gráfico do Helm a seguir podem ser armazenadas no Registro de Contêiner do Azure e instaladas pelos clientes do Helm 2 e do Helm 3.

Versão Helm 2 Helm 3
apiVersion v1 ✔️ ✔️
apiVersion v2 ✔️

Migrar do Helm 2 para o Helm 3

Se você já armazenou e implantou gráficos usando o Helm 2 e o Registro de Contêiner do Azure, recomendamos migrar para o Helm 3. Consulte:

Pré-requisitos

Os recursos a seguir são necessários para o cenário neste artigo:

Configurar o cliente Helm

Use o comando helm version para verificar se você instalou o Helm 3:

helm version

Observação

A versão indicada deve ser pelo menos a 3.8.0, já que o suporte à OCI nas versões anteriores era experimental.

Defina as variáveis de ambiente a seguir para o registro de destino. O ACR_NAME é o nome do recurso do registro. Se a URL do registro do ACR for myregistry.azurecr.io, defina o ACR_NAME como myregistry

ACR_NAME=<container-registry-name>

Crie um gráfico de exemplo

Crie um gráfico de teste usando os seguintes comandos:

mkdir helmtest

cd helmtest
helm create hello-world

Como um exemplo básico, altere o diretório para a pasta templates e, antes de mais nada, exclua os conteúdos dessa pasta:

cd hello-world/templates
rm -rf *

Na pasta templates, crie um arquivo chamado configmap.yaml, executando o seguinte comando:

cat <<EOF > configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: hello-world-configmap
data:
  myvalue: "Hello World"
EOF

Para mais informações sobre como criar e executar este exemplo, consulte Introdução no docs do Helm.

Salvar gráfico em um arquivo local

Altere o diretório para o subdiretório hello-world. Em seguida, execute helm package para salvar o gráfico em um arquivo local.

No exemplo a seguir, o gráfico é salvo com o nome e a versão em Chart.yaml.

cd ..
helm package .

A saída é semelhante a:

Successfully packaged chart and saved it to: /my/path/hello-world-0.1.0.tgz

Autenticar com um registro

Execute helm registry login para se autenticar com um registro. Você pode passar as credenciais do registro apropriadas para o seu cenário, como as credenciais da entidade de serviço, a identidade do usuário ou um token com escopo do repositório.

  • Autentique-se com uma entidade de serviço com permissões de pull e push do Microsoft Entra (função AcrPush) para o registro. 
    SERVICE_PRINCIPAL_NAME=<acr-helm-sp>
ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
          --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
           --role acrpush \
          --query "password" --output tsv)
USER_NAME=$(az identity show -n $SERVICE_PRINCIPAL_NAME -g $RESOURCE_GROUP_NAME --subscription $SUBSCRIPTION_ID --query "clientId" -o tsv)
  • Autentique-se com sua identidade individual do Microsoft Entra para efetuar push e pull de gráficos do Helm usando um token do AD. 
    USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
  • Autentique-se com um token com escopo do repositório (versão prévia). 
    USER_NAME="helmtoken"
PASSWORD=$(az acr token create -n $USER_NAME \
                  -r $ACR_NAME \
                  --scope-map _repositories_admin \
                  --only-show-errors \
                  --query "credentials.passwords[0].value" -o tsv)
  • Em seguida, forneça as credenciais para helm registry login. 
    helm registry login $ACR_NAME.azurecr.io \
  --username $USER_NAME \
  --password $PASSWORD

Enviar gráfico por push ao Registro como artefato de OCI

Execute o comando helm push na CLI do Helm 3 para enviar o arquivo de gráfico por push para o repositório de destino totalmente qualificado. Separe as palavras nos nomes do gráfico e use apenas letras minúsculas e números. No exemplo a seguir, o namespace do repositório de destino é helm/hello-world, e o gráfico é marcado com 0.1.0:

helm push hello-world-0.1.0.tgz oci://$ACR_NAME.azurecr.io/helm

Após um push bem-sucedido, a saída será semelhante a:

Pushed: <registry>.azurecr.io/helm/hello-world:0.1.0
digest: sha256:5899db028dcf96aeaabdadfa5899db02589b2899b025899b059db02

Listar gráficos no repositório

Assim como acontece com as imagens armazenadas em um registro de contêiner do Azure, você pode usar os comandos az acr repository para mostrar os repositórios que hospedam seus gráficos e as marcas e os manifestos do gráfico.

Por exemplo, execute az acr repository show para ver as propriedades do repositório que você criou na etapa anterior:

az acr repository show \
  --name $ACR_NAME \
  --repository helm/hello-world

A saída é semelhante a:

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2021-10-05T12:11:37.6701689Z",
  "imageName": "helm/hello-world",
  "lastUpdateTime": "2021-10-05T12:11:37.7637082Z",
  "manifestCount": 1,
  "registry": "mycontainerregistry.azurecr.io",
  "tagCount": 1
}

Execute o comando az acr manifest list-metadata para ver detalhes do gráfico armazenado no repositório. Por exemplo:

az acr manifest list-metadata \
  --registry $ACR_NAME \
  --name helm/hello-world

A saída, abreviada neste exemplo, mostra um configMediaType de application/vnd.cncf.helm.config.v1+json:

[
  {
    [...]
    "configMediaType": "application/vnd.cncf.helm.config.v1+json",
    "createdTime": "2021-10-05T12:11:37.7167893Z",
    "digest": "sha256:0c03b71c225c3ddff53660258ea16ca7412b53b1f6811bf769d8c85a1f0663ee",
    "imageSize": 3301,
    "lastUpdateTime": "2021-10-05T12:11:37.7167893Z",
    "mediaType": "application/vnd.oci.image.manifest.v1+json",
    "tags": [
      "0.1.0"
    ]

Instalar Pacote do Helm

Execute helm install para instalar o gráfico Helm enviado por push ao Registro. A marca do gráfico é passada usando o parâmetro --version. Especifique um nome de versão, como myhelmtest, ou passe o parâmetro --generate-name. Por exemplo:

helm install myhelmtest oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

A saída após a instalação bem-sucedida do gráfico é semelhante a:

NAME: myhelmtest
LAST DEPLOYED: Tue Oct  4 16:59:51 2021
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None

Para verificar sua instalação, execute o comando helm get manifest.

helm get manifest myhelmtest

O comando retorna os dados de YAML em seu arquivo de modelo configmap.yaml.

Execute helm uninstall para desinstalar a versão do gráfico em seu cluster:

helm uninstall myhelmtest

Efetuar pull de gráfico para um arquivo local

Opcionalmente, você pode efetuar pull de um gráfico do registro de contêiner para um arquivo local usando helm pull. A marca do gráfico é passada usando o parâmetro --version. Se houver um arquivo local no caminho atual, esse comando o substituirá.

helm pull oci://$ACR_NAME.azurecr.io/helm/hello-world --version 0.1.0

Excluir gráfico do registro

Para excluir um gráfico do repositório, use o comando az acr helm delete. Execute o comando a seguir e confirme a operação quando solicitado:

az acr repository delete --name $ACR_NAME --image helm/hello-world:0.1.0

Migrar o seu registro para armazenar artefatos OCI do Helm

Se você já tiver definido o registro de contêiner do Azure como um repositório de gráficos usando o Helm 2 e os comandos az acr helm, recomendamos que você atualize para o cliente do Helm 3. Em seguida, siga estas etapas para armazenar os gráficos como artefatos OCI no seu registro.

Importante

  • Depois de concluir a migração de um repositório de gráficos no estilo 2 do Helm (baseado em index.yaml) para repositórios de artefatos OCI, use a CLI do Helm e os comandos az acr repository para gerenciar os gráficos. Veja seções anteriores neste artigo.
  • Os repositórios de artefatos OCI do Helm não são podem ser descobertos usando comandos do Helm, como helm search e helm repo list. Para obter mais informações sobre os comandos do Helm usados para armazenar gráficos como artefatos OCI, confira a documentação do Helm.

Habilitar o suporte ao OCI (habilitado por padrão no Helm v3.8.0)

Verifique se você está usando o cliente do Helm 3:

helm version

Se você estiver usando o Helm v3.8.0 ou superior, isso será habilitado por padrão. Se você estiver usando uma versão inferior, poderá habilitar o suporte do OCI para definir a variável de ambiente:

export HELM_EXPERIMENTAL_OCI=1

Listar gráficos atuais

Liste os gráficos atualmente armazenados no registro, aqui chamados de myregistry:

helm search repo myregistry

A saída mostra os gráficos e as versões do gráfico:

NAME                            CHART VERSION   APP VERSION     DESCRIPTION                                       
myregistry/ingress-nginx        3.20.1          0.43.0          Ingress controller for Kubernetes...
myregistry/wordpress            9.0.3           5.3.2           Web publishing platform for building...
[...]

Efetuar pull de arquivos de gráfico localmente

Para cada gráfico no repositório, efetue pull do arquivo de gráfico localmente e anote o nome do arquivo:

helm pull myregisry/ingress-nginx
ls *.tgz

Um arquivo de gráfico local como ingress-nginx-3.20.1.tgz é criado.

Efetuar push de gráficos como artefatos de OCI para o Registro

Efetue logon no registro:

az acr login --name $ACR_NAME

Efetue push de cada arquivo de gráfico para o Registro. Exemplo:

helm push ingress-nginx-3.20.1.tgz oci://$ACR_NAME.azurecr.io/helm

Depois de enviar por push um gráfico, confirme se ele está armazenado no registro:

az acr repository list --name $ACR_NAME

Depois de enviar por push todos os gráficos, remova opcionalmente o repositório de gráficos no estilo 2 do Helm do registro. Isso reduz o armazenamento no registro:

helm repo remove $ACR_NAME

Próximas etapas