Gestire gli artefatti OCI e gli artefatti della catena di approvvigionamento con ORAS

  • Articolo

Registro Azure Container (ACR) consente di gestire gli artefatti OCI (Open Container Initiative) e gli artefatti della catena di approvvigionamento. Questo articolo informa su come usare Registro Azure Container per gestire gli artefatti OCI e gli artefatti della catena di approvvigionamento in modo efficace. Informazioni su come archiviare, gestire e recuperare sia gli artefatti OCI che un grafo di artefatti della catena di approvvigionamento, tra cui firme, distinta base del software (SBOM), risultati dell'analisi della sicurezza e altri tipi.

Questo articolo è diviso in due sezioni principali:

Prerequisiti

  • Registro Azure Container: creare un registro di contenitori nella sottoscrizione di Azure. Ad esempio usare il portale di Azure oppure l'interfaccia della riga di comando di Azure.
  • Interfaccia della riga di comando di Azure: è necessaria la versione 2.29.1o una versione successiva. Vedere Installare l'interfaccia della riga di comando di Azure per l'installazione e/o l'aggiornamento.
  • Interfaccia della riga di comando ORAS: è necessaria la versione v1.1.0 o una versione successiva. Vedere: Installazione di ORAS.
  • Docker (facoltativo): per completare la procedura dettagliata, viene fatto riferimento a un'immagine del contenitore. È possibile usare Docker installato localmente per compilare ed eseguire il push di un'immagine del contenitore oppure usare acr build per la compilazione remota in Azure.
    Anche se Docker Desktop non è obbligatorio, l'orasinterfaccia della riga di comando usa l'archivio credenziali di Docker Desktop per l'archiviazione delle credenziali. Se Docker Desktop è installato, deve essere in esecuzione per oras login.

Configurare il registro

Per configurare l'ambiente per semplificare l'esecuzione dei comandi, seguire questa procedura:

  1. Impostare la variabile ACR_NAME sul nome del registro.
  2. Impostare la variabile REGISTRY su $ACR_NAME.azurecr.io.
  3. Impostare la variabile REPO sul nome dell’archivio.
  4. Impostare la variabile TAG sul tag desiderato.
  5. Impostare la variabile IMAGE su $REGISTRY/${REPO}:$TAG.

Impostare le variabili di ambiente

Configurare un nome del registro, credenziali di accesso, un nome dell’archivio e un tag per eseguire il push e il pull degli artefatti. Nell'esempio seguente vengono usati il nome net-monitore il tag v1dell’archivio. Sostituire con il proprio nome e tag dell’archivio.

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

Accedere a un registro

Eseguire l'autenticazione con Registro Azure Container per consentire di eseguire il pull e il push delle immagini del contenitore.

az login  
az acr login -n $REGISTRY

Se Docker non è disponibile, è possibile usare il token di Progettazione applicazioni fornito per l'autenticazione. Eseguire l'autenticazione con l'identità singola di Microsoft Entra usando un token di Progettazione applicazioni. Usare sempre "000..." per il USER_NAME perché il token viene analizzato tramite la variabile PASSWORD.

# Login to Azure
az login

Accedere con ORAS

Specificare le credenziali per oras login.

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

Questa configurazione consente di eseguire facilmente il push e il pull degli artefatti da e verso Registro Azure Container. Modificare le variabili in base alle esigenze per la configurazione specifica.

Eseguire il push e il pull degli artefatti OCI con ORAS

È possibile usare un Registro Azure Container per archiviare e gestire artefatti OCI (Open Container Initiative), nonché immagini del contenitore Docker e OCI.

Per mostrare questa funzionalità, questa sezione spiega come usare l'interfaccia della riga di comando di ORAS (OCI Registry as Storage) per eseguire il push e il pull degli artefatti OCI da e verso un Registro Azure Container. È possibile gestire vari artefatti OCI in un Registro Azure Container usando diversi strumenti della riga di comando appropriati per ogni artefatto.

Nota

Registro Azure Container e ORAS supportano più opzioni di autenticazione per gli utenti e l'automazione del sistema. Questo articolo usa una singola identità usando un token di Azure. Per altre opzioni di autenticazione, vedere Eseguire l'autenticazione con Registro Azure Container.

Eseguire il push di un artefatto

Un singolo file artefatto senza subject elemento padre può essere qualsiasi elemento come un'immagine del contenitore, un grafico Helm, un file leggimi per l’archivio. Gli artefatti di riferimento possono essere qualsiasi elemento come una firma, una distinta base del software, report di analisi o altri tipi in evoluzione. Gli artefatti di riferimento, descritti in Collegare, eseguire il push e il pull degli artefatti della catena di approvvigionamento sono artefatti che fanno riferimento a un altro artefatto.

