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

Se não existir um repositório de destino, crie um novo repositório.
Verifique se você tem as permissões necessárias para o repositório.
(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:

Veja imagens, arquivos em imagens e tags: Leitor do Artifact Registry (roles/artifactregistry.reader)
Marque imagens ou edite tags usando o Artifact Registry: Gravador do Artifact Registry (roles/artifactregistry.writer)
Excluir imagens ou remover tags: Administrador do repositório do Artifact Registry (roles/artifactregistry.repoAdmin)

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Talvez você também consiga receber as permissões necessárias por meio de papéis personalizados ou outros papéis predefinidos.

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 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 gerenciamento de imagens.

Console

Para visualizar imagens em um repositório:

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

Abrir a página Repositórios
Clique no repositório com a imagem do contêiner.
Clique em uma imagem para conferir as versões dela.

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

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 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 repositórios e imagens.

Como listar arquivos

Modos de repositório:padrão, remoto

Você pode listar arquivos em um repositório, arquivos em todas as versões de uma imagem de contêiner específica 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 sinalização --limit ao comando.

Para listar todos os arquivos no projeto, no repositório e no 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 os 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 os 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 os 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.

Examples

Considere as seguintes informações sobre a imagem:

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

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

gcloud artifacts files list \
    --location=us-central1 \
    --repository=my-repo

O comando a seguir lista os arquivos na versão da imagem com o resumo sha256:88b205d7995332e10e836514fbfd59ecaf8976fc15060cd66e85cdcebe7fb356.

gcloud artifacts files list \
    --project=my-project \
    --location=us-central1 \
    --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-central1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Como marcar imagens

Marque as imagens existentes em um repositório do Artifact Registry ou marque-as antes de enviá-las para 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 console do Google Cloud 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:

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

Abrir a página Repositórios
Clique na imagem para ver as versões dela.
Selecione a versão da imagem a ser marcada.
Na linha da versão selecionada, clique em Mais ações () e, em seguida, clique em Editar tags.
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 especifique a tag a ser adicionada. Execute um dos seguintes comandos:

gcloud artifacts docker tags add IMAGE-VERSION TAG

Por

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

É possível remover uma tag de uma imagem no Artifact Registry usando o console do Google Cloud ou a linha de comando.

Console

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

Abrir a página Repositórios
Clique na imagem para ver as versões dela.
Selecione a versão da imagem para remover a tag.
Na linha da versão selecionada, clique em Mais ações () e, em seguida, clique em Editar tags.
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

Por

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.

Depois de excluir uma imagem, não é possível desfazer a ação.
No caso de 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, o repositório será transferido por download e armazenado 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 imagens do console do Google Cloud ou da CLI gcloud:

Console

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

Abrir a página Repositórios
Clique no nome da imagem para ver as versões dessa imagem.
Selecione as versões que você quer excluir.
Clique em EXCLUIR.
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]

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

Por

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.