Docker Pull: Registry, Autentikasi, dan Pemecahan Masalah

Perintah docker pull cukup mudah dipahami, tetapi ada banyak hal yang terjadi di balik layar yang bahkan para ahli berpengalaman pun sering tidak tahu.

Setiap pengembang seharusnya mengetahui ini. Anda menarik (pull) image setiap hari, tetapi saat sesuatu gagal, sulit untuk mengetahui penyebabnya. Entah autentikasi gagal tanpa alasan yang jelas, batas laju (rate limit) aktif, atau Anda berakhir dengan versi image yang salah di produksi. Setiap kegagalan menyita waktu Anda untuk memperbaikinya, padahal seharusnya tidak terjadi sejak awal.

Memahami bagaimana docker pull benar-benar bekerja akan memberi Anda kendali. Anda akan tahu dari mana image berasal, cara menariknya, dan cara menelusuri masalah sebelum mencapai produksi.

Dalam artikel ini, saya akan menjelaskan cara kerja penarikan image di balik layar, bagaimana registry terlibat, dan cara menarik image baik di pengembangan lokal maupun lingkungan produksi.

Jika Anda benar-benar baru mengenal Docker, saya sangat menyarankan Anda mengikuti kursus Introduction to Docker kami, karena akan membahas dasar-dasar yang Anda perlukan untuk memahami artikel ini.

Cara Kerja docker pull di Balik Layar

Di bagian ini, saya akan membahas mekanisme perintah docker pull dan menghilangkan kebingungan tentang apa yang terjadi di balik layar.

Apa yang terjadi selama docker pull

Sintaks dasarnya sederhana:

docker pull python:3.14.2-bookworm

Perintah ini secara default berkomunikasi dengan Docker Hub, mengunduh image Python, dan menyimpannya secara lokal di mesin Anda. Namun ada lebih banyak hal yang terjadi daripada yang terlihat.

Alurnya seperti ini:

• Klien Docker Anda mengirim permintaan ke registry (Docker Hub, kecuali Anda menentukan lainnya)

• Registry merespons dengan manifest image, yang mencantumkan semua layer penyusun image

• Klien Anda kemudian mengunduh setiap layer yang belum dimiliki dan menyimpannya di /var/lib/docker pada sistem Linux, dan di direktori yang dikelola Docker Desktop (misalnya, di bawah ~Library/Containers/… pada macOS dan C:\Users\[Username]\AppData\... pada Windows.)

Tag :latest adalah default Docker saat Anda tidak menentukan versi. Jalankan docker pull python tanpa tag, dan Anda akan mendapat python:latest. Ini terdengar praktis, tetapi berisiko. Tag :latest bukan berarti "versi stabil paling mutakhir." Artinya "apa pun yang ditandai maintainer image sebagai latest." Itu bisa berubah antar pull, merusak build Anda tanpa peringatan.

Layer image dan content-addressable storage

Image Docker dibangun dari layer.

Setiap layer merepresentasikan perubahan dari layer sebelumnya. Saat Anda membangun sebuah image, setiap instruksi RUN, COPY, atau ADD pada Dockerfile membuat layer baru. Image final adalah tumpukan layer tersebut yang dirangkai berurutan.

Sebagai contoh, lihat perintah di balik image Python 3.14 di atas - banyak hal yang terjadi.

Content-addressable storage adalah kunci yang membuat ini bekerja. Setiap layer mendapatkan hash unik berdasarkan isinya. Jika dua image berbagi base layer yang sama (seperti ubuntu:24.04), Docker hanya menyimpan layer itu sekali. Saat Anda menarik image baru yang menggunakan base yang sama, Docker melewatkan pengunduhannya.

Ini menghemat bandwidth dan penyimpanan. Tarik sepuluh image Python dengan tag berbeda, dan Docker memakai ulang layer yang sama di semuanya. Anda hanya mengunduh yang benar-benar berbeda.

docker pull vs docker image pull

Kedua perintah ini secara fungsional identik. Keduanya menarik image dari registry dan menyimpannya secara lokal.