Eseguire il push di un singolo file artefatto

Per questo esempio, creare contenuto che rappresenta un file markdown:

echo 'Readme Content' > readme.md

Nel passaggio seguente si esegue il push del file readme.md in <myregistry>.azurecr.io/samples/artifact:readme.

  • Il registro viene identificato con il nome completo <myregistry>.azurecr.io del registro (tutte minuscole), seguito dallo spazio dei nomi e dall’archivio: /samples/artifact.
  • L'artefatto è contrassegnato come :readme, per identificarlo in modo univoco da altri artefatti elencati nell’archivio (:latest, :v1, :v1.0.1).
  • L'impostazione --artifact-type readme/example differenzia l'artefatto da un'immagine del contenitore, che usa application/vnd.oci.image.config.v1+json.
  • ./readme.md Identifica il file caricato e :application/markdown rappresenta l'IANA mediaType del file.
    Per altre informazioni, vedere Materiale sussidiario per gli autori di artefatti OCI.

Usare il comando oras push per eseguire il push del file nel registro.

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

L'output per un push eseguito correttamente è simile all'output seguente:

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

aec5d9dcf7748dd702682d53

Eseguire il push di un artefatto con più file

Quando viene eseguito il push degli artefatti OCI in un registro con ORAS, ogni file di riferimento viene inserito come BLOB (oggetto binario di grandi dimensioni). Per eseguire il push di BLOB separati, fare riferimento ai file singolarmente o alla raccolta di file facendo riferimento a una directory.
Per altre informazioni su come eseguire il push di una raccolta di file, vedere Eseguire il push di artefatti con più file.

Creare una documentazione per l’archivio:

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

Eseguire il push dell'artefatto con più file:

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

Trovare il manifesto

Per visualizzare il manifesto creato come risultato di oras push, usare oras manifest fetch:

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

L'output è simile a:

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

Eseguire il pull di un artefatto

Creare una directory pulita per il download.

mkdir ./download

Eseguire il comando oras pull per eseguire il pull dell'artefatto dal registro.

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

Visualizzare i file spostati

tree ./download

Rimuovere l'artefatto (facoltativo)

Per rimuovere l'artefatto dal registro, usare il comando oras manifest delete.

 oras manifest delete $REGISTRY/samples/artifact:readme

Collegare, eseguire il push e il pull degli artefatti della catena di approvvigionamento con ORAS

Per mostrare questa funzionalità, questo articolo spiega come usare l'interfaccia della riga di comando di ORAS (OCI Registry as Storage) per push, discover e pull un grafo degli artefatti della catena di approvvigionamento in un Registro Azure Container. L'archiviazione di singoli artefatti OCI (oggetto) è descritta in Eseguire il push e pull di artefatti OCI.

Per archiviare un grafo di artefatti, viene definito un subjectriferimento a un artefatto usando il manifesto dell'immagine OCI, che fa parte della Specifica di distribuzione OCI 1.1 versione preliminare.

Eseguire il push di un'immagine del contenitore

Per associare un grafo di artefatti a un'immagine del contenitore usando l'interfaccia della riga di comando di Azure:

È possibile compilare ed eseguire il push di un'immagine del contenitore oppure ignorare questo passaggio se $IMAGE fa riferimento a un'immagine esistente nel registro.

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

Collegare una firma

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

Collegare una firma al registro, come riferimento all'immagine del contenitore

Il comando oras attach crea un riferimento tra il file (./signature.json) e $IMAGE. --artifact-type permette di differenziare gli artefatti, in modo simile alle estensioni di file che consentono tipi di file diversi. È possibile collegare uno o più file specificando [file]:[mediaType].

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

Per altre informazioni su oras attach, vedere la documentazione di ORAS.

Collegare un artefatto con più file come riferimento

Quando viene eseguito il push degli artefatti OCI in un registro con ORAS, ogni file di riferimento viene inserito come BLOB (oggetto binario di grandi dimensioni). Per eseguire il push di BLOB separati, fare riferimento ai file singolarmente o alla raccolta di file facendo riferimento a una directory.
Per altre informazioni su come eseguire il push di una raccolta di file, vedere Push di artefatti con più file.

Trovare i riferimenti agli artefatti

