Como gerenciar gráficos do Helm

Esta página explica como gerenciar gráficos do Helm salvos como imagens de contêiner OCI, incluindo push (upload), pull (download), listagem, marcação e exclusão de gráficos.

Antes de começar

  1. Se não existir um repositório de destino, crie um novo repositório. Escolha o Docker como formato do repositório.
  2. Verifique se você tem as permissões necessárias para o repositório.
  3. (Opcional) Configure padrões para comandos gcloud.
  4. Instale o Helm 3 se ainda não estiver instalado.

  5. Ative o suporte experimental do Helm para imagens OCI com a variável HELM_EXPERIMENTAL_OCI. Adicione a seguinte linha ao ~/.bashrc (ou ~/.bash_profile no macOS ou sempre que o shell armazenar variáveis de ambiente):

    export HELM_EXPERIMENTAL_OCI=1
    
  6. Execute o seguinte comando para carregar seu arquivo .bashrc (ou .bash_profile) atualizado:

    source ~/.bashrc
    
  7. Configure o Helm para fazer a autenticação com o Artifact Registry.

Como criar ou receber um gráfico

Nesta documentação, nosso foco é gerenciar as imagens de gráficos e presumir que você tem gráficos ou está familiarizado com a criação de gráficos. Para saber mais sobre como criar gráficos ou acessar gráficos disponíveis publicamente no Artifact Hub, consulte as seguintes informações na documentação do Helm.

Como salvar um gráfico no formato OCI

Antes de enviar um gráfico ao Artifact Registry, salve-o como uma imagem de contêiner.

  1. Mude para o diretório que contém o gráfico.

  2. Salve o gráfico como uma imagem OCI, usando o caminho completo para o local da imagem no repositório de destino.

    helm chart save CHART-PATH LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
    

    Substitua os seguintes valores:

    • CHART-PATH é o caminho que contém o arquivo Chart.yaml.
    • LOCATION é o local regional ou multirregional do repositório.
    • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
    • REPOSITORY é o nome do repositório em que a imagem está armazenada.
    • IMAGE é o nome da imagem no repositório.
    • TAG é a tag para a versão da imagem.

    Se você não especificar uma tag com :TAG, o Helm marcará a imagem com o número de versão padrão do gráfico no arquivo CHART-PATH/Chart.yaml. A atualização desse número sempre que você fizer alterações em um gráfico é uma maneira útil de manter os metadados em Chart.yaml sincronizados com suas tags de imagem de contêiner.

    Veja este exemplo:

    helm chart save my-chart/ us-central1-docker.pkg.dev/my-project/my-repo/my-chart
    

    Se a versão do gráfico for 0.1.0, o Helm usará esse número de versão como tag. A resposta ao comando "save" é semelhante a:

    ref:     us-central1-docker.pkg.dev/my-project/my-repo/my-chart:0.1.0
    digest:  decd0b41c389fd46c586c292eaf05f446fe05dc56248f409bef2c123ab7b7032
    size:    3.5 KiB
    name:    my-chart
    version: 0.1.0
    0.1.0: saved
    
  3. Liste gráficos no seu cache local para confirmar que eles foram salvos localmente.

    helm chart list
    

    A lista inclui o gráfico salvo.

    REF                                                             NAME            VERSION DIGEST  SIZE    CREATED
    us-central1-docker.pkg.dev/my-project/my-repo...   my-chart     0.1.0   decd0b4 3.5 KiB 2 minutes
    

Agora é possível enviar a imagem do seu gráfico para o Artifact Registry.

Como enviar um gráfico

Depois de salvar o gráfico como uma imagem de contêiner, é possível enviá-lo para o Artifact Registry.

Para enviar o gráfico por push, execute o seguinte comando:

helm chart push LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

Substitua os seguintes valores:

  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY é o nome do repositório em que a imagem está armazenada.
  • IMAGE é o nome da imagem no repositório.
  • TAG é a tag para a versão da imagem.

Execute o seguinte comando para verificar se o gráfico está armazenado no repositório:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY

Se você não precisar mais de uma cópia da imagem no cache local do Helm, exclua a cópia local.

Como extrair gráficos