Perbedaannya bersifat organisasional. Docker memperkenalkan grup perintah docker image sebagai bagian dari restrukturisasi CLI agar perintah lebih intuitif. Alih-alih memiliki docker pull, docker rmi, dan docker images yang tersebar, mereka mengelompokkan perintah terkait image di bawah docker image pull, docker image rm, dan docker image ls.

Gunakan mana pun yang Anda suka. docker pull lebih pendek dan lebih umum di dokumentasi. docker image pull lebih eksplisit dan lebih cocok di skrip saat kejelasan penting. Pilih satu gaya dan konsisten di seluruh tim Anda.

Penjelasan referensi image Docker

Sebuah referensi image memiliki hingga lima bagian: HOST/NAMESPACE/REPOSITORY:TAG@DIGEST.

Berikut arti tiap bagiannya:

• HOST: Alamat registry (mis., docker.io, gcr.io, quay.io). Jika dihilangkan, Docker akan default ke Docker Hub.

• NAMESPACE: Biasanya nama pengguna atau organisasi Anda (mis., library untuk image resmi, atau mycompany untuk yang privat).

• REPOSITORY: Nama image sebenarnya (mis., python, nginx, redis).

• TAG: Penanda versi (mis., 3.14.2-bookworm, latest). Default ke :latest jika Anda melewatinya.

• DIGEST: Hash SHA256 dari manifest image (mis., @sha256:abc123...). Ini tidak dapat diubah - tag bisa berubah, digest tidak.

Sebagian besar pull terlihat seperti ini:

docker pull python:3.14.2-bookworm

Ini diperluas menjadi docker.io/library/python:3.14.2-bookworm di balik layar.

Untuk registry privat, Anda memerlukan referensi lengkap:

docker pull myregistry.example.com/myteam/myimage

Menggunakan referensi yang presisi (tag atau digest spesifik) menjaga deployment Anda tetap dapat direproduksi. Tarik python:3.14.2-bookworm hari ini dan bulan depan, dan Anda akan mendapatkan image yang sama. Tarik python:latest dua kali, dan kemungkinan besar tidak.

Registry Docker dan Asal Usul Image

Registry adalah tempat Docker menyimpan dan mendistribusikan image - inilah sumber untuk setiap perintah docker pull yang Anda jalankan.

Docker Hub sebagai registry default

Docker Hub adalah registry default untuk semua perintah docker pull kecuali Anda menentukan lainnya.

Jalankan docker pull python:3.14.2-bookworm, dan Docker otomatis menerjemahkannya menjadi docker.io/library/python:3.14.2-bookworm. Anda tidak perlu login untuk image publik - Docker Hub menyajikannya secara anonim, meski dengan batas laju bagi pengguna yang tidak diautentikasi.

Ada dua jenis image di Docker Hub: Official Images dan community images.

• Official Images berasal dari penerbit terverifikasi dan dikelola oleh Docker atau vendor perangkat lunak itu sendiri. Image ini berada di bawah namespace library (yang disembunyikan Docker). Saat Anda menarik python, nginx, atau redis, Anda mendapatkan Official Images yang mengikuti praktik terbaik Docker untuk keamanan dan pembaruan rutin.

• Community images adalah sisanya. Siapa pun dapat memublikasikan image ke Docker Hub di bawah nama pengguna atau organisasinya. Menarik johndoe/python-custom berarti Anda mempercayai johndoe untuk memelihara image itu dengan benar. Beberapa community images bagus dan terawat. Yang lain tidak diperbarui selama bertahun-tahun dan mengandung kerentanan yang diketahui.

Kepercayaan penting di sini. Official Images mendapatkan patch keamanan rutin dan memiliki dokumentasi yang jelas. Namun dengan community images, Anda harus memverifikasi sendiri siapa yang memeliharanya dan apakah aman digunakan.

Registry privat dan kustom

Sebagian besar perusahaan tidak ingin image kontainernya berada di Docker Hub publik.

Registry privat adalah solusinya. Anda menentukan siapa yang boleh menarik image, mengontrol kebijakan retensi, dan menjaga kode properti tetap di dalam infrastruktur Anda. Ini penting untuk kepatuhan, keamanan, dan pengelolaan akses lintas tim.

Solusi registry privat yang umum meliputi:

