Memorizzare i metadati degli elementi negli allegati

Questa pagina descrive come archiviare i metadati relativi a un artefatto archiviato in Artifact Registry come allegato.

I metadati archiviati negli allegati possono includere informazioni su vulnerabilità degli artefatti, provenienza della build, contenuti del pacchetto, certificazione, valutazione delle vulnerabilità, Software Bill of Materials (SBOM) e altro ancora. Le informazioni archiviate negli allegati di Artifact Registry possono essere utilizzate dai sistemi di policy e ispezionate dagli utenti per garantire la conformità.

Per ulteriori informazioni sull'utilizzo degli allegati, consulta Gestire i metadati con gli allegati.

Prima di iniziare

  1. Se non ne hai già uno, crea un repository in modalità standard.
  2. (Facoltativo) Configura le impostazioni predefinite per i comandi Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per creare allegati, chiedi all'amministratore di concederti il ruolo IAM Artifact Registry Writer (roles/artifactregistry.writer) nel repository. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Creare un allegato

Per i repository Docker, gli allegati devono essere artefatti OCI. Per tutti i formati diversi da Docker, gli allegati possono essere di qualsiasi tipo.

Puoi utilizzare gcloud CLI o Oras per creare allegati nei repository in formato Docker.

Per creare un allegato, completa i seguenti passaggi:

gcloud (tutti i formati)

Prima di utilizzare i dati dei comandi riportati di seguito, effettua le seguenti sostituzioni:

  • ATTACHMENT: il nome completo dell'allegato, ad esempio projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. In alternativa, fornisci solo l'ID allegato e utilizza i flag --location e --repository.
  • TARGET: il nome della versione completo. Solo per le immagini Docker, puoi utilizzare anche l'URI Artifact Registry dell'artefatto a cui fa riferimento l'allegato. Nell'URI puoi utilizzare il digest o, per le immagini Docker, il tag, ad esempio, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
  • TYPE: l'attributo type dell'allegato. Per le immagini Docker, type deve essere conforme alle specifiche OCI per la proprietà artifactType.
  • ATTACHMENT_NAMESPACE: una variabile specifica per gli allegati che identifica l'origine dati dell'allegato, ad esempio example.com.
  • FILES: un elenco separato da virgole di file locali da includere nell'allegato.

      • Esegui questo comando:

      Linux, macOS o 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
             Per ulteriori informazioni, consulta il comando gcloud artifacts attachments create.

Oras (solo Docker)

Quando crei un allegato con Oras, Artifact Registry genera un UUID casuale da utilizzare come nome dell'allegato.

Prima di utilizzare Oras, completa i seguenti passaggi:

  1. Installa Oras 1.2 o versioni successive. Per verificare la tua versione, esegui il comando oras version.

  2. Configura Oras per l'autenticazione con Artifact Registry.

Prima di eseguire il comando, effettua le seguenti sostituzioni:

  • ARTIFACT_TYPE: il artifactType dell'allegato.

  • IMAGE_URI: l'URI del container immagine a cui fa riferimento l'allegato.

  • FILE: un file locale da includere come metadati nell'allegato.

  • MEDIA_TYPE: il mediaType del livello.

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

L'esempio seguente crea un allegato costituito da un file, hello-world.txt, che fa riferimento a un'immagine container, my-image, identificata dal relativo 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

Dove:

  • doc/example definisce la proprietà artifactType dell'allegato.

  • us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 è l'URI che include il tag della versione dell'immagine container a cui farà riferimento l'allegato.

  • hello-world.txt è il file locale che l'allegato conterrà come dati.

  • application/vnd.me.hi definisce il mediaType del livello.

Per una guida completa e altri esempi, consulta la documentazione di oras attach.

Gestire gli allegati con le policy di pulizia

Gli allegati del repository Docker, inclusa la provenienza della build, vengono eliminati quando vengono eliminati gli artefatti a cui sono allegati. Se utilizzi i criteri di pulizia per eliminare le immagini dal repository, per impostazione predefinita verranno eliminati anche gli allegati di queste immagini.

Per assicurarti che gli allegati che vuoi conservare non vengano eliminati accidentalmente da una policy di pulizia, puoi assegnare un tag a un'immagine che contiene allegati che vuoi conservare. Poi, puoi configurare un criterio di pulizia per conservare le immagini con questi tag. Ad esempio, puoi assegnare un tag production-signed alle immagini con provenienza della build allegata.

Passaggi successivi