Armazenar metadados de artefatos em anexos

Esta página descreve como armazenar metadados relacionados a um artefato armazenado no Artifact Registry como um anexo.

Os metadados armazenados em anexos podem incluir informações sobre vulnerabilidades de artefatos, origem do build, conteúdo do pacote, certificação, avaliação de vulnerabilidade, SBOM (Software Bill of Materials) e muito mais. As informações armazenadas em anexos do Artifact Registry podem ser usadas por sistemas de políticas e inspecionadas pelos usuários para garantir a conformidade.

Para mais informações sobre como trabalhar com anexos, consulte Gerenciar metadados com anexos.

Antes de começar

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

Funções exigidas

Para receber as permissões necessárias para criar anexos, peça ao administrador para conceder a você o papel do IAM de Gravador do registro de artefatos (roles/artifactregistry.writer) 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.

Criar um anexo

Para repositórios do Docker, os anexos precisam ser artefatos OCI. Para todos os formatos, exceto o Docker, os anexos podem ser de qualquer tipo de arquivo.

É possível usar a CLI gcloud ou o Oras para criar anexos em repositórios no formato Docker.

Para criar um anexo, siga estas etapas:

gcloud (todos os formatos)

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

  • ATTACHMENT: o nome totalmente qualificado do anexo, como projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Como alternativa, informe apenas o ID do anexo e use as flags --location e --repository.
  • TARGET: o nome da versão totalmente qualificado. Somente para imagens do Docker, também é possível usar o URI do Artifact Registry do artefato ao qual o anexo se refere. No URI, é possível usar o resumo ou, para imagens do Docker, a tag, por exemplo, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
  • TYPE: o atributo type do anexo. Para imagens do Docker, o type precisa obedecer às 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, como 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 \
    --attachment-type=TYPE \
    --attachment-namespace=ATTACHMENT_NAMESPACE \
    --files=FILES

      Windows (PowerShell)

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

      Windows (cmd.exe)

      gcloud artifacts attachments create ATTACHMENT ^
    --target=TARGET ^
    --attachment-type=TYPE ^
    --attachment-namespace=ATTACHMENT_NAMESPACE ^
    --files=FILES
             Para mais informações, consulte o comando gcloud artifacts attachments create.

Oras (somente Docker)

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

Antes de usar o Oras, siga estas etapas:

  1. Instale o Oras 1.2 ou mais recente. Para verificar sua versão, execute o comando oras version.

  2. Configure o Oras para autenticar com o Artifact Registry.

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 do contêiner, my-image, identificado 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 a que o anexo se refere.

  • hello-world.txt é o arquivo local que o anexo vai conter como dados.

  • application/vnd.me.hi define o mediaType da camada.

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

A seguir