Hantera OCI-artefakter och leveranskedjeartefakter med ORAS

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:

• Push och dra OCI-artefakter med ORAS
• Koppla, pusha och hämta leveranskedjeartefakter med ORAS

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.2.3 eller senare version krävs. Se: ORAS-installation.
• Docker (valfritt) – För att slutföra genomgången refereras en containeravbildning. oras CLI använder Docker Desktop Credential Store för lagring av autentiseringsuppgifter. 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.

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  

Med den här konfigurationen kan du sömlöst skicka och hämta artefakter till och från Azure Container Registry. Nu kan ORAS användas med ACR utan ytterligare autentisering med hjälp oras login av kommandot .

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 USER_NAME eftersom token parsas genom variabeln PASSWORD. Token som används av az acr login är giltig i tre timmar.

Push- och pull-OCI-artifakter 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.

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, en programvarumateriallista, skanningsrapporter eller andra typer som utvecklas. Referensartefakter, som beskrivs i Bifoga, skapa och hämta artefakter i leveranskedjan, är artefakter som hänvisar till en annan artefakt.

Push-överför en Single-File artefakt

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.
För mer information om hur du pushar en samling filer, se Push av 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

Överför flerfilsartefakten:

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

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

För att lagra en graf av artefakter, definieras en referens till en subject artefakt med OCI-bildmanifest, som är en del av OCI 1.1-distributionsspecifikationen för förhandsversion.

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 pusha en containeravbildning eller hoppa över det här steget om $IMAGE refererar till en befintlig avbildning i registret.

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

Bifoga 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. --artifact-type möjliggör differentiering av artefakter, liknande filnamnstillägg som tillåter olika filtyper. En eller flera filer kan bifogas genom att ange [file]:[mediaType].

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 man överför en samling filer finns under Överföra objekt 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 en graf med artefakter, där signaturen och dokumenten visas som underordnade till 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

Artefakter som skickas som referenser har vanligtvis inte taggar eftersom de anses vara en del av subject artefakten. För att skicka en signatur till en artefakt som är ett barn av en annan artefakt, använd oras discover med --artifact-type filtrering för att hitta digest. 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 överför artefakter från utveckling till testmiljö 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

Upptäck det framlyfta artefakt-diagrammet

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 hittas referenssammandraget med kommandot oras discover.

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

Dra dokumenten till nedladdningsmappen

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

Visa dokumentationen

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 den specifika artefakten och alla relaterade artefakter för att skapa 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 över de överförda artefakterna och visade grafen över artefakter som är kopplade till containerbilden.

Nästa steg

• Lär dig mer om artefaktreferenser, som associerar signaturer, programvarans materialförteckning och andra referenstyper.
• Läs mer om ORAS-projektet, inklusive hur du konfigurerar ett manifest för en artefakt.
• Besök OCI Artifacts-lagringsplatsen för referensinformation om nya artefakttyper.