Enviar e puxar gráficos Helm para um registro de contêiner do Azure

Artigo
09/28/2024

Para gerenciar e implantar rapidamente aplicativos para Kubernetes, você pode usar o gerenciador de pacotes Helm de código aberto. Com o Helm, os pacotes de aplicativos são definidos como gráficos, que são coletados e armazenados em um repositório de gráficos Helm.

Este artigo mostra como hospedar repositórios de gráficos Helm em um registro de contêiner do Azure, usando comandos Helm 3 e armazenando gráficos como artefatos OCI. Em muitos cenários, você criaria e carregaria seus próprios gráficos para os aplicativos que desenvolve. Para obter mais informações sobre como criar seus próprios gráficos Helm, consulte o Guia do desenvolvedor do modelo de gráfico. Você também pode armazenar um gráfico Helm existente de outro repositório Helm.

Nota

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

Importante

Em novembro de 2020, o leme 2 chegou ao fim da vida útil. A partir de 30 de março de 2025, o Registro de Contêiner do Azure não suportará mais o Helm 2. Portanto, a funcionalidade herdada "Helm repositories" também será desativada. Recomendamos que você faça a transição para o Leme 3 imediatamente.
A partir de 21 de janeiro de 2025, o comando da CLI az acr helm push será aposentado para evitar o envio de novos gráficos Helm para repositórios Helm legados.
A partir de 30 de março de 2025, o grupo de comando da CLI az acr helm será desativado, encerrando todos os recursos herdados do repositório Helm no Azure Container Registry.
Todos os gráficos Helm não armazenados como um 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áficos Helm armazenados em um repositório Helm aqui: az acr helm list. Se o gráfico Helm que você está usando estiver listado, ele será armazenado em um repositório Helm herdado e correrá o risco de exclusão.

Leme 3 ou Leme 2?

Para armazenar, gerenciar e instalar gráficos Helm, use comandos na CLI do Helm. Os principais lançamentos do Helm incluem o Helm 3 e o Helm 2. Para obter detalhes sobre as diferenças de versão, consulte as Perguntas frequentes sobre a versão.

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

Pode armazenar e gerenciar gráficos Helm em repositórios em um registro de contêiner do Azure
Armazene gráficos Helm em seu registro como artefatos OCI. O Registro de Contêiner do Azure fornece suporte de GA para artefatos OCI, incluindo gráficos de leme.
Autentique-se com seu registro usando o helm registry login comando ou az acr login .
Usar helm comandos para enviar, puxar e gerenciar gráficos Helm em um registro
Use helm install para instalar gráficos em um cluster Kubernetes a partir do Registro.

Suporte de funcionalidades

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

Caraterística	Leme 2	Leme 3
Gerenciar gráficos usando `az acr helm` comandos	✔️
Armazenar gráficos como artefatos OCI		✔️
Gerenciar gráficos usando `az acr repository` comandos e a folha Repositórios no portal do Azure		✔️

Compatibilidade da versão do gráfico

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

Versão	Leme 2	Leme 3
apiVersion v1	✔️	✔️
apiVersão v2		✔️

Migrar do Leme 2 para o Leme 3

Se você já armazenou e implantou gráficos usando o Helm 2 e o Azure Container Registry, recomendamos migrar para o Helm 3. Veja:

Migração do Leme 2 para o 3 na documentação do Leme.
Migre seu registro para armazenar artefatos Helm OCI, mais adiante neste artigo

Pré-requisitos

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

Um registro de contêiner do Azure em sua assinatura do Azure. Se necessário, crie um registro usando o portal do Azure ou a CLI do Azure.
Helm client versão 3.7 ou posterior - Execute helm version para encontrar sua versão atual. Para obter mais informações sobre como instalar e atualizar o Helm, consulte Instalando o Helm. Se você atualizar de uma versão anterior do Helm 3, revise as notas de versão.
Um cluster Kubernetes onde você instalará um gráfico Helm. Se necessário, crie um cluster AKS usando a CLI do Azure, usando o Azure PowerShell ou usando o portal do Azure.
Azure CLI versão 2.0.71 ou posterior - Execute az --version para localizar a versão. Se precisar de instalar ou atualizar, veja Install Azure CLI (Instalar o Azure CLI).

Configurar o cliente Helm

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

helm version

Nota

A versão indicada deve ser pelo menos 3.8.0, pois o suporte a OCI em versões anteriores era experimental.

Defina as seguintes variáveis de ambiente para o registro de destino. O ACR_NAME é o nome do recurso do Registro. Se o URL do registo ACR estiver myregistry.azurecr.io, defina o ACR_NAME como myregistry

ACR_NAME=<container-registry-name>

Criar um gráfico de exemplo

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

mkdir helmtest

cd helmtest
helm create hello-world

Como exemplo básico, altere o diretório para a templates pasta e primeiro exclua o conteúdo lá:

cd hello-world/templates
rm -rf *

templates Na pasta, 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 obter mais informações sobre como criar e executar este exemplo, consulte Introdução ao Helm Docs.

Salvar gráfico no arquivo morto local

Altere o diretório para o hello-world subdiretório. 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 o registo

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

Autentique-se com uma entidade de serviço do Microsoft Entra com permissões pull e push (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 enviar e puxar gráficos Helm usando um token 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 de repositório (Visualização).

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 para o registro como artefato OCI

Execute o helm push comando na CLI do Helm 3 para enviar o arquivo de gráficos para o repositório de destino totalmente qualificado. Separe as palavras nos nomes dos gráficos 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 como 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 é 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 marcas e manifestos de gráficos.

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 os 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 gráfico Helm

Execute helm install para instalar o gráfico Helm que você enviou para o registro. A tag do gráfico é passada usando o --version parâmetro. Especifique um nome de versão, como myhelmtest, ou passe o --generate-name parâmetro. 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 a instalação, execute o helm get manifest comando.

helm get manifest myhelmtest

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

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

helm uninstall myhelmtest

Puxar gráfico para arquivo local

Opcionalmente, você pode extrair um gráfico do registro do contêiner para um arquivo local usando helm pullo . A tag do gráfico é passada usando o --version parâmetro. Se existir um arquivo morto local no caminho atual, este 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 registro de contêiner, use o comando az acr repository delete . Execute o seguinte comando e confirme a operação quando solicitado:

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

Migrar seu registro para armazenar artefatos Helm OCI

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

Importante

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

Ativar suporte a OCI (ativado por padrão no Helm v3.8.0)

Certifique-se de que está a utilizar o cliente Helm 3:

helm version

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

export HELM_EXPERIMENTAL_OCI=1

Listar gráficos atuais

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

helm search repo myregistry

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

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...
[...]

Puxar arquivos de gráficos localmente

Para cada gráfico no repositório, puxe o 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.

Enviar gráficos como artefatos OCI para o registro

Inicie sessão no registo:

az acr login --name $ACR_NAME

Envie 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 um gráfico, confirme se ele está armazenado no registro:

az acr repository list --name $ACR_NAME

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

helm repo remove $ACR_NAME

Próximos passos

Para obter mais informações sobre como criar e implantar gráficos de leme, consulte Desenvolvendo gráficos de leme.
Saiba mais sobre como instalar aplicativos com o Helm no Serviço Kubernetes do Azure (AKS).
Os gráficos de leme podem ser usados como parte do processo de construção do contêiner. Para obter mais informações, consulte Usar tarefas do Registro de Contêiner do Azure.

Partilhar via