Správa artefaktů OCI a artefaktů dodavatelského řetězce pomocí ORAS

Azure Container Registry (ACR) pomáhá spravovat artefakty open container initiative (OCI) i artefakty dodavatelského řetězce. V tomto článku se dozvíte, jak používat ACR ke správě artefaktů OCI a artefaktů dodavatelského řetězce efektivně. Naučte se ukládat, spravovat a načítat artefakty OCI i graf artefaktů dodavatelského řetězce, včetně podpisů, faktur softwaru (SBOM), výsledků kontroly zabezpečení a dalších typů.

Tento článek je rozdělený do dvou hlavních částí:

Požadavky

  • Registr kontejnerů Azure – Vytvořte registr kontejnerů ve svém předplatném Azure. Použijte například Azure Portal nebo Azure CLI.
  • Azure CLI – Vyžaduje se verze 2.29.1 nebo novější. Viz Instalace Azure CLI pro instalaci nebo upgrade.
  • ORAS CLI – Je vyžadována verze v1.2.3 nebo novější. Viz: Instalace ORAS.
  • Docker (volitelné) – K dokončení návodu se odkazuje na image kontejneru. Rozhraní oras příkazového řádku využívá úložiště přihlašovacích údajů desktopového Dockeru k ukládání přihlašovacích údajů. Docker nainstalovaný místně můžete použít k sestavení a nasdílení image kontejneru nebo k acr build vzdálenému sestavení v Azure.

Konfigurace registru

Pokud chcete nakonfigurovat prostředí pro snadné provádění příkazů, postupujte takto:

  1. Nastavte proměnnou ACR_NAME na název registru.
  2. Nastavte proměnnou REGISTRY na $ACR_NAME.azurecr.iohodnotu .
  3. Nastavte proměnnou REPO na název úložiště.
  4. Nastavte proměnnou TAG na požadovanou značku.
  5. Nastavte proměnnou IMAGE na $REGISTRY/${REPO}:$TAGhodnotu .

Nastavení proměnných prostředí

Nakonfigurujte název registru, přihlašovací údaje, název úložiště a značku pro odeslání a stažení artefaktů. Následující příklad používá net-monitor název a v1 značku úložiště. Nahraďte názvem a značkou vlastního úložiště.

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

Přihlášení k registru

Ověřte se pomocí služby ACR, abyste mohli načíst a odeslat image kontejneru.

az login  
az acr login -n $REGISTRY

Toto nastavení umožňuje bezproblémově odesílat a stahovat artefakty ze a do Azure Container Registry. Teď je možné ORAS používat s ACR bez dalšího ověřování pomocí oras login příkazu.

Pokud Docker není k dispozici, můžete k ověřování použít token AD. Ověřte se svou individuální identitou Microsoft Entra pomocí tokenu AD. Vždy použijte "000..." pro USER_NAME token, protože token se parsuje prostřednictvím proměnné PASSWORD. Token používaný službou az acr login je platný po dobu tří hodin.

Poznámka:

ACR a ORAS podporují více možností ověřování pro uživatele a automatizaci systému. Tento článek používá jednotlivou identitu pro snadnost předvedení. Další možnosti ověřování najdete v tématu Ověřování pomocí registru kontejneru Azure.

Odesílání a stahování artefaktů OCI pomocí ORAS

Můžete použít Azure Container Registry k ukládání a správě artefaktů Open Container Initiative (OCI) a obrazů kontejnerů Dockeru a OCI.

K demonstraci této funkce tato část ukazuje, jak pomocí rozhraní příkazového OCI Registry as Storage (ORAS) CLI pushnout a stáhnout OCI artefakty do/z Azure kontejnerového registru. Různé artefakty OCI v registru kontejneru Azure můžete spravovat pomocí různých nástrojů příkazového řádku odpovídajících jednotlivým artefaktům.

Odeslání artefaktu

Jediný artefakt souboru, který nemá nadřazený subject objekt, může být cokoli z image kontejneru, chartu Helmu, souboru readme pro úložiště. Referenční artefakty můžou být cokoli od podpisu, softwarového seznamu materiálů, skenovacích zpráv nebo jiných vyvíjejících se typů. Referenční artefakty, popsané v Připojení, vložení a vytažení artefaktů dodavatelského řetězce, jsou artefakty, které odkazují na jiný artefakt.

