Mendorong dan menarik artefak rantai pasokan, menggunakan registri kontainer privat di Azure (Pratinjau)

Gunakan registri kontainer Azure untuk menyimpan dan mengelola grafik artefak, termasuk tanda tangan, tagihan perangkat lunak (SBoM), hasil pemindaian keamanan atau jenis lainnya.

Grafik artefak, termasuk gambar kontainer, tanda tangan, dan tagihan perangkat lunak yang ditandatangani

Untuk menunjukkan kemampuan ini, artikel ini menunjukkan cara menggunakan alat OCI Registry as Storage (ORAS) untuk mendorong dan menarik grafik artefak ke registri kontainer Azure.

Dukungan Artefak ORAS adalah fitur pratinjau dan tunduk pada keterbatasan. Ini membutuhkan redundansi zona, yang tersedia di tingkat layanan Premium. Untuk informasi tentang tingkat dan batas layanan registri, lihat tingkat layanan Azure Container Registry.

Prasyarat

  • ORAS CLI - ORAS CLI memungkinkan untuk mendorong, menemukan, menarik artefak ke registri yang mendukung Artefak ORAS.
  • Azure CLI - Untuk membuat repositori identitas, daftar, dan hapus, Anda memerlukan penginstalan lokal Azure CLI. Versi 2.29.1 atau yang lebih baru disarankan. Jalankan az --version untuk menemukan versinya. Jika Anda perlu menginstal atau memutakhirkan, lihat Menginstal Azure CLI.
  • Docker (opsional) - Untuk melengkapi panduan, gambar kontainer direferensikan. Anda dapat menggunakan Docker yang diinstal secara lokal untuk mengompilasi dan mendorong gambar kontainer, atau mereferensikan gambar kontainer yang ada. Docker menyediakan paket yang mengkonfigurasi Docker pada sistem macOS, Windows, atau Linux.

Batasan pratinjau

Dukungan Artefak ORAS terbatas pada wilayah US Selatan Tengah, dengan dukungan Zona Ketersediaan.

  • Registri replikasi geo tidak akan mereplikasi artefak yang dirujuk ke wilayah lain. Karena wilayah tambahan mendukung Artefak ORAS, artefak yang dirujuk akan direplikasi.

Penginstalan ORAS

Unduh dan pasang rilis ORAS pratinjau untuk sistem operasi Anda. Lihat Instruksi penginstalan ORAS untuk cara mengekstrak dan menginstal file untuk sistem operasi Anda, merujuk build pratinjau Alpha.1 dari ORAS GitHub repo

Mengonfigurasi registri privat

Konfigurasikan variabel lingkungan untuk menyalin/menempelkan perintah dengan mudah ke dalam shell Anda. Perintah dapat dijalankan di Azure Cloud Shell

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

Membuat grup sumber daya

Jika diperlukan, jalankan perintah az group create untuk membuat grup sumber daya untuk registri.

az group create --name $ACR_NAME --location southcentralus

Membuat registri yang mendukung Artefak ORAS

Dukungan pratinjau untuk Artefak ORAS memerlukan Redundansi Zona, yang membutuhkan tingkat layanan Premium, di wilayah US Tengah Selatan. Jalankan perintah az acr create untuk membuat registri yang mendukung Artefak ORAS. Lihat bantuan perintah az acr create untuk opsi registri lainnya.

az acr create \
  --resource-group $ACR_NAME \
  --name $ACR_NAME \
  --zone-redundancy enabled \
  --sku Premium \
  --output jsonc

Dalam output perintah, perhatikan properti zoneRedundancy untuk registri. Ketika diaktifkan, registri bersifat zona redundan dan Artefak ORAS diaktifkan:

{
  [...]
  "zoneRedundancy": "Enabled",
}

Masuk dengan Azure CLI

Masuk ke Azure CLI dengan identitas Anda untuk mendorong dan menarik artefak dari registri kontainer.

Kemudian, gunakan perintah Azure CLI masuk az acr untuk mengakses registri.

az login
az acr login --name $ACR_NAME

Catatan

