Halaman ini menjelaskan cara mengonfigurasi Docker untuk melakukan autentikasi ke repositori Docker Artifact Registry.
Anda tidak perlu mengonfigurasi autentikasi untuk lingkungan runtime Cloud Build atau Google Cloud seperti Google Kubernetes Engine dan Cloud Run, tetapi Anda harus memastikan bahwa izin yang diperlukan telah dikonfigurasi.
Sebelum memulai
-
Instal Google Cloud CLI, lalu initialize dengan menjalankan perintah berikut:
gcloud init
- (Opsional) Konfigurasikan default untuk perintah gcloud CLI.
- Pastikan akun yang Anda gunakan untuk autentikasi memiliki izin untuk mengakses Artifact Registry. Sebaiknya gunakan akun layanan, bukan akun pengguna.
- Instal Docker jika belum diinstal. Docker disertakan dalam Cloud Shell.
Docker memerlukan akses hak istimewa untuk berinteraksi dengan registry. Di Linux atau Windows, tambahkan pengguna yang Anda gunakan untuk menjalankan perintah Docker ke grup keamanan Docker. Langkah ini tidak diperlukan di macOS karena Docker Desktop berjalan di virtual machine sebagai pengguna root.
Linux
Grup keamanan Docker disebut
docker
. Untuk menambahkan nama pengguna, jalankan perintah berikut:sudo usermod -a -G docker ${USER}
Windows
Grup keamanan Docker disebut
docker-users
. Untuk menambahkan pengguna dari command prompt Administrator, jalankan perintah berikut:net localgroup docker-users DOMAIN\USERNAME /add
Dari mana
- DOMAIN adalah domain Windows Anda.
- USERNAME adalah nama pengguna Anda.
Logout dan login kembali agar perubahan keanggotaan grup diterapkan. Jika menggunakan virtual machine, Anda mungkin perlu memulai ulang mesin virtual agar perubahan keanggotaan diterapkan.
Memilih metode autentikasi
Tersedia metode autentikasi berikut:
- Pembantu kredensial gcloud CLI
- Konfigurasi kredensial Artifact Registry untuk digunakan dengan Docker langsung di gcloud CLI. Ini adalah metode autentikasi yang paling sederhana, tetapi bisa lebih lambat daripada helper kredensial mandiri.
- Helper kredensial Docker mandiri
- Opsi ini terutama untuk mengonfigurasi kredensial Anda agar dapat digunakan dengan Docker tanpa Google Cloud CLI. Alat ini jauh lebih cepat daripada helper kredensial gcloud CLI dan menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial di lingkungan Anda secara otomatis.
- Token akses
- Anda dapat membuat token akses yang memiliki masa aktif singkat untuk akun layanan, lalu menggunakan token tersebut untuk autentikasi sandi. Karena token hanya valid selama 60 menit, ini adalah opsi yang lebih aman daripada kunci akun layanan.
- Kunci akun layanan
- Pasangan kunci yang dikelola pengguna yang dapat Anda gunakan sebagai kredensial untuk akun layanan. Karena kredensial berumur panjang, kredensial ini adalah opsi yang paling tidak aman dari semua metode autentikasi yang tersedia.
Jika memungkinkan, gunakan token akses atau helper kredensial untuk mengurangi risiko akses tidak sah ke image container. Jika Anda harus menggunakan kunci akun layanan, pastikan Anda mengikuti praktik terbaik untuk mengelola kredensial.
Setelan autentikasi di file konfigurasi Docker
Docker menyimpan setelan autentikasi di file konfigurasi config.json.
- Linux:
~/.docker/config.json
- Windows:
%USERPROFILE%\.docker\config.json
Ada bagian terpisah dalam file tersebut untuk metode autentikasi yang berbeda:
credHelpers
- Jika Anda menggunakan helper kredensial Docker untuk autentikasi,
Artifact Registry akan menyimpan setelan helper kredensial di
bagian
credHelpers
file. auths
- Jika Anda menggunakan Docker untuk login dengan token atau kunci akun layanan sebagai sandi, Docker akan menyimpan versi kredensial berenkode base64 Anda di bagian
auths
file. credStore
- Jika Anda mengonfigurasi
penyimpanan kredensial
untuk mengelola kredensial, setelan untuk penyimpanan kredensial berada di
bagian
credStore
file.
Saat terhubung ke registry, Docker akan memeriksa helper kredensial yang terkait dengan host terlebih dahulu. Jadi, jika config.json
Anda menyertakan setelan Artifact Registry di bagian credHelpers
dan auths
, setelan di bagian auths
akan diabaikan.
helper kredensial gcloud CLI
Helper kredensial gcloud CLI menyediakan akses yang aman dan berumur pendek ke resource project Anda. Compose mengonfigurasi Docker untuk melakukan autentikasi ke host Artifact Registry di lingkungan mana pun tempat Google Cloud CLI diinstal. Cloud Shell menyertakan Google Cloud CLI dan versi Docker saat ini.
Helper kredensial gcloud CLI adalah metode autentikasi yang paling sederhana untuk disiapkan. Compose mengonfigurasi Docker dengan kredensial pengguna aktif atau akun layanan dalam sesi gcloud CLI Anda. Karena helper kredensial ini bergantung pada gcloud CLI, helpernya bisa jauh lebih lambat daripada helper kredensial mandiri. Untuk build otomatis dengan alat pihak ketiga atau klien Docker yang memiliki banyak host registry terkonfigurasi, gunakan helper kredensial mandiri.
Untuk melakukan autentikasi ke Artifact Registry:
Login ke gcloud CLI sebagai pengguna yang akan menjalankan perintah Docker.
Untuk mengonfigurasi autentikasi dengan kredensial pengguna, jalankan perintah berikut:
gcloud auth login
Untuk mengonfigurasi autentikasi dengan kredensial akun layanan, jalankan perintah berikut:
gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
Dari mana
- ACCOUNT adalah akun layanan yang ingin Anda gunakan dengan
Artifact Registry dalam format
USERNAME@PROJECT-ID.iam.gserviceaccount.com
. Jika ingin menggunakan akun yang sudah ada, Anda dapat melihat daftar akun layanan di halaman Akun Layanan pada Konsol Google Cloud atau dengan perintahgcloud iam service-accounts list
- KEY-FILE adalah file kunci akun layanan. Lihat dokumentasi Identity and Access Management (IAM) untuk mengetahui informasi tentang cara membuat kunci.
- ACCOUNT adalah akun layanan yang ingin Anda gunakan dengan
Artifact Registry dalam format
Jalankan perintah berikut:
gcloud auth configure-docker HOSTNAME-LIST
Dengan HOSTNAME-LIST adalah daftar nama host repositori yang dipisahkan koma yang akan ditambahkan ke konfigurasi helper kredensial.
Misalnya, untuk menambahkan region
us-central1
danasia-northeast1
, jalankan perintah:gcloud auth configure-docker us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Nama host yang ditentukan akan ditambahkan ke konfigurasi helper kredensial. Anda dapat menambahkan nama host lain ke konfigurasi nanti dengan menjalankan perintah lagi.
Untuk melihat daftar lokasi repositori yang didukung, jalankan perintah:
gcloud artifacts locations list
Perintah ini menampilkan bagian
credHelpers
dari konfigurasi Docker saat ini dan konfigurasi yang diperbarui setelah menambahkan nama host yang ditentukan.Untuk menerima perubahan konfigurasi, masukkan
y
.Kredensial Anda disimpan di direktori utama pengguna.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Docker memerlukan helper kredensial agar berada di sistem
PATH
. Pastikan perintahgcloud
ada dalamPATH
sistem.
Helper kredensial mandiri
Helper kredensial Docker mandiri mengonfigurasi Docker untuk melakukan autentikasi ke Artifact Registry pada sistem yang tidak menyediakan gcloud CLI. Alat ini jauh lebih cepat daripada pembantu kredensial gcloud CLI dan menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial di lingkungan Anda secara otomatis. Untuk operasi selain mengirim dan menarik gambar, seperti memberi tag atau mencantumkan gambar. Sebaiknya gunakan metode autentikasi ini untuk build otomatis dengan alat pihak ketiga atau klien Docker yang memiliki banyak host registry yang dikonfigurasi.
Helper kredensial Docker mandiri mengambil kredensial Artifact Registry dan menuliskannya ke file konfigurasi Docker. Dengan cara ini, Anda
dapat menggunakan alat command line Docker, docker
, untuk berinteraksi langsung dengan
Artifact Registry.
Untuk menggunakan helper kredensial Docker:
Login ke komputer sebagai pengguna yang akan menjalankan perintah Docker.
Download helper kredensial Docker mandiri dari GitHub.
Secara opsional, Anda dapat menggunakan utilitas command line
curl
. Contoh:VERSION=2.1.22 OS=linux # or "darwin" for OSX, "windows" for Windows. ARCH=amd64 # or "386" for 32-bit OSs curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \ | tar xz docker-credential-gcr \ && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
Konfigurasikan Docker untuk menggunakan kredensial Artifact Registry saat berinteraksi dengan Artifact Registry (Anda hanya perlu melakukannya satu kali):
docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
Dengan HOSTNAME-LIST adalah daftar nama host repositori yang dipisahkan koma yang akan ditambahkan ke konfigurasi helper kredensial.
Misalnya, untuk menambahkan region
us-central1
danasia-northeast1
, jalankan perintah:docker-credential-gcr configure-docker --registries=us-central1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
Nama host yang ditentukan akan ditambahkan ke konfigurasi helper kredensial. Anda dapat menambahkan nama host lain ke konfigurasi nanti dengan menjalankan perintah lagi.
Untuk melihat daftar lokasi repositori yang didukung, jalankan perintah:
gcloud artifacts locations list
Lihat dokumentasi helper kredensial Docker mandiri di GitHub untuk mengetahui informasi selengkapnya.
Kredensial Anda disimpan di direktori utama pengguna.
- Linux:
$HOME/.docker/config.json
- Windows:
%USERPROFILE%/.docker/config.json
- Linux:
Docker memerlukan helper kredensial agar berada di sistem
PATH
. Pastikan perintahdocker-credential-gcr
ada dalamPATH
sistem.Untuk memverifikasi bahwa helper kredensial dapat berhasil mengambil kredensial Anda, jalankan perintah berikut:
echo "https://HOSTNAME" | docker-credential-gcr get
Ganti HOSTNAME dengan nama host yang Anda tambahkan ke konfigurasi. Contoh:
echo "https://us-central1-docker.pkg.dev" | docker-credential-gcr get
Jika perintah berhasil, output JSON yang ditampilkan akan menyertakan token di kolom
Secret
. Contoh:{"ServerURL":"https://us-central1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
Docker kini dikonfigurasi untuk melakukan autentikasi dengan Artifact Registry. Untuk mengirim dan mengambil image, pastikan izin dikonfigurasi dengan benar.
Token akses
Anda dapat membuat token akses OAuth yang memiliki masa aktif singkat untuk melakukan autentikasi dengan Artifact Registry. Karena token ini valid selama 60 menit, Anda harus memintanya kurang dari satu jam sebelum menggunakannya untuk terhubung dengan Artifact Registry.
Untuk menggunakan token akses dengan kredensial akun layanan:
Buat akun layanan untuk bertindak atas nama aplikasi Anda, atau pilih akun layanan yang ada yang Anda gunakan untuk otomatisasi.
Berikan peran Artifact Registry spesifik ke akun layanan untuk memberikan akses repositori.
Buat token akses untuk akun layanan dan lakukan autentikasi:
Anda harus memiliki izin dalam peran Service Account Token Creator (
roles/iam.serviceAccountTokenCreator
) untuk meniru identitas akun layanan, mendapatkan token untuk akun tersebut, lalu melakukan autentikasi sebagai akun layanan.Jalankan perintah berikut dengan mengganti ACCOUNT dengan alamat email akun layanan Anda dan lokasi regional atau multi-regional LOCATION dari repositori.
Linux
gcloud auth print-access-token \ --impersonate-service-account ACCOUNT | docker login \ -u oauth2accesstoken \ --password-stdin https://LOCATION-docker.pkg.dev
Windows
gcloud auth print-access-token --impersonate-service-account ACCOUNT | docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
Docker kini diautentikasi dengan Artifact Registry.
Kunci akun layanan
Siapa pun yang memiliki akses ke kunci pribadi yang valid untuk akun layanan akan dapat mengakses resource melalui akun layanan. Perhatikan bahwa siklus proses akses kunci ke akun layanan (sehingga data yang dapat diakses akun layanan) tidak bergantung pada siklus proses pengguna yang mendownload kunci.
Gunakan panduan berikut untuk membatasi akses ke repositori Anda:
- Buat akun layanan khusus yang hanya digunakan untuk berinteraksi dengan repositori.
- Berikan peran Artifact Registry khusus untuk akses yang diperlukan oleh akun layanan. Misalnya, akun layanan yang hanya mendownload artefak hanya memerlukan peran Artifact Registry Reader.
- Konfigurasikan izin untuk akun layanan khusus Anda di setiap repositori, bukan di level project. Kemudian, Anda dapat menentukan akses berdasarkan konteks repositori. Misalnya, akun layanan untuk build pengembangan mungkin memiliki peran Artifact Registry Reader untuk repositori produksi dan peran Artifact Registry Writer untuk repositori staging.
- Ikuti praktik terbaik untuk mengelola kredensial.
Untuk membuat akun layanan baru dan kunci akun layanan yang hanya dapat digunakan dengan repositori Artifact Registry:
Buat akun layanan untuk bertindak atas nama aplikasi Anda, atau pilih akun layanan yang ada yang Anda gunakan untuk otomatisasi.
Anda memerlukan lokasi file kunci akun layanan untuk menyiapkan autentikasi dengan Artifact Registry. Untuk akun yang ada, Anda dapat melihat kunci dan membuat kunci baru di halaman Akun Layanan.
Secara opsional, Anda dapat mengenkode base64 semua konten file kunci.
Linux
base64 FILE-NAME > NEW-FILE-NAME
macOS
base64 -i FILE-NAME -o NEW-FILE-NAME
Windows
Base64.exe -e FILE-NAME > NEW-FILE-NAME
Dengan FILE-NAME adalah nama file kunci asli dan NEW-FILE-NAME adalah file kunci berenkode base64 Anda.
Pastikan izin dikonfigurasi dengan benar untuk akun layanan. Jika menggunakan akun layanan Compute Engine, Anda harus mengonfigurasi izin dan cakupan akses dengan benar.
Gunakan kunci akun layanan untuk mengonfigurasi integrasi dengan Docker:
Jalankan perintah berikut:
Linux / Mac
cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \ https://LOCATION-docker.pkg.dev
Windows
Get-Content KEY-FILE | docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev
Ganti kode berikut:
- KEY-TYPE adalah salah satu dari yang berikut:
_json_key
jika Anda menggunakan kunci akun layanan dalam format JSON seperti yang diberikan saat Anda membuat file._json_key_base64
jika Anda melakukan enkode base64 pada semua konten file.
- KEY-FILE adalah nama file kunci akun layanan dalam format JSON.
- LOCATION adalah lokasi regional atau multi-regional dari repositori tempat gambar disimpan.
- KEY-TYPE adalah salah satu dari yang berikut:
Docker kini diautentikasi dengan Artifact Registry.