Armazene metadados de artefactos em anexos

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

Os metadados armazenados em anexos podem incluir informações sobre vulnerabilidades de artefactos, proveniência de compilação, conteúdos de pacotes, certificação, avaliação de vulnerabilidades, lista de materiais de software (SBOM) e muito mais. As informações armazenadas em anexos do Artifact Registry podem ser usadas por sistemas de políticas e inspecionadas pelos utilizadores para garantir a conformidade.

Para mais informações sobre como trabalhar com anexos, consulte o artigo Faça a gestão de metadados com anexos.

Antes de começar

  1. Se ainda não tiver um, crie um repositório no modo padrão.
  2. (Opcional) Configure as predefinições para os comandos da CLI gcloud.

Funções necessárias

Para receber as autorizações de que precisa para criar anexos, peça ao seu administrador para lhe conceder a função de IAM Gravador do Artifact Registry (roles/artifactregistry.writer) no repositório. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Crie um anexo

Para repositórios do Docker, os anexos têm de ser artefactos da OCI. Para todos os formatos, exceto o Docker, os anexos podem ser de qualquer tipo de ficheiro.

Pode usar a CLI gcloud ou o Oras para criar anexos em repositórios no formato Docker.

Para criar um anexo, conclua os seguintes passos:

gcloud (todos os formatos)

Antes de usar qualquer um dos dados de comandos abaixo, faça as seguintes substituições:

  • ATTACHMENT: o nome totalmente qualificado do anexo, como projects/my-project/locations/u-france-east1/repositories/my-repo/attachments/my-attachment. Em alternativa, forneça apenas o ID do anexo e use as flags --location e --repository.
  • TARGET: o nome da versão totalmente qualificado. Apenas para imagens do Docker, também pode usar o URI do Artifact Registry do artefacto ao qual o anexo se refere. No URI, pode usar o resumo ou, para imagens do Docker, a etiqueta, por exemplo, u-france-east1-docker.s3nsregistry.fr/my-project/my-repo/my-image:tag1.
  • TYPE: o atributo type do anexo. Para imagens do Docker, o type tem de estar em conformidade com as especificações da OCI para a propriedade artifactType.
  • ATTACHMENT_NAMESPACE: uma variável específica dos anexos que identifica a origem de dados do anexo, como example.com.
  • FILES: uma lista separada por vírgulas de ficheiros locais a incluir 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 (apenas Docker)

Quando cria 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 os seguintes passos:

  1. Instale o Oras 1.2 ou posterior. Para verificar a 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 as seguintes substituições:

  • ARTIFACT_TYPE: o artifactType do anexo.

  • IMAGE_URI: o URI do contentor de imagens ao qual o anexo se refere.

  • FILE: um ficheiro local a incluir como metadados no anexo.

  • MEDIA_TYPE: o mediaType da camada.

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

O exemplo seguinte cria um anexo composto por um ficheiro, hello-world.txt, que faz referência a uma imagem de contentor, my-image, identificada pelo seu URI e etiqueta:

  oras attach --artifact-type doc/example \
  u-france-east1-docker.s3nsregistry.fr/my-project/my-repo/my-image:tag1 \
  hello-world.txt:application/vnd.me.hi

Onde:

  • doc/example define a propriedade artifactType do anexo.

  • u-france-east1-docker.s3nsregistry.fr/my-project/my-repo/my-image:tag1 é o URI que inclui a etiqueta da versão da imagem do contentor à qual o anexo se vai referir.

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

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

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

Faça a gestão de anexos com políticas de limpeza

Os anexos do repositório Docker, incluindo a proveniência da compilação, são eliminados quando os artefactos aos quais estão anexados são eliminados. Se usar as políticas de limpeza para eliminar imagens do repositório, por predefinição, os anexos dessas imagens também são eliminados.

Para garantir que os anexos que quer manter não são eliminados acidentalmente por uma política de limpeza, pode atribuir uma etiqueta a uma imagem com anexos que quer manter. Em seguida, pode configurar uma política de limpeza para reter imagens com essas etiquetas. Por exemplo, pode atribuir uma etiqueta production-signed a imagens com proveniência de compilação anexada.

O que se segue