Kebijakan Pull dan Digest

Menarik image berdasarkan digest agar reproducible dan membaca metadata manifest.

Daftar isi

Rujukan image berbasis tag, label teks yang menunjuk satu varian image, nyaman ditulis tetapi menyimpan risiko, karena isi yang ditunjuknya dapat berubah tanpa sepengetahuan penggunanya. Topik ini membahas digest, penanda isi image yang tidak berpindah, cara mendapatkannya, dan cara menarik image berdasarkan digest. Bagian akhir merangkum kebijakan pemilihan rujukan untuk kebutuhan pengembangan maupun deployment yang diaudit. Contoh image dasarnya menggunakan alpine, image resmi yang ringkas dan lazim dipakai.

Tag bergerak dan digest tetap#

Digest adalah penanda isi image berformat sha256:... yang dihitung dari manifest, daftar isi image yang merujuk setiap layer beserta penandanya. Manifest itu tersimpan pada registry, gudang image yang melayani unggahan dan unduhan melalui jaringan. Karena merujuk seluruh layer, digest manifest mengunci isi image secara tidak langsung, dan setiap perubahan isi menghasilkan digest yang berbeda. Nilai yang sama tidak pernah dipakai untuk isi yang berbeda, sehingga satu digest selalu menunjuk tepat satu isi.

Tag berlaku sebaliknya. Pemilik repository, wadah untuk satu nama image beserta seluruh versinya, bebas memindahkan tag ke image baru, menimpanya, atau menghapusnya, sehingga alpine:3.24 hari ini tidak menjamin menunjuk byte yang sama minggu depan. Rujukan berformat library/alpine@sha256:... tidak mengenal perpindahan semacam itu, karena digestnya menyatu dengan nama dan mengunci isi yang ditunjuk. Penarikan pada waktu berapa pun di komputer mana pun menghasilkan byte yang sama persis, dan sifat inilah yang disebut reproducible, dapat direproduksi dengan hasil yang sama.

Mendapatkan digest image#

Cara pertama adalah docker images --digests, perintah penampil daftar image lokal yang menambahkan kolom khusus digest. Perintah ini dipakai untuk memeriksa image mana yang sudah terkunci dan image mana yang belum memilikinya.

bash

# tidak-dijalankan: Docker tidak tersedia di sandbox
# menampilkan digest pada daftar image lokal
docker images --digests

Keluarannya berupa tabel dengan kolom REPOSITORY, TAG, DIGEST, IMAGE ID, CREATED, dan SIZE. Kolom DIGEST memuat penanda sha256:... dari manifest yang dirujuk pasangan repository dan tag pada baris itu. Kolom yang sama bisa kosong untuk image buatan lokal yang belum pernah diunggah ke registry, karena digest hanya diterbitkan registry setelah proses unggah. Image ID, sebaliknya, selalu terisi karena dihitung dari isi image itu sendiri.

Cara kedua adalah docker inspect, perintah yang menampilkan seluruh metadata image dalam bentuk JSON. Perintah ini berguna saat digest perlu dibaca secara terprogram oleh skrip.

bash

# tidak-dijalankan: Docker tidak tersedia di sandbox
# membaca metadata image lengkap dengan digestnya
docker inspect alpine:3.24

Pada Docker Engine 29 yang memakai penyimpanan containerd, kunci Descriptor pada keluaran itu memuat digest index OCI milik image, yaitu manifest yang mendaftar seluruh varian arsitekturnya. Kunci RepoDigests sendiri mencantumkan rujukan name@digest hasil penarikan dari registry. Kunci ini hanya terisi untuk image yang ditarik dari registry, sehingga kelengkapannya menjadi penanda asal image. Untuk keperluan sehari-hari, kolom DIGEST pada docker images --digests sudah cukup.

Cara ketiga bekerja tanpa Docker sama sekali, yaitu membaca API Docker Hub dengan curl. Tag latest, penanda bawaan yang berpindah ke rilis terbaru, menjadi contohnya.

bash

