Gérer les artefacts OCI et les artefacts de chaîne d’approvisionnement avec ORAS
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 :
- Envoyer (push) et extraire (pull) des artefacts OCI avec ORAS
- Attacher, envoyer et extraire des artefacts de chaîne d’approvisionnement avec ORAS
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.1ou 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.0ou 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 buildpour générer à distance dans Azure.
Bien que Docker Desktop ne soit pas obligatoire, l’interface CLIorasutilise 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é pouroras login.
Configurer le registre
Pour configurer votre environnement pour faciliter l’exécution des commandes, procédez comme suit :
- Définissez la variable
ACR_NAMEsur le nom de votre registre. - Définissez la variable
REGISTRYsur$ACR_NAME.azurecr.io. - Définissez la variable
REPOsur le nom de votre référentiel. - Définissez la variable
TAGsur la balise souhaitée. - Définissez la variable
IMAGEsur$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
Se connecter à un registre
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
Se connecter avec ORAS
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/exampledifférencie l’artefact d’une image conteneur, qui utiliseapplication/vnd.oci.image.config.v1+json. ./readme.mdidentifie le fichier chargé et:application/markdownreprésente lemediaTypeIANA 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
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.
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.
Commentaires
Bientôt disponible : Tout au long de l’année 2024, nous abandonnerons progressivement le mécanisme de retour d’information GitHub Issues pour le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez : https://aka.ms/ContentUserFeedback.
Soumettre et afficher des commentaires pour