Gérer les artefacts OCI et les artefacts de chaîne d’approvisionnement avec ORAS

Article
10/16/2024

Azure Container Registry (ACR) vous aide à gérer les artefacts OCI (Open Container Initiative) et les artefacts de chaîne d’approvisionnement. Cet article explique comment utiliser ACR pour gérer efficacement les artefacts OCI et les artefacts de chaîne d’approvisionnement. Découvrez comment stocker, gérer et récupérer les artefacts OCI et un graphe d’artefacts de la chaîne d’approvisionnement, notamment les signatures, les nomenclatures logicielles (SBOM), les résultats de l’analyse de sécurité et d’autres types.

Cet article est divisé en deux parties principales :

Prérequis

Azure Container Registry : créez un Registre de conteneur dans votre abonnement Azure. Par exemple, utilisez le portail Azure ou Azure CLI.
Azure CLI : la version 2.29.1 ou ultérieure est exigée. Pour obtenir des informations sur l’installation et/ou la mise à niveau, consultez Installer Azure CLI.
Interface CLI ORAS : la version v1.1.0 ou ultérieure est requise. Consultez Installation d’ORAS.
Docker (facultatif) : pour suivre la procédure pas à pas, une image conteneur est référencée. Vous pouvez utiliser soit Docker installé localement pour générer et envoyer (push) une image conteneur, soit acr build pour générer à distance dans Azure.
Bien que Docker Desktop ne soit pas obligatoire, l’interface CLI oras utilise le magasin d’informations d’identification de Docker Desktop pour stocker les informations d’identification. Si Docker Desktop est installé, il doit être exécuté pour oras login.

Configurer le registre

Pour configurer votre environnement pour faciliter l’exécution des commandes, procédez comme suit :

Définissez la variable ACR_NAME sur le nom de votre registre.
Définissez la variable REGISTRY sur $ACR_NAME.azurecr.io.
Définissez la variable REPO sur le nom de votre référentiel.
Définissez la variable TAG sur la balise souhaitée.
Définissez la variable IMAGE sur $REGISTRY/${REPO}:$TAG.

Définir des variables d’environnement

Configurez un nom de registre, des informations d’identification de connexion, un nom de référentiel et une balise pour envoyer et extraire des artefacts. L’exemple suivant utilise le nom du référentiel net-monitor et la balise v1. Remplacez-les par le nom et la balise de votre propre référentiel.

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io
REPO=net-monitor
TAG=v1
IMAGE=$REGISTRY/${REPO}:$TAG

Authentifiez-vous auprès de l’ACR pour vous permettre d’extraire et d’envoyer (push) des images conteneur.

az login  
az acr login -n $REGISTRY

Si Docker n’est pas disponible, vous pouvez utiliser le jeton AD fourni pour l’authentification. Authentifiez-vous avec votre identité Microsoft Entra individuelle à l’aide d’un jeton AD. Utilisez toujours « 000... » pour USER_NAME car le jeton est analysé par le biais de la variable PASSWORD.

# Login to Azure
az login

Fournissez les informations d’identification à oras login.

oras login $REGISTRY \
    --username $USER_NAME \
    --password $PASSWORD

Cette configuration vous permet d’envoyer et d’extraire en toute transparence des artefacts vers et à partir de votre Azure Container Registry. Ajustez les variables selon les besoins de votre configuration spécifique.

Envoyer (push) et extraire (pull) des artefacts OCI avec ORAS

Vous pouvez utiliser un registre de conteneurs Azure pour stocker et gérer des artefacts OCI (Open Container Initiative) ainsi que des images conteneur Docker et OCI.

Afin d’illustrer cette fonctionnalité, cette section montre comment utiliser l’interface CLI ORAS (OCI Registry as Storage) pour envoyer (push) et extraire (pull) des artefacts OCI vers et depuis un registre de conteneurs Azure. Vous pouvez gérer divers artefacts OCI dans un registre de conteneurs Azure à l’aide de différents outils en ligne de commande adaptés à chaque artefact.

Remarque

ACR et ORAS prennent en charge plusieurs options d’authentification pour les utilisateurs et l’automatisation du système. Cet article utilise une identité individuelle à l’aide d’un jeton Azure. Pour plus d’options d’authentification, consultez S’authentifier auprès d’un registre de conteneurs Azure.

