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

Também é possível conseguir as permissões necessárias por meio de papéis personalizados ou de outros papéis predefinidos.

Listar imagens

Modos de repositório: padrão, remoto

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

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

Console

Para conferir imagens em um repositório:

  1. Abra a página Repositórios no console 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 imagens em um repositório em um local específico, execute o comando:

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

Para listar todos os resumos e as 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 flag 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 uma imagem de contêiner especificada ou arquivos em uma versão específica de uma imagem.

Para todos os comandos a seguir, é possível definir um número máximo de arquivos a serem retornados adicionando a flag --limit ao comando.

Para listar todos os arquivos no projeto, repositório e local padrão 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 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.
  • PACKAGE: o nome da imagem.
  • VERSION: o 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 no 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 digest 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 a tag 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 imagens atuais em um repositório do Artifact Registry ou marcá-las antes de enviá-las a um 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 Google Cloud console ou a 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 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 do nome da imagem, incluindo projetos com escopo de domínio, consulte Nomes de repositório e de 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

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

Console

  1. Abra a página Repositórios no console 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

Substitua:

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

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. Camadas sem referência são excluídas diariamente.
  • Para repositórios remotos, a cópia em cache da imagem é removida. A imagem continua disponível na origem upstream. Se o repositório remoto receber uma nova solicitação para a mesma imagem, ele fará o download e o armazenamento em cache novamente.

Outras ferramentas estão disponíveis para ajudar você a gerenciar imagens não utilizadas. Por exemplo, a ferramenta gcr-cleaner descobre e exclui imagens antigas com base em critérios diferentes. 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 do console do Google Cloud ou da CLI gcloud:

Console

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

    Abrir a página Repositórios

  2. Clique no nome da imagem para conferir as versões dela.

  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 . Se o ID do projeto contiver 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 flag 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