Teilen über

Verwalten von OCI-Artefakten und Lieferkettenartefakten mit ORAS

  • Artikel

Azure Container Registry (ACR) unterstützt Sie beim Verwalten von OCI-Artefakten (Open Container Initiative) und Lieferkettenartefakten. In diesem Artikel erfahren Sie, wie Sie ACR zum effektiven Verwalten von OCI-Artefakten und Lieferkettenartefakten verwenden. Sie erfahren, wie Sie OCI-Artefakte und einen Graph von Lieferkettenartefakten speichern, verwalten und abrufen, einschließlich Signaturen, Softwarestücklisten (SBOM), Sicherheitsscanergebnissen und weiterer Typen.

Dieser Artikel ist in zwei Hauptabschnitte unterteilt:

Voraussetzungen

  • Azure-Containerregistrierung: Erstellen Sie in Ihrem Azure-Abonnement eine Containerregistrierung. Verwenden Sie beispielsweise das Azure-Portal oder die Azure CLI.
  • 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 v1.1.0 oder höher ist erforderlich. Siehe Installation von ORAS
  • Docker (optional): Um die exemplarische Vorgehensweise abzuschließen, wird auf ein Containerimage verwiesen. Sie können eine lokal installierte Docker-Instanz zum Erstellen und Pushen eines Containerimages oder acr build für die Remoteerstellung in Azure verwenden.
    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 die Ausführung für oras login erfolgen.

Konfigurieren der Registrierung

Führen Sie die folgenden Schritte aus, um Ihre Umgebung für die einfache Ausführung von Befehlen zu konfigurieren:

  1. Legen Sie die Variable ACR_NAME auf den Namen Ihrer Registrierung fest.
  2. Legen Sie die Variable REGISTRY auf $ACR_NAME.azurecr.io fest.
  3. Legen Sie die Variable REPO auf den Namen Ihres Repositorys fest.
  4. Legen Sie die Variable TAG auf das von Ihnen gewünschte Tag fest.
  5. Legen Sie die Variable IMAGE auf $REGISTRY/${REPO}:$TAG fest.

Festlegen von Umgebungsvariablen

Konfigurieren Sie einen Registrierungsnamen, Anmeldeinformationen, einen Repositorynamen und ein Tag zum Pushen und Pullen von Artefakten. Im folgenden Beispiel wird der Name des net-monitor-Repositorys und das v1-Tag verwendet. Ersetzen Sie diese durch den Namen Ihres eigenen Repositorys und Ihr eigenes Tag.

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

Anmelden bei einer Registrierung

Authentifizieren Sie sich bei ACR, damit Sie Containerimages pullen und pushen können.

az login  
az acr login -n $REGISTRY

Wenn Docker nicht verfügbar ist, können Sie das für die Authentifizierung bereitgestellte AD-Token verwenden. 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

Anmelden mit ORAS

Geben Sie die Anmeldeinformationen für oras login an.

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

Mit diesem Setup können Sie Artefakte nahtlos in Ihre Azure Container Registry-Instanz pushen und diese aus ihr pullen. Passen Sie die Variablen je nach Bedarf an Ihre spezifische Konfiguration an.

Pushen und Pullen von OCI-Artefakten mit ORAS

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 Abschnitt gezeigt, wie Sie die CLI von OCI Registry as Storage (ORAS) zum Pushen und Pullen eines Graphs von Artefakten in bzw. aus einer Azure Container Registry-Instanz verwenden. In einer Azure-Containerregistrierung können verschiedene OCI-Artefakte mithilfe verschiedener, für das jeweilige Artefakt geeigneter Befehlszeilentools verwaltet werden.

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 Container Registry-Instanz.

Pushen eines Artefakts

