Perubahan untuk Docker

Dokumen ini memandu Anda memahami perbedaan antara Container Registry dan Artifact Registry untuk mengautentikasi, mengirim, dan mengambil image container dengan Docker.

Dalam panduan ini, perbandingan berfokus pada repositori Artifact Registry pkg.dev, repositori Artifact Registry reguler yang independen dari Container Registry dan mendukung semua fitur Artifact Registry.

Jika administrator menyiapkan repositori dengan dukungan domain gcr.io, permintaan ke nama host gcr.io akan otomatis dialihkan ke repositori Artifact Registry yang sesuai. Untuk menggunakan repositori gcr.io yang dihosting di Artifact Registry, Anda harus memiliki peran Artifact Registry yang sesuai atau peran dengan izin yang setara.

Untuk mempelajari perbedaan antara Container Registry dan Artifact Registry saat mem-build dengan Cloud Build dan men-deploy ke Cloud Run atau Google Kubernetes Engine, lihat Perubahan untuk Cloud Build, Cloud Run, dan GKE.

Gunakan informasi ini untuk membantu Anda menyesuaikan perintah, konfigurasi, atau dokumentasi yang ada yang berfokus pada Container Registry dengan Docker.

Sebelum memulai

Dokumen ini mengasumsikan bahwa Anda telah:

  1. Mengaktifkan Artifact Registry di project Anda.
  2. Menginstal Docker. Docker disertakan dalam Cloud Shell.

Ringkasan

Pada tingkat tinggi, alur kerja untuk menggunakan Docker dengan Container Registry atau Artifact Registry sama.

Container Registry Artifact Registry
Administrator
  1. Mengaktifkan Container Registry API
  2. Tambahkan host registry, seperti `gcr.io`, dengan menerapkan image awal ke host.
  3. Berikan peran Cloud Storage di bucket penyimpanan untuk host registry guna memberikan akses ke image.
 Administrator
  1. Mengaktifkan Artifact Registry API
  2. Tambahkan repositori Docker.
  3. Berikan peran Artifact Registry untuk memberikan akses ke image.
Mendaftarkan pengguna
  1. Tentukan gambar sebagai file Dockerfile.
  2. Membangun image
  3. Lakukan autentikasi ke registry.
  4. Beri tag dan kirim image ke registry.
  5. Ambil image dari registry atau deploy ke runtime Google Cloud.
 Mendaftarkan pengguna
  1. Tentukan gambar sebagai file Dockerfile.
  2. Membangun image
  3. Lakukan autentikasi ke registry.
  4. Beri tag dan kirim image ke registry.
  5. Ambil image dari registry atau deploy ke runtime Google Cloud.

Namun, pintasan untuk Container Registry menggabungkan peran administrator dan pengguna ke dalam satu alur kerja. Pintasan ini umum digunakan di:

  • Panduan memulai dan tutorial tempat Anda melakukan pengujian di lingkungan tempat Anda memiliki izin yang luas.
  • Alur kerja yang menggunakan Cloud Build, karena akun layanan Cloud Build memiliki izin untuk menambahkan host registry di project Google Cloud yang sama.

Alur kerja pintasan terlihat seperti ini:

  1. Aktifkan Container Registry API.
  2. Berikan izin ke akun yang akan mengakses Container Registry.

  3. Lakukan autentikasi ke registry. Opsi autentikasi yang paling sederhana adalah menggunakan helper kredensial Docker di Google Cloud CLI. Ini adalah langkah konfigurasi satu kali.

    gcloud auth configure-docker

  4. Build dan beri tag pada gambar. Misalnya, perintah ini mem-build dan memberi tag pada image gcr.io/my-project/my-image:tag1:

    docker build -t gcr.io/my-project/my-image:tag1

  5. Kirim image ke registry. Contoh:

    docker push gcr.io/my-project/my-image:tag1

    Jika host registry gcr.io tidak ada dalam project, Container Registry akan menambahkan host sebelum mengupload image.

  6. Ambil image dari registry atau deploy ke runtime Google Cloud. Misalnya:

    docker pull gcr.io/my-project/my-image:tag1