La Specifica OCI v1.1 definisce i referrer dell’API per trovare i riferimenti a un subject artefatto. Il comando oras discover può visualizzare l'elenco di riferimenti all'immagine del contenitore.

Usare oras discover per visualizzare il grafo degli artefatti ora archiviati nel registro.

oras discover -o tree $IMAGE

L'output mostra l'inizio di un grafo di artefatti, in cui la firma e la documentazione vengono visualizzate come elementi figlio dell'immagine del contenitore.

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

Creazione di Grafi di artefatti

La Specifica OCI v1.1 consente grafici profondi, abilitando la distinta base del software (SBOM) e altri tipi di artefatti.

Ecco come creare e collegare una SBOM al registro:

Creare una SBOM di esempio

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

Collegare una SBOM di esempio all'immagine nel registro

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

Firmare la SBOM

Importante

Microsoft consiglia di usare uno strumento di firma di crittografia sicuro, ad esempio Notation per firmare l'immagine e generare una firma per la firma delle SBOM.

Gli artefatti di cui viene eseguito il push come riferimenti, in genere non hanno tag perché sono considerati parte dell'artefatto subject. Per eseguire il push di una firma in un artefatto figlio di un altro artefatto, usare oras discover con --artifact-type applicando il filtro per trovare il digest. In questo esempio viene usata una semplice firma JSON a scopo dimostrativo.

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

Creare una firma di una SBOM.

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

Collegare la firma SBOM

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

Visualizzare il grafo

oras discover -o tree $IMAGE

Genera l'output seguente:

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

Alzare di livello del Grafo di artefatto

Un flusso di lavoro DevOps tipico alza di livello gli artefatti dallo sviluppo tramite staging all'ambiente di produzione. I flussi di lavoro della catena di approvvigionamento sicura alzano di livello il contenuto pubblico in ambienti protetti privatamente. In entrambi i casi si vogliono alzare di livello le firme, le SBOM, i risultati dell'analisi e altri artefatti correlati con l'artefatto soggetto per avere un grafo completo delle dipendenze.

Usando il comando oras copy è possibile alzare di livello un grafo filtrato di artefatti tra registri.

Copiare l'immagine net-monitor:v1 e gli artefatti correlati in sample-staging/net-monitor:v1:

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

L'output dioras 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

Trovare il grafo dell'artefatto alzato di livello

oras discover -o tree $TARGET_REPO:$TAG

Output di 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

Effettuare il pull di artefatti di riferimento

Per eseguire il pull di un artefatto di riferimento specifico, il digest di riferimento viene trovato con il comando oras discover:

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

Creare una directory pulita per il download

mkdir ./download

Eseguire il pull dei documenti nella directory di download

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

Visualizzare la documentazione

tree ./download

L'output ditree:

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

Visualizzare l’archivio e l'elenco di tag

ORAS consente di eseguire il push, trovare, eseguire il pull e la copia dei grafi degli artefatti senza dover assegnare tag. Consente inoltre a un elenco di tag di concentrarsi sugli artefatti a cui gli utenti pensano, invece delle firme e delle SBOM associate alle immagini del contenitore, ai grafici Helm e ad altri artefatti.

Visualizzare un elenco di tag

oras repo tags $REGISTRY/$REPO

Eliminazione di tutti gli artefatti nel grafo

Il supporto per la Specifica OCI v1.1 consente di eliminare il grafo degli artefatti associati all'artefatto del soggetto. Usare il comando oras manifest delete per eliminare il grafo degli artefatti (firma, SBOM e firma della SBOM).

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

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

È possibile visualizzare l'elenco dei manifesti per confermare l'eliminazione dell'artefatto del soggetto e tutti gli artefatti correlati lasciando un ambiente pulito.

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

Output:

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

Riepilogo

In questo articolo si è appreso come usare Registro Azure Container per archiviare, gestire e recuperare sia gli artefatti OCI sia gli artefatti della catena di approvvigionamento. È stata usata l'interfaccia della riga di comando ORAS per eseguire il push e il pull degli artefatti da e verso un Registro Azure Container. È stato anche individuato il manifesto degli artefatti di cui è stato eseguito il push ed è stato visualizzato il grafo degli artefatti Collegati all'immagine del contenitore.

Passaggi successivi

  • Informazioni sui Riferimenti agli artefatti, sull'associazione di firme, sulla distinta base del software e su altri tipi di riferimento.
  • Altre informazioni sul progetto ORAS, tra cui come configurare un manifesto per un artefatto.
  • Per informazioni di riferimento sui nuovi tipi di artefatti visitare l’archivio artefatti OCI.