Gérer les métadonnées de conteneur

Cette page explique comment conteneuriser, importer dans Artifact Registry et gérer les métadonnées d'une image de conteneur stockée dans Artifact Registry en tant qu'pièce jointe.

Les pièces jointes sont des artefacts OCI et ne peuvent être stockées que dans des dépôts au format Docker.

Avant de commencer

1. Si vous n'en avez pas encore, créez un dépôt standard au format Docker.
2. (Facultatif) Configurez des valeurs par défaut pour les commandes Google Cloud CLI.

Rôles requis

Pour obtenir les autorisations nécessaires pour gérer les pièces jointes, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le dépôt:

• Afficher et télécharger les pièces jointes : Lecteur Artifact Registry (roles/artifactregistry.reader)
• Créer des pièces jointes : Rédacteur Artifact Registry (roles/artifactregistry.writer)
• Supprimer des pièces jointes : Administrateur de dépôts Artifact Registry (roles/artifactregistry.repoAdmin)

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Configurer Oras (facultatif)

En plus d'utiliser gcloud CLI, vous pouvez également utiliser Oras pour créer, lister et télécharger des pièces jointes.

1. Installez Oras 1.2 ou une version ultérieure. Pour vérifier votre version, exécutez la commande oras version.

2. Configurez Oras pour qu'il s'authentifie avec Artifact Registry.

Créer des rattachements

Vous pouvez créer une pièce jointe à l'aide de gcloud CLI ou d'Oras.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

• ATTACHMENT: nom complet de l'attachement. Exemple : projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Vous pouvez également ne fournir que l'ID de l'attachement et utiliser les options --location et --repository.
• TARGET: nom de version complet ou URI Artifact Registry de l'artefact auquel la pièce jointe fera référence. Vous pouvez utiliser le récapitulatif ou la balise. Exemple : us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.
• TYPE: attribut type de la pièce jointe. Cela doit respecter les spécifications OCI pour la propriété artifactType.
• ATTACHMENT_NAMESPACE: variable spécifique aux pièces jointes qui identifie la source de données des pièces jointes. Exemple :example.com
• FILES: liste de fichiers locaux à inclure dans la pièce jointe, séparés par une virgule.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

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

Windows (PowerShell)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

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

Windows (cmd.exe)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

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

Pour en savoir plus, consultez la commande gcloud artifacts attachments create.

Oras

Lorsque vous créez une pièce jointe avec Oras, Artifact Registry génère un UUID aléatoire à utiliser comme nom de pièce jointe.

Avant d'exécuter la commande, effectuez les remplacements suivants :

• ARTIFACT_TYPE: artifactType de l'attachement.

• IMAGE_URI: URI du conteneur d'image auquel la pièce jointe fait référence.

• FILE: fichier local à inclure en tant que métadonnées dans la pièce jointe.

• MEDIA_TYPE: mediaType de la couche.

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

L'exemple suivant crée une pièce jointe composée d'un fichier, hello-world.txt, qui fait référence à une image de conteneur, my-image, identifiée par son URI et sa balise:

  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

Où :

• doc/example définit la propriété artifactType de la pièce jointe.

• us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 est l'URI incluant le tag de la version de l'image de conteneur à laquelle l'attachement fera référence.

• hello-world.txt est le fichier local qui contiendra les données de l'attachement.

• application/vnd.me.hi définit le mediaType de la couche.

Pour obtenir un guide complet et d'autres exemples, consultez la documentation oras attach.

Pièces jointes des listes

Une image de conteneur peut être associée à un nombre illimité de pièces jointes. Vous pouvez lister les pièces jointes à l'aide de la console Google Cloud , de gcloud CLI ou d'Oras.

Console

1. Dans la console Google Cloud , ouvrez la page Dépôts.

   Ouvrir la page "Dépôts"

2. Cliquez sur le nom du dépôt pour afficher les images qu'il contient.

3. Pour afficher les versions d'une image, cliquez sur son nom.

4. Cliquez sur la version d'image appropriée.

5. Pour afficher les pièces jointes de cette version, cliquez sur l'onglet Pièces jointes.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

• TARGET: nom de version complet ou URI Artifact Registry de l'artefact pour lequel vous souhaitez lister les pièces jointes. Vous pouvez utiliser le récapitulatif ou la balise. Exemple : us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments list \
    --target=TARGET