Envoyer (push) un artefact

Un artefact à fichier unique qui n’a aucun parent subject peut être une image conteneur, un graphique Helm ou un fichier lisez-moi pour le référentiel. Les artefacts de référence peuvent être une signature, une nomenclature logicielle, des rapports d’analyse ou d’autres types évolutifs. Les artefacts de référence, décrits dans Attacher, envoyer et tirer des artefacts de chaîne logistique, sont des artefacts qui font référence à un autre artefact.

Envoyer (push) un artefact à fichier unique

Pour cet exemple, créez un contenu représentant un fichier Markdown :

echo 'Readme Content' > readme.md

L’étape suivante envoie le fichier readme.md à <myregistry>.azurecr.io/samples/artifact:readme.

Le registre est identifié par le nom de registre complet <myregistry>.azurecr.io (tout en minuscules), suivi de l’espace de noms et du référentiel : /samples/artifact.
L’artefact est étiqueté :readme, ce qui l’identifie de manière unique parmi les autres artefacts listés dans le référentiel (:latest, :v1, :v1.0.1).
Le paramètre --artifact-type readme/example différencie l’artefact d’une image conteneur, qui utilise application/vnd.oci.image.config.v1+json.
./readme.md identifie le fichier chargé et :application/markdown représente le mediaType IANA du fichier.
Pour plus d’informations, consultez Conseils pour les auteurs d’artefacts OCI.

Utilisez la commande oras push pour envoyer le fichier à votre registre.

Linux, WSL2 ou macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example \
    ./readme.md:application/markdown

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown

La sortie d’un envoi réussi ressemble à ce qui suit :

Uploading 2fdeac43552b readme.md
Uploaded  2fdeac43552b readme.md
Pushed <myregistry>.azurecr.io/samples/artifact:readme
Digest: sha256:e2d60d1b171f08bd10e2ed171d56092e39c7bac1

aec5d9dcf7748dd702682d53

Envoyer (push) un artefact multifichier

Quand des artefacts OCI sont envoyés à un registre avec ORAS, chaque référence de fichier est envoyée en tant qu’objet blob. Pour envoyer des objets blob distincts, référencez les fichiers individuellement ou un répertoire contenant une collection de fichiers.
Pour plus d’informations sur la façon d’envoyer une collection de fichiers, consultez Envoyer des artefacts avec plusieurs fichiers.

Créez une documentation pour le référentiel :

echo 'Readme Content' > readme.md
mkdir details/
echo 'Detailed Content' > details/readme-details.md
echo 'More detailed Content' > details/readme-more-details.md

Envoyez l’artefact multifichier :

Linux, WSL2 ou macOS

oras push $REGISTRY/samples/artifact:readme \
    --artifact-type readme/example\
    ./readme.md:application/markdown\
    ./details

Windows

.\oras.exe push $REGISTRY/samples/artifact:readme ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

Découvrir le manifeste

Pour afficher le manifeste créé à la suite de oras push, utilisez oras manifest fetch :

oras manifest fetch --pretty $REGISTRY/samples/artifact:readme

Le résultat ressemble à ce qui suit :

{
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json",
  "artifactType": "readme/example",
  "blobs": [
    {
      "mediaType": "application/markdown",
      "digest": "sha256:2fdeac43552b71eb9db534137714c7bad86b53a93c56ca96d4850c9b41b777fc",
      "size": 15,
      "annotations": {
        "org.opencontainers.image.title": "readme.md"
      }
    },
    {
      "mediaType": "application/vnd.oci.image.layer.v1.tar+gzip",
      "digest": "sha256:0d6c7434a34f6854f971487621426332e6c0fda08040b9e6cc8a93f354cee0b1",
      "size": 189,
      "annotations": {
        "io.deis.oras.content.digest": "sha256:11eceb2e7ac3183ec9109003a7389468ec73ad5ceaec0c4edad0c1b664c5593a",
        "io.deis.oras.content.unpack": "true",
        "org.opencontainers.image.title": "details"
      }
    }
  ],
  "annotations": {
    "org.opencontainers.artifact.created": "2023-01-10T14:44:06Z"
  }
}

Tirer (pull) un artefact

Créez un répertoire propre pour le téléchargement.