Ein einzelnes Dateiartefakt ohne übergeordnetes subject-Element kann unter anderem ein Containerimage, ein Helm-Charts oder eine Infodatei für das Repository darstellen. Verweisartefakte können unter anderem eine Signatur, eine Softwarestückliste, Überprüfungsberichte oder weitere sich entwickelnde Typen darstellen. Verweisartefakte, die unter Anfügen, Pushen und Pullen von Lieferkettenartefakten beschrieben werden, sind Artefakte, die auf ein anderes Artefakt verweisen.

Pushen eines Einzeldateiartefaktes

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:e2d60d1b171f08bd10e2ed171d56092e39c7bac1

aec5d9dcf7748dd702682d53

Pushen eines Multidateiartefaktes

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 sieht in etwa wie folgt aus:

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

Erstellen Sie ein leeres Verzeichnis für das 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

Anfügen, Pushen und Pullen von Lieferkettenartefakten mit ORAS

Zur Veranschaulichung dieser Funktion wird in diesem Artikel gezeigt, wie Sie die CLI von OCI Registry as Storage (ORAS) zum Ausführen von push-, discover- und pull-Vorgängen für einen Graph von Lieferkettenartefakten in eine Azure Container Registry-Instanz ausführen. Das Speichern einzelner OCI-Artefakte (subject-Artefakte) wird unter Pushen und Pullen von OCI-Artefakten behandelt.

Zum Speichern eines Graphs von Artefakten wird mithilfe des OCI-Imagemanifests ein Verweis auf ein subject-Artefakt definiert, das Teil der Vorabversion der Spezifikation für die OCI 1.1-Distribution ist.

Pushen eines Containerimages

So ordnen Sie mithilfe der Azure CLI einen Graph von Artefakten einem Containerimage zu:

Sie können ein Containerimage erstellen oder pushen, oder überspringen Sie diesen Schritt, wenn $IMAGE auf ein vorhandenes Image in der Registrierung verweist.

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

Anfügen einer Signatur

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

Anfügen einer Signatur in die Registrierung (als Verweis auf das Containerimage)

Der Befehl oras attach erstellt einen Verweis zwischen der Datei (./signature.json) und $IMAGE. --artifact-type dient der Unterscheidung von Artefakten, ähnlich wie Dateierweiterungen, die unterschiedliche Dateitypen ermöglichen. Durch Angabe von [file]:[mediaType] können eine oder mehrere Dateien angefügt werden.

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

Weitere Informationen zum Anfügen eines ORAS-Befehls finden Sie in der ORAS-Dokumentation.

Anfügen eines Artefakts mit mehreren Dateien als Referenz

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.

Ermitteln von Artefaktverweisen

In der OCI v1.1-Spezifikation ist eine Verweis-API zum Ermitteln von Verweisen auf ein Artefakt vom Typ subject definiert. Der Befehl oras discover kann die Liste der Verweise auf das Containerimage zeigen.

Zeigen Sie mit oras discover den Graphen der jetzt in der Registrierung gespeicherten Artefakte an.

oras discover -o tree $IMAGE

Die Ausgabe zeigt den Beginn eines Graphen von Artefakten, in dem Signatur und Dokumente als untergeordnete Elemente des Containerimages angezeigt werden.

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

Erstellen von Artefaktgraphen

Die OCI v1.1-Spezifikation ermöglicht tiefe Graphen, sodass signierte Softwarestücklisten (Software Bill of Materials, SBoM) und andere Artefakttypen aktiviert werden.

So erstellen Sie eine SBOM und fügen diese an die Registrierung an:

Erstellen einer Beispiel-SBoM

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

Anfügen einer Beispiel-SBoM an das Image in der Registrierung

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

Signieren der SBoM

Wichtig

Microsoft empfiehlt die Verwendung eines sicheren Kryptosignierungstools wie Notation, um das Image zu signieren und eine Signatur für das Signieren von SBOMs zu generieren.

Artefakte, die als Verweise gepusht werden, verfügen in der Regel nicht über Tags, da sie als Teil des Artefakts subject betrachtet werden. Um eine Signatur in ein Artefakt zu übertragen, das ein untergeordnetes Element eines anderen Artefakts ist, filtern Sie mit oras discover und --artifact-type, um den Digest zu finden. In diesem Beispiel wird zu Demonstrationszwecken eine einfache JSON-Signatur verwendet.

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

