Registry

Image yang dibangun di satu komputer perlu tempat penyimpanan yang dapat dijangkau komputer lain, dan peran itu diisi oleh registry, gudang image yang melayani permintaan unduhan dan unggahan melalui jaringan. Topik ini menjelaskan cara kerja registry, konvensi penamaan image pada Docker Hub, dan alur pull, proses mengunduh image dari registry ke komputer lokal. Sebuah demo dengan curl menampilkan percakapan pertama antara klien dan API registry secara langsung.

Peran registry#

Registry menyimpan repository, wadah untuk satu nama image yang memuat seluruh versinya. Setiap versi di dalam repository ditandai tag, label teks seperti 3.20 atau latest yang menunjuk satu varian image. Docker Hub adalah registry default yang dipakai daemon apabila nama image tidak menyebut registry lain, sekaligus rumah bagi image resmi yang dikurasi Docker. Selain Docker Hub, tersedia registry lain baik yang berjalan di awan maupun yang dipasang sendiri di jaringan internal, dan semuanya berkomunikasi dengan API yang serupa.

Selain melayani unduhan, registry menerima unggahan melalui push, proses mengirim image dari komputer lokal ke registry. Pasangan pull dan push menjadikan registry titik pertukaran image antar komputer. Image yang dibangun di satu komputer dapat dijalankan di komputer lain tanpa membangunnya ulang, asalkan keduanya menjangkau registry yang sama.

Perintah pada CLI Docker tidak berkomunikasi langsung dengan registry. Perintah seperti docker pull dan docker push diteruskan ke daemon, proses latar belakang yang mengerjakan seluruh pekerjaan container, dan daemon itulah yang bertukar data dengan registry. Pola ini berlaku untuk seluruh operasi image, sehingga koneksi ke registry selalu dibuat oleh daemon dan bukan oleh klien CLI.

Konvensi penamaan image#

Nama image mengikuti format [registry/][namespace/]repositori:tag, dan setiap bagian yang tidak ditulis diisi nilai default. Tanpa awalan registry, daemon memakai Docker Hub yang beralamat docker.io. Tanpa namespace (bagian yang menunjukkan pemilik repository), daemon memakai namespace library yang menampung image resmi. Tanpa tag, daemon memakai tag latest. Tabel berikut membandingkan nama yang ditulis dengan nama lengkap yang sesungguhnya dipakai daemon.

Format seragam ini dimungkinkan oleh spesifikasi Open Container Initiative (OCI), badan standardisasi yang menetapkan bentuk image container. Spesifikasi tersebut menetapkan manifest sebagai daftar isi image yang merujuk setiap layer beserta digest-nya. Digest adalah penanda isi yang dihitung dari hash, sehingga perubahan sekecil apa pun menghasilkan penanda yang berbeda. Registry menyimpan manifest dan layer itu, sedangkan daemon menyusunnya kembali saat menarik image.

Alur pull antara daemon dan registry#

Perintah docker pull alpine:3.20 memicu serangkaian langkah antara daemon dan registry sebagai berikut.

1. CLI meneruskan perintah ke daemon, dan daemon melengkapi nama singkat menjadi docker.io/library/alpine:3.20.
2. Daemon meminta manifest untuk nama dan arsitektur yang diminta.
3. Registry menjawab dengan manifest yang mencantumkan daftar layer beserta digest masing-masing.
4. Daemon memeriksa layer mana yang sudah ada di host (komputer tempat Docker berjalan), mengunduh layer yang belum ada, lalu memverifikasi digestnya satu per satu.
5. Setelah seluruh layer terverifikasi, image dinyatakan selesai ditarik dan siap dijalankan.

# tidak-dijalankan: daemon Docker tidak tersedia di sandbox
docker pull alpine:3.20

Keluaran perintah tersebut memuat satu baris untuk setiap layer, berupa status unduhan dengan progres atau keterangan bahwa layer sudah ada, dan ditutup dengan ringkasan digest yang ditarik. Beberapa layer dapat diunduh bersamaan karena unduhannya tidak saling menunggu, sedangkan urutan penyusunannya tetap mengikuti lapisan pada manifest. Baris-baris itu sesuai dengan langkah ketiga hingga kelima di atas, sehingga alur pull dapat dibaca langsung dari terminal.

Percakapan langsung dengan API registry#

Registry melayani permintaan melalui API HTTP bernama Registry API v2, sehingga percakapan pertamanya dapat dicoba dengan curl tanpa Docker sama sekali. Alamat https://registry-1.docker.io/v2/ adalah titik masuk API Docker Hub yang menyatakan kesiapan layanannya. Berikut percobaannya.

curl -s https://registry-1.docker.io/v2/

{"errors":[{"code":"UNAUTHORIZED","message":"authentication required","detail":null}]}

Registry menjawab dengan JSON berisi satu error berkode UNAUTHORIZED. Jawaban ini bukan kegagalan koneksi, melainkan mekanisme normal registry yang mewajibkan token autentikasi sebelum melayani konten. Kode status HTTP dari jawaban yang sama dapat ditampilkan dengan opsi format keluaran milik curl.

curl -s -o /dev/null -w "Kode status HTTP: %{http_code}\n" https://registry-1.docker.io/v2/

Kode status HTTP: 401

Status 401 menyatakan permintaan belum terautentikasi. Saat daemon menarik image, daemon menyelesaikan pertukaran token ini secara otomatis sehingga unduhan berjalan tanpa langkah manual. Untuk membaca isi repository tanpa autentikasi, Docker Hub menyediakan API layanan webnya sendiri, misalnya untuk menampilkan tag terbaru dari repository resmi alpine.

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

latest
3.24.3
3.24

Daftar di atas ditarik langsung dari Docker Hub saat contoh ini dibuat, sehingga isinya dapat berubah seiring dirilisnya tag baru. Ketiga tag itu memperlihatkan konvensi yang telah dibahas, yaitu tag latest untuk varian yang mengikuti rilis terbaru dan tag versi eksplisit seperti 3.24.3 untuk versi yang terkunci.

Ringkasan#

• Registry menyimpan repository yang memuat versi image, dan Docker Hub menjadi registry default dengan namespace library untuk image resmi.
• Nama lengkap image berformat [registry/][namespace/]repositori:tag, dan bagian yang tidak ditulis diisi docker.io, library, serta latest.
• Saat pull, daemon meminta manifest, mengunduh layer yang belum ada di host, lalu memverifikasi digest setiap layer.
• Tanpa token, API registry menjawab error UNAUTHORIZED dengan status HTTP 401, dan daemon menangani pertukaran token itu secara otomatis.

Referensi#

• Docker Hub — Docker Docs — Dokumentasi Docker Hub, registry default yang menyimpan dan mendistribusikan image Docker.
• docker image pull — Docker Docs — Referensi perintah yang menarik image dari registry ke host.
• OCI image manifest — Open Container Initiative — Spesifikasi manifest yang menjadi dasar alur pull.