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

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.

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).

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.

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:

• Migrando o Helm 2 para 3 na documentação do Helm.
• Migre seu registro para armazenar artefatos OCI do Helm, disponível mais adiante neste artigo

Pré-requisitos

Os recursos a seguir 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.
• Versão de cliente do Helm 3.7 ou posterior- executehelm version para descobrir sua versão atual. Para saber mais sobre como instalar e usar o Helm, consulte Instalar o Helm. Se você atualizar de uma versão anterior do Helm 3, examine as notas sobre a versão.
• Um cluster kubernetes em que você instalará um gráfico do Helm. Se necessário, crie um cluster do AKS usando a CLI do Azure, usando o Azure PowerShell ou usando o portal do Azure.
• CLI do Azure versão 2.0.71 ou posterior – Execute az --version para localizar a versão. Se você precisa instalar ou atualizar, consulte Instalar a CLI do Azure.

Configurar o cliente Helm

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

helm version

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.

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

• Para obter mais informações sobre como criar e implantar gráficos do Helm, confira Developing Helm charts (Desenvolvendo gráficos do Helm).
• Saiba mais sobre como instalar aplicativos com o Helm no Serviço de Kubernetes do Azure (AKS).
• Os gráficos do Helm podem ser usados como parte do processo de build do contêiner. Para obter mais informações, confira Tarefas do Registro de Contêiner do Azure.