curl -s "https://hub.docker.com/v2/repositories/library/alpine/tags/latest" \
  | python3 -c "import json,sys; data=json.load(sys.stdin); print('name :', data['name']); print('digest:', data['digest'])"

text Keluaran

name : latest
digest: sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a

Keluaran di atas memuat digest sungguhan milik tag latest pada repository resmi alpine, dan nilai itu dapat langsung dirujuk pada perintah pull, proses menarik image dari registry ke komputer lokal. Nilainya berpindah setiap kali latest menunjuk image baru, sehingga keluaran di atas adalah cuplikan pada saat topik ini ditulis. Digest yang sudah tercatat justru tetap sah untuk isinya, karena nilai lama tidak pernah dipakai ulang untuk isi yang berbeda.

Menarik image berdasarkan digest#

Penarikan berbasis digest dilakukan dengan menulis rujukan name@digest sebagai ganti nama ber-tag. Perintah berikut memakai digest yang diperoleh dari percobaan di atas. Hasilnya selalu sama, sekalipun perintah dijalankan berbulan-bulan kemudian.

bash

# tidak-dijalankan: Docker tidak tersedia di sandbox
# menarik image alpine pada digest yang terkunci
docker pull library/alpine@sha256:be2656061b536c1883c4034790e21d0a09c5aaaf51968b89368a3c0371ea2c9a

Daemon meminta manifest tepat pada digest itu, mengunduh layer-layer yang dicantumkannya, lalu memverifikasi digest setiap layer sesudah diunduh. Layer yang isinya tidak cocok dengan digestnya ditolak, sehingga rujukan digest aman terhadap isi yang ditukar sekalipun registrynya tidak sepenuhnya dipercaya. Bentuk keluarannya sama dengan penarikan berbasis tag, yaitu baris per layer dan ringkasan digest pada baris akhir.

Kebijakan pemilihan rujukan#

Tag dan digest melayani kebutuhan yang berbeda, dan keduanya dipakai berdampingan dalam satu alur kerja. Tabel berikut merangkum bentuk rujukan yang tepat untuk setiap kebutuhan.

Kebutuhan	Bentuk rujukan	Contoh
Pengembangan harian	tag spesifik	`library/alpine:3.24`
Deployment yang diaudit	digest	`library/alpine@sha256:...`

Kebijakan praktisnya, tag spesifik dipakai untuk pengembangan dan digest untuk deployment yang diaudit. Tag spesifik seperti alpine:3.24 memberi kejelasan versi dan tetap menerima pembaruan tambalan, sehingga pengerjaan harian tidak terhambat proses pembaruan manual. Deployment yang diaudit menuntut kepastian byte, sehingga pipeline menuliskan digest image yang lolos pengujian dan menarik tepat nilai itu saat penyebaran.

Jaminan di balik rujukan digest bukan kebetulan, melainkan ketentuan dari OCI image specification, standar terbuka yang menetapkan bentuk manifest dan aturan digestnya. Manifest mencantumkan digest setiap layer, sehingga digest manifest mengunci seluruh isi image di bawahnya. Spesifikasi yang sama dipatuhi Docker Hub, distribution, dan registry awan, sehingga kebijakan berbasis digest dapat dipakai lintas registry tanpa penyesuaian.

Ringkasan#

Digest adalah sha256 dari manifest image, berubah setiap isi berubah, dan tidak pernah dipakai ulang untuk isi lain.
Tag dapat dipindahkan oleh pemilik repository, sedangkan rujukan repositori@sha256:... mengunci isi penarikan secara permanen.
Digest diperoleh dari kolom DIGEST pada docker images --digests, kunci Descriptor pada docker inspect, atau API Docker Hub.
Kebijakan praktisnya, tag spesifik untuk pengembangan dan digest untuk deployment yang diaudit.

Referensi#

docker image pull — Docker Docs — Referensi perintah yang menarik image dari registry, termasuk berdasarkan digest.
docker image inspect — Docker Docs — Referensi perintah yang menampilkan metadata image dalam bentuk JSON.
OCI image manifest — Open Container Initiative — Spesifikasi manifest dan aturan digest yang menjadi dasar rujukan image.