Delen via

OCI-artefacten en toeleveringsketenartefacten beheren met ORAS

  • Artikel

Azure Container Registry (ACR) helpt u bij het beheren van zowel de OCI-artefacten (Open Container Initiative) als toeleveringsketenartefacten. In dit artikel wordt uitgelegd hoe u ACR gebruikt voor het effectief beheren van OCI-artefacten en toeleveringsketenartefacten. Meer informatie over het opslaan, beheren en ophalen van zowel OCI-artefacten als een grafiek van toeleveringsketenartefacten, waaronder handtekeningen, softwarefactuur van materialen (SBOM), resultaten van beveiligingsscans en andere typen.

Dit artikel is onderverdeeld in twee hoofdsecties:

Vereisten

  • Azure-containerregister: maak een containerregister in uw Azure-abonnement. Gebruik bijvoorbeeld De Azure-portal of de Azure CLI.
  • Azure CLI : versie 2.29.1 of hoger is vereist. Zie Azure CLI installeren voor installatie en/of upgrade.
  • ORAS CLI : versie v1.1.0 of latere versie is vereist. Zie: ORAS-installatie.
  • Docker (optioneel): er wordt verwezen naar een containerinstallatiekopieën om het overzicht te voltooien. U kunt Docker gebruiken die lokaal is geïnstalleerd om een containerinstallatiekopieën te bouwen en te pushen of acr build om extern te bouwen in Azure.
    Docker Desktop is niet vereist, maar de oras cli maakt gebruik van het docker-bureaubladreferentiearchief voor het opslaan van referenties. Als Docker Desktop is geïnstalleerd, moet deze worden uitgevoerd voor oras login.

Het register configureren

Volg deze stappen om uw omgeving te configureren voor eenvoudige uitvoering van opdrachten:

  1. Stel de variabele in op de ACR_NAME registernaam.
  2. Stel de REGISTRY variabele in op $ACR_NAME.azurecr.io.
  3. Stel de variabele in op de REPO naam van uw opslagplaats.
  4. Stel de TAG variabele in op de gewenste tag.
  5. Stel de IMAGE variabele in op $REGISTRY/${REPO}:$TAG.

Omgevingsvariabelen instellen

Configureer een registernaam, aanmeldingsreferenties, een opslagplaatsnaam en tag om artefacten te pushen en op te halen. In het volgende voorbeeld wordt de naam en v1 tag van de net-monitor opslagplaats gebruikt. Vervang door de naam en tag van uw eigen opslagplaats.

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

Aanmelden bij een register

Verifieer met de ACR, zodat u containerinstallatiekopieën kunt ophalen en pushen.

az login  
az acr login -n $REGISTRY

Als Docker niet beschikbaar is, kunt u het AD-token gebruiken dat is opgegeven voor verificatie. Verifieer met uwafzonderlijke Microsoft Entra-identiteit met behulp van een AD-token. Gebruik altijd '000...' als USER_NAME het token wordt geparseerd via de PASSWORD variabele.

# Login to Azure
az login

Aanmelden met ORAS

Geef de referenties op voor oras login.

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

Met deze installatie kunt u naadloos artefacten naar en van uw Azure Container Registry pushen en ophalen. Pas de variabelen zo nodig aan voor uw specifieke configuratie.

OCI-artefacten pushen en ophalen met ORAS

U kunt een Azure-containerregister gebruiken om OCI-artefacten (Open Container Initiative) en Docker- en OCI-containerinstallatiekopieën op te slaan en te beheren.

Om deze mogelijkheid te demonstreren, laat deze sectie zien hoe u de OCI Registry as Storage (ORAS) CLI gebruikt om OCI-artefacten naar/van een Azure-containerregister te pushen en op te halen. U kunt verschillende OCI-artefacten in een Azure-containerregister beheren met behulp van verschillende opdrachtregelprogramma's die geschikt zijn voor elk artefact.

Notitie

ACR en ORAS ondersteunen meerdere verificatieopties voor gebruikers en systeemautomatisering. In dit artikel wordt gebruikgemaakt van een afzonderlijke identiteit, met behulp van een Azure-token. Zie Verifiëren met een Azure-containerregister voor meer verificatieopties .

Een artefact pushen

Een enkel bestandsartefact met geen subject bovenliggend element kan iets zijn van een containerinstallatiekopieën, een Helm-grafiek, een leesmij-bestand voor de opslagplaats. Referentieartefacten kunnen van alles zijn, zoals een handtekening, softwarefactuur van materialen, scanrapporten of andere veranderende typen. Referentieartefacten, beschreven in Attach, push en pull-toeleveringsketenartefacten , zijn artefacten die verwijzen naar een ander artefact.

Een artefact met één bestand pushen