Alur kerja ini mengandalkan pintasan berikut:

  • Akun yang mendorong gambar memiliki peran Storage Admin atau peran dengan izin yang sama seperti Pemilik. Izin luas peran ini memungkinkan akses baca dan tulis untuk semua bucket penyimpanan dalam project, termasuk bucket yang tidak digunakan oleh Container Registry.
  • Saat Anda mengaktifkan beberapa Google Cloud API, Container Registry API akan diaktifkan secara otomatis. Artinya, pengguna layanan ini memiliki akses implisit ke Container Registry dalam project yang sama. Misalnya, pengguna yang dapat menjalankan build di Cloud Build dapat mengirim image ke registry dan menambahkan host registry secara default.

Di Artifact Registry, ada pemisahan yang jelas antara peran pengguna administrator dan repositori yang mengubah langkah-langkah dalam alur kerja build dan deployment. Untuk menyesuaikan alur kerja Container Registry untuk Artifact Registry, lakukan perubahan berikut. Setiap langkah ditautkan ke informasi tambahan tentang cara mengubah alur kerja.

  1. Baru: Aktifkan Artifact Registry API.

    Anda harus mengaktifkan Artifact Registry API. Cloud Build dan lingkungan runtime seperti Cloud Run dan GKE tidak otomatis mengaktifkan API untuk Anda.

  2. Baru: Buat repositori Docker target jika belum ada. Anda harus membuat repositori sebelum dapat mengirim image apa pun ke dalamnya. Mengirim image tidak dapat memicu pembuatan repositori dan akun layanan Cloud Build tidak memiliki izin untuk membuat repositori.

  3. Berikan izin ke akun yang akan berinteraksi dengan Artifact Registry.

  4. Diubah: Autentikasi ke repositori. Jika menggunakan helper kredensial di gcloud CLI, Anda harus menentukan host yang ingin ditambahkan ke konfigurasi klien Docker. Misalnya, perintah ini menambahkan us-central1-docker.pkg.dev host:

    gcloud auth configure-docker us-central1-docker.pkg.dev

  5. Berubah: Mem-build dan memberi tag pada image.

    Contoh perintah berikut sama dengan contoh Container Registry, tetapi menggunakan jalur repositori Artifact Registry untuk image.

    docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  6. Berubah: Kirim image ke repositori menggunakan jalur Artifact Registry. Contoh:

    docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

  7. Berubah: Pull image dari repositori menggunakan jalur Artifact Registry. Contoh:

    docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

Mengaktifkan API

Poin utama:

Perbandingan berikut menjelaskan cara mengaktifkan API untuk setiap layanan:

Container Registry

Anda harus mengaktifkan Container Registry API sebelum menggunakan Docker atau klien pihak ketiga lainnya dengan Container Registry.

Saat Anda mengaktifkan Google Cloud API berikut, Container Registry API juga akan otomatis diaktifkan:

  • Lingkungan fleksibel App Engine
  • Cloud Build
  • Fungsi Cloud Run
  • Cloud Run
  • Pemindaian Container atau Pemindaian On-Demand di Artifact Analysis
  • Google Kubernetes Engine

Dengan izin default, pengguna yang dapat menjalankan build di Cloud Build, memindai penampung dengan Analisis Artefak, atau men-deploy penampung ke runtime Google Cloud secara implisit memiliki akses ke image di Container Registry jika registry berada dalam project yang sama.

Artifact Registry

Anda harus mengaktifkan Artifact Registry API sebelum menggunakan klien Docker atau layanan Google Cloud lainnya dengan Artifact Registry.

Layanan seperti Cloud Build, Cloud Run, dan GKE tidak otomatis mengaktifkan Artifact Registry API.

Anda dapat mengaktifkan beberapa API dalam project yang sama menggunakan gcloud. Misalnya, untuk mengaktifkan Cloud Build API dan Artifact Registry API, jalankan perintah:

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Menambahkan registry dan repositori