az acr login menggunakan klien Docker untuk mengatur token Azure Active Directory dalam file docker.config. Klien Docker harus diinstal dan dijalankan untuk menyelesaikan alur autentikasi individual.

Masuk dengan ORAS

Bagian ini memperlihatkan opsi untuk masuk ke registri. Pilih metode yang sesuai untuk lingkungan Anda.

Jalankan oras login untuk mengautentikasi dengan registri. Anda dapat meneruskan informasi masuk registri yang sesuai untuk skenario Anda, seperti kredensial perwakilan layanan, identitas pengguna, atau token cakupan repositori (pratinjau).

  • Mengautentikasi dengan identitas Azure Active Directory pribadi Anda untuk menggunakan token AD.

    USER_NAME="00000000-0000-0000-0000-000000000000"
    PASSWORD=$(az acr login --name $ACR_NAME --expose-token --output tsv --query accessToken)
    
  • Mengautentikasi dengan token cakupan repositori (Pratinjau) untuk menggunakan token berbasis non-AD.

    USER_NAME="oras-token"
    PASSWORD=$(az acr token create -n $USER_NAME \
                      -r $ACR_NAME \
                      --repository $REPO content/write \
                      --only-show-errors \
                      --query "credentials.passwords[0].value" -o tsv)
    
  • Mengautentikasi dengan prinsipal layanan Azure Active Directory dengan izin tarik dan dorong (peran AcrPush) ke registri.

    SERVICE_PRINCIPAL_NAME="oras-sp"
    ACR_REGISTRY_ID=$(az acr show --name $ACR_NAME --query id --output tsv)
    PASSWORD=$(az ad sp create-for-rbac --name $SERVICE_PRINCIPAL_NAME \
              --scopes $(az acr show --name $ACR_NAME --query id --output tsv) \
               --role acrpush \
              --query "password" --output tsv)
    USER_NAME=$(az ad sp list --display-name $SERVICE_PRINCIPAL_NAME --query "[].appId" --output tsv)
    

Masuk dengan ORAS

Berikan kredensial ke oras login.

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

Untuk membaca kata sandi dari Stdin, gunakan --password-stdin.

Mendorong gambar kontainer

Contoh ini mengaitkan grafik artefak dengan gambar kontainer. Membangun dan mendorong gambar kontainer, atau mereferensikan gambar yang ada di registri privat.

docker build -t $IMAGE https://github.com/wabbit-networks/net-monitor.git#main
docker push $IMAGE

Membuat tanda tangan sampel ke gambar kontainer

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

Mendorong tanda tangan ke registri, sebagai referensi ke gambar kontainer

Perintah ORAS mendorong tanda tangan ke repositori, merujuk artefak lain melalui parameter subject. --artifact-type menyediakan artefak pembeda, mirip dengan ekstensi file yang memungkinkan jenis file yang berbeda. Satu atau beberapa file dapat didorong dengan menentukan file:mediaType

oras push $REGISTRY/$REPO \
    --artifact-type 'signature/example' \
    --subject $IMAGE \
    ./signature.json:application/json

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

Dorong artefak multi-file sebagai referensi

Buat beberapa dokumentasi terkait artefak

echo 'Readme Content' > readme.md
echo 'Detailed Content' > readme-details.md

Dorong artefak multi-file sebagai referensi

oras push $REGISTRY/$REPO \
    --artifact-type 'readme/example' \
    --subject $IMAGE \
    ./readme.md:application/markdown \
    ./readme-details.md:application/markdown

Menemukan referensi artefak

Spesifikasi Artefak ORAS mendefinisikan [API referen][oras-artifacts-referrers] untuk menemukan referensi ke artefak subject. 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 mendalam

Spesifikasi Artefak ORAS memungkinkan grafik mendalam, memungkinkan tagihan perangkat lunak (SBoM) yang ditandatangani dan jenis artefak lainnya.

Membuat SBoM sampel

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

Dorong sampel SBoM ke registri

oras push $REGISTRY/$REPO \
  --artifact-type 'sbom/example' \
  --subject $IMAGE \
  ./sbom.json:application/json

