Kepercayaan konten di Azure Container Registry

  • Artikel

Azure Container Registry mengimplementasikan model kepercayaan konten Docker, mengaktifkan mendorong dan menarik citra yang ditandatangani. Artikel ini membuat Anda mulai mengaktifkan kepercayaan konten dalam registri kontainer Anda.

Catatan

Kepercayaan konten adalah fitur dari tingkat layanan Premium Azure Container Registry.

Batasan

  • Token dengan izin yang dicakup repositori saat ini tidak mendukung docker push dan penarikan gambar yang ditandatangani.

Cara kerja kepercayaan konten

Penting untuk setiap sistem terdistribusi yang dirancang dengan pertimbangan keamanan adalah memverifikasi sumber dan integritas data yang memasuki sistem. Konsumen data harus dapat memverifikasi penerbit (sumber) data, serta memastikan data tidak diubah setelah diterbitkan (integritas).

Sebagai penerbit citra, kepercayaan konten memungkinkan Anda untuk menandatangani citra yang Anda dorong ke registri Anda. Konsumen citra Anda (orang atau sistem yang menarik citra dari registri Anda) dapat mengonfigurasi klien mereka untuk hanya menarik citra yang ditandatangani. Ketika konsumen citra menarik citra yang ditandatangani, klien Docker mereka memverifikasi integritas citra. Dalam model ini, konsumen yakin bahwa citra yang ditandatangani dalam registri Anda memang diterbitkan oleh Anda, dan bahwa data belum diubah sejak diterbitkan.

Catatan

Azure Container Registry (ACR) tidak mendukung acr import untuk mengimpor gambar yang ditandatangani dengan Docker Content Trust (DCT). Secara desain, tanda tangan tidak terlihat setelah impor, dan notaris v2 menyimpan tanda tangan ini sebagai artefak.

Citra tepercaya

Kepercayaan konten berfungsi dengan tag di repositori. Repositori citra dapat berisi citra dengan tag yang ditandatangani dan tidak ditandatangani. Misalnya, Anda mungkin hanya menandatangani citra myimage:stable dan myimage:latest, tetapi tidak myimage:dev.

Kunci penandatanganan

Kepercayaan konten dikelola melalui penggunaan seperangkat kunci penandatanganan kriptografi. Kunci ini dikaitkan dengan repositori tertentu dalam registri. Ada beberapa jenis kunci penandatanganan yang digunakan klien Docker dan registri Anda dalam mengelola kepercayaan untuk tag di repositori. Saat Anda mengaktifkan kepercayaan konten dan mengintegrasikannya ke dalam saluran penerbitan dan konsumsi kontainer Anda, Anda harus mengelola kunci ini dengan hati-hati. Untuk informasi selengkapnya, lihat Manajemen kunci di artikel ini dan Mengelola kunci untuk kepercayaan konten dalam dokumentasi Docker.

Tip

Ini adalah gambaran umum tingkat yang sangat tinggi dari model kepercayaan konten Docker. Untuk diskusi mendalam tentang kepercayaan konten, lihat Kepercayaan konten di Docker.

Mengaktifkan kepercayaan konten registri

Langkah pertama Anda adalah mengaktifkan kepercayaan konten di tingkat registri. Setelah Anda mengaktifkan kepercayaan konten, klien (pengguna atau layanan) dapat mendorong citra yang ditandatangani ke registri Anda. Mengaktifkan kepercayaan konten pada registri Anda tidak membatasi penggunaan registri hanya untuk konsumen dengan kepercayaan konten yang diaktifkan. Konsumen tanpa kepercayaan konten yang diaktifkan dapat terus menggunakan registri Anda seperti biasa. Konsumen yang telah mengaktifkan kepercayaan konten pada klien mereka, bagaimanapun, hanya akan dapat melihat citra yang ditandatangani di registri Anda.

Untuk mengaktifkan kepercayaan konten untuk registri Anda, navigasikan terlebih dahulu ke registri di portal Microsoft Azure. Di bawah Kebijakan, pilih Kepercayaan Konten>Diaktifkan>Simpan. Anda juga dapat menggunakan perintah perbarui kepercayaan konten konfigurasi az acr di Azure CLI.