Erstellen Sie die Signatur einer SBOM.

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

Anfügen der SBoM-Signatur

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

Anzeigen des Graphen

oras discover -o tree $IMAGE

Generiert folgende Ausgabe:

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

Höherstufen des Artefaktgraphs

Ein typischer DevOps-Workflow stuft Artefakte von der Entwicklungs- über die Staging- bis zur Produktionsumgebung höher. Sichere Lieferkettenworkflows stufen öffentliche Inhalte in privat gesicherte Umgebungen höher. In beiden Fällen sollten Sie die Signaturen, SBOMs, Überprüfungsergebnisse und weitere zugehörige Artefakte mit dem subject-Artefakt höher stufen, um einen vollständigen Graph von Abhängigkeiten zu erhalten.

Mit dem Befehl oras copy können Sie einen gefilterten Graphen von Artefakten registrierungsübergreifend höher stufen.

Kopieren Sie das net-monitor:v1-Image und die zugehörigen Artefakte in sample-staging/net-monitor:v1:

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

Die Ausgabe von 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

Ermitteln des höhergestuften Artefaktgraphen

oras discover -o tree $TARGET_REPO:$TAG

Ausgabe von 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

Pullen referenzierter Artefakte

Um ein bestimmtes Artefakt, auf das verwiesen wird, zu pullen, wird der Digest des Verweises mit dem Befehl oras discover ermittelt:

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

Erstellen eines bereinigten Verzeichnisses zum Herunterladen

mkdir ./download

Pullen der Dokumentation in das Downloadverzeichnis

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

Anzeigen der Dokumentation

tree ./download

Die Ausgabe von tree:

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

Anzeigen des Repositorys und der Tagauflistung

ORAS ermöglicht das Pushen, Entdecken, Pullen und Kopieren von Artefaktgraphen, ohne Tags zuweisen zu müssen. Außerdem kann sich eine Tagauflistung mit ORAS auf die Artefakte konzentrieren, die die Benutzer interessieren, im Gegensatz zu den Signaturen und SBOMs, die Containerimages, Helm-Charts und weiteren Artefakten zugeordnet sind.

Anzeigen einer Liste mit Tags

oras repo tags $REGISTRY/$REPO

Löschen aller Artefakte im Graph

Die Unterstützung der OCI-Spezifikation Version 1.1 ermöglicht das Löschen des Graphs der Artefakte, die dem subject-Artefakt zugeordnet sind. Verwenden Sie den Befehl oras manifest delete, um den Graph von Artefakten (Signatur, SBOM und Signatur der SBOM) zu löschen.

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

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

Sie können die Liste der Manifeste anzeigen, um das Löschen des subject-Artefakts und aller zugehörigen Artefakte zu bestätigen. Dadurch bleibt eine bereinigte Umgebung zurück.

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

Ausgabe:

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

Zusammenfassung

In diesem Artikel haben Sie erfahren, wie Sie Azure Container Registry zum Speichern, Verwalten und Abrufen von OCI-Artefakten und Lieferkettenartefakten verwenden. Sie haben die ORAS-CLI verwendet, um Artefakte in eine Azure Container Registry-Instanz zu pushen und diese aus ihr zu pullen. Sie haben sich zudem mit dem Manifest der gepushten Artefakte auseinandergesetzt und den Graph der Artefakte angezeigt, die an das Containerimage angefügt sind.

Nächste Schritte

  • Hier erfahren Sie mehr über Artefaktverweise, das Zuordnen von Signaturen, Softwarestücklisten und weitere Verweistypen.
  • Hier erfahren Sie mehr über das ORAS-Projekt, einschließlich der Konfiguration des Manifests für ein Artefakt.
  • Referenzinformationen zu neuen Artefakttypen finden Sie im Repository OCI Artifacts (OCI-Artefakte).