Tandatangani SBoM

Artefak yang didorong sebagai referensi, umumnya tidak memiliki tag karena dianggap sebagai bagian dari artefak subjek. Untuk mendorong tanda tangan ke artefak yang merupakan turunan dari artefak lain, gunakan oras discover dengan penyaringan --artifact-type untuk menemukan digest.

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

Buat tanda tangan SBoM

echo '{"artifact": "'$REGISTRY/${REPO}@$SBOM_DIGEST'", "signature": "pat hancock"}' > sbom-signature.json

Dorong tanda tangan SBoM

oras push $REGISTRY/$REPO \
  --artifact-type 'signature/example' \
  --subject $REGISTRY/$REPO@$SBOM_DIGEST \
  ./sbom-signature.json:application/json

Lihat grafik

oras discover -o tree $IMAGE

Menghasilkan output berikut:

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

Tarik artefak yang direferensikan

Untuk menarik jenis yang direferensikan, digest referensi ditemukan dengan perintah oras discover

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

Buat direktori bersih untuk pengunduhan

mkdir ./download

Tarik dokumen ke dalam direktori unduhan

oras pull -a -o ./download $REGISTRY/$REPO@$DOC_DIGEST

Lihat dokumen

ls ./download

Lihat repositori dan daftar tag

Artefak ORAS memungkinkan grafik artefak untuk didorong, ditemukan, ditarik, dan disalin tanpa harus menetapkan tag. Hal ini memungkinkan daftar tag untuk fokus pada artefak yang dipikirkan pengguna, alih-alih tanda tangan dan SBoM yang terkait dengan gambar kontainer, bagan helm, dan artefak lainnya.

Lihat daftar tag

az acr repository show-tags \
  -n $ACR_NAME \
  --repository $REPO \
  -o jsonc

Lihat daftar manifes

Repositori dapat memiliki daftar manifes yang memiliki tag atau tanpa tag

az acr repository show-manifests \
  -n $ACR_NAME \
  --repository $REPO \
  --detail -o jsonc

Perhatikan bahwa manifes gambar kontainer memiliki "tags":

{
  "architecture": "amd64",
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "configMediaType": "application/vnd.docker.container.image.v1+json",
  "createdTime": "2021-11-12T00:18:54.5123449Z",
  "digest": "sha256:a0fc570a245b09ed752c42d600ee3bb5b4f77bbd70d8898780b7ab4...",
  "imageSize": 2814446,
  "lastUpdateTime": "2021-11-12T00:18:54.5123449Z",
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "os": "linux",
  "tags": [
    "v1"
  ]
}

Tanda tangan tidak memiliki tag, tetapi dilacak sebagai referensi oras.artifact.manifest untuk gambar kontainer

{
  "changeableAttributes": {
    "deleteEnabled": true,
    "listEnabled": true,
    "readEnabled": true,
    "writeEnabled": true
  },
  "createdTime": "2021-11-12T00:19:10.987156Z",
  "digest": "sha256:555ea91f39e7fb30c06f3b7aa483663f067f2950dcbcc0b0d...",
  "imageSize": 85,
  "lastUpdateTime": "2021-11-12T00:19:10.987156Z",
  "mediaType": "application/vnd.cncf.oras.artifact.manifest.v1+json"
}

Menghapus semua artefak di grafik

Dukungan untuk spesifikasi Artefak ORAS memungkinkan penghapusan grafik artefak yang terkait dengan artefak akar. Gunakan perintah az acr repository delete untuk menghapus tanda tangan, SBoM, dan tanda tangan SBoM.

az acr repository delete \
  -n $ACR_NAME \
  -t ${REPO}:$TAG -y

Lihat manifes yang tersisa

az acr repository show-manifests \
  -n $ACR_NAME \
  --repository $REPO \
  --detail -o jsonc

Langkah berikutnya

  • Pelajari selengkapnya tentang CLI ORAS
  • Pelajari selengkapnya tentang Artefak ORAS untuk cara mendorong, menemukan, menarik, menyalin grafik artefak rantai pasokan