Screenshot shows enabling content trust for a registry in the Azure portal.

Mengaktifkan kepercayaan konten klien

Untuk bekerja dengan citra tepercaya, penerbit citra dan konsumen perlu mengaktifkan kepercayaan konten untuk klien Docker mereka. Sebagai penerbit, Anda dapat menandatangani citra yang Anda dorong ke registri yang mengaktifkan kepercayaan konten. Sebagai konsumen, mengaktifkan kepercayaan konten membatasi tampilan registri Anda hanya untuk citra yang ditandatangani. Kepercayaan konten dinonaktifkan secara default di klien Docker, tetapi Anda dapat mengaktifkannya per sesi shell atau per perintah.

Untuk mengaktifkan kepercayaan konten untuk sesi shell, atur variabel lingkungan DOCKER_CONTENT_TRUST ke 1. Misalnya, dalam Bash shell:

# Enable content trust for shell session
export DOCKER_CONTENT_TRUST=1

Jika Anda ingin mengaktifkan atau menonaktifkan kepercayaan konten untuk satu perintah, beberapa perintah Docker mendukung argumen --disable-content-trust. Untuk mengaktifkan kepercayaan konten untuk satu perintah:

# Enable content trust for single command
docker build --disable-content-trust=false -t myacr.azurecr.io/myimage:v1 .

Jika Anda telah mengaktifkan kepercayaan konten untuk sesi shell Anda dan ingin menonaktifkannya untuk satu perintah:

# Disable content trust for single command
docker build --disable-content-trust -t myacr.azurecr.io/myimage:v1 .

Berikan izin penandatanganan citra

Hanya pengguna atau sistem yang Anda berikan izin yang dapat mendorong citra tepercaya ke registri Anda. Untuk memberikan izin push gambar tepercaya kepada pengguna (atau sistem yang menggunakan perwakilan layanan), berikan peran identitas AcrImageSigner Microsoft Entra mereka. Selain peran AcrPush (atau setara) yang diperlukan untuk mendorong citra ke registri. Untuk detailnya, lihat Peran dan izin Azure Container Registry.

Penting

Anda tidak dapat memberikan izin dorong citra tepercaya ke akun administratif berikut:

  • akun admin registri kontainer Azure
  • akun pengguna di ID Microsoft Entra dengan peran administrator sistem klasik.

Catatan

Mulai Juli 2021, peran AcrImageSigner mencakup tindakan Microsoft.ContainerRegistry/registries/sign/write dan tindakan data Microsoft.ContainerRegistry/registries/trustedCollections/write.

Detail untuk memberikan peran AcrImageSigner di portal Microsoft Azure dan diikuti Azure CLI.

Portal Azure

  1. Pilih Kontrol akses (IAM).

  2. Pilih Tambahkan>Tambahkan penetapan peran untuk membuka halaman Tambahkan penetapan peran.

  3. Tetapkan peran berikut. Dalam contoh ini, peran tersebut ditugaskan ke pengguna individu. Untuk langkah-langkah mendetail, lihat Menetapkan peran Azure menggunakan portal Azure.

    Pengaturan Nilai
    Peran AcrImageSigner
    Tetapkan akses ke User
    Anggota Alain

    Add role assignment page in Azure portal.

Azure CLI

Untuk memberikan izin penandatanganan kepada pengguna dengan Azure CLI, tetapkan peran AcrImageSigner kepada pengguna, yang tercakup ke registri Anda. Format perintahnya adalah:

az role assignment create --scope <registry ID> --role AcrImageSigner --assignee <user name>

Misalnya, untuk memberikan peran kepada pengguna non-administratif, Anda dapat menjalankan perintah berikut dalam sesi Azure CLI yang diautentikasi. Ubah nilai REGISTRY untuk mencerminkan nama registri kontainer Azure Anda.

# Grant signing permissions to authenticated Azure CLI user
REGISTRY=myregistry
REGISTRY_ID=$(az acr show --name $REGISTRY --query id --output tsv)

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee azureuser@contoso.com

