Gestire i metadati dei contenitori

Questa pagina descrive come eseguire il containerizzazione, il caricamento in Artifact Registry e la gestione dei metadati di un'immagine container archiviata in Artifact Registry come allegato.

Gli allegati sono artefatti OCI e possono essere archiviati solo in repository in formato Docker.

Prima di iniziare

1. Se non ne hai già uno, crea un repository standard in formato Docker.
2. (Facoltativo) Configura i valori predefiniti per i comandi Google Cloud CLI.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per gestire gli allegati, chiedi all'amministratore di concederti i seguenti ruoli IAM nel repository:

• Visualizza e scarica gli allegati: Artifact Registry Reader (roles/artifactregistry.reader)
• Crea allegati: Artifact Registry Writer (roles/artifactregistry.writer)
• Eliminare gli allegati: Amministratore del repository Artifact Registry (roles/artifactregistry.repoAdmin)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

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

(Facoltativo) Configurare Oras

Oltre a utilizzare gcloud CLI, facoltativamente puoi utilizzare Oras per creare, elencare e scaricare gli allegati.

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

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

Creare allegati

Puoi creare un allegato utilizzando gcloud CLI o Oras.

gcloud Oras

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 completo della versione oppure l'URI di Artifact Registry dell'artefatto a cui farà riferimento l'allegato. Puoi utilizzare il digest o il tag. Ad esempio, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
• TYPE: l'attributo type dell'allegato. Deve essere conforme alle specifiche OCI per la proprietà artifactType.
• ATTACHMENT_NAMESPACE: una variabile specifica per gli allegati che identifica l'origine dati degli allegati. Ad esempio, example.com.
• FILES: un elenco separato da virgole di file locali da includere nell'allegato.

Esegui il seguente comando:

Linux, macOS o Cloud Shell

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

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

Windows (PowerShell)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

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

Windows (cmd.exe)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

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.

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

Prima di eseguire il comando, effettua le seguenti sostituzioni:

• ARTIFACT_TYPE: il artifactType dell'allegato.

• IMAGE_URI: l'URI per il contenitore dell'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 contenitore, my-image, identificata dall'URI e dal 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 del 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.

Allegati elenco

Un'immagine container può avere un numero illimitato di allegati che fanno riferimento a essa. Puoi elencare gli allegati utilizzando la console Google Cloud, la CLI gcloud o Oras.

Console gcloud Oras

1. Nella console Google Cloud, apri la pagina Repositories (Repositoi).

   Apri la pagina Repositori

2. Fai clic sul nome del repository per visualizzare le immagini al suo interno.

3. Per visualizzare le versioni di un'immagine, fai clic sul nome dell'immagine.

4. Fai clic sulla versione dell'immagine appropriata.

5. Per visualizzare gli allegati della versione, fai clic sulla scheda Allegati.

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

• TARGET: il nome completo della versione o l'URI di Artifact Registry dell'artefatto per cui vuoi elencare gli allegati. Puoi utilizzare il digest o il tag. Ad esempio, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.

Esegui il seguente comando:

Linux, macOS o Cloud Shell

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments list ^
    --target=TARGET

Per ulteriori informazioni, consulta il comando gcloud artifacts attachments list.

Prima di eseguire il comando, effettua la seguente sostituzione:

• IMAGE_URI: l'URI dell'immagine di destinazione a cui fanno riferimento gli eventuali allegati elencati.

oras discover --distribution-spec v1.1-referrers-api IMAGE_URI

L'esempio seguente elenca gli allegati per un'immagine container, my-image, identificata dall'URI e dal tag:

oras discover --distribution-spec v1.1-referrers-api \
us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1

Dove:

• v1.1-referrers-api è l'API Referrer utilizzata. Per ulteriori informazioni, consulta i dettagli nella specifica di distribuzione.

• us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 è l'URI che include il tag della versione dell'immagine del container per cui elencare gli allegati.

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

Scaricare gli allegati

Puoi scaricare gli allegati utilizzando gcloud CLI o Oras.

gcloud Oras

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 qui e utilizza i flag --location e --repository.
• DESTINATION: il percorso nel sistema di file locale in cui scaricare l'allegato.

Esegui il seguente comando:

Linux, macOS o Cloud Shell

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

In alternativa a ATTACHMENT, puoi fornire il flag --oci-version-name seguito dal nome della versione completa dell'allegato o dall'URI del Registry degli elementi. Puoi utilizzare il digest o il tag. Ad esempio, projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123.

Per ulteriori informazioni, consulta il comando gcloud artifacts attachments download.

Prima di eseguire il comando, effettua le seguenti sostituzioni:

• DESTINATION: la directory di destinazione dell'allegato.

• ATTACHMENT_URI: l'URI dell'allegato da scaricare. Si tratta dell'URI del contenitore dell'immagine a cui fa riferimento l'allegato, seguito dall'SHA univoco dell'allegato.

oras pull -o DESTINATION ATTACHMENT_URI

L'esempio seguente scarica un allegato identificato dal relativo URI e digest:

oras pull -o . us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx

Dove:

• -o . assegna il nome della directory corrente come destinazione del download.

• us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx è l'URI dell'immagine che include il digest dell'allegato da scaricare.

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

Eliminare gli allegati

Puoi eliminare gli allegati direttamente utilizzando la console Google Cloud o la CLI gcloud. Puoi eliminare gli allegati indirettamente eliminando l'immagine del contenitore a cui fanno riferimento.

Eliminare direttamente gli allegati

Puoi eliminare direttamente gli allegati con una delle seguenti opzioni:

Console gcloud

1. Nella console Google Cloud, apri la pagina Repositories (Repositoi).

   Apri la pagina Repositori

2. Fai clic sul nome del repository per visualizzare le immagini al suo interno.

3. Fai clic sul nome dell'immagine per visualizzarne le versioni.

4. Fai clic sulla versione dell'immagine per cui vuoi visualizzare gli allegati.

5. Fai clic sulla scheda Allegati per visualizzare gli allegati della versione.

6. Fai clic sul digest dell'allegato da eliminare.

7. Fai clic su ELIMINA.

8. Nella finestra di dialogo di conferma, fai clic su ELIMINA.

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 qui e utilizza i flag --location e --repository.

Esegui il seguente comando:

Linux, macOS o Cloud Shell

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

Nota: assicurati di aver inizializzato Google Cloud CLI con l'autenticazione e un progetto, eseguendo gcloud init oppure gcloud auth login e gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Per ulteriori informazioni, consulta il comando gcloud artifacts attachments list.

Eliminare gli allegati indirettamente

Se un'immagine del contenitore viene eliminata, vengono eliminati anche tutti gli allegati di riferimento. Questo vale sia per l'eliminazione manuale delle immagini contenitore sia per le eliminazioni causate dai criteri di pulizia.

Nota: i criteri di pulizia non si applicano direttamente agli allegati. Tuttavia, se un criterio di pulizia elimina un'immagine container, vengono eliminati tutti gli allegati che fanno riferimento a quell'immagine container.