Não é possível implantar uma versão diretamente de um gráfico salvo como uma imagem de contêiner. Para usar o gráfico, extraia a imagem, extraia os arquivos do gráfico e use os arquivos extraídos para realizar a implantação.

  1. Extraia a imagem do gráfico do Artifact Registry com o comando:

    helm chart pull LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
    

    Substitua os seguintes valores:

    • LOCATION é o local regional ou multirregional do repositório.
    • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
    • REPOSITORY é o nome do repositório em que a imagem está armazenada.
    • IMAGE é o nome da imagem no repositório.
    • TAG é a tag para a versão da imagem.
  2. Para extrair os arquivos do gráfico da imagem, execute o comando:

    helm chart export LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG
    

Agora é possível usar os arquivos de gráfico extraídos para instalar uma versão com o comando helm install.

No exemplo a seguir, uma versão chamada release1 é instalada usando um gráfico armazenado no diretório my-chart.

helm install release1 ./my-chart

Como listar gráficos

É possível listar gráficos usando o Console do Google Cloud ou a linha de comando. Se você armazenar imagens e gráficos de contêiner no mesmo repositório do Docker, os dois tipos de artefato aparecerão na lista.

Console

Para ver imagens em um repositório:

  1. Abra a página Repositórios no Console do Cloud.

    Abrir a página Repositórios

  2. Clique no repositório que contém o gráfico.

  3. Clique em uma imagem para ver as versões.

gcloud

Para listar todas as imagens no projeto, no repositório e no local padrão quando os valores padrão estiverem configurados:

gcloud artifacts docker images list [--include-tags]

Para listar imagens em um repositório em um local específico, execute o comando:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY \
[--include-tags]

Para listar todos os resumos e tags de uma imagem específica, execute o comando:

gcloud artifacts docker images list LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE \
[--include-tags]

Substitua os seguintes valores:

  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY é o nome do repositório em que a imagem está armazenada.
  • IMAGE é o nome da imagem no repositório.
  • --include-tags mostra todas as versões das imagens, incluindo resumos e tags. Se essa sinalização for omitida, a lista retornada incluirá apenas imagens de contêiner de nível superior.

Por exemplo, considere uma imagem com as seguintes características:

  • Local do repositório: us
  • Nome do repositório: my-repo
  • ID do projeto: my-project
  • Nome da imagem: my-image

O nome completo do repositório é:

us-docker.pkg.dev/my-project/my-repo

O nome completo da imagem é:

us-docker.pkg.dev/my-project/my-repo/my-image

Para detalhes sobre o formato do nome da imagem, consulte Nomes de imagem e repositório.

Como adicionar e remover tags

Ao empacotar um gráfico como uma imagem OCI sem especificar uma tag, o Helm adiciona automaticamente uma tag usando o número da versão do gráfico em Chart.yaml.

É possível adicionar e excluir outras tags no Artifact Registry usando o Console do Google Cloud ou a linha de comando.

Como adicionar tags

Em um repositório, as tags são exclusivas de uma versão de uma imagem. Portanto, se você tiver várias versões de uma imagem, cada tag se aplicará somente a uma das versões. Se você marcar uma imagem com uma tag que já está em uso, moverá a tag da versão original para a versão recém-marcada.

Console

Para marcar uma imagem em um repositório:

  1. Abra a página Repositórios no Console do Cloud.

    Abrir a página Repositórios

  2. Clique na imagem para ver as versões dela.

  3. Selecione a versão da imagem a ser marcada.

  4. Na linha da versão selecionada, clique em Mais ações (Mais ações) e, em seguida, clique em Editar tags.

  5. Insira novas tags no campo e clique em SALVAR.

gcloud

Para marcar imagens em um repositório, especifique a versão da imagem usando o resumo ou a tag de imagem e, em seguida, especifique a tag a ser adicionada. Execute um dos seguintes comandos:

gcloud artifacts docker tags add IMAGE-VERSION TAG

Onde

  • IMAGE-VERSION é o nome completo da versão de imagem a ser marcada, usando o resumo da imagem ou uma tag existente na versão da imagem.
  • TAG é o nome completo da tag que você quer adicionar.