• Harbor: Registry open-source dengan pemindaian keamanan dan kontrol akses bawaan
• JFrog Artifactory: Solusi enterprise yang menangani image Docker plus jenis artefak lainnya
• Registry cloud: AWS ECR, Google Container Registry (GCR), Azure Container Registry (ACR)

Tentu saja, referensi image akan berubah saat Anda menggunakan registry kustom. Alih-alih python:3.14.2-bookworm, kini Anda perlu menentukan path lengkap:

docker pull myregistry.company.com/team/python:3.14.2-bookworm

Hostname registry diletakkan terlebih dahulu, lalu namespace Anda (biasanya nama tim atau proyek), kemudian repository dan tag. Docker tidak akan default ke Docker Hub saat melihat hostname kustom - ia langsung menuju registry privat Anda.

Autentikasi, Batas Laju, dan Kontrol Akses

Autentikasi diperlukan untuk push dan pull image, dan menjadi sangat penting saat Anda terkena batas laju atau mengakses registry privat.

Masuk dan mengelola kredensial

Anda dapat menggunakan perintah docker login untuk melakukan autentikasi dengan sebuah registry:

docker login

Perintah ini akan meminta nama pengguna dan kata sandi Docker Hub Anda. Untuk registry privat, cukup tentukan hostname:

docker login myregistry.company.com

Docker menyimpan kredensial Anda secara lokal setelah login. Di Linux, tersimpan di ~/.docker/config.json. Di macOS, Docker menggunakan keychain sistem untuk keamanan yang lebih baik.

Masalahnya adalah file konfigurasi menyimpan kredensial dalam pengkodean base64 secara default, yang bukan enkripsi. Siapa pun yang memiliki akses ke direktori home Anda dapat mendekodenya. Untuk mengurangi risiko, Anda bisa menggunakan credential helper - Docker mendukung keychain OS native yang menyimpan kata sandi dengan aman.

Berikut beberapa praktik terbaik untuk pengelolaan kredensial:

• Gunakan credential helper (docker-credential-osxkeychain, docker-credential-wincred)

• Jangan pernah meng-commit config.json ke version control

• Gunakan access token alih-alih kata sandi bila memungkinkan

• Rotasi kredensial secara berkala, terutama untuk akun bersama

Batas laju Docker Hub

Docker Hub membatasi berapa banyak image yang dapat Anda tarik dalam jangka waktu tertentu.

Pengguna anonim (tanpa login) mendapatkan 100 pull per enam jam per alamat IP. Pengguna gratis yang diautentikasi mendapatkan 200 pull per enam jam. Paket berbayar mendapatkan batas yang lebih tinggi atau tanpa batas tergantung tingkatannya.

Batas ini penting saat Anda menjalankan pipeline CI/CD, sering menarik image selama pengembangan, atau bekerja di infrastruktur bersama di mana banyak pengguna berbagi IP yang sama. Saat Anda mencapai batas, pull akan gagal hingga jendela waktu direset.

Anda dapat memeriksa status batas laju saat ini:

TOKEN=$(curl "<https://auth.docker.io/token?service=registry.docker.io&scope=repository:ratelimitpreview/test:pull>" | jq -r .token)
curl --head -H "Authorization: Bearer $TOKEN" <https://registry-1.docker.io/v2/ratelimitpreview/test/manifests/latest>

Berikut beberapa cara untuk meningkatkan batas laju Anda (tidak akan menjadi masalah bagi sebagian besar pengembang):

• Autentikasi pull Anda: Masuk untuk mendapatkan batas lebih tinggi, bahkan dengan akun gratis
• Gunakan cermin registry: Siapkan cache pull-through yang menyimpan image secara lokal
• Beralih ke registry privat: Hosting registry sendiri untuk sepenuhnya menghindari batas Docker Hub
• Cache image secara lokal: Tarik sekali, gunakan berkali-kali alih-alih menarik berulang-ulang

Perbaikan termudah adalah cukup masuk. Ini saja sudah menggandakan batas laju Anda.

Opsi Penarikan Image Lanjutan

Opsi lanjutan ini memberi Anda presisi dan kendali, yang sangat dibutuhkan di lingkungan produksi.

Menarik image berdasarkan digest

Digest adalah pengenal yang tidak dapat diubah berdasarkan hash konten image.