Windows (PowerShell)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments list `
    --target=TARGET

Windows (cmd.exe)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments list ^
    --target=TARGET

Pour en savoir plus, consultez la commande gcloud artifacts attachments list.

Oras

Avant d'exécuter la commande, effectuez le remplacement suivant:

• IMAGE_URI: URI de l'image cible référencée par les pièces jointes listées.

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

L'exemple suivant liste les pièces jointes d'une image de conteneur, my-image, identifiée par son URI et son tag:

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

Où :

• v1.1-referrers-api est l'API de référent utilisée. Pour en savoir plus, consultez les détails de la spécification de distribution.

• us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1 est l'URI incluant le tag de la version de l'image du conteneur pour laquelle lister les pièces jointes.

Pour obtenir un guide complet et d'autres exemples, consultez la documentation oras discover.

Télécharger les pièces jointes

Vous pouvez télécharger des pièces jointes à l'aide de la gcloud CLI ou d'Oras.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

• ATTACHMENT: nom complet de l'attachement. Exemple : projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Vous pouvez également ne fournir que l'ID de l'attachement ici et utiliser les options --location et --repository.
• DESTINATION: chemin d'accès dans votre système de fichiers local vers lequel télécharger la pièce jointe.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments download ATTACHMENT \
    --destination=DESTINATION

Windows (PowerShell)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments download ATTACHMENT `
    --destination=DESTINATION

Windows (cmd.exe)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments download ATTACHMENT ^
    --destination=DESTINATION

Au lieu de fournir ATTACHMENT, vous pouvez fournir l'indicateur --oci-version-name suivi du nom de version complet de la pièce jointe ou de l'URI du registre d'artefacts. Vous pouvez utiliser le récapitulatif ou la balise. Par exemple, projects/my-project/locations/us-west1/repositories/my-repo/packages/my-package/versions/sha256:abc123.

Pour en savoir plus, consultez la commande gcloud artifacts attachments download.

Oras

Avant d'exécuter la commande, effectuez les remplacements suivants :

• DESTINATION: répertoire de destination de votre pièce jointe.

• ATTACHMENT_URI: URI de la pièce jointe à télécharger. Il s'agit de l'URI du conteneur d'image auquel la pièce jointe fait référence, suivi du SHA unique de la pièce jointe.

oras pull -o DESTINATION ATTACHMENT_URI

L'exemple suivant télécharge une pièce jointe identifiée par son URI et son récapitulatif:

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

Où :

• -o . nomme le répertoire actuel comme destination de téléchargement.

• us-west1-docker.pkg.dev/my-project/my-repo/my-image@sha256:xxxx correspond à l'URI de l'image, y compris le récapitulatif de la pièce jointe à télécharger.

Pour obtenir un guide complet et d'autres exemples, consultez la documentation oras pull.

Supprimer les pièces jointes

Vous pouvez supprimer des pièces jointes directement à l'aide de la console Google Cloud ou de gcloud CLI. Vous pouvez supprimer indirectement les pièces jointes en supprimant l'image de conteneur à laquelle elles font référence.

Supprimer directement les pièces jointes

Vous pouvez supprimer des pièces jointes directement à l'aide de l'une des options suivantes:

Console

1. Dans la console Google Cloud , ouvrez la page Dépôts.

   Ouvrir la page "Dépôts"

2. Cliquez sur le nom du dépôt pour afficher les images qu'il contient.

3. Cliquez sur le nom de l'image pour afficher ses versions.

4. Cliquez sur la version de l'image pour laquelle vous souhaitez afficher les pièces jointes.

5. Cliquez sur l'onglet Pièces jointes pour afficher les pièces jointes de cette version.

6. Cliquez sur le récapitulatif de la pièce jointe à supprimer.

7. Cliquez sur SUPPRIMER.

8. Dans la boîte de dialogue de confirmation, cliquez sur SUPPRIMER.

gcloud

Avant d'utiliser les données de la commande ci-dessous, effectuez les remplacements suivants :

• ATTACHMENT: nom complet de l'attachement. Exemple : projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Vous pouvez également ne fournir que l'ID de l'attachement ici et utiliser les options --location et --repository.

Exécutez la commande suivante :

Linux, macOS ou Cloud Shell

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (PowerShell)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Windows (cmd.exe)

Remarque : Assurez-vous d'avoir initialisé Google Cloud CLI avec l'authentification et un projet en exécutant la commande gcloud init ou gcloud auth login et gcloud config set project.

gcloud artifacts attachments delete ATTACHMENT

Pour en savoir plus, consultez la commande gcloud artifacts attachments list.

Supprimer des pièces jointes indirectement

Si une image de conteneur est supprimée, toutes les pièces jointes référentes sont également supprimées. Cela s'applique à la fois à la suppression manuelle des images de conteneurs et aux suppressions causées par des règles de nettoyage.

Remarque :Les règles de nettoyage ne s'appliquent pas directement aux pièces jointes. Toutefois, si une règle de nettoyage supprime une image de conteneur, toutes les pièces jointes qui y font référence sont supprimées.