Anda juga dapat memberikan hak kepada perwakilan layanan untuk mendorong citra tepercaya ke registri Anda. Menggunakan perwakilan layanan berguna untuk sistem build dan sistem tanpa pengawasan lainnya yang perlu mendorong citra tepercaya ke registri Anda. Formatnya serupa dengan memberikan izin pengguna, tetapi tentukan ID perwakilan layanan untuk nilai --assignee tersebut.

az role assignment create --scope $REGISTRY_ID --role AcrImageSigner --assignee <service principal ID>

<service principal ID> dapat berupa appId, objectId, atau salah satu layananPrincipalNames perwakilan layanan. Untuk informasi selengkapnya tentang bekerja dengan perwakilan layanan dan Azure Container Registry, lihat autentikasi Azure Container Registry dengan perwakilan layanan.

Penting

Setelah peran berubah, jalankan az acr login untuk menyegarkan token identitas lokal untuk Azure CLI sehingga peran baru dapat diterapkan. Untuk informasi tentang cara memverifikasi peran untuk identitas, lihat Menambahkan atau menghapus penetapan peran Azure menggunakan Azure CLI dan Memecahkan Masalah Azure RBAC.

Mendorong citra tepercaya

Untuk mendorong tag citra tepercaya ke registri kontainer Anda, aktifkan kepercayaan konten dan dorong citra dengan docker push. Setelah pendorongan dengan tag yang ditandatangani selesai pertama kalinya, Anda diminta untuk membuat frasa sandi untuk kunci penandatanganan akar dan kunci penandatanganan repositori. Kunci akar dan repositori dihasilkan dan disimpan secara lokal di komputer Anda.

$ docker push myregistry.azurecr.io/myimage:v1
[...]
The push refers to repository [myregistry.azurecr.io/myimage]
ee83fc5847cb: Pushed
v1: digest: sha256:aca41a608e5eb015f1ec6755f490f3be26b48010b178e78c00eac21ffbe246f1 size: 524
Signing and pushing trust metadata
You are about to create a new root signing key passphrase. This passphrase
will be used to protect the most sensitive key in your signing system. Please
choose a long, complex passphrase and be careful to keep the password and the
key file itself secure and backed up. It is highly recommended that you use a
password manager to generate the passphrase and keep it safe. There will be no
way to recover this key. You can find the key in your config directory.
Enter passphrase for new root key with ID 4c6c56a:
Repeat passphrase for new root key with ID 4c6c56a:
Enter passphrase for new repository key with ID bcd6d98:
Repeat passphrase for new repository key with ID bcd6d98:
Finished initializing "myregistry.azurecr.io/myimage"
Successfully signed myregistry.azurecr.io/myimage:v1

Setelah docker push pertama Anda dengan kepercayaan konten diaktifkan, klien Docker menggunakan kunci akar yang sama untuk dorongan berikutnya. Pada setiap dorongan berikutnya ke repositori yang sama, Anda hanya diminta untuk kunci repositori. Setiap kali Anda mendorong citra tepercaya ke repositori baru, Anda diminta untuk menyediakan frasa sandi untuk kunci repositori baru.

Menarik citra tepercaya

Untuk menarik citra tepercaya, aktifkan kepercayaan konten dan jalankan docker pull perintah seperti biasa. Untuk menarik citra tepercaya, peran AcrPull sudah cukup untuk pengguna normal. Tidak diperlukan peran tambahan seperti AcrImageSigner. Konsumen dengan kepercayaan konten diaktifkan hanya dapat menarik citra dengan tag yang ditandatangani. Berikut adalah contoh menarik tag yang ditandatangani:

$ docker pull myregistry.azurecr.io/myimage:signed
Pull (1 of 1): myregistry.azurecr.io/myimage:signed@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b: Pulling from myimage
8e3ba11ec2a2: Pull complete
Digest: sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Status: Downloaded newer image for myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b
Tagging myregistry.azurecr.io/myimage@sha256:0800d17e37fb4f8194495b1a188f121e5b54efb52b5d93dc9e0ed97fce49564b as myregistry.azurecr.io/myimage:signed

