Armazenar metadados de artefatos em anexos

Nesta página, descrevemos 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 vulnerabilidades, lista de materiais de software (SBOM, na sigla em inglês) e muito mais. As informações armazenadas em anexos do Artifact Registry podem ser usadas por sistemas de políticas e inspecionadas por 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 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 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 que não sejam 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, forneça apenas o ID do anexo e use as flags --location e --repository.
  • TARGET: o nome totalmente qualificado da versão. 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 obedecer às 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, conclua as etapas a seguir:

  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 para incluir 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 por URI e 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 armazenar 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.

Gerenciar anexos com políticas de limpeza

Os anexos do repositório do Docker, incluindo a origem da 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 seu repositório, os anexos dessas imagens também serão excluídos por padrão.

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, configure uma política de limpeza para reter imagens com essas tags. Por exemplo, você pode atribuir uma tag production-signed a imagens com comprovação de build anexada.

A seguir