Tag bisa berubah. Seseorang mendorong image baru dengan tag yang sama, dan tiba-tiba python:3.14.2-bookworm merujuk ke konten yang berbeda dari kemarin. Digest tidak dapat berubah - itu adalah hash SHA256 dari manifest image. Digest yang sama selalu berarti image yang persis sama.

Tarik berdasarkan digest seperti ini:

docker pull python@sha256:6d58c1a9444bc2664f0fa20c43a592fcdb2698eb9a9c32257516538a2746c19a

docker pull --platform linux/amd64 python:3.14.2-bookworm

Ini paling penting di CI/CD dan produksi. Anda menguji terhadap image tertentu, Anda menerapkan image yang persis sama. Tanpa kejutan, tanpa pergeseran antar lingkungan. Jika deployment Anda bergantung pada versi spesifik, gunakan digest - bukan tag.

Penarikan image multi-arsitektur

Image multi-arch membundel versi untuk arsitektur CPU berbeda dalam satu referensi image.

Tarik python:3.14.2-bookworm, dan Docker otomatis memilih versi yang tepat untuk sistem Anda - amd64 untuk mesin x86, arm64 untuk Apple Silicon atau server ARM. Registry menyajikan arsitektur yang benar tanpa perlu tindakan apa pun dari Anda.

Tetapi terkadang Anda memerlukan arsitektur tertentu. Gunakan flag --platform:

docker pull --platform linux/amd64 python:3.14.2-bookworm

Ini berguna saat Anda mengembangkan di Apple Silicon tetapi perlu menguji versi amd64 yang akan berjalan di produksi, atau saat Anda membangun image untuk arsitektur yang berbeda dari mesin build Anda.

Menarik banyak tag

Flag --all-tags menarik semua tag untuk sebuah repository:

docker pull --all-tags python

Ini mengunduh semua tag Python - puluhan versi, varian, dan arsitektur. Anda akan berakhir dengan gigabita image.

Jangan gunakan ini kecuali benar-benar perlu. Bandwidth berbiaya, penyimpanan cepat penuh, dan Anda mungkin tidak memerlukan setiap versi Python yang pernah dirilis. Tarik tag spesifik yang benar-benar Anda gunakan saja.

Membatalkan pull

Tekan Ctrl+C atau CMD+C untuk membatalkan pull yang sedang berlangsung.

Docker menghentikan pengunduhan layer baru tetapi menyimpan layer yang sudah selesai. Saat Anda menarik image yang sama lagi, proses dilanjutkan dari titik terakhir alih-alih mulai dari awal.

Ini berguna saat Anda tidak sengaja menarik image yang salah, saat pull terlalu lama di koneksi lambat, atau saat Anda sadar ternyata tidak memerlukan image itu sekarang. Batalkan, perbaiki perintah, dan tarik lagi tanpa menyia-nyiakan pekerjaan yang sudah dilakukan.

Pertimbangan Kinerja dengan docker pull 

Jaringan dunia nyata memiliki kendala, seperti batas bandwidth, proxy, dan koneksi lambat. Ini bisa membuat penarikan image lebih lama dari seharusnya, jadi berikut yang bisa Anda lakukan.

Mengoptimalkan kinerja pull

Docker mengunduh layer image secara bersamaan (concurrent) secara default.

Alih-alih menarik layer satu per satu, Docker membuka beberapa koneksi dan mengunduh beberapa layer sekaligus. Ini mempercepat pull pada koneksi cepat, tetapi Anda tidak akan melihat banyak perbedaan pada jaringan lambat di mana bandwidth menjadi penghambat.

Dua strategi umum yang semakin membantu:

• Caching menyimpan image yang sudah ditarik secara lokal. Tarik sebuah image sekali, gunakan ratusan kali. Docker memeriksa apakah Anda sudah memiliki layer sebelum mengunduh apa pun. Jika image tidak berubah, pull selesai seketika.
• Preloading image berarti menariknya di luar jam sibuk atau sebagai bagian dari proses deployment Anda. Sistem CI/CD sering mencache base image pada build agent sehingga pengembang tidak menunggu pull setiap kali menjalankan build. Server produksi dapat menghangatkan cache saat deployment untuk menghindari menarik image saat lalu lintas datang.