In dit voorbeeld maakt u inhoud die een Markdown-bestand vertegenwoordigt:

echo 'Readme Content' > readme.md

De volgende stap pusht het readme.md bestand naar <myregistry>.azurecr.io/samples/artifact:readme.

  • Het register wordt geïdentificeerd met de volledig gekwalificeerde registernaam <myregistry>.azurecr.io (alle kleine letters), gevolgd door de naamruimte en opslagplaats: /samples/artifact.
  • Het artefact is gelabeld :readmeom het uniek te identificeren van andere artefacten die worden vermeld in de opslagplaats (:latest, :v1, :v1.0.1).
  • Instelling --artifact-type readme/example onderscheidt het artefact van een containerinstallatiekopie, die gebruikmaakt van application/vnd.oci.image.config.v1+json.
  • Het ./readme.md identificeert het geüploade bestand en de :application/markdownIANA mediaType van het bestand.
    Zie richtlijnen voor auteurs van OCI-artefacten voor meer informatie.

Gebruik de oras push opdracht om het bestand naar het register te pushen.

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

De uitvoer voor een geslaagde push is vergelijkbaar met de volgende uitvoer:

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

aec5d9dcf7748dd702682d53

Een artefact met meerdere bestanden pushen

Wanneer OCI-artefacten worden gepusht naar een register met ORAS, wordt elke bestandsreferentie gepusht als een blob. Als u afzonderlijke blobs wilt pushen, verwijst u naar de bestanden afzonderlijk of verzameling bestanden door te verwijzen naar een map.
Zie Artefacten pushen met meerdere bestanden voor meer informatie over het pushen van een verzameling bestanden.

Maak enkele documentatie voor de opslagplaats:

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

Push het artefact met meerdere bestanden:

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

Het manifest detecteren

Als u het manifest wilt weergeven dat is gemaakt als gevolg van oras push, gebruikt u oras manifest fetch:

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

De uitvoer is vergelijkbaar met:

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

Een artefact ophalen

Maak een schone map om te downloaden.

mkdir ./download

Voer de oras pull opdracht uit om het artefact op te halen uit het register.

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

De opgehaalde bestanden weergeven

tree ./download

Het artefact verwijderen (optioneel)

Gebruik de oras manifest delete opdracht om het artefact uit het register te verwijderen.

 oras manifest delete $REGISTRY/samples/artifact:readme

Artefacten van toeleveringsketens koppelen, pushen en ophalen met ORAS

Om deze mogelijkheid te demonstreren, laat dit artikel zien hoe u de OCI Registry as Storage (ORAS) CLI gebruikt voor push, discoveren pull een grafiek van toeleveringsketenartefacten naar een Azure-containerregister. Het opslaan van afzonderlijke (onderwerp) OCI-artefacten wordt behandeld in Push- en pull-OCI-artefacten.

Als u een grafiek met artefacten wilt opslaan, wordt een verwijzing naar een subject artefact gedefinieerd met behulp van het OCI-installatiekopieënmanifest, dat deel uitmaakt van de prerelease OCI 1.1-distributiespecificatie.

Een containerinstallatiekopieën pushen

Een grafiek met artefacten koppelen aan een containerinstallatiekopieën met behulp van de Azure CLI:

U kunt een containerinstallatiekopieën bouwen en pushen of deze stap overslaan als $IMAGE deze verwijst naar een bestaande installatiekopieën in het register.

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

Een handtekening toevoegen

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

Voeg een handtekening toe aan het register als verwijzing naar de containerinstallatiekopieën

Met de oras attach opdracht maakt u een verwijzing tussen het bestand (./signature.json) naar de $IMAGE. De --artifact-type functie biedt voor het onderscheiden van artefacten, vergelijkbaar met bestandsextensies die verschillende bestandstypen inschakelen. Een of meer bestanden kunnen worden bijgevoegd door op te [file]:[mediaType]geven.

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

Zie de ORAS-documentatie voor meer informatie over oras-bijlage.

Een artefact met meerdere bestanden toevoegen als verwijzing

Wanneer OCI-artefacten worden gepusht naar een register met ORAS, wordt elke bestandsreferentie gepusht als een blob. Als u afzonderlijke blobs wilt pushen, verwijst u naar de bestanden afzonderlijk of verzameling bestanden door te verwijzen naar een map.
Zie Artefacten pushen met meerdere bestanden voor meer informatie over het pushen van een verzameling bestanden.

Artefactverwijzingen detecteren

De OCI v1.1-specificatie definieert een verwijzings-API voor het detecteren van verwijzingen naar een subject artefact. Met oras discover de opdracht kunt u de lijst met verwijzingen naar de containerinstallatiekopieën weergeven.

Bekijk met behulp oras discovervan de grafiek van artefacten die nu zijn opgeslagen in het register.

