Pushen und Pullen von OCI-Artefakten unter Verwendung einer Azure-Containerregistrierung

Artikel
10/31/2023

Sie können eine Azure-Containerregistrierung verwenden, um OCI-Artefakte (Open Container Initiative) sowie Docker- und OCI-Containerimages zu speichern und zu verwalten.

Zur Veranschaulichung dieser Funktion wird in diesem Artikel gezeigt, wie Sie die ORAS CLI (OCI Registry as Storage) verwenden, um ein Beispielartefakt (eine Textdatei) in eine Azure-Containerregistrierung zu pushen. Anschließend wird das Artefakt aus der Registrierung gepullt. In einer Azure-Containerregistrierung können verschiedene OCI-Artefakte mithilfe verschiedener, für das jeweilige Artefakt geeigneter Befehlszeilentools verwaltet werden.

Voraussetzungen

Azure-Containerregistrierung: Erstellen Sie in Ihrem Azure-Abonnement eine Containerregistrierung. Verwenden Sie beispielsweise das Azure-Portal oder az acr create.
Azure CLI: Version 2.29.1 oder höher ist erforderlich. Informationen zum Ausführen einer Installation oder eines Upgrades finden Sie unter Installieren der Azure CLI.
ORAS CLI: Version v0.16.0 ist erforderlich. Siehe Installation von ORAS.
Docker (optional): Docker Desktop ist zwar nicht erforderlich, doch die oras CLI nutzt den Anmeldeinformationsspeicher von Docker Desktop zum Speichern von Anmeldeinformationen. Wenn Docker Desktop installiert ist, muss es für oras login ausgeführt werden.

Konfigurieren einer Registrierung

Konfigurieren Sie Umgebungsvariablen, um Befehle einfach in Ihre Shell zu kopieren/einzufügen. Die Befehle können lokal oder in der Azure Cloud Shell ausgeführt werden.

ACR_NAME=myregistry
REGISTRY=$ACR_NAME.azurecr.io

Authentifizieren Sie sich mit Ihrer persönlichen Microsoft Entra-Identität mithilfe eines AD-Tokens. Verwenden Sie immer „000...“ als USER_NAME, da das Token anhand der Variablen PASSWORD analysiert wird.

# 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)

Hinweis

ACR und ORAS unterstützen mehrere Authentifizierungsoptionen für Benutzer und Systemautomatisierung. In diesem Artikel wird eine einzelne Identität mithilfe eines Azure-Tokens verwendet. Weitere Authentifizierungsoptionen finden Sie unter Authentifizieren bei einer Azure-Containerregistrierung.

Geben Sie die Anmeldeinformationen für oras login an.

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

Pushen eines Stammartefakts

Ein Stammartefakt ist ein Artefakt ohne übergeordnetes subject-Element. Stammartefakte können alles zwischen einem Containerimage, einem Helm-Diagramm und einer Infodatei für das Repository sein. Verweisartefakte, die unter Anfügen, Pushen und Pullen von Lieferkettenartefakten beschrieben werden, sind Artefakte, die auf ein anderes Artefakt verweisen. Verweisartefakte können alles zwischen einer Signatur, einer Software-Stückliste, einem Überprüfungsbericht oder anderen sich entwickelnden Typen sein.

Erstellen Sie für dieses Beispiel Inhalte, die eine Markdowndatei darstellen:

echo 'Readme Content' > readme.md

Im folgenden Schritt wird die Datei readme.md in <myregistry>.azurecr.io/samples/artifact:readme gepusht.

Die Registrierung wird mit dem vollqualifizierten Registrierungsnamen <myregistry>.azurecr.io (alles Kleinbuchstaben) identifiziert, gefolgt vom Namespace und dem Repository: /samples/artifact.
Das Artefakt ist mit :readme gekennzeichnet, um es eindeutig von anderen Artefakten im Repository zu unterscheiden (:latest, :v1, :v1.0.1).
Die Einstellung --artifact-type readme/example unterscheidet das Artefakt von einem Containerimage, das application/vnd.oci.image.config.v1+json verwendet.
./readme.md identifiziert die hochgeladene Datei, und :application/markdown stellt den IANA-mediaType der Datei dar.
Weitere Informationen finden Sie unter Leitfaden für OCI-Artefaktautoren.

Verwenden Sie den Befehl oras push, um die Datei in Ihre Registrierung zu pushen.

Linux, WSL2 oder 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

Die Ausgabe für einen erfolgreichen Pushvorgang sieht in etwa wie folgt aus:

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

Pushen eines Stammartefakts mit mehreren Dateien

Wenn OCI-Artefakte mit ORAS in eine Registrierung gepusht werden, wird jede referenzierte Datei als Blob gepusht. Um separate Blobs zu pushen, verweisen Sie einzeln auf die Dateien oder auf eine Sammlung von Dateien, indem Sie auf ein Verzeichnis verweisen.
Weitere Informationen zum Pushen einer Sammlung von Dateien finden Sie unter Pushen von Artefakten mit mehreren Dateien.

Erstellen Sie eine Dokumentation für das Repository:

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

Pushen des Artefakts mit mehreren Dateien:

Linux, WSL2 oder 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

Ermitteln des Manifests

Zum Anzeigen des Manifests, das als Ergebnis von oras push erstellt wurde, verwenden Sie oras manifest fetch:

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

Die Ausgabe ähnelt der folgenden:

{
  "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"
  }
}

Pullen eines Stammartefakts

Erstellen eines bereinigten Verzeichnisses zum Herunterladen

mkdir ./download

Führen Sie den Befehl oras pull aus, um das Artefakt aus Ihrer Registrierung abzurufen.

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

Anzeigen der gepullten Dateien

tree ./download

Entfernen des Artefakts (optional)

Um das Artefakt aus Ihrer Registrierung zu entfernen, verwenden Sie den Befehl oras manifest delete.

 oras manifest delete $REGISTRY/samples/artifact:readme

Nächste Schritte

Erfahren Sie mehr über Artefaktverweise, das Zuordnen von Signaturen, Software-Stücklisten und andere Verweistypen.
Erfahren Sie mehr über das ORAS-Projekt, und wie Sie ein Manifest für ein Artefakt konfigurieren.
Besuchen Sie das Repository OCI Artifacts (OCI-Artefakte), und machen Sie sich mit Referenzinformationen zu neuen Artefakttypen vertraut.