Envoyer (push) et tirer (pull) des artefacts de chaîne d’approvisionnement avec un registre Azure (préversion)

Article
10/31/2023

Utilisez un registre de conteneurs Azure pour stocker et gérer un graphe d’artefacts de la chaîne logistique, notamment les signatures, les nomenclatures logicielles (SBOM), les résultats de l’analyse de sécurité et d’autres types.

Graph of artifacts, including a container image, signature and signed software bill of materials

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 logistique à un registre de conteneurs Azure, le découvrir (discover) et le tirer (pull). Le stockage des artefacts OCI individuels (racine) est abordé dans Envoyer (push) et tirer (pull) des artefacts OCI.

Pour stocker un graphique d’artefacts, une référence à un artefact subject est définie selon la spécification OCI Artifact Manifest, qui fait partie de la spécification de la distribution OCI 1.1 en préversion. La prise en charge d’OCI 1.1 Artifact Manifest est une fonctionnalité d’évaluation d’ACR et est sujette à des limitations.

Prérequis

Azure Container Registry : créez un Registre de conteneur dans votre abonnement Azure. Par exemple, utilisez le portail Azure ou Azure CLI.
Consultez les limitations de la préversion pour la prise en charge du cloud Azure.
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.
ORAS CLI : la version v0.16.0 est exigée. 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.

Limitations de la version préliminaire

La prise en charge d’OCI Artifact Manifest (spécification OCI 1.1) est disponible dans toutes les régions publiques d’Azure. Microsoft Azure exploité par 21Vianet et les clouds gouvernementaux ne sont pas encore pris en charge.

Configurer un registre

Configurez les variables d’environnement pour copier-coller facilement des commandes dans votre interpréteur de commandes. Les commandes peuvent être exécutées localement ou dans Azure Cloud Shell.

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

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

# Login to ACR, using a token based on your Azure identity
USER_NAME="00000000-0000-0000-0000-000000000000"
PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)

Notes

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.

Fournissez les informations d’identification à oras login.

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

Envoi (push) d’une image conteneur

Cet exemple associe un graphe d’artefacts à une image conteneur.

Générez et envoyez une image conteneur ou ignorez 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

Création d’un exemple de signature pour l’image conteneur

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.

Créez une documentation autour d’un artefact :

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

Attachez l’artefact multi-fichier comme référence à $IMAGE :

Linux, WSL2 ou macOS

oras attach $IMAGE \
    --artifact-type readme/example \
    ./readme.md:application/markdown \
    ./details

Windows

.\oras.exe attach $IMAGE ^
    --artifact-type readme/example ^
    .\readme.md:application/markdown ^
    .\details

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 d’un graphe profond 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.

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

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é.

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

Créer une signature d’une 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

Promouvoir le graphe

Un flux de travail DevOps classique promeut les artefacts de l’environnement de développement vers l’environnement de production par le biais de l’environnement de préproduction. Les workflows sécurisés de la chaîne logistique promeuvent le contenu public vers des environnements privés sécurisés. Dans les deux cas, vous souhaiterez promouvoir les signatures, les SBOM, les résultats de l’analyse et d’autres artefacts associés avec l’artefact racine 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 ses 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

Tirage (pull) d’un artefact auquel il est fait référence

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

OCI Artifact Manifest permet d’envoyer, de découvrir, de tirer et de copier des graphes d’artefacts sans avoir à affecter de balises. Les manifestes d’artefacts permettent à une liste de balises de se concentrer sur les artefacts que les utilisateurs ont en tête, par opposition aux signatures et aux SBOM associées aux images conteneur, aux charts Helm et à d’autres artefacts.

Affichage d’une liste de balises

oras repo tags $REGISTRY/$REPO

Affichage d’une liste de manifestes

Un référentiel peut comporter une liste de manifestes, balisés ou non. À l’aide de l’interface CLI az acr manifest, affichez la liste complète des manifestes :

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

Notez que les manifestes d’image conteneur ont "tags", contrairement aux types référence ("mediaType": "application/vnd.oci.artifact.manifest.v1+json").

Dans la sortie, la signature n’est pas balisée, mais suivie comme référence oci.artifact.manifest à l’image conteneur :

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2023-01-10T17:58:28.4403142Z",
  "digest": "sha256:00da2c1c3ceea087b16e70c3f4e80dbce6f5b7625d6c8308ad095f7d3f6107b5",
  "imageSize": 80,
  "lastUpdateTime": "2023-01-10T17:58:28.4403142Z",
  "mediaType": "application/vnd.oci.artifact.manifest.v1+json"
}

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 racine. Utilisez la commande oras 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

Affichage des manifestes restants

En supprimant l’artefact racine, tous les artefacts associés sont également supprimés, laissant 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, un graphe d’artefacts de chaîne logistique est créé, découvert, promu et tiré, ce qui permet de gérer le cycle de vie des artefacts que vous créez et dont vous dépendez.

Étapes suivantes

En savoir plus sur l’interface CLI ORAS
En savoir plus sur OCI Artifact Manifest, et notamment comment envoyer (push), découvrir, tirer (pull) et copier un graphe d’artefacts de chaîne d’approvisionnement