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 memverifikasi bahwa izin yang diperlukan telah dikonfigurasi.

Sebelum memulai

  1. Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init
  2. (Opsional) Konfigurasikan default untuk perintah gcloud CLI.
  3. Pastikan akun yang Anda gunakan untuk autentikasi memiliki izin untuk mengakses Artifact Registry. Sebaiknya gunakan akun layanan, bukan akun pengguna.
  4. Instal Docker jika belum diinstal. Docker disertakan dalam Cloud Shell.
  5. Docker memerlukan akses dengan 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

    Dengan keterangan:

    • 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 virtual machine agar perubahan keanggotaan diterapkan.

Memilih metode autentikasi

Metode autentikasi berikut tersedia:

Pembantu kredensial gcloud CLI
Konfigurasikan kredensial Artifact Registry untuk digunakan dengan Docker langsung di gcloud CLI. Ini adalah metode autentikasi yang paling sederhana, tetapi dapat lebih lambat daripada helper kredensial mandiri.
Helper kredensial Docker mandiri
Opsi ini terutama untuk mengonfigurasi kredensial Anda agar dapat digunakan dengan Docker jika tidak ada Google Cloud CLI. Library ini jauh lebih cepat daripada helper kredensial gcloud CLI dan menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial secara otomatis di lingkungan Anda.
Token akses
Anda dapat membuat token akses berumur pendek untuk akun layanan, lalu menggunakan token tersebut untuk autentikasi sandi. Karena token hanya berlaku selama 60 menit, token ini merupakan 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 memiliki masa berlaku yang lama, 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 Anda. 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 dalam file konfigurasi config.json.

  • Linux: ~/.docker/config.json
  • Windows: %USERPROFILE%\.docker\config.json

Ada bagian terpisah dalam file 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 kredensial Anda dalam versi yang dienkode base64 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 terlebih dahulu helper kredensial yang terkait dengan host. Jadi, jika config.json Anda menyertakan setelan Artifact Registry di bagian credHelpers dan auths, setelan di bagian auths akan diabaikan.

Helper kredensial gcloud CLI

Pembantu kredensial gcloud CLI memberikan akses yang aman dan berumur pendek ke resource project Anda. Tindakan ini akan 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 Docker versi saat ini.

Helper kredensial gcloud CLI adalah metode autentikasi yang paling sederhana untuk disiapkan. Perintah ini mengonfigurasi Docker dengan kredensial pengguna aktif atau akun layanan dalam sesi gcloud CLI Anda. Karena helper kredensial ini bergantung pada gcloud CLI, prosesnya dapat berjalan jauh lebih lambat daripada helper kredensial mandiri. Untuk build otomatis dengan alat pihak ketiga atau klien Docker dengan banyak host registry yang dikonfigurasi, gunakan helper kredensial mandiri.

Untuk melakukan autentikasi ke Artifact Registry:

  1. 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 ada, Anda dapat melihat daftar akun layanan di halaman Service Accounts di 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.

  2. Jalankan perintah berikut:

    gcloud auth configure-docker HOSTNAME-LIST

    Dengan HOSTNAME-LIST adalah daftar nama host repositori yang dipisahkan koma untuk ditambahkan ke konfigurasi helper kredensial.

    Misalnya, untuk menambahkan region us-west1 dan asia-northeast1, jalankan perintah:

    gcloud auth configure-docker us-west1-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

  3. 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 beranda pengguna.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker mewajibkan helper kredensial berada di PATH sistem. Pastikan perintah gcloud ada di PATH sistem.

Helper kredensial mandiri

Pembantu kredensial Docker mandiri mengonfigurasi Docker untuk melakukan autentikasi ke Artifact Registry di sistem tempat gcloud CLI tidak tersedia. Alat ini jauh lebih cepat daripada helper kredensial gcloud CLI dan menggunakan Kredensial Default Aplikasi (ADC) untuk menemukan kredensial secara otomatis di lingkungan Anda. Untuk operasi selain mendorong dan menarik gambar, seperti memberi tag atau mencantumkan gambar. Sebaiknya gunakan metode autentikasi ini untuk build otomatis dengan alat pihak ketiga atau klien Docker dengan sejumlah besar host registry yang dikonfigurasi.