Jika klien dengan kepercayaan konten diaktifkan mencoba menarik tag yang tidak ditandatangani, operasi gagal dengan kesalahan yang serupa dengan yang berikut ini:

$ docker pull myregistry.azurecr.io/myimage:unsigned
Error: remote trust data does not exist

Di balik layar

Saat Anda menjalankan docker pull, klien Docker menggunakan pustaka yang sama seperti di Notary CLI untuk meminta pemetaan hash tag ke SHA-256 untuk tag yang Anda tarik. Setelah memvalidasi tanda tangan pada data kepercayaan, klien menginstruksikan Docker Engine untuk melakukan "pull by digest." Selama penarikan, Mesin menggunakan checksum SHA-256 sebagai alamat konten untuk meminta dan memvalidasi manifes gambar dari registri kontainer Azure.

Catatan

Azure Container Registry tidak secara resmi mendukung Notary CLI tetapi kompatibel dengan Notary Server API, yang disertakan dengan Docker Desktop. Notary versi 0.6.0 saat ini direkomendasikan.

Manajemen kunci

Seperti yang dinyatakan dalam output docker push ketika Anda mendorong citra tepercaya pertama Anda, kunci akar adalah yang paling sensitif. Pastikan untuk mencadangkan kunci akar Anda dan menyimpannya di lokasi yang aman. Secara default, klien Docker menyimpan kunci penandatanganan di direktori berikut:

~/.docker/trust/private

Cadangkan kunci akar dan repositori Anda dengan mengompresnya dalam arsip dan menyimpannya di lokasi yang aman. Misalnya, di Bash:

umask 077; tar -zcvf docker_private_keys_backup.tar.gz ~/.docker/trust/private; umask 022

Bersama dengan kunci akar dan repositori yang dihasilkan secara lokal, beberapa lainnya dihasilkan dan disimpan oleh Azure Container Registry ketika Anda mendorong citra tepercaya. Untuk diskusi terperinci tentang berbagai kunci dalam implementasi kepercayaan konten Docker, termasuk panduan manajemen tambahan, lihat Mengelola kunci untuk kepercayaan konten dalam dokumentasi Docker.

Kunci akar yang hilang

Jika Anda kehilangan akses ke kunci akar, Anda kehilangan akses ke tag yang ditandatangani di repositori apa pun yang tagnya ditandatangani dengan kunci tersebut. Azure Container Registry tidak dapat memulihkan akses ke tag citra yang ditandatangani dengan kunci akar yang hilang. Untuk menghapus semua data kepercayaan (tanda tangan) untuk registri Anda, nonaktifkan terlebih dahulu, lalu aktifkan kembali kepercayaan konten untuk registri.

Peringatan

Menonaktifkan dan mengaktifkan kembali kepercayaan konten di registri Anda menghapus semua data kepercayaan untuk semua tag yang ditandatangani di setiap repositori di registri Anda. Tindakan ini tidak dapat diubah--Azure Container Registry tidak dapat memulihkan data kepercayaan yang dihapus. Menonaktifkan kepercayaan konten tidak menghapus citra itu sendiri.

Untuk menonakifkan kepercayaan konten untuk registri Anda, navigasikan ke registri di portal Microsoft Azure. Di bawah Kebijakan, pilih Kepercayaan Konten>Dinonaktifkan>Simpan. Anda diperingatkan atas hilangnya semua tanda tangan dalam registri. Pilih OK untuk menghapus semua tanda tangan di registri Anda secara permanen.

Disabling content trust for a registry in the Azure portal

Langkah berikutnya

  • Lihat Kepercayaan konten di Docker untuk informasi tambahan tentang kepercayaan konten, termasuk perintah kepercayaan docker dan delegasi kepercayaan. Meskipun beberapa poin penting disentuh dalam artikel ini, kepercayaan konten adalah topik yang luas dan dibahas lebih mendalam dalam dokumentasi Docker.

  • Lihat dokumentasi Azure Pipelines untuk contoh menggunakan kepercayaan konten saat Anda membuat dan mendorong citra Docker.