Por exemplo, considere uma imagem com as seguintes características:

  • Local do repositório: us
  • Nome do repositório: my-repo
  • ID do projeto: my-project
  • Nome da imagem: my-image
  • Tag existente: iteration6-final
  • Tag a ser adicionada: release-candidate

Para adicionar a tag release-candidate à versão da imagem com a tag iteration6-final, execute o seguinte comando:

gcloud artifacts docker tags add \
us-docker.pkg.dev/my-project/my-repo/my-image:iteration6-final \
us-docker.pkg.dev/my-project/my-repo/my-image:release-candidate

Para detalhes sobre o formato do nome da imagem, incluindo o gerenciamento de projetos com escopo de domínio, consulte Nomes de repositório e imagens.

Como excluir tags

Você pode remover uma tag de uma imagem no Artifact Registry usando o Console do Google Cloud ou a linha de comando.

Console

  1. Abra a página Repositórios no Console do Cloud.

    Abrir a página Repositórios

  2. Clique na imagem para ver as versões dela.

  3. Selecione a versão da imagem para remover a tag.

  4. Na linha da versão selecionada, clique em Mais ações (Mais ações) e, em seguida, clique em Editar tags.

  5. Exclua a tag e clique em SALVAR.

gcloud

Para excluir uma tag e removê-la da imagem, execute o seguinte comando:

 gcloud artifacts docker tags delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

Onde

  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY é o nome do repositório em que a imagem está armazenada.
  • IMAGE é o nome da imagem no repositório.
  • TAG é a tag da versão que você quer excluir.

Excluir imagens

Quando você salva arquivos de gráfico localmente como uma imagem com o comando helm chart save, o Helm armazena a imagem no cache local. Depois que a imagem estiver armazenada no Artifact Registry, você poderá excluir a cópia local dela do cache.

Em um repositório do Artifact Registry, é possível excluir uma imagem inteira de contêiner ou excluir uma versão de imagem específica associada a uma tag ou resumo. Depois de excluir uma imagem, não é possível desfazer a ação.

Para excluir uma imagem no cache de imagem local do Helm, execute o seguinte comando.

helm chart remove LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG

Substitua os seguintes valores:

  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto do Google Cloud.
  • REPOSITORY é o nome do repositório em que a imagem está armazenada.
  • IMAGE é o nome da imagem no repositório.
  • TAG é a tag para a versão da imagem.

Para excluir uma imagem armazenada no Artifact Registry:

Console

  1. Abra a página Repositórios no Console do Cloud.

    Abrir a página Repositórios

  2. Clique no nome da imagem para ver as versões dessa imagem.

  3. Selecione as versões que você quer excluir.

  4. Clique em EXCLUIR.

  5. Na caixa de diálogo de confirmação, clique em Excluir.

gcloud

Para excluir uma imagem e todas as tags dela, execute o seguinte comando:

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE --delete-tags

Para excluir uma versão de imagem específica, use um dos comandos a seguir.

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE:TAG [--delete-tags]

ou

gcloud artifacts docker images delete LOCATION-docker.pkg.dev/PROJECT/REPOSITORY/IMAGE@IMAGE-DIGEST [--delete-tags]

Onde

  • LOCATION é o local regional ou multirregional do repositório.
  • PROJECT é o ID do projeto do Google Cloud. Caso o ID do projeto contenha dois pontos (:), consulte Projetos com escopo de domínio.
  • REPOSITORY é o nome do repositório em que a imagem está armazenada.
  • IMAGE é o nome da imagem no repositório.
  • TAG é a tag da versão que você quer excluir. Se várias tags estiverem associadas à mesma versão de imagem, será necessário incluir --delete-tags para excluir a versão de imagem sem remover as tags primeiro.
  • IMAGE-DIGEST é o valor de hash sha256 da versão que você quer excluir. Se uma tag estiver associada ao resumo da imagem, você precisará incluir --delete-tags para excluir a versão da imagem sem remover a tag primeiro.
  • --delete-tags remove todas as tags aplicadas à versão da imagem. Essa sinalização permite forçar a exclusão de uma versão de imagem quando:
    • Você tiver especificado uma tag, mas existir outras tags associadas à versão da imagem.
    • Você tiver especificado um resumo de imagem com pelo menos uma tag.

A seguir