Bagikan melalui

Mengelola Artefak OCI dan Artefak Rantai Pasokan dengan ORAS

  • Artikel

Azure container registry (ACR) membantu Anda mengelola artefak Open container initiative (OCI) dan artefak rantai pasokan. Artikel ini memandu Anda cara menggunakan ACR untuk mengelola artefak OCI dan artefak rantai pasokan secara efektif. Pelajari cara menyimpan, mengelola, dan mengambil artefak OCI dan grafik artefak rantai pasokan, termasuk tanda tangan, tagihan perangkat lunak bahan (SBOM), hasil pemindaian keamanan, dan jenis lainnya.

Artikel ini dibagi menjadi dua bagian utama:

Prasyarat

  • Azure Container Registry - Membuat registri kontainer pada langganan Azure Anda. Misalnya, gunakan portal Microsoft Azure atau Azure CLI.
  • Azure CLI - Versi atau yang 2.29.1 lebih baru diperlukan. Lihat Menginstal Azure CLI untuk penginstalan dan/atau peningkatan.
  • ORAS CLI - Versi v1.1.0 atau versi yang lebih baru diperlukan. Lihat: Penginstalan ORAS.
  • Docker (Opsional) - Untuk menyelesaikan panduan, gambar kontainer dirujuk. Anda dapat menggunakan Docker yang diinstal secara lokal untuk membangun dan mendorong gambar kontainer, atau menggunakan acr build untuk membangun dari jarak jauh di Azure.
    Meskipun Docker Desktop tidak diperlukan, oras cli menggunakan penyimpanan kredensial desktop Docker untuk menyimpan kredensial. Jika Docker Desktop diinstal, Docker Desktop harus berjalan untuk oras login.

Mengonfigurasi registri

Untuk mengonfigurasi lingkungan Anda untuk eksekusi perintah yang mudah, ikuti langkah-langkah berikut:

  1. Atur ACR_NAME variabel ke nama registri Anda.
  2. Atur variabel ke REGISTRY$ACR_NAME.azurecr.io.
  3. Atur REPO variabel ke nama repositori Anda.
  4. Atur TAG variabel ke tag yang Anda inginkan.
  5. Atur variabel ke IMAGE$REGISTRY/${REPO}:$TAG.

Atur variabel lingkungan

Konfigurasikan nama registri, info masuk masuk, nama repositori, dan tag untuk mendorong dan menarik artefak. Contoh berikut menggunakan net-monitor nama dan v1 tag repositori. Ganti dengan nama dan tag repositori Anda sendiri.

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

Masuk ke registri

Autentikasi dengan ACR, untuk memungkinkan Anda menarik dan mendorong gambar kontainer.

az login  
az acr login -n $REGISTRY

Jika Docker tidak tersedia, Anda dapat menggunakan token AD yang disediakan untuk autentikasi. Autentikasi dengan identitas Microsoft Entra individual Andamenggunakan token AD. Selalu gunakan "000..." untuk USER_NAME saat token diurai melalui PASSWORD variabel.

# Login to Azure
az login

Masuk dengan ORAS

Berikan kredensial ke oras login.

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

Penyiapan ini memungkinkan Anda mendorong dan menarik artefak dengan lancar ke dan dari Azure Container Registry Anda. Sesuaikan variabel sesuai kebutuhan untuk konfigurasi spesifik Anda.

Dorong dan Tarik Artefak OCI dengan ORAS

Anda dapat menggunakan registri kontainer Azure untuk menyimpan dan mengelola artefak Open Container Initiative (OCI) serta gambar kontainer Docker dan OCI.

Untuk menunjukkan kemampuan ini, bagian ini menunjukkan cara menggunakan CLI OCI Registry as Storage (ORAS) untuk mendorong dan menarik artefak OCI ke/dari registri kontainer Azure. Anda dapat mengelola berbagai artefak OCI di registri kontainer Azure menggunakan alat baris perintah yang berbeda yang sesuai dengan setiap artefak.

Catatan

ACR dan ORAS mendukung beberapa opsi autentikasi untuk pengguna dan otomatisasi sistem. Artikel ini menggunakan identitas individual, menggunakan token Azure. Untuk opsi autentikasi lainnya, lihat Mengautentikasi dengan registri kontainer Azure.

Mendorong artefak

Artefak file tunggal yang tidak subject memiliki induk dapat berupa apa pun dari gambar kontainer, bagan helm, file readme untuk repositori. Artefak referensi dapat berupa apa pun dari tanda tangan, tagihan perangkat lunak bahan, laporan pemindaian, atau jenis lain yang berkembang. Artefak referensi, yang dijelaskan dalam Melampirkan, mendorong, dan menarik artefak rantai pasokan adalah artefak yang merujuk ke artefak lain.

Mendorong Artefak File Tunggal

Untuk contoh ini, buat konten yang mewakili file markdown:

echo 'Readme Content' > readme.md

Langkah berikut mendorong file ke readme.md<myregistry>.azurecr.io/samples/artifact:readme.

  • Registri diidentifikasi dengan nama <myregistry>.azurecr.io registri yang sepenuhnya memenuhi syarat (semua huruf kecil), diikuti oleh namespace layanan dan repositori: /samples/artifact.
  • Artefak ditandai :readme, untuk mengidentifikasinya secara unik dari artefak lain yang tercantum dalam repositori (:latest, :v1, :v1.0.1).
  • Pengaturan --artifact-type readme/example membedakan artefak dari gambar kontainer, yang menggunakan application/vnd.oci.image.config.v1+json.
  • ./readme.md Mengidentifikasi file yang diunggah, dan :application/markdown mewakili IANA mediaType file.
    Untuk informasi selengkapnya, lihat Panduan Penulis Artefak OCI.

oras push Gunakan perintah untuk mendorong file ke registri Anda.

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

Output untuk pendorongan yang berhasil mirip dengan output berikut:

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

aec5d9dcf7748dd702682d53

Mendorong artefak multi-file

Ketika artefak OCI didorong ke registri dengan ORAS, setiap referensi file didorong sebagai blob. Untuk mendorong blob terpisah, referensikan file satu per satu, atau kumpulan file dengan mereferensikan direktori.
Untuk informasi selengkapnya cara mendorong kumpulan file, lihat Mendorong artefak dengan beberapa file.

Buat beberapa dokumentasi untuk repositori:

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

Dorong artefak multi-file:

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

Menemukan manifes

Untuk melihat manifes yang dibuat sebagai hasil dari oras push, gunakan oras manifest fetch:

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

Output mirip dengan:

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

Menarik artefak

Buat direktori bersih untuk diunduh.

mkdir ./download

Jalankan perintah oras pull untuk menarik artefak dari registri Anda.

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

Menampilkan file yang ditarik

tree ./download

Menghapus artefak (opsional)

Untuk menghapus artefak dari registri Anda, gunakan oras manifest delete perintah .

 oras manifest delete $REGISTRY/samples/artifact:readme

Memasang, mendorong, dan menarik artefak rantai pasokan dengan ORAS

Untuk menunjukkan kemampuan ini, artikel ini menunjukkan cara menggunakan OCI Registry sebagai Storage (ORAS) CLI ke push, discover, dan pull grafik artefak rantai pasokan ke registri kontainer Azure. Menyimpan Artefak OCI individu (subjek) dibahas dalam artefak Push dan pull OCI.

Untuk menyimpan grafik artefak, referensi ke subject artefak didefinisikan menggunakan manifes gambar OCI, yang merupakan bagian dari spesifikasi Distribusi OCI 1.1 prarilis.

Mendorong gambar kontainer

Untuk mengaitkan grafik artefak dengan gambar kontainer menggunakan Azure CLI:

Anda dapat membangun dan mendorong gambar kontainer, atau melewati langkah ini jika $IMAGE mereferensikan gambar yang ada di registri.

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

Melampirkan Tanda Tangan

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

Melampirkan tanda tangan ke registri, sebagai referensi ke gambar kontainer

Perintah oras attach membuat referensi antara file (./signature.json) ke $IMAGE. --artifact-type menyediakan artefak pembeda, mirip dengan ekstensi file yang memungkinkan jenis file yang berbeda. Satu atau beberapa file dapat dilampirkan dengan menentukan [file]:[mediaType].

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

Untuk informasi lebih lanjut tentang pelampiran oras, lihat dokumentasi ORAS.

Melampirkan artefak multi-file sebagai referensi

Ketika artefak OCI didorong ke registri dengan ORAS, setiap referensi file didorong sebagai blob. Untuk mendorong blob terpisah, referensikan file satu per satu, atau kumpulan file dengan mereferensikan direktori.
Untuk informasi selengkapnya cara mendorong kumpulan file, lihat Mendorong artefak dengan beberapa file.

Menemukan referensi artefak

Spesifikasi OCI v1.1 mendefinisikan API perujuk untuk menemukan referensi ke subject artefak. Perintah oras discover dapat menampilkan daftar referensi ke gambar kontainer.

Menggunakan oras discover, lihat grafik artefak yang sekarang disimpan dalam registri.

oras discover -o tree $IMAGE

Output menunjukkan awal dari grafik artefak, di mana tanda tangan dan dokumen dianggap sebagai turunan dari gambar kontainer.

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

Membuat grafik Artefak

Spesifikasi OCI v1.1 memungkinkan grafik mendalam, memungkinkan tagihan perangkat lunak bahan (SBOM) yang ditandatangani dan jenis artefak lainnya.

Berikut cara membuat dan melampirkan SBOM ke registri:

Membuat sampel SBOM

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

Melampirkan sampel SBOM ke gambar di registri

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

Menandatangani SBOM

Penting

Microsoft merekomendasikan penggunaan alat penandatanganan kripto yang aman, seperti Notasi untuk menandatangani gambar dan menghasilkan tanda tangan untuk menandatangani SBOM.

Artefak yang didorong sebagai referensi, biasanya tidak memiliki tag karena dianggap sebagai bagian subject dari artefak. Untuk mendorong tanda tangan ke artefak yang merupakan turunan dari artefak lain, gunakan oras discover dengan penyaringan --artifact-type untuk menemukan digest. Contoh ini menggunakan tanda tangan JSON sederhana untuk tujuan demonstrasi.

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

Buat tanda tangan SBOM.

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

Melampirkan tanda tangan SBOM

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

Lihat grafik

oras discover -o tree $IMAGE

Menghasilkan output berikut:

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

Mempromosikan Grafik Artefak

Alur kerja DevOps yang khas mempromosikan artefak dari dev melalui penahapan, ke lingkungan produksi. Alur kerja rantai pasokan yang aman mempromosikan konten publik ke lingkungan yang diamankan secara privat. Dalam kedua kasus, Anda ingin mempromosikan tanda tangan, SBOM, hasil pemindaian, dan artefak terkait lainnya dengan artefak subjek untuk memiliki grafik dependensi yang lengkap.

oras copy Dengan menggunakan perintah , Anda dapat mempromosikan grafik artefak yang difilter di seluruh registri.

net-monitor:v1 Salin gambar, dan artefak terkait ke sample-staging/net-monitor:v1:

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

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

Menemukan grafik artefak yang dipromosikan

oras discover -o tree $TARGET_REPO:$TAG

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

Menarik Artefak Yang Dirujuk

Untuk menarik artefak referensi tertentu, hash referensi ditemukan dengan oras discover perintah :

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

Buat direktori bersih untuk pengunduhan

mkdir ./download

Tarik dokumen ke dalam direktori unduhan

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

Lihat dokumen

tree ./download

Output dari tree:

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

Lihat repositori dan daftar tag

ORAS memungkinkan grafik artefak didorong, ditemukan, ditarik, dan disalin tanpa harus menetapkan tag. Ini juga memungkinkan daftar tag untuk fokus pada artefak yang dipikirkan pengguna, dibandingkan dengan tanda tangan dan SBOM yang terkait dengan gambar kontainer, bagan helm, dan artefak lainnya.

Lihat daftar tag

oras repo tags $REGISTRY/$REPO

Menghapus semua artefak dalam grafik

Dukungan untuk Spesifikasi OCI v1.1 memungkinkan penghapusan grafik artefak yang terkait dengan artefak subjek. oras manifest delete Gunakan perintah untuk menghapus grafik artefak (tanda tangan, SBOM, dan tanda tangan SBOM).

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

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

Anda dapat melihat daftar manifes untuk mengonfirmasi penghapusan artefak subjek, dan semua artefak terkait meninggalkan lingkungan yang bersih.

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.

Ringkasan

Dalam artikel ini, Anda mempelajari cara menggunakan Azure Container Registry untuk menyimpan, mengelola, dan mengambil artefak OCI dan artefak rantai pasokan. Anda menggunakan ORAS CLI untuk mendorong dan menarik artefak ke/dari Azure Container Registry. Anda juga menemukan manifes artefak yang didorong dan melihat grafik artefak yang melekat pada gambar kontainer.

Langkah berikutnya

  • Pelajari tentang Referensi Artefak, mengaitkan tanda tangan, tagihan perangkat lunak materi, dan jenis referensi lainnya.
  • Pelajari selengkapnya tentang Proyek ORAS, termasuk cara mengonfigurasi manifes untuk artefak.
  • Kunjungi repositori Artefak OCI untuk informasi referensi tentang jenis artefak baru.