Poin utama:

  • Anda harus membuat repositori Docker Artifact Registry sebelum mengirim image ke dalamnya.

    Langkah pembuatan registry sering dikecualikan dalam dokumentasi yang menjelaskan pengiriman image ke Container Registry karena akun dengan izin Storage Admin dapat menambahkan registry ke project dengan pengiriman awal ke host registry.

  • Container Registry menyimpan semua image dalam satu multi-region di bucket penyimpanan yang sama. Di Artifact Registry, Anda dapat membuat beberapa repositori di region yang sama atau multi-region dengan kebijakan akses terpisah.

Perbandingan berikut menjelaskan penyiapan repositori di setiap layanan:

Container Registry

Di Container Registry, Anda dapat menambahkan hingga empat host registry ke project Anda. Anda menambahkan host registry dengan mengirimkan image pertama.

  1. Untuk menambahkan registry seperti gcr.io ke project Anda, akun dengan peran Storage Admin di level project akan mendorong image awal.

    Misalnya, jika host gcr.io tidak ada di project my-project, mendorong image gcr.io/my-project/my-image:1.0 akan memicu langkah-langkah berikut:

    1. Menambahkan host gcr.io ke project
    2. Buat bucket penyimpanan untuk gcr.io dalam project.
    3. Menyimpan gambar sebagai gcr.io/my-project/my-image:1.0

  2. Setelah pengiriman awal ini, Anda dapat memberikan izin ke bucket penyimpanan untuk pengguna lain.

Dalam project, host registry menyimpan semua image dalam bucket penyimpanan yang sama. Pada contoh berikut, project my-project memiliki dua image yang disebut web-app di registry gcr.io. Satu di antaranya berada tepat di bawah project ID my-project. Image lainnya ada di repositori team1.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Akun dengan peran Administrator Repositori Artifact Registry harus create repositori sebelum Anda mengirim image ke repositori tersebut. Kemudian, Anda dapat memberikan izin ke repositori untuk pengguna lain.

Di Artifact Registry, setiap repositori adalah resource terpisah. Oleh karena itu, semua jalur gambar harus menyertakan repositori.

Jalur gambar yang valid:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

Jalur gambar tidak valid (tidak menyertakan repositori) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

Contoh berikut menunjukkan situasi saat pengiriman image ke repositori yang hilang gagal.

  • Mengirim gambar ke us-central1-docker.pkg.dev/my-project/team1 jika us-central1-docker.pkg.dev/my-project/team1 tidak ada.
  • Mendorong gambar ke us-central1-docker.pkg.dev/my-project/team2 saat us-central1-docker.pkg.dev/my-project/team1 ada, tetapi us-central1-docker.pkg.dev/my-project/team2 tidak ada.

Memberikan izin

Poin utama:

  • Berikan peran Artifact Registry yang sesuai ke akun yang Anda gunakan dengan Artifact Registry.
  • Layanan Google Cloud memiliki akses baca atau tulis yang setara ke Container Registry dan Artifact Registry. Namun, akun layanan Cloud Build default tidak dapat membuat repositori.
  • Container Registry mendukung kontrol akses di tingkat bucket penyimpanan. Artifact Registry mendukung kontrol akses di tingkat repositori.

Perbandingan berikut menjelaskan penyiapan izin di setiap layanan:

Container Registry

Container Registry menggunakan peran Cloud Storage untuk mengontrol akses.

Storage Object Viewer di tingkat bucket penyimpanan
Mengambil (membaca) image dari host registry yang ada dalam project.
Storage Legacy Bucket Writer di tingkat bucket penyimpanan
Mengirim (menulis) dan menarik (membaca) image untuk host registry yang ada dalam project.
Storage Admin di tingkat project
Menambahkan host registry ke project dengan mendorong image awal ke host.

Setelah pengiriman image awal ke registry, Anda memberikan peran Cloud Storage ke akun lain yang memerlukan akses ke bucket penyimpanan. Perhatikan bahwa akun apa pun dengan semua izin dalam peran Storage Admin dapat membaca, menulis, dan menghapus bucket penyimpanan serta objek penyimpanan di seluruh project.

