Hantera OCI-artefakter och leveranskedjeartefakter med ORAS

  • Artikel

Azure Container Registry (ACR) hjälper dig att hantera både OCI-artefakter (Open container initiative) och artefakter i leveranskedjan. Den här artikeln beskriver hur du använder ACR för att effektivt hantera OCI-artefakter och leveranskedjeartefakter. Lär dig att lagra, hantera och hämta både OCI-artefakter och ett diagram över artefakter i leveranskedjan, inklusive signaturer, programvarufaktura (SBOM), resultat av säkerhetsgenomsökning och andra typer.

Den här artikeln är uppdelad i två huvudavsnitt:

Förutsättningar

  • Azure-containerregister – Skapa ett containerregister i din Azure-prenumeration. Använd till exempel Azure Portal eller Azure CLI.
  • Azure CLI – Version 2.29.1 eller senare krävs. Se Installera Azure CLI för installation och/eller uppgradering.
  • ORAS CLI – Version v1.1.0 eller senare version krävs. Se: ORAS-installation.
  • Docker (valfritt) – För att slutföra genomgången refereras en containeravbildning. Du kan använda Docker installerat lokalt för att skapa och push-överföra en containeravbildning eller använda acr build för att fjärransluta i Azure.
    Docker Desktop krävs inte, oras men cli använder Docker Desktops autentiseringsarkiv för lagring av autentiseringsuppgifter. Om Docker Desktop är installerat måste det köras för oras login.

Konfigurera registret

Följ dessa steg för att konfigurera din miljö för enkel kommandokörning:

  1. Ange variabeln ACR_NAME till ditt registernamn.
  2. Ange variabeln REGISTRY till $ACR_NAME.azurecr.io.
  3. Ange variabeln REPO till namnet på lagringsplatsen.
  4. Ange variabeln TAG till önskad tagg.
  5. Ange variabeln IMAGE till $REGISTRY/${REPO}:$TAG.

Ange miljövariabler

Konfigurera ett registernamn, inloggningsuppgifter, ett lagringsplatsnamn och en tagg för att skicka och hämta artefakter. I följande exempel används lagringsplatsens net-monitor namn och v1 tagg. Ersätt med ditt eget namn och tagg för lagringsplatsen.

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

Logga in på ett register

Autentisera med ACR så att du kan hämta och push-överföra containeravbildningar.

az login  
az acr login -n $REGISTRY

Om Docker inte är tillgängligt kan du använda AD-token som tillhandahålls för autentisering. Autentisera med din enskilda Microsoft Entra-identitet med hjälp av en AD-token. Använd alltid "000..." för när USER_NAME token parsas genom variabeln PASSWORD .

# Login to Azure
az login

Logga in med ORAS

Ange autentiseringsuppgifterna till oras login.

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

Med den här konfigurationen kan du sömlöst skicka och hämta artefakter till och från Azure Container Registry. Justera variablerna efter behov för din specifika konfiguration.

Push- och pull-OCI-artefakter med ORAS

Du kan använda ett Azure-containerregister för att lagra och hantera OCI-artefakter (Open Container Initiative) samt Docker- och OCI-containeravbildningar .

För att demonstrera den här funktionen visar det här avsnittet hur du använder OCI Registry as Storage (ORAS) CLI för att push-överföra och hämta OCI-artefakter till/från ett Azure-containerregister. Du kan hantera olika OCI-artefakter i ett Azure-containerregister med hjälp av olika kommandoradsverktyg som är lämpliga för varje artefakt.

Kommentar

ACR och ORAS stöder flera autentiseringsalternativ för användare och systemautomatisering. Den här artikeln använder individuell identitet med hjälp av en Azure-token. Fler autentiseringsalternativ finns i Autentisera med ett Azure-containerregister.

Skicka en artefakt

En enskild filartefakt som inte har någon subject överordnad kan vara allt från en containeravbildning, ett helm-diagram, en readme-fil för lagringsplatsen. Referensartefakter kan vara allt från en signatur, programvarufakturering av material, genomsökningsrapporter eller andra typer som utvecklas. Referensartefakter som beskrivs i Bifoga, push- och pull-artefakter i leveranskedjan är artefakter som refererar till en annan artefakt.

Push-överför en artefakt med en fil

I det här exemplet skapar du innehåll som representerar en markdown-fil:

echo 'Readme Content' > readme.md

Följande steg skickar readme.md filen till <myregistry>.azurecr.io/samples/artifact:readme.

  • Registret identifieras med det fullständigt kvalificerade registernamnet <myregistry>.azurecr.io (alla gemener), följt av namnområdet och lagringsplatsen: /samples/artifact.
  • Artefakten har taggats :readme, för att identifiera den unikt från andra artefakter som anges i lagringsplatsen (:latest, :v1, :v1.0.1).
  • Inställningen --artifact-type readme/example skiljer artefakten från en containeravbildning, som använder application/vnd.oci.image.config.v1+json.
  • Identifierar ./readme.md den uppladdade filen och :application/markdown representerar filens IANA mediaType .
    Mer information finns i Vägledning för OCI-artefaktförfattare.

oras push Använd kommandot för att skicka filen till registret.

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

Utdata för en lyckad push liknar följande utdata:

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

aec5d9dcf7748dd702682d53

Skicka en artefakt med flera filer

När OCI-artefakter skickas till ett register med ORAS skickas varje filreferens som en blob. Om du vill skicka separata blobar refererar du till filerna individuellt eller en samling filer genom att referera till en katalog.
Mer information om hur du push-överför en samling filer finns i Push-överföra artefakter med flera filer.

Skapa dokumentation för lagringsplatsen:

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

Push-överför artefakten med flera filer:

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

Identifiera manifestet

Om du vill visa manifestet som skapats som ett resultat av oras pushanvänder du oras manifest fetch:

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

Utdatan liknar följande:

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

Hämta en artefakt

Skapa en ren katalog för nedladdning.

mkdir ./download

oras pull Kör kommandot för att hämta artefakten från registret.

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

Visa de hämtade filerna

tree ./download

Ta bort artefakten (valfritt)

Om du vill ta bort artefakten från registret använder du oras manifest delete kommandot .

 oras manifest delete $REGISTRY/samples/artifact:readme

Koppla, push-överföra och hämta leveranskedjeartefakter med ORAS

För att demonstrera den här funktionen visar den här artikeln hur du använder OCI Registry as Storage (ORAS) CLI till push, discoveroch pull ett diagram över leveranskedjeartefakter till ett Azure-containerregister. Lagring av enskilda (ämne) OCI-artefakter beskrivs i Push- och pull-OCI-artefakter.

Om du vill lagra ett diagram över artefakter definieras en referens till en subject artefakt med hjälp av OCI-bildmanifestet, som är en del av distributionsspecifikationen för förhandsversion OCI 1.1.

Skicka en containeravbildning

Så här associerar du ett diagram med artefakter med en containeravbildning med hjälp av Azure CLI:

Du kan skapa och push-överföra en containeravbildning eller hoppa över det här steget om $IMAGE det refererar till en befintlig avbildning i registret.

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

Koppla en signatur

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

Bifoga en signatur till registret som en referens till containeravbildningen

Kommandot oras attach skapar en referens mellan filen (./signature.json) till $IMAGE. Tillhandahåller --artifact-type för differentiering av artefakter, liknande filnamnstillägg som aktiverar olika filtyper. En eller flera filer kan bifogas genom att [file]:[mediaType]ange .

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

Mer information om oras attach finns i ORAS-dokumentationen.

Bifoga en artefakt med flera filer som referens

När OCI-artefakter skickas till ett register med ORAS skickas varje filreferens som en blob. Om du vill skicka separata blobar refererar du till filerna individuellt eller en samling filer genom att referera till en katalog.
Mer information om hur du push-överför en samling filer finns i Push-överföra artefakter med flera filer.

Identifiera artefaktreferenser

OCI v1.1-specifikationen definierar ett referens-API för identifiering av referenser till en subject artefakt. Kommandot oras discover kan visa listan med referenser till containeravbildningen.

Med hjälp oras discoverav visar du diagrammet över artefakter som nu lagras i registret.

oras discover -o tree $IMAGE

Utdata visar början av ett diagram med artefakter, där signaturen och dokumenten visas som underordnade i containeravbildningen.

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

Skapa diagram över artefakter

OCI v1.1-specifikationen möjliggör djupa grafer, vilket möjliggör signerad programvarufaktura (SBOM) och andra artefakttyper.

Så här skapar och kopplar du en SBOM till registret:

Skapa en exempel-SBOM

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

Koppla en exempel-SBOM till avbildningen i registret

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

Signera SBOM

Viktigt!

Microsoft rekommenderar att du använder ett säkert verktyg för krypteringssignering, till exempel Notation för att signera avbildningen och generera en signatur för signering av SBOM:er.

Artefakter som skickas som referenser har vanligtvis inte taggar eftersom de anses vara en del av subject artefakten. Om du vill skicka en signatur till en artefakt som är underordnad oras discover en annan artefakt använder du med --artifact-type filtrering för att hitta sammanfattningen. I det här exemplet används en enkel JSON-signatur i demonstrationssyfte.

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

Skapa en signatur för en SBOM.

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

Bifoga SBOM-signaturen

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

Visa diagrammet

oras discover -o tree $IMAGE

Genererar följande utdata:

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

Främja artefaktdiagrammet

Ett typiskt DevOps-arbetsflöde främjar artefakter från utveckling till mellanlagring till produktionsmiljön. Säkra arbetsflöden i leveranskedjan främjar offentligt innehåll till privat skyddade miljöer. I båda fallen vill du höja upp signaturer, SBOM:er, genomsökningsresultat och annan relaterad artefakt med ämnesartefakten för att ha en fullständig graf över beroenden.

Med hjälp av oras copy kommandot kan du höja upp ett filtrerat diagram över artefakter mellan register.

Kopiera bilden net-monitor:v1 och relaterade artefakter till sample-staging/net-monitor:v1:

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

Utdata från 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

Identifiera det upphöjda artefaktdiagrammet

oras discover -o tree $TARGET_REPO:$TAG

Utdata från 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

Hämta refererade artefakter

Om du vill hämta en specifik refererad artefakt identifieras referenssammandraget oras discover med kommandot :

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

Skapa en ren katalog för nedladdning

mkdir ./download

Hämta dokumenten till nedladdningskatalogen

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

Visa dokumenten

tree ./download

Utdata från tree:

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

Visa lagringsplatsen och tagglistan

ORAS gör det möjligt att push-överföra, identifiera, hämta och kopiera artefaktdiagram utan att behöva tilldela taggar. Det gör också att en tagglista kan fokusera på de artefakter som användarna tänker på, i motsats till de signaturer och SBOM:er som är associerade med containeravbildningar, helm-diagram och andra artefakter.

Visa en lista med taggar

oras repo tags $REGISTRY/$REPO

Ta bort alla artefakter i diagrammet

Stöd för OCI v1.1-specifikationen gör det möjligt att ta bort grafen över artefakter som är associerade med ämnesartefakten. oras manifest delete Använd kommandot för att ta bort grafen med artefakter (signatur, SBOM och signaturen för SBOM).

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

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

Du kan visa listan med manifest för att bekräfta borttagningen av ämnesartefakten och alla relaterade artefakter som lämnar en ren miljö.

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

Utdata:

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

Sammanfattning

I den här artikeln har du lärt dig hur du använder Azure Container Registry för att lagra, hantera och hämta både OCI-artefakter och artefakter i leveranskedjan. Du använde ORAS CLI för att skicka och hämta artefakter till/från ett Azure Container Registry. Du upptäckte också manifestet för de push-överförda artefakterna och visade diagrammet över artefakter som är kopplade till containeravbildningen.

Nästa steg