mkdir ./download

Exécutez la commande oras pull pour tirer (pull) l’artefact de votre registre.

oras pull -o ./download $REGISTRY/samples/artifact:readme

Afficher les fichiers tirés

tree ./download

Supprimer l’artefact (facultatif)

Pour supprimer l’artefact de votre registre, utilisez la commande oras manifest delete.

 oras manifest delete $REGISTRY/samples/artifact:readme

Attacher, envoyer et extraire des artefacts de chaîne d’approvisionnement avec ORAS

Afin d’illustrer cette fonctionnalité, cet article montre comment utiliser l’interface CLI ORAS (OCI Registry as Storage) pour envoyer (push) un graphe d’artefacts de chaîne d’approvisionnement à un registre de conteneurs Azure, le découvrir (discover) et l’extraire (pull). Le stockage des artefacts OCI individuels (objet) est abordé dans Envoyer (push) et extraire (pull) des artefacts OCI.

Pour stocker un graphe d’artefacts, une référence à un artefact subject est définie selon le manifeste d’image OCI, qui fait partie de la spécification de la distribution OCI 1.1 en préversion.

Envoi (push) d’une image conteneur

Pour associer un graphe d’artefacts à une image conteneur à l’aide d’Azure CLI :

Vous pouvez générer et envoyer une image conteneur ou ignorer cette étape si $IMAGE fait référence à une image existante dans le registre.

az acr build -r $ACR_NAME -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main

Joindre une signature

echo '{"artifact": "'${IMAGE}'", "signature": "jayden hancock"}' > signature.json

Attachement d’une signature au registre, comme référence à l’image conteneur

La commande oras attach crée une référence entre le fichier (./signature.json) et $IMAGE. --artifact-type fournit des artefacts de différenciation, comme des extensions de fichier qui permettent de créer différents types de fichiers. Il est possible d’attacher un ou plusieurs fichiers en spécifiant [file]:[mediaType].

oras attach $IMAGE \
    --artifact-type signature/example \
    ./signature.json:application/json

Pour plus d’informations sur l’attachement ORAS, consultez Documentation d’ORAS.

Attacher un artefact multi-fichier comme référence

Découverte des références aux artefacts

La spécification OCI v1.1 définit une API de référents pour la découverte des références à un subject artefact. La commande oras discover peut afficher la liste des références à l’image conteneur.

Utilisez oras discover pour afficher le graphe des artefacts maintenant stockés dans le registre.

oras discover -o tree $IMAGE

La sortie indique le début d’un graphe d’artefacts, dans lequel la signature et la documentation apparaissent comme les enfants de l’image conteneur.

myregistry.azurecr.io/net-monitor:v1
├── signature/example
│   └── sha256:555ea91f39e7fb30c06f3b7aa483663f067f2950dcb...
└── readme/example
    └── sha256:1a118663d1085e229ff1b2d4d89b5f6d67911f22e55...

Création de graphes d’artefacts

La spécification OCI v1.1 autorise les graphes profonds, ce qui donne accès à la nomenclature logicielle (SBOM) signée et à d’autres types d’artefacts.

Voici comment créer et attacher un SBOM au registre :

Créer un exemple de SBOM

echo '{"version": "0.0.0.0", "artifact": "'${IMAGE}'", "contents": "good"}' > sbom.json

Attacher un exemple de SBOM à l’image dans le registre

Linux, WSL2 ou macOS

oras attach $IMAGE \
  --artifact-type sbom/example \
  ./sbom.json:application/json

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type sbom/example ^
    ./sbom.json:application/json

Signer la SBOM

Important

Microsoft recommande d’utiliser un outil de signature de chiffrement sécurisé, comme Notation pour signer l’image et générer une signature pour la signature de SBOM.

Les artefacts envoyés comme références n’ont généralement pas de balises, car ils sont considérés comme faisant partie de l’artefact subject. Pour envoyer (push) une signature à un artefact enfant d’un autre artefact, utilisez oras discover avec filtrage --artifact-type permettant de rechercher le condensé. Cet exemple utilise une signature JSON simple à des fins de démonstration.

SBOM_DIGEST=$(oras discover -o json \
                --artifact-type sbom/example \
                $IMAGE | jq -r ".manifests[0].digest")

