Stocker les métadonnées d'artefact dans les pièces jointes

Cette page explique comment stocker les métadonnées associées à un artefact stocké dans Artifact Registry en tant que pièce jointe.

Les métadonnées stockées dans les pièces jointes peuvent inclure des informations sur les failles des artefacts, la provenance des compilations, le contenu des packages, la certification, l'évaluation des failles, la nomenclature logicielle (SBOM, Software Bill of Materials) et plus encore. Les informations stockées dans les pièces jointes Artifact Registry peuvent être utilisées par les systèmes de règles et inspectées par les utilisateurs pour garantir la conformité.

Pour en savoir plus sur l'utilisation des pièces jointes, consultez Gérer les métadonnées avec des pièces jointes.

Avant de commencer

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

Rôles requis

Pour obtenir les autorisations nécessaires pour créer des pièces jointes, demandez à votre administrateur de vous accorder le rôle IAM Rédacteur Artifact Registry (roles/artifactregistry.writer) sur le dépôt. 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 avec des rôles personnalisés ou d'autres rôles prédéfinis.

Créer un rattachement

Pour les dépôts Docker, les pièces jointes doivent être des artefacts OCI. Pour tous les formats autres que Docker, les pièces jointes peuvent être de n'importe quel type de fichier.

Vous pouvez utiliser la gcloud CLI ou Oras pour créer des pièces jointes dans des dépôts au format Docker.

Pour créer une pièce jointe, procédez comme suit :

gcloud (tous les formats)

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

  • ATTACHMENT : nom complet du rattachement, par exemple projects/my-project/locations/us-west1/repositories/my-repo/attachments/my-attachment. Vous pouvez également ne fournir que l'ID de pièce jointe et utiliser les options --location et --repository.
  • TARGET : nom complet de la version. Pour les images Docker uniquement, vous pouvez également utiliser l'URI Artifact Registry de l'artefact auquel la pièce jointe fait référence. Dans l'URI, vous pouvez utiliser le résumé ou, pour les images Docker, le tag (par exemple, us-west1-docker.pkg.dev/my-project/my-repo/my-image:tag1).
  • TYPE : attribut type de la pièce jointe. Pour les images Docker, le type 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 de la pièce jointe, par 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

      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
             Pour en savoir plus, consultez la commande gcloud artifacts attachments create.

Oras (Docker uniquement)

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

Avant d'utiliser Oras, procédez comme suit :

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

  2. Configurez Oras pour s'authentifier auprès d'Artifact Registry.

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

  • ARTIFACT_TYPE : artifactType du rattachement.

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

  • 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 son 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

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 la pièce jointe fera référence.

  • hello-world.txt est le fichier local que la pièce jointe contiendra en tant que données.

  • application/vnd.me.hi définit le mediaType du calque.

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

Gérer les pièces jointes avec les règles de nettoyage

Les pièces jointes des dépôts Docker, y compris la provenance des compilations, sont supprimées lorsque les artefacts auxquels elles sont associées sont supprimés. Si vous utilisez des règles de nettoyage pour supprimer des images de votre dépôt, les pièces jointes de ces images seront également supprimées par défaut.

Pour vous assurer que les pièces jointes que vous souhaitez conserver ne sont pas supprimées accidentellement par une règle de nettoyage, vous pouvez attribuer un tag à une image comportant des pièces jointes que vous souhaitez conserver. Vous pouvez ensuite configurer une règle de nettoyage pour conserver les images avec ces tags. Par exemple, vous pouvez attribuer un tag production-signed aux images avec provenance de compilation associée.

Étapes suivantes