Cara Kerja Container Registry: Push/Pull Image Secara Langsung

• Container registry terlihat sederhana di permukaan, tetapi untuk men-debug masalah seperti tag yang salah, ketidakcocokan platform, layer yang hilang, atau kegagalan penghapusan nyata, kita harus memahami cara kerjanya di dalam
• Inti registry adalah penyimpanan blob content-addressable, tempat semua layer, file konfigurasi, dan artefak disimpan dengan digest sebagai alamatnya
• Push image berlangsung dengan urutan unggah blob lalu bungkus dengan manifest, sedangkan pull adalah struktur kebalikannya: mengambil manifest terlebih dahulu lalu mengunduh blob satu per satu
• Penghapusan image tidak sepenuhnya selesai hanya dengan untag; kita harus lebih dulu memeriksa layer yang masih dibagikan oleh manifest lain, lalu menghapus blob secara langsung
• Image multi-platform diimplementasikan dengan tetap mempertahankan endpoint API yang ada, hanya menambahkan satu lapisan indireksi tambahan berupa image index (manifest list)

---

Ringkasan Registry API

• Sebagian besar container registry modern mengimplementasikan OCI Distribution Specification, yang mendefinisikan protokol API untuk menstandarkan distribusi konten
• Registry API pada praktiknya ringkas dan mudah dipahami, dan cukup bisa dimanipulasi langsung hanya dengan curl

Upload dan Download Blob

• Registry pada dasarnya adalah penyimpanan blob content-addressable, yang meng-hash file secara lokal lalu mengunggahnya dengan digest sebagai alamat
• Metode upload paling sederhana adalah Monolithic PUT, dengan struktur dua tahap: menginisialisasi sesi lewat POST, lalu mengirim blob lewat PUT
  • Untuk file besar, metode upload chunk POST + PATCH + PUT lebih efisien, tetapi untuk blob kecil Monolithic PUT sudah memadai
• Jika upload berhasil, respons HTTP/2 201 Created akan dikembalikan bersama header Location yang menunjuk ke lokasi blob baru
• Download bisa langsung dilakukan lewat GET /v2/<repo>/blobs/<digest> selama digest-nya diketahui

Push Image

• Prosedur push image: (1) upload blob layer rootfs masing-masing → (2) upload blob image configuration → (3) push file manifest yang menggabungkan semua digest ke dalam satu dokumen JSON
• Manifest diunggah ke endpoint PUT /v2/<repo>/manifests/<tag>, dan pada saat itulah tag dibuat
• Klien nyata (misalnya docker push) melakukan upload blob secara paralel, tetapi untuk memahami prinsipnya pemrosesan berurutan juga memungkinkan
• Contoh susunan direktori image: config.json, layer-1.tar.gz, layer-2.tar.gz, manifest.json

Melihat Daftar Tag

• Endpoint GET /v2/<repo>/tags/list memungkinkan kita melihat seluruh daftar tag dari repositori tertentu
• Fitur ini tidak diekspos di CLI docker, dan hanya bisa diakses melalui alat seperti curl, crane, atau regctl
  • crane dan regctl membungkus endpoint yang sama dengan perintah ls

Pull Image

• Prosedur pull adalah kebalikan dari push: (1) ambil manifest lewat GET /v2/<repo>/manifests/<tag> → (2) unduh semua blob menggunakan digest yang tercantum di manifest
• Manifest modern juga dimanfaatkan sebagai penyimpanan umum yang merujuk blob untuk artefak arbitrer seperti chart Helm, SBOM, provenance attestation, bobot LLM, selain layer rootfs dan konfigurasi image

Menghapus Image

• Penghapusan image tidak sederhana, dan menghapus tag (untag) saja tidak akan menghapus manifest itu sendiri
• Prosedur penghapusan penuh:
  • (1) hapus tag dengan DELETE /v2/<repo>/manifests/<tag>
  • (2) ambil manifest berdasarkan digest untuk memeriksa semua blob yang dirujuk
  • (3) hapus secara selektif hanya blob yang tidak dibagikan oleh manifest lain
  • (4) hapus blob manifest dengan DELETE /v2/<repo>/blobs/<manifest-digest>
• Karena registry adalah penyimpanan content-addressable, layer rootfs yang sama bisa dibagikan oleh banyak image, dan penghapusan dapat memengaruhi semua image yang merujuk layer tersebut
• Sebagai alternatif, semua tag bisa dihapus lalu mengandalkan pengaturan garbage collection milik registry, tetapi di registry publik fitur ini tidak selalu aktif

Image Multi-Platform

• Image multi-platform diimplementasikan tanpa mengubah struktur Registry API — tanpa menambah atau mengubah endpoint, API yang ada tetap digunakan
• Cara penyusunannya:
  • Tiap varian platform tunggal (amd64, arm64, dan seterusnya) lebih dulu di-push berdasarkan digest bersama manifest terpisah
  • Setelah itu, manifest tingkat atas yang disebut image index (manifest list) di-push bersama tag
• Saat memanggil GET /v2/<repo>/manifests/<tag>, hasilnya bisa berupa manifest platform tunggal atau image index, dan pemanggil harus membedakannya dari content type dokumen yang dikembalikan
• Hasil akhirnya, dukungan multi-platform hanya menambahkan satu lapisan indireksi dan satu tahap upload/download dokumen index ke struktur yang sudah ada

Melindungi Registry API

• OCI Distribution Spec tidak mendefinisikan metode autentikasi secara ketat, tetapi kebanyakan registry nyata menggunakan autentikasi HTTP Basic
• Untuk mencegah kredensial dikirim dalam bentuk teks biasa, registry harus dijalankan di atas HTTPS