Nahrání artefaktu jako jednoho souboru

V tomto příkladu vytvořte obsah, který představuje soubor Markdown:

echo 'Readme Content' > readme.md

Následující krok odešle readme.md soubor na <myregistry>.azurecr.io/samples/artifact:readme soubor.

  • Registr je identifikován plně kvalifikovaným názvem <myregistry>.azurecr.io registru (malými písmeny), za kterým následuje obor názvů a úložiště: /samples/artifact.
  • Artefakt je označený :readme, aby ho jednoznačně identifikoval z jiných artefaktů uvedených v úložišti (:latest, :v1, :v1.0.1).
  • Nastavení --artifact-type readme/example rozlišuje artefakt od image kontejneru, která používá application/vnd.oci.image.config.v1+json.
  • Identifikuje ./readme.md soubor nahraný a :application/markdown představuje IANA mediaType souboru.
    Další informace najdete v tématu Pokyny pro autory artefaktů OCI.

oras push Pomocí příkazu nasdílejte soubor do registru.

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

Výstup úspěšného odeslání je podobný následujícímu výstupu:

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

aec5d9dcf7748dd702682d53

Nasdílení artefaktu s více soubory

Když jsou artefakty OCI odeslány do registru pomocí ORAS, každý odkaz na soubor se odešle jako blob. Pokud chcete odeslat samostatné objekty blob, odkazujte na soubory jednotlivě nebo na kolekci souborů odkazováním na adresář.
Další informace o tom, jak odeslat kolekci souborů, naleznete v tématu Odesílání artefaktů s více soubory.

Vytvořte pro úložiště určitou dokumentaci:

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

Nasdílení artefaktu s více soubory:

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

Objevte manifest

Pokud chcete zobrazit manifest vytvořený jako výsledek oras push, použijte oras manifest fetch:

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

Výstup je podobný tomuto:

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

Stažení artefaktu

Vytvořte čistý adresář pro stahování.

mkdir ./download

Spuštěním oras pull příkazu stáhněte artefakt z registru.

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

Zobrazení natažených souborů

tree ./download

Odebrání artefaktu (volitelné)

Pokud chcete odebrat artefakt z registru, použijte oras manifest delete příkaz.

 oras manifest delete $REGISTRY/samples/artifact:readme

Připojte, spusťte a stáhněte artefakty dodavatelského řetězce pomocí ORAS

K demonstraci této funkce článek ukazuje použití rozhraní příkazového řádku OCI Registry jako úložiště (ORAS) k push, discovera pull grafu artefaktů dodavatelského řetězce do registru kontejnerů Azure. Ukládání jednotlivých artefaktů OCI (osoby) je popsáno v Push a pull OCI artefakty.

Pokud chcete uložit graf artefaktů, definuje se odkaz na subject artefakt pomocí manifestu image OCI, který je součástí předběžné specifikace distribuce OCI 1.1.

Poznámka:

ORAS v1.2.3 používá rozhraní API referrers OCI k ukládání připojených artefaktů referreru do registru ve výchozím nastavení. Rozhraní OCI Referrers API je podporováno většinou funkcí ACR s výjimkou registru zašifrovaného pomocí CMK. ORAS se vrátí k použití schématu značek refererů OCI k uložení připojených refererů v registru s šifrováním CMK.

Nasdílení image kontejneru

Přidružení grafu artefaktů k imagi kontejneru pomocí Azure CLI:

Pokud odkazujete na existující image v registru, můžete sestavit a odeslat image kontejneru nebo tento krok $IMAGE přeskočit.

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

Připojení podpisu

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

Připojte podpis k registru jako referenci na obraz kontejneru

Příkaz oras attach vytvoří odkaz mezi souborem (./signature.json) na $IMAGE. Umožňuje rozlišení artefaktů, podobně jako přípony souborů umožňují odlišení různých typů souborů. Jeden nebo více souborů lze připojit zadáním [file]:[mediaType].

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

Další informace o připojení ORAS najdete v dokumentaci ORAS.

Připojení artefaktu s více soubory jako odkazu

Když jsou artefakty OCI odeslány do registru pomocí ORAS, každý odkaz na soubor se odešle jako blob. Pokud chcete odeslat samostatné objekty blob, odkazujte na soubory jednotlivě nebo na kolekci souborů odkazováním na adresář.
Další informace o tom, jak odeslat kolekci souborů, naleznete v tématu Odesílání artefaktů s více soubory.

Zjišťování odkazů na artefakty

Specifikace OCI v1.1 definuje referenční rozhraní API pro zjišťování odkazů na subject artefakt. Příkaz oras discover může zobrazit seznam odkazů na image kontejneru.

Pomocí oras discover si nyní prohlédněte graf artefaktů uložených v registru.

oras discover -o tree $IMAGE

Výstup ukazuje začátek grafu artefaktů, kde se podpis a dokumenty zobrazují jako potomky obrazu kontejneru.

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

Vytváření grafů artefaktů

Specifikace OCI v1.1 umožňuje komplexní grafy, podepsané softwarové bill of materials (SBOM) a další typy artefaktů.

Tady je postup vytvoření a připojení SBOM k registru:

Vytvořte ukázkový SBOM

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

Připojit ukázkový SBOM k obrazu v registru

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

Podepište SBOM

Důležité

Microsoft doporučuje použít zabezpečený kryptografický podpisový nástroj, jako je notace , podepsat obrázek a vygenerovat podpis pro podepisování SBOM.

Artefakty, které jsou poskytnuty jako reference, obvykle nemají štítky, protože jsou považovány za součást artefaktu subject. Pokud chcete aplikovat podpis na artefakt, který je potomkem jiného artefaktu, použijte oras discover s filtrováním --artifact-type pro nalezení digest. Tento příklad používá jednoduchý podpis JSON pro demonstrační účely.

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

Vytvořte podpis SBOM.

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

Připojte podpis SBOM

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

Zobrazení grafu

oras discover -o tree $IMAGE

Generuje následující výstup:

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

Podpora grafu artefaktů

Typický pracovní postup DevOps propaguje artefakty z vývoje přes přípravu až po produkční prostředí. Pracovní postupy zabezpečeného dodavatelského řetězce propagují veřejný obsah na soukromě zabezpečená prostředí. V obou případech chcete propagovat podpisy, SBOMy, výsledky skenování a další související artefakty spolu s předmětným artefaktem, abyste měli úplný graf závislostí.

Pomocí příkazu oras copy můžete propagovat filtrovaný graf artefaktů mezi registry.

net-monitor:v1 Zkopírujte obrázek a související artefakty dosample-staging/net-monitor:v1:

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

Výstup 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

Zjištění grafu upřednostněných artefaktů

oras discover -o tree $TARGET_REPO:$TAG

Výstup 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

Načítání odkazovaných artefaktů

Pokud chcete vyžádat konkrétní odkazovaný artefakt, zjistí se hodnota hash odkazu pomocí oras discover příkazu:

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

Vytvoření čistého adresáře pro stahování

mkdir ./download

Stažení dokumentů do adresáře pro stahování

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

Zobrazení dokumentace

tree ./download

Výstup tree:

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

Zobrazení úložiště a výpisu značek

ORAS umožňuje odesílat, zjišťovat, natahovat a kopírovat grafy artefaktů, aniž by bylo nutné přiřazovat značky. Umožňuje také výpis značek zaměřit se na artefakty, o které si uživatelé myslí, a ne na podpisy a SBOM, které jsou přidružené k imagím kontejnerů, chartům helmu a dalším artefaktům.

Zobrazení seznamu značek

oras repo tags $REGISTRY/$REPO

Odstranění všech artefaktů v grafu

Podpora specifikace OCI v1.1 umožňuje odstranit diagram artefaktů přidružených k hlavnímu artefaktu. oras manifest delete Pomocí příkazu odstraňte graf artefaktů (podpis, SBOM a podpis SBOM).

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

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

Seznam manifestů můžete zobrazit pro potvrzení odstranění daného artefaktu a všech souvisejících artefaktů, čímž zůstane prostředí čisté.

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

Výstup:

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

Shrnutí

V tomto článku jste zjistili, jak pomocí služby Azure Container Registry ukládat, spravovat a načítat artefakty OCI i artefakty dodavatelského řetězce. Použili jste rozhraní příkazového řádku ORAS k přesunutí a stažení artefaktů do/z služby Azure Container Registry. Také jste zjistili manifest nasdílených artefaktů a zobrazili jste graf artefaktů připojených k imagi kontejneru.

Další kroky

  • Last updated on