Créez une signature d’un SBOM.

echo '{"artifact": "'$IMAGE@$SBOM_DIGEST'", "signature": "jayden hancock"}' > sbom-signature.json

Attacher la signature de la SBOM

oras attach $IMAGE@$SBOM_DIGEST \
  --artifact-type 'signature/example' \
  ./sbom-signature.json:application/json

Affichage du graphe

oras discover -o tree $IMAGE

Voici la sortie générée :

myregistry.azurecr.io/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

Promotion du graphe d’artefacts

Un workflow DevOps classique promeut les artefacts du développement à la préproduction et à l’environnement de production. Les workflows de chaîne d’approvisionnement sécurisés promeuvent le contenu public auprès des environnements sécurisés en privé. Dans les deux cas, vous souhaitez promouvoir les signatures, les SBOM, les résultats de l’analyse et d’autres artefacts associés avec l’artefact objet pour obtenir un graphe complet des dépendances.

À l’aide de la commande oras copy, vous pouvez promouvoir un graphe filtré d’artefacts sur plusieurs registres.

Copiez l’image net-monitor:v1 et les artefacts associés dans sample-staging/net-monitor:v1 :

TARGET_REPO=$REGISTRY/sample-staging/$REPO
oras copy -r $IMAGE $TARGET_REPO:$TAG

Sortie de oras copy :

Copying 6bdea3cdc730 sbom-signature.json
Copying 78e159e81c6b sbom.json
Copied  6bdea3cdc730 sbom-signature.json
Copied  78e159e81c6b sbom.json
Copying 7cf1385c7f4d signature.json
Copied  7cf1385c7f4d signature.json
Copying 3e797ecd0697 details
Copying 2fdeac43552b readme.md
Copied  3e797ecd0697 details
Copied  2fdeac43552b readme.md
Copied demo42.myregistry.io/net-monitor:v1 => myregistry.azurecr.io/sample-staging/net-monitor:v1
Digest: sha256:ff858b2ea3cdf4373cba65d2ca6bcede4da1d620503a547cab5916614080c763

Découvrir le graphe d’artefacts promu

oras discover -o tree $TARGET_REPO:$TAG

Sortie de oras discover :

myregistry.azurecr.io/sample-staging/net-monitor:v1
├── sbom/example
│   └── sha256:4f1843833c029ecf0524bc214a0df9a5787409fd27bed2160d83f8cc39fedef5
│       └── signature/example
│           └── sha256:3c43b8cb0c941ec165c9f33f197d7f75980a292400d340f1a51c6b325764aa93
├── readme/example
│   └── sha256:5fafd40589e2c980e2864a78818bff51ee641119cf96ebb0d5be83f42aa215af
└── signature/example
    └── sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5

Extraction d’artefacts référencés

Pour tirer un artefact référencé spécifique, la synthèse de la référence est découverte avec la commande oras discover :

DOC_DIGEST=$(oras discover -o json \
              --artifact-type 'readme/example' \
              $TARGET_REPO:$TAG | jq -r ".manifests[0].digest")

Création d’un répertoire propre pour le téléchargement

mkdir ./download

Tirage (pull) des documents dans le répertoire de téléchargement

oras pull -o ./download $TARGET_REPO@$DOC_DIGEST

Affichage des documents

tree ./download

Sortie de tree :

./download
├── details
│   ├── readme-details.md
│   └── readme-more-details.md
└── readme.md

Affichage du référentiel et de la liste des balises

ORAS permet d’envoyer (push), de découvrir, d’extraire (pull) et de copier des graphes d’artefacts sans avoir à assigner des balises. La liste de balises peut ainsi se concentrer sur les artefacts que les utilisateurs ont en tête, par opposition aux signatures et aux nomenclatures logicielles associées aux images conteneur, aux graphiques Helm et à d’autres artefacts.

Affichage d’une liste de balises

oras repo tags $REGISTRY/$REPO

Suppression de tous les artefacts du graphe

La prise en charge de la spécification OCI v1.1 permet de supprimer le graphe d’artefacts associé à l’artefact objet. Utilisez la commande oras manifest delete pour supprimer le graphe d’artefacts (signature, SBOM et signature de la SBOM).

oras manifest delete -f $REGISTRY/$REPO:$TAG

oras manifest delete -f $REGISTRY/sample-staging/$REPO:$TAG

Vous pouvez afficher la liste des manifestes pour confirmer la suppression de l’artefact objet et tous les artefacts associés, ce qui laisse un environnement propre.

az acr manifest list-metadata \
  --name $REPO \
  --registry $ACR_NAME -o jsonc

Sortie :

2023-01-10 18:38:45.366387 Error: repository "net-monitor" is not found.

Résumé

Dans cet article, vous avez appris à utiliser Azure Container Registry pour stocker, gérer et récupérer des artefacts OCI et des artefacts de chaîne d’approvisionnement. Vous avez utilisé l’interface CLI ORAS pour envoyer (push) et extraire (pull) des artefacts vers/depuis Azure Container Registry. Vous avez également découvert le manifeste des artefacts envoyés (push) et consulté le graphe des artefacts attachés à l’image conteneur.

Étapes suivantes

En savoir plus sur les références d’artefacts, l’association de signatures, la nomenclature logicielle et les autres types de références.
En savoir plus sur le projet ORAS, notamment la configuration d’un manifeste pour un artefact.
Consultez le référentiel Artefacts OCI pour obtenir des informations de référence sur les nouveaux types d’artefacts.

Partager via

Gérer les artefacts OCI et les artefacts de chaîne d’approvisionnement avec ORAS

Prérequis

Configurer le registre

Définir des variables d’environnement

Envoyer (push) et extraire (pull) des artefacts OCI avec ORAS

Envoyer (push) un artefact

Envoyer (push) un artefact à fichier unique

Envoyer (push) un artefact multifichier

Découvrir le manifeste

Tirer (pull) un artefact

Afficher les fichiers tirés

Supprimer l’artefact (facultatif)

Attacher, envoyer et extraire des artefacts de chaîne d’approvisionnement avec ORAS

Envoi (push) d’une image conteneur

Joindre une signature

Attachement d’une signature au registre, comme référence à l’image conteneur

Attacher un artefact multi-fichier comme référence

Découverte des références aux artefacts

Création de graphes d’artefacts

Créer un exemple de SBOM

Attacher un exemple de SBOM à l’image dans le registre

Signer la SBOM

Attacher la signature de la SBOM

Affichage du graphe

Promotion du graphe d’artefacts

Découvrir le graphe d’artefacts promu

Extraction d’artefacts référencés

Création d’un répertoire propre pour le téléchargement

Tirage (pull) des documents dans le répertoire de téléchargement

Affichage des documents

Affichage du référentiel et de la liste des balises

Affichage d’une liste de balises

Suppression de tous les artefacts du graphe

Résumé

Étapes suivantes

Commentaires

Ressources supplémentaires

Partager via

Gérer les artefacts OCI et les artefacts de chaîne d’approvisionnement avec ORAS

Prérequis

Configurer le registre

Définir des variables d’environnement

Se connecter à un registre

Se connecter avec ORAS

Envoyer (push) et extraire (pull) des artefacts OCI avec ORAS

Envoyer (push) un artefact

Envoyer (push) un artefact à fichier unique

Envoyer (push) un artefact multifichier

Découvrir le manifeste

Tirer (pull) un artefact

Afficher les fichiers tirés

Supprimer l’artefact (facultatif)

Attacher, envoyer et extraire des artefacts de chaîne d’approvisionnement avec ORAS

Envoi (push) d’une image conteneur

Joindre une signature

Attachement d’une signature au registre, comme référence à l’image conteneur

Attacher un artefact multi-fichier comme référence

Découverte des références aux artefacts

Création de graphes d’artefacts

Créer un exemple de SBOM

Attacher un exemple de SBOM à l’image dans le registre

Signer la SBOM

Attacher la signature de la SBOM

Affichage du graphe

Promotion du graphe d’artefacts

Découvrir le graphe d’artefacts promu

Extraction d’artefacts référencés

Création d’un répertoire propre pour le téléchargement

Tirage (pull) des documents dans le répertoire de téléchargement

Affichage des documents

Affichage du référentiel et de la liste des balises

Affichage d’une liste de balises

Suppression de tous les artefacts du graphe

Résumé

Étapes suivantes

Commentaires

Ressources supplémentaires