Gerenciar imagens

Nesta página, explicamos como gerenciar imagens de contêiner em um repositório do Docker. Gerenciar imagens inclui listar imagens em um repositório, adicionar tags, excluir tags, copiar imagens para um novo repositório e excluir imagens.

Para informações sobre como enviar e extrair imagens, consulte Como enviar e extrair imagens.

Antes de começar

  1. Se não existir um repositório de destino, crie um novo repositório.
  2. Verifique se você tem as permissões necessárias para o repositório.
  3. (Opcional) Configure padrões para comandos gcloud.

Funções exigidas

Para ter as permissões necessárias para gerenciar imagens, peça ao administrador para conceder a você os seguintes papéis do IAM no repositório:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Você também pode conseguir as permissões necessárias por meio de tags personalizadas ou outras funções predefinidas papéis.

Listar imagens

Modos de repositório: padrão, remoto

É possível listar as imagens usando o console do Google Cloud ou CLI gcloud.

A lista de repositórios inclui o Artifact Registry e repositórios do Container Registry. Para trabalhar com imagens em um Container Registry consulte a documentação do Container Registry sobre como gerenciar imagens.

Console

Para conferir imagens em um repositório:

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

    Abrir a página Repositórios

  2. Clique no repositório com a imagem do contêiner.

  3. Clique em uma imagem para conferir as versões dela.

gcloud

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

gcloud artifacts docker images list

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

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

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 regional ou multirregional local 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-west1
  • Nome do repositório: my-repo
  • ID do projeto: my-project
  • Nome da imagem: my-image

O nome completo do repositório é:

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

O nome completo da imagem é:

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

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

Como listar arquivos

Modos de repositório: padrão, remoto

É possível listar arquivos em um repositório, arquivos em todas as versões de um imagem de contêiner ou arquivos em uma versão específica de uma imagem.

Para todos os comandos a seguir, você pode definir um número máximo de arquivos a serem retornados adicionando a sinalização --limit ao comando.

Para listar todos os arquivos no projeto, repositório e local quando os valores padrão estiverem configurados:

gcloud artifacts files list

Para listar arquivos em um projeto, repositório e local especificados, execute o comando:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

Para listar arquivos de todas as versões de uma imagem de contêiner específica:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

Para listar arquivos de uma versão específica da imagem do contêiner:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION
Para listar arquivos de uma tag específica:

gcloud artifacts files list \
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Substitua os seguintes valores:

  • LOCATION: o regional ou multirregional local do repositório.
  • PROJECT: seuID de projeto no 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 são armazenados.
  • PACKAGE: o nome da imagem.
  • VERSION: resumo da imagem, uma string que começa com sha256:.
  • TAG: a tag associada à imagem do contêiner.

Exemplos

Considere as seguintes informações da imagem:

  • Projeto: my-project
  • Repositório: my-repo
  • Local do repositório: us-west1
  • Imagem: my-app

O comando a seguir lista todos os arquivos no repositório my-repo na Local us-west1 no projeto padrão:

gcloud artifacts files list \
    --location=us-west1 \
    --repository=my-repo
O comando a seguir lista os arquivos na versão da imagem com o resumo por e-mail sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --version=sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356
O comando a seguir lista os arquivos na versão da imagem com o marcar 1.0-dev

gcloud artifacts files list \
    --project=my-project \
    --location=us-west1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Como marcar imagens

É possível marcar as imagens atuais em um repositório do Artifact Registry ou marque-os antes de enviá-los ao repositório.

Como marcar imagens em um repositório

Modos de repositório: padrão

É possível adicionar uma tag a uma imagem em um repositório do Artifact Registry usando o Console do Google Cloud ou linha de comando. Em um registro, as tags são exclusivas para uma versão de uma imagem. Portanto, se você tiver várias versões de uma imagem, cada tag se aplicará apenas a uma delas. Se adicionar à imagem uma tag que já está em uso, a tag da versão original será movida 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 Google 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 da 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-west1
  • 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-west1-docker.pkg.dev/my-project/my-repo/my-image:iteration6-final \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:release-candidate

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

Como marcar imagens locais

Para enviar qualquer imagem local para o Artifact Registry, primeiro marque-a com o nome do registro e, em seguida, envie a imagem. Para ver instruções, consulte Como enviar e extrair.

Como desmarcar imagens

Modos de repositório: padrão

Para remover a tag de uma imagem no Artifact Registry, use o Console do Google Cloud ou linha de comando.

Console

  1. Abra a página Repositórios no console do Google 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 regional ou multirregional local do repositório.
  • PROJECT é seu Google Cloud ID do projeto. 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.

Como excluir imagens

Modos de repositório: padrão, remoto

É possível excluir uma imagem de contêiner inteira ou uma versão de imagem específica associada a uma tag ou um resumo.

  • Não é possível desfazer a exclusão de uma imagem.
  • A exclusão de imagens não exclui imediatamente as camadas referenciadas. Sem referência camadas são excluídas diariamente.
  • Para repositórios remotos, a cópia em cache da imagem é removida. A imagem permanece disponível na origem upstream. Se o controle remoto repositório receber uma nova solicitação para a mesma imagem, faça o download e armazene em cache novamente.

Outras ferramentas estão disponíveis para ajudar você a gerenciar imagens não utilizadas. Por exemplo o comando gcr-cleaner localiza e exclui imagens antigas com base em diferentes critérios. A remoção de imagens não usadas pode ajudar a reduzir os custos de armazenamento. A ferramenta gcr-cleaner não é um produto oficial do Google.

Para excluir uma imagem usando o console do Google Cloud ou a CLI gcloud:

Console

  1. Abra a página Repositórios no console do Google 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 regional ou multirregional local do repositório.
  • PROJECT é seu Google Cloud ID do projeto. 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