Esta página foi traduzida pela API Cloud Translation.

Gerenciar metadados do contêiner

Nesta página, descrevemos como conteinerizar, fazer upload para o Artifact Registry e gerenciar metadados sobre uma imagem de contêiner armazenada no Artifact Registry como um anexo.

Os anexos são artefatos do OCI e só podem ser armazenados em repositórios no formato Docker.

Antes de começar

Se você ainda não tiver um, crie um repositório padrão no formato Docker.
(Opcional) Configure padrões para os comandos da Google Cloud CLI.

Funções exigidas

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

Acessar e fazer o download de anexos: Leitor do Artifact Registry (roles/artifactregistry.reader)
Para criar anexos: Gravador do Artifact Registry (roles/artifactregistry.writer)
Para excluir anexos: Administrador de repositórios do Artifact Registry (roles/artifactregistry.repoAdmin)

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.

Configurar Oras (opcional)

Além de usar a CLI gcloud, você pode usar o Oras para criar, listar e fazer o download de anexos.

Instale o Oras 1.2 ou mais recente. Para verificar sua versão, execute o comando oras version.
Configure o Oras para autenticar com o Artifact Registry.

Criar anexos

É possível criar um anexo usando a CLI gcloud ou o Oras.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

ATTACHMENT: o nome totalmente qualificado do anexo. Por exemplo, projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, forneça apenas o ID do anexo e use os métodos --location e --repository.
TARGET: o nome da versão totalmente qualificado ou o URI do Artifact Registry do artefato a que o anexo se referirá. É possível usar o resumo ou a tag. Por exemplo, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
TYPE: o type do anexo. . Isso precisa estar em conformidade com as especificações do OCI para a propriedade artifactType.
ATTACHMENT_NAMESPACE: uma variável específica para anexos que identifica a fonte de dados de anexos. Por exemplo, example.com.
FILES: uma lista separada por vírgulas de arquivos locais a serem incluídos no anexo.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts attachments create ATTACHMENT \
    --target=TARGET \
    --type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

Windows (PowerShell)

gcloud artifacts attachments create ATTACHMENT `
    --target=TARGET `
    --type=TYPE `
    --attachment-namespace=ATTACHMENT_NAMESPACE `
    --files=FILES

Windows (cmd.exe)

gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES

gcloud artifacts attachments create

Oras

Ao criar um anexo com o Oras, o Artifact Registry gera um UUID aleatório para usar como nome do anexo.

Antes de executar o comando, faça estas substituições:

ARTIFACT_TYPE: o artifactType do anexo.
IMAGE_URI: o URI do contêiner de imagem ao qual o anexo se refere.
FILE: um arquivo local a ser incluído como metadados no anexo.
MEDIA_TYPE: o mediaType da camada.

  oras attach --artifact-type ARTIFACT_TYPE IMAGE_URI FILE:MEDIA_TYPE

O exemplo a seguir cria um anexo que consiste em um arquivo, hello-world.txt, que se refere a uma imagem de contêiner, my-image, identificada pelo URI e pela tag:

  oras attach --artifact-type doc/example \
  us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

Em que:

doc/example define a propriedade artifactType do anexo.
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 é o URI que inclui a tag da versão da imagem do contêiner no anexo se referirão.
hello-world.txt é o arquivo local que o anexo vai armazenar como dados.
application/vnd.me.hi define o mediaType da camada.

Para ter um guia completo e mais exemplos, consulte a documentação do oras attach.

Anexos da lista

Uma imagem de contêiner pode ter qualquer número de anexos que se referem a ela. É possível listar anexos usando o console do Google Cloud, a CLI gcloud ou o Oras.

Console

No Console do Google Cloud, abra a página Repositórios.

Abrir a página Repositórios
Clique no nome do repositório para ver as imagens.
Para conferir as versões de uma imagem, clique no nome dela.
Clique na versão de imagem adequada.
Para conferir os anexos dessa versão, clique na guia Anexos.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

TARGET: o nome da versão totalmente qualificado ou o URI do Artifact Registry do artefato para o qual você quer listar os anexos. É possível usar o resumo ou a tag. Por exemplo, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

gcloud artifacts attachments list ^
    --target=TARGET

Para mais informações, consulte o comando gcloud artifacts attachments list.

Oras

Antes de executar o comando, faça a seguinte substituição:

IMAGE_URI: o URI de a imagem de destino citada por qualquer anexo listado.

oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

O exemplo a seguir lista os anexos de uma imagem de contêiner, my-image, identificado por seu URI e tag:

oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

Em que:

v1.1-referrers-api é a API de referenciador usada. Para mais informações, consulte os detalhes na especificação de distribuição.
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 é o URI que inclui a tag da versão da imagem do contêiner para listar anexos.

Para ter um guia completo e mais exemplos, consulte a documentação do oras discover.

Fazer o download de anexos

É possível fazer o download de anexos usando a CLI gcloud ou o Oras.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

ATTACHMENT: o nome totalmente qualificado do anexo. Por exemplo, projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, forneça apenas o ID do anexo aqui e use --location e --repository.
DESTINATION: o caminho no seu sistema de arquivos local para fazer o download do anexo.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

Como alternativa ao fornecimento de ATTACHMENT, você pode fornecer a flag --oci-version-name seguida pelo nome da versão completa do anexo ou URI do Registro de artefatos. Você pode usar o resumo ou a tag. Por exemplo, projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123.

Para mais informações, consulte o comando gcloud artifacts attachments download.

Orás

Antes de executar o comando, faça estas substituições:

DESTINATION: o diretório de destino do anexo.
ATTACHMENT_URI: o URI do anexo a ser baixado. É o URI do contêiner de imagem ao qual o anexo se refere, seguido pelo SHA exclusivo do anexo.

oras pull -o DESTINATION ATTACHMENT_URI

O exemplo a seguir faz o download de um anexo identificado pelo URI e pelo resumo:

oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

Em que:

-o . nomeia o diretório atual como o destino do download.
us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx é o URI da imagem que inclui o resumo do anexo para download.

Para ter um guia completo e mais exemplos, consulte a documentação do oras pull.

Excluir anexos

É possível excluir anexos diretamente usando o console do Google Cloud ou a gcloud CLI. Você pode excluir anexos indiretamente excluindo o imagem do contêiner a que ela se refere.

Excluir anexos diretamente

Você pode excluir anexos diretamente com uma das seguintes opções:

Console

No Console do Google Cloud, abra a página Repositórios.

Abrir a página Repositórios
Clique no nome do repositório para ver as imagens.
Clique no nome da imagem para conferir as versões dela.
Clique na versão da imagem para ver os anexos.
Clique na guia Anexos para ver os anexos dessa versão.
Clique no resumo do anexo para excluir.
Clique em EXCLUIR.
Na caixa de diálogo de confirmação, clique em EXCLUIR.

gcloud

Antes de usar os dados do comando abaixo, faça estas substituições:

ATTACHMENT: o nome totalmente qualificado do anexo. Por exemplo, projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, forneça apenas o ID do anexo aqui e use --location e --repository.

Execute o seguinte comando:

Linux, macOS ou Cloud Shell

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

gcloud artifacts attachments delete ATTACHMENT

Para mais informações, consulte o comando gcloud artifacts attachments list.

Excluir anexos indiretamente

Se uma imagem de contêiner for excluída, todos os anexos de referência também serão excluídos. Isso se aplica tanto à exclusão manual de imagens de contêiner quanto e exclusões causadas por políticas de limpeza.