Helper kredensial Docker mandiri mengambil kredensial Artifact Registry Anda dan menulisnya 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:

  1. Login ke mesin sebagai pengguna yang akan menjalankan perintah Docker.

  2. Download helper kredensial Docker mandiri dari GitHub.

    Anda dapat menggunakan utilitas command line curl secara opsional. Contoh:

    VERSION=2.1.25
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/

  3. Konfigurasi Docker untuk menggunakan kredensial Artifact Registry saat berinteraksi dengan Artifact Registry (Anda hanya perlu melakukannya sekali):

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    Dengan HOSTNAME-LIST adalah daftar nama host repositori yang dipisahkan koma untuk ditambahkan ke konfigurasi helper kredensial.

    Misalnya, untuk menambahkan region us-west1 dan asia-northeast1, jalankan perintah:

    docker-credential-gcr configure-docker --registries=us-west1-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 beranda pengguna.

    • Linux: $HOME/.docker/config.json
    • Windows: %USERPROFILE%/.docker/config.json

  4. Docker mewajibkan helper kredensial berada di PATH sistem. Pastikan perintah docker-credential-gcr ada di PATH sistem.

  5. Untuk memverifikasi bahwa helper kredensial 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-west1-docker.pkg.dev" | docker-credential-gcr get

    Jika perintah berhasil, output JSON yang ditampilkan akan menyertakan token di kolom Secret. Contoh:

    {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

Docker kini dikonfigurasi untuk melakukan autentikasi dengan Artifact Registry. Untuk mengirim dan menarik gambar, pastikan izin dikonfigurasi dengan benar.

Token akses

Anda dapat membuat token akses OAuth yang berlaku singkat untuk mengautentikasi dengan Artifact Registry. Karena token 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:

  1. Buat akun layanan untuk bertindak atas nama aplikasi Anda, atau pilih akun layanan yang ada yang Anda gunakan untuk otomatisasi.

  2. Berikan peran Artifact Registry tertentu ke akun layanan untuk memberikan akses repositori.

  3. Buat token akses untuk akun layanan dan 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 LOCATION dengan lokasi regional atau multi-regional 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 (dan dengan demikian, data yang dapat diakses akun layanan) tidak bergantung pada siklus proses pengguna yang telah 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 tertentu untuk akses yang diperlukan oleh akun layanan. Misalnya, akun layanan yang hanya mendownload artefak hanya memerlukan peran Pembaca Artifact Registry.
  • 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 Pembaca Artifact Registry untuk repositori produksi dan peran Penulis Artifact Registry untuk repositori staging.
  • Ikuti praktik terbaik untuk mengelola kredensial.

Untuk membuat akun layanan baru dan kunci akun layanan hanya untuk digunakan dengan repositori Artifact Registry:

  1. 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

  2. Anda dapat mengenkode semua konten file kunci dengan base64 secara opsional.

    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 yang dienkode base64.

  3. Pastikan izin dikonfigurasi dengan benar untuk akun layanan. Jika menggunakan akun layanan Compute Engine, Anda harus mengonfigurasi izin dan cakupan akses dengan benar.

  4. Gunakan kunci akun layanan untuk mengonfigurasi integrasi dengan Docker:

    Jalankan perintah berikut:

    Linux / macOS

    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 berikut ini:
      • _json_key jika Anda menggunakan kunci akun layanan dalam format JSON seperti yang diberikan saat Anda membuat file.
      • _json_key_base64 jika Anda mengenkode semua konten file dengan base64.
    • KEY-FILE adalah nama file kunci akun layanan dalam format JSON.
    • LOCATION adalah lokasi regional atau multi-regional repositori tempat image disimpan.

Docker kini diautentikasi dengan Artifact Registry.