Izin di bucket penyimpanan berlaku untuk semua repositori di registry. Misalnya, setiap pengguna dengan izin Storage Object Viewer di bucket untuk gcr.io/my-project dapat membaca gambar di semua repositori ini:

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry memiliki peran sendiri untuk mengontrol akses. Peran ini memberikan pemisahan yang jelas antara peran administrator dan pengguna repositori.

Hanya akun yang mengelola repositori yang harus memiliki peran Artifact Registry Repository Administrator atau Artifact Registry Administrator.

Pembaca Artifact Registry
Mencantumkan artefak dan repositori. Download artefak.
Penulis Artifact Registry
Mencantumkan artefak dan repositori. Mendownload artefak, mengupload versi artefak baru, dan menambahkan atau memperbarui tag.
Administrator Repositori Artifact Registry
Izin Artifact Registry Writer dan izin untuk menghapus artefak dan tag.
Artifact Registry Administrator
Izin Administrator Repositori Artifact Registry dan izin untuk membuat, memperbarui, menghapus, dan memberikan izin ke repositori.

Anda dapat menerapkan izin ini di tingkat repositori. Contoh:

  • Memberikan akses ke Tim 1 untuk us-central1-docker.pkg.dev/my-project/team1
  • Berikan akses ke Tim 2 untuk us-central1-docker.pkg.dev/my-project/team2.

Untuk mengetahui detail tentang cara memberikan izin Artifact Registry, lihat dokumentasi kontrol akses.

Mengautentikasi ke registry

Poin utama:

  • Artifact Registry mendukung metode autentikasi yang sama dengan Container Registry.
  • Untuk helper kredensial Docker, Anda harus menentukan host yang akan ditambahkan ke konfigurasi klien Docker.
  • Untuk autentikasi menggunakan docker login, gunakan host Artifact Registry, bukan host Container Registry.

Menggunakan helper kredensial

Perintah gcloud auth configure-docker dan helper kredensial mandiri hanya mengonfigurasi Docker untuk nama host *.gcr.io secara default. Untuk Artifact Registry, Anda harus menentukan daftar host Artifact Registry yang ingin ditambahkan ke konfigurasi klien Docker.

Misalnya, untuk menyiapkan autentikasi ke repositori Docker di region us-central1, jalankan perintah berikut:

gcloud auth configure-docker us-central1-docker.pkg.dev

Jika nanti menambahkan repositori di us-east1 dan asia-east1, Anda harus menjalankan perintah lagi untuk menambahkan nama host regional yang sesuai ke konfigurasi Docker.

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

Untuk mengetahui detail metode autentikasi Artifact Registry, lihat Menyiapkan autentikasi untuk Docker.

Menggunakan autentikasi sandi

Saat Anda login ke Docker, gunakan nama host Artifact Registry, bukan nama host *.gcr.io. Contoh berikut menunjukkan autentikasi dengan kunci akun layanan yang dienkode base64 ke host us-central1-docker.pkg.dev:

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-central1-docker.pkg.dev

Membuat dan memberi tag pada image

Poin penting: - Artifact Registry menggunakan nama host yang berbeda untuk repositori.

Saat memberi tag pada image, gunakan jalur Artifact Registry, bukan jalur Container Registry. Contoh:

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Mengirim image ke registry

Poin utama: - Di Artifact Registry, repositori target harus ada sebelum Anda mengirim image ke sana. - Artifact Registry menggunakan nama host yang berbeda untuk repositori.

Saat Anda mengirim image, gunakan jalur Artifact Registry, bukan jalur Container Registry. Contoh:

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Mengambil image dari registry

Poin utama:

  • Nama host Artifact Registry berbeda dengan nama host Container Registry.

Saat mengambil image, gunakan jalur Artifact Registry, bukan jalur Container Registry. Contoh:

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Untuk contoh deployment image ke runtime Google Cloud seperti Cloud Run dan GKE, lihat Men-deploy image.