Mengonfigurasi autentikasi ke Artifact Registry untuk Docker

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.

Catatan: Grup keamanan Docker memiliki akses yang setara dengan pengguna root atau Administrator. Hanya tambahkan pengguna tepercaya yang memerlukan akses ke Docker. Untuk mengetahui detail tentang dampak keamanan, lihat Keamanan daemon Docker.

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 perintah gcloud 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.
  Catatan: Kunci akun layanan merupakan risiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.
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 dan asia-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
Docker memerlukan helper kredensial agar berada di sistem PATH. Pastikan perintah gcloud ada dalam PATH 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:

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 dan asia-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.

Catatan: Jika Anda biasanya menjalankan perintah Docker di Linux dengan sudo, Docker akan mencari kredensial Artifact Registry di /root/.docker/config.json, bukan $HOME/.docker/config.json. Jika Anda ingin menggunakan sudo dengan perintah docker, bukan menggunakan grup keamanan Docker, konfigurasikan kredensial dengan sudo docker-credential-gcr configure-docker.

Kredensial Anda disimpan di direktori utama pengguna.
- Linux: $HOME/.docker/config.json
- Windows: %USERPROFILE%/.docker/config.json
Docker memerlukan helper kredensial agar berada di sistem PATH. Pastikan perintah docker-credential-gcr ada dalam PATH 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.

Buka halaman Service Accounts

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus melakukan autentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan untuk operasi lain yang dijelaskan dalam Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.
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.

Docker kini diautentikasi dengan Artifact Registry.

Mengonfigurasi autentikasi ke Artifact Registry untuk Docker

Sebelum memulai

Linux

Windows

Memilih metode autentikasi

Setelan autentikasi di file konfigurasi Docker

helper kredensial gcloud CLI

Helper kredensial mandiri

Token akses

Linux

Windows

Kunci akun layanan

Linux

macOS

Windows

Linux / Mac

Windows