Menarik image di balik proxy

Jaringan perusahaan mengarahkan lalu lintas melalui proxy untuk keamanan, pemantauan, dan kontrol akses.

Docker perlu mengetahui proxy ini untuk menarik image. Tanpa konfigurasi proxy, pull akan gagal dengan timeout koneksi atau kesalahan DNS karena Docker mencoba menjangkau registry secara langsung alih-alih melalui proxy.

Anda mengonfigurasi proxy pada dua level: klien Docker dan daemon Docker. Klien (perintah docker Anda) menggunakan pengaturan proxy HTTP sistem secara otomatis. Daemon memerlukan konfigurasi eksplisit di /etc/docker/daemon.json atau melalui berkas layanan systemd.

Menelusuri Masalah Pull yang Umum

Berikut daftar periksa praktis saat pull gagal - karena itu akan terjadi, dan Anda perlu tahu apa yang harus dicek terlebih dahulu.

Kesalahan umum dan cara mendiagnosisnya

Kegagalan autentikasi muncul sebagai kesalahan "unauthorized" atau "access denied".

Periksa apakah Anda sudah login dengan docker login. Jika sudah, kredensial Anda mungkin kedaluwarsa atau salah. Keluar dengan docker logout, lalu masuk kembali. Untuk registry privat, pastikan Anda menggunakan hostname yang benar pada perintah login.

Tag hilang memberikan kesalahan "manifest unknown" atau "not found".

Tag tersebut tidak ada. Periksa kembali nama tag karena salah ketik sering terjadi. Cek antarmuka web registry untuk melihat tag apa yang benar-benar ada. Ingat bahwa tag bisa dihapus, jadi sesuatu yang berfungsi kemarin mungkin tidak berfungsi hari ini.

Timeout jaringan terjadi ketika Docker tidak dapat menjangkau registry.

Pertama, periksa koneksi internet Anda. Lalu verifikasi bahwa Anda bisa menjangkau registry secara langsung - jalankan ping registry-1.docker.io atau curl -I <https://registry-1.docker.io>. Jika Anda berada di balik proxy, pastikan Docker mengetahuinya. Jika registry bersifat privat, periksa aturan firewall dan koneksi VPN.

Masalah izin muncul sebagai kesalahan "denied" bahkan ketika Anda sudah diautentikasi.

Anda sudah login, tetapi akun Anda tidak memiliki akses pull ke repository tertentu ini. Hubungi pemilik repository atau administrator registry Anda untuk mendapatkan akses. Untuk Docker Hub, ini biasanya berarti image bersifat privat dan Anda tidak ada dalam daftar akses.

Masalah resolusi DNS dan jaringan

Kegagalan DNS menghentikan Docker menemukan server registry.

Anda akan melihat kesalahan seperti "no such host" atau "temporary failure in name resolution." Yang sebenarnya terjadi adalah Docker tidak dapat menerjemahkan hostname registry menjadi alamat IP, sehingga koneksi tidak dapat dibuat.

Untuk mengatasinya, periksa resolusi DNS dengan nslookup registry-1.docker.io atau dig registry-1.docker.io. Jika perintah ini gagal, server DNS Anda tidak dapat dijangkau atau salah konfigurasi. Coba beralih sementara ke server DNS publik seperti 8.8.8.8 untuk melihat apakah itu memperbaikinya.

Di jaringan perusahaan, server DNS mungkin hanya menyelesaikan hostname internal. Pastikan hostname registry privat Anda ada di server DNS, atau tambahkan ke /etc/hosts sebagai solusi sementara hingga DNS diperbaiki.

docker pull dalam Alur Kerja Orkestrasi dan Lokal

Sekarang ke bagian yang menarik - bagaimana perintah docker pull bekerja dalam skenario yang bisa Anda temui dalam pekerjaan sehari-hari.

Penarikan image di Kubernetes

Kubernetes secara otomatis menarik image saat Anda menerapkan pod.

Anda mendefinisikan sebuah container dalam spesifikasi pod dengan referensi image, dan Kubernetes menangani pull untuk Anda. Kubelet pada setiap node memeriksa apakah image ada secara lokal. Jika tidak, ia menarik dari registry sebelum memulai container.

Kebijakan pull mengontrol kapan Kubernetes menarik image:

• Always: Selalu tarik image, bahkan jika sudah ada secara lokal

• IfNotPresent: Hanya tarik jika image belum ada di node (default untuk image bertag)

• Never: Jangan pernah menarik, gagal jika image belum ada secara lokal

Tetapkan kebijakan di spesifikasi pod Anda dengan imagePullPolicy. Gunakan Always untuk tag :latest di pengembangan agar mendapatkan pembaruan. Gunakan IfNotPresent untuk tag spesifik di produksi agar menghindari pull yang tidak perlu.

imagePullSecrets memberi Kubernetes akses ke registry privat. Anda dapat membuat secret dengan kredensial registry Anda, lalu mereferensikannya di spesifikasi pod. Tanpanya, Kubernetes hanya dapat menarik image publik.

Docker Compose dan pengembangan lokal

Compose mengotomatisasi pull saat Anda memulai aplikasi multi-layanan.

Jalankan docker compose up, dan Compose memeriksa image setiap layanan. Jika sebuah image tidak ada, Compose menariknya sebelum memulai container. Anda tidak perlu menjalankan docker pull secara manual untuk setiap layanan, karena Compose menanganinya untuk Anda.

Ini sangat cocok untuk pengembangan. Anda dapat mendefinisikan layanan di docker-compose.yml, menjalankan satu perintah, dan Compose menarik semua yang Anda butuhkan. up pertama memakan waktu lebih lama saat image diunduh, tetapi menjalankan berikutnya akan instan jika image belum berubah.

docker compose vs docker compose pull

Ini adalah dua perintah berbeda yang melakukan hal berbeda.

docker compose up memulai layanan Anda. Perintah ini menarik image yang hilang secara otomatis, namun hanya jika belum ada secara lokal. Jika Anda sudah memiliki python:3.14.2-bookworm di mesin Anda, Compose akan menggunakannya tanpa memeriksa pembaruan.

docker compose pull secara eksplisit menarik semua image yang didefinisikan di berkas compose Anda, terlepas dari apakah sudah ada secara lokal atau tidak. Ini memeriksa pembaruan di registry dan mengunduh versi yang lebih baru jika tersedia.

Berikut kapan Anda perlu docker compose pull:

• Anda menggunakan tag :latest dan ingin versi terbaru. Jalankan docker compose pull terlebih dahulu untuk mendapatkan pembaruan, lalu docker compose up untuk memulai dengan image terbaru.

• Anda sedang debug dan menduga image lokal sudah usang atau rusak. Tarik salinan baru dengan docker compose pull, lalu mulai ulang.

• Anda ingin memuat awal image sebelum benar-benar memulai layanan. Jalankan docker compose pull saat deployment untuk mencache image, lalu docker compose up berjalan seketika tanpa menunggu unduhan.

Perbedaan utamanya adalah up hanya menarik yang hilang, dan pull memperbarui semuanya terlepas dari apa yang sudah Anda miliki.

Kesimpulan

Perintah docker pull terlihat sederhana, tetapi banyak yang terjadi di bawah permukaan dan banyak yang bisa Anda atur. Berikut beberapa praktik terbaik yang perlu diingat.

Gunakan tag atau digest eksplisit alih-alih :latest. Autentikasikan pull Anda untuk menghindari batas laju. Perhatikan bandwidth dan penyimpanan saat menarik image, terutama di pipeline CI/CD di mana Anda menarik secara konstan.

Perlakukan penarikan image sebagai bagian dari pipeline keamanan Anda. Setiap pull berpotensi menjadi vektor serangan jika Anda menggunakan sumber yang tidak tepercaya atau image usang dengan kerentanan yang diketahui. Verifikasi sumber, pindai masalah, dan perbarui base image secara rutin.

Registry Docker dan tooling berubah secara berkala. Tetap ikuti pembaruan dari penyedia registry Anda untuk menghindari kejutan yang dapat merusak alur kerja Anda.

Saat Anda siap meningkatkan keterampilan Docker dan kontainerisasi ke level profesional, lihat kursus Intermediate Docker kami atau pilih jalur lengkap Containerization and Virtualization with Docker and Kubernetes kami..