Perubahan untuk Docker

Dokumen ini akan 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 standar, repositori Artifact Registry reguler yang independen dari Container Registry, dan mendukung semua fitur Artifact Registry.

Jika administrator Anda 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 membangun 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.
2. Docker yang terinstal. Docker disertakan dalam Cloud Shell.

Ringkasan

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

Container Registry	Artifact Registry
Administrator Mengaktifkan Container Registry API Tambahkan host registry, seperti `gcr.io`, dengan mengirim image awal ke host. Memberikan peran Cloud Storage pada bucket penyimpanan agar host registry dapat memberikan akses ke image.	Administrator Mengaktifkan Artifact Registry API Tambahkan repositori Docker. Berikan peran Artifact Registry untuk memberikan akses ke image.
Pengguna registry Tentukan gambar sebagai file Dockerfile. Membangun image Autentikasi ke registry. Beri tag dan kirim image ke registry. Ambil image dari registry atau deploy ke runtime Google Cloud.	Pengguna registry Tentukan gambar sebagai file Dockerfile. Membangun image Autentikasi ke registry. Beri tag dan kirim image ke registry. 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 di:

• Panduan memulai dan tutorial di mana 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. 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 image. Misalnya, perintah ini mem-build dan memberi tag pada gcr.io/my-project/my-image:tag1 image:

   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 di 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 bergantung pada pintasan berikut:

• Akun yang mengirim gambar memiliki peran Admin Penyimpanan atau peran dengan izin yang sama, seperti Pemilik. Izin yang luas dari peran ini memungkinkan akses baca dan tulis untuk semua bucket penyimpanan dalam suatu project, termasuk bucket yang tidak digunakan oleh Container Registry.
• Saat Anda mengaktifkan beberapa Google Cloud API, Container Registry API akan otomatis diaktifkan. 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 peran pengguna administrator dan repositori yang jelas yang mengubah langkah-langkah dalam alur kerja build dan deploy. Agar dapat menyesuaikan alur kerja Container Registry untuk Artifact Registry, lakukan perubahan berikut. Setiap langkah ditautkan ke informasi tambahan tentang cara mengubah alur kerja.

1. Baru: Mengaktifkan Artifact Registry API.

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

2. Baru: Membuat 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 host us-central1-docker.pkg.dev:

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

5. Diubah: Membuat dan memberi tag 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. Diubah: Mendorong image ke repositori menggunakan jalur Artifact Registry. Contoh:

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

7. Diubah: Ambil 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:

• Anda harus mengaktifkan Artifact Registry API selain API untuk layanan Google Cloud lainnya seperti Cloud Build, Cloud Run, dan GKE.

Perbandingan berikut menjelaskan pengaktifan 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 otomatis diaktifkan:

• Lingkungan fleksibel App Engine
• Cloud Build
• Cloud Functions
• Cloud Run
• Pemindaian Container atau Pemindaian On-Demand dalam Analisis Artefak
• Google Kubernetes Engine

Dengan izin default, pengguna yang dapat menjalankan build di Cloud Build, memindai container dengan Analisis Artefak, atau men-deploy container ke runtime Google Cloud secara implisit memiliki akses ke image di Container Registry saat 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 kali 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 atau multi-region yang sama dengan kebijakan akses yang terpisah.

Perbandingan berikut menjelaskan penyiapan repositori di setiap layanan:

Container Registry

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

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

   Misalnya, jika host gcr.io tidak ada dalam project my-project, mengirim 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 di project.
   3. Simpan gambar sebagai gcr.io/my-project/my-image:1.0

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

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

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

Artifact Registry

Akun dengan peran Artifact Registry Repository Administrator harus membuat repositori sebelum Anda mengirim gambar ke dalamnya. Anda kemudian dapat memberikan izin ke repositori untuk pengguna lain.

Di Artifact Registry, setiap repositori adalah resource terpisah. Oleh karena itu, semua jalur image 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 image tidak valid (tidak termasuk repositori) :

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

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

• Mengirim image ke us-central1-docker.pkg.dev/my-project/team1 jika us-central1-docker.pkg.dev/my-project/team1 tidak ada.
• Mengirim gambar ke us-central1-docker.pkg.dev/my-project/team2 jika 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 level bucket penyimpanan. Artifact Registry mendukung kontrol akses di level repositori.

Perbandingan berikut menjelaskan penyiapan izin di setiap layanan:

Container Registry

Container Registry menggunakan peran Cloud Storage untuk mengontrol akses.

Storage Object Viewer pada level bucket penyimpanan

Ambil (baca) image dari host registry yang ada dalam project.

Penulis Bucket Lama Penyimpanan di level bucket penyimpanan

Mendorong (menulis) dan menarik (membaca) image untuk host registry yang ada dalam project.

Admin Penyimpanan di level project

Menambahkan host registry ke project dengan mengirim image awal ke host.

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

Izin pada bucket penyimpanan berlaku untuk semua repositori dalam registry. Misalnya, setiap pengguna yang memiliki 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 perannya sendiri untuk mengontrol akses. Peran ini memberikan pemisahan yang jelas antara peran pengguna administrator dan repositori.

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

Pembaca Artifact Registry

Membuat daftar artefak dan repositori. Download artefak.

Penulis Artifact Registry

Membuat daftar artefak dan repositori. Download artefak, upload versi artefak baru, dan tambahkan atau perbarui tag.

Administrator Repositori Artifact Registry

Izin dan izin Penulis Artifact Registry untuk menghapus artefak dan tag.

Artifact Registry Administrator

Izin dan izin Administrator Repositori Artifact Registry untuk membuat, memperbarui, menghapus, dan memberikan izin ke repositori.

Anda dapat menerapkan izin ini di level repositori. Contoh:

• Berikan 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 nantinya Anda 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 login ke Docker, gunakan nama host Artifact Registry, bukan nama host *.gcr.io. Contoh berikut menunjukkan autentikasi dengan kunci akun layanan berenkode base64 ke us-central1-docker.pkg.dev host:

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

Membuat dan memberi tag pada gambar

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

Saat Anda 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 dalamnya. - 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 Anda 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 mengetahui contoh deployment image ke runtime Google Cloud seperti Cloud Run dan GKE, lihat Men-deploy image.