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, procedência do build, conteúdo de pacotes, certificação, Avaliação de Vulnerabilidades, Lista de materiais de software (SBOM, na sigla em inglês) e muito mais. As informações armazenadas nos 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. Crie um repositório de modo padrão, se ainda não tiver um, create a standard-mode repository.
  2. (Opcional) Configure padrões para comandos da Google Cloud CLI.

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 Artifact Registry (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 usando personalizados papéis ou outros predefinidos papéis.

Criar um anexo

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

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, forneça apenas o ID do anexo e use as --location e --repository flags.
  • TARGET: o nome da versão totalmente qualificada. Somente para imagens do Docker, também é possível usar o URI do Artifact Registry do artefato a que 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 estar em conformidade com as especificações da OCI para a propriedade artifactType.
  • ATTACHMENT_NAMESPACE: uma variável específica para anexos que identifica a fonte de dados do anexo, 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 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 a que 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 de imagem do contêiner a que o anexo se refere.

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

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

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

Gerenciar anexos com políticas de limpeza

Os anexos do repositório do Docker, incluindo a procedência do build, são excluídos quando os artefatos a que estão anexados são excluídos. Se você usar políticas de limpeza para excluir imagens do repositório, por padrão, os anexos dessas imagens também serão excluídos.

Para garantir que os anexos que você quer manter não sejam excluídos acidentalmente por uma política de limpeza, atribua uma tag a uma imagem que tenha anexos que você quer manter. Em seguida, é possível configurar uma política de limpeza para reter imagens com essas tags. Por exemplo, você pode atribuir uma tag production-signed a imagens com procedência do build anexada.

A seguir