Mengelola Artefak OCI dan Artefak Rantai Pasokan dengan ORAS

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 dari artefak rantai pasokan, termasuk tanda tangan, daftar bahan perangkat lunak (SBOM), hasil pemindaian keamanan, dan jenis lainnya.

Artikel ini dibagi menjadi dua bagian utama:

• Mengunggah dan mengunduh artefak OCI dengan ORAS
• Memasang, mendorong, dan menarik artefak rantai pasokan dengan ORAS

Prasyarat

• Azure Container Registry - Membuat registri kontainer pada langganan Azure Anda. Misalnya, gunakan portal Microsoft Azure atau Azure CLI.
• Azure CLI - Versi 2.29.1 atau lebih baru diperlukan. Lihat Menginstal Azure CLI untuk penginstalan dan/atau peningkatan.
• ORAS CLI - Versi v1.2.3 atau versi yang lebih baru diperlukan. Lihat: Penginstalan ORAS.
• Docker (Opsional) - Untuk menyelesaikan panduan, gambar kontainer dirujuk. oras CLI menggunakan penyimpanan kredensial desktop Docker untuk menyimpan kredensial. 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.

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, nama repositori, dan tag untuk push dan pull 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

Lakukan autentikasi dengan ACR, agar Anda dapat melakukan pull dan push gambar kontainer.

az login  
az acr login -n $REGISTRY  

Penyiapan ini memungkinkan Anda mendorong dan menarik artefak dengan lancar ke dan dari Azure Container Registry Anda. Sekarang ORAS dapat digunakan dengan ACR tanpa autentikasi tambahan dengan menggunakan oras login perintah.

Jika Docker tidak tersedia, Anda dapat menggunakan token AD yang disediakan untuk autentikasi. Masuk dengan identitas Microsoft Entra pribadi Anda menggunakan token AD. Selalu gunakan "000..." untuk USER_NAME saat token diurai melalui PASSWORD variabel. Token yang digunakan oleh az acr login berlaku selama tiga jam.

Catatan

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

Dorong dan Tarik Artefak OCI dengan ORAS

Anda dapat menggunakan registri kontainer Azure untuk menyimpan dan mengelola artefak Open Container Initiative (OCI) serta image 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.

Memindahkan artefak ke repositori

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 bahan perangkat lunak, laporan pemindaian, atau jenis lain yang terus berkembang. Artefak referensi, seperti yang dijelaskan dalam Melampirkan, mendorong, dan menarik artefak rantai pasokan, adalah artefak yang merujuk pada artefak lainnya.

Mengunggah Artefak File Tunggal

Untuk contoh ini, buat konten yang mewakili file markdown:

echo 'Readme Content' > readme.md

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

• Registri diidentifikasi dengan nama registri yang sepenuhnya memenuhi spesifikasi <myregistry>.azurecr.io (semua huruf kecil), diikuti oleh namespace 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 untuk Penulis Artefak OCI.

Gunakan perintah oras push untuk mendorong file ke dalam 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 push 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

Unggah artefak multi-berkas

Ketika artefak OCI dikirim ke registri dengan ORAS, setiap referensi berkas dikirim sebagai blob. Untuk mengunggah 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

Unggah artefak multi-berkas.

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 mendemonstrasikan kemampuan ini, artikel ini menjelaskan cara menggunakan OCI Registry sebagai Storage (ORAS) CLI untuk push, discover, dan pull sebuah graf artefak rantai pasokan ke registri kontainer Azure. Menyimpan artefak OCI individu (subjek) dibahas dalam Mem-push dan Menarik Artefak OCI.

Untuk menyimpan graf artefak, referensi ke artefak subject didefinisikan menggunakan manifes gambar OCI, yang termasuk dalam spesifikasi Distribusi OCI 1.1 prarilis.

Catatan

ORAS v1.2.3 menggunakan API Perujuk OCI](https://github.com/opencontainers/distribution-spec/blob/v1.1.1/spec.md#listing-referrers) untuk menyimpan artefak perujuk terlampir dalam registri secara default. API Referen OCI didukung oleh sebagian besar fitur ACR kecuali registri terenkripsi CMK. ORAS akan kembali menggunakan Skema Tag Referen OCI untuk menyimpan perujuk terlampir di registri terenkripsi CMK.

Mendorong gambar kontainer

Untuk mengaitkan grafik artefak dengan gambar kontainer menggunakan Azure CLI:

Anda dapat membangun dan mengunggah gambar kontainer, atau melewati langkah ini jika $IMAGE mengacu pada 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 fungsi "oras attach", lihat dokumentasi ORAS.

Melampirkan artefak multi-file sebagai referensi

Ketika artefak OCI dikirim ke registri dengan ORAS, setiap referensi berkas dikirim sebagai blob. Untuk mengunggah 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 graf terdalam, memungkinkan daftar bahan perangkat lunak (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

Lampirkan 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 dipublikasikan sebagai referensi biasanya tidak memiliki tag karena dianggap sebagai bagian dari artefak subject. Untuk mengunggah tanda tangan ke artefak yang merupakan turunan dari artefak lain, gunakan oras discover dengan penyaringan --artifact-type untuk menemukan ringkasan/hash. 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 pengembangan melalui pengujian, 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

Keluaran 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 mengambil artefak referensi tertentu, digesti referensi ditemukan dengan perintah oras discover.

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. Gunakan perintah oras manifest delete untuk menghapus grafik dari 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 yang dimaksud, dan semua artefak terkait sehingga meninggalkan lingkungan yang bersih.

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

Keluaran:

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.