oras discover -o tree $IMAGE

In de uitvoer ziet u het begin van een grafiek met artefacten, waarbij de handtekening en documenten worden weergegeven als onderliggende elementen van de containerinstallatiekopieën.

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

Artefactengrafieken maken

De OCI v1.1-specificatie maakt diepe grafieken mogelijk, waardoor ondertekende softwarefactuur van materialen (SBOM) en andere artefacttypen mogelijk is.

U kunt als volgt een SBOM maken en koppelen aan het register:

Een voorbeeld-SBOM maken

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

Een voorbeeld-SBOM koppelen aan de installatiekopieën in het register

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

De SBOM ondertekenen

Belangrijk

Microsoft raadt u aan een veilig hulpprogramma voor crypto-ondertekening te gebruiken, zoals Notation om de afbeelding te ondertekenen en een handtekening te genereren voor het ondertekenen van SBOM's.

Artefacten die als verwijzingen worden gepusht, hebben doorgaans geen tags omdat ze worden beschouwd als onderdeel van het subject artefact. Als u een handtekening wilt pushen naar een artefact dat een onderliggend element van een ander artefact is, gebruikt u de oras discover functie met --artifact-type filteren om de samenvatting te vinden. In dit voorbeeld wordt een eenvoudige JSON-handtekening gebruikt voor demonstratiedoeleinden.

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

Maak een handtekening van een SBOM.

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

De SBOM-handtekening bijvoegen

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

De grafiek weergeven

oras discover -o tree $IMAGE

Hiermee wordt de volgende uitvoer gegenereerd:

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

De artefactgrafiek promoten

Een typische DevOps-werkstroom bevordert artefacten van dev via fasering naar de productieomgeving. Veilige supply chain-werkstromen bevorderen openbare inhoud naar privé beveiligde omgevingen. In beide gevallen wilt u de handtekeningen, SBOM's, scanresultaten en andere gerelateerde artefacten promoveren met het onderwerpartefact om een volledige grafiek met afhankelijkheden te hebben.

Met behulp van de oras copy opdracht kunt u een gefilterde grafiek van artefacten in registers promoveren.

Kopieer de net-monitor:v1 installatiekopie en gerelateerde artefacten naar sample-staging/net-monitor:v1:

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

De uitvoer van 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

De grafiek met gepromoveerde artefacten ontdekken

oras discover -o tree $TARGET_REPO:$TAG

Uitvoer van 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

Verwijzingsartefacten ophalen

Als u een specifiek artefact wilt ophalen waarnaar wordt verwezen, wordt de samenvatting van de verwijzing gedetecteerd met de oras discover opdracht:

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

Een schone map maken om te downloaden

mkdir ./download

Haal de documenten naar de downloadmap

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

De documenten weergeven

tree ./download

De uitvoer van tree:

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

De opslagplaats en tagvermelding weergeven

MET ORAS kunnen artefactgrafieken worden gepusht, gedetecteerd, opgehaald en gekopieerd zonder tags toe te wijzen. Ook kan een tagvermelding zich richten op de artefacten die gebruikers bedenken, in plaats van de handtekeningen en SBOM's die zijn gekoppeld aan de containerinstallatiekopieën, Helm-grafieken en andere artefacten.

Een lijst met tags weergeven

oras repo tags $REGISTRY/$REPO

Alle artefacten in de grafiek verwijderen

Ondersteuning voor de OCI v1.1-specificatie maakt het mogelijk om de grafiek te verwijderen van artefacten die zijn gekoppeld aan het onderwerpartefact. Gebruik de oras manifest delete opdracht om de grafiek van artefacten (handtekening, SBOM en de handtekening van de SBOM) te verwijderen.

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

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

U kunt de lijst met manifesten bekijken om het verwijderen van het onderwerpartefact te bevestigen en alle gerelateerde artefacten die een schone omgeving verlaten.

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

Uitvoer:

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

Samenvatting

In dit artikel hebt u geleerd hoe u Azure Container Registry gebruikt om OCI-artefacten en toeleveringsketenartefacten op te slaan, te beheren en op te halen. U hebt ORAS CLI gebruikt om artefacten naar/van een Azure Container Registry te pushen en op te halen. U hebt ook het manifest van de gepushte artefacten gedetecteerd en de grafiek bekeken van artefacten die zijn gekoppeld aan de containerinstallatiekopieën.

Volgende stappen

  • Meer informatie over artefactverwijzingen, het koppelen van handtekeningen, softwarefactuur van materialen en andere referentietypen.
  • Meer informatie over het ORAS-project, waaronder het configureren van een manifest voor een artefact.
  • Ga naar de opslagplaats OCI Artifacts voor referentie-informatie over nieuwe artefacttypen.