Migrasi manual ke repositori `gcr.io` di Artifact Registry

Dokumen ini menjelaskan cara menyiapkan repositori gcr.io secara manual di Artifact Registry.

Jika Anda ingin membuat repositori gcr.io di Artifact Registry menggunakan kunci enkripsi yang dikelola pelanggan (CMEK), selesaikan langkah-langkah di Sebelum memulai, lalu ikuti petunjuk di Pembuatan repositori manual.

Sebelum memulai

  1. Instal Google Cloud CLI jika belum diinstal. Untuk penginstalan yang ada, jalankan perintah berikut untuk mengupdate komponen ke versi terbaru:

    gcloud components update

  2. Aktifkan Artifact Registry API dan Resource Manager API. gcloud CLI menggunakan Resource Manager API untuk memeriksa salah satu izin yang diperlukan.

    Jalankan perintah berikut:

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

  3. Pelajari harga untuk Artifact Registry sebelum memulai transisi.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan guna menyiapkan repositori gcr.io, minta administrator untuk memberi Anda peran IAM berikut:

  • Untuk membuat repositori Artifact Registry dan memberikan akses ke setiap repositori: Administrator Artifact Registry (roles/artifactregistry.admin) di project Google Cloud
  • Untuk melihat dan mengelola konfigurasi Container Registry yang ada yang diterapkan ke bucket penyimpanan Cloud Storage: Storage Admin (roles/storage.admin) di project Google Cloud
  • Untuk membuat repositori gcr.io saat pertama kali Anda mengirim image ke nama host gcr.io: Artifact Registry Create-on-push Writer (roles/artifactregistry.createOnPushWriter) di project Google Cloud
  • Untuk memberikan akses repositori di tingkat project: Project IAM Admin (roles/resourcemanager.projectIamAdmin) di project Google Cloud
  • Untuk mencantumkan layanan yang diaktifkan di organisasi: Cloud Asset Viewer (roles/cloudasset.viewer) di organisasi

Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran khusus atau peran bawaan lainnya.

Batasan

Batasan berikut berlaku untuk repositori gcr.io Artifact Registry:

  • Saat bertransisi dari Container Registry, Anda tidak dapat memetakan host Container Registry ke repositori Artifact Registry di project lain.
  • Setiap nama host Container Registry hanya dipetakan ke satu repositori gcr.io Artifact Registry yang sesuai di multi-region yang sama.
  • Nama untuk repositori gcr.io telah ditentukan sebelumnya dan Anda tidak dapat mengubahnya.

Jika memerlukan kontrol lebih besar atas lokasi repositori, Anda dapat bertransisi ke repositori pkg.dev di Artifact Registry. Karena repositori pkg.dev tidak memiliki dukungan untuk domain gcr.io, pendekatan transisi ini memerlukan lebih banyak perubahan pada otomatisasi dan alur kerja yang ada. Lihat Memilih opsi transisi untuk mempelajari perbedaan fitur.

Membuat repositori

Buat repositori gcr.io agar Anda dapat mengonfigurasi akses untuk pengguna dan menyalin image Container Registry yang ada ke Artifact Registry sebelum mengaktifkan pengalihan.

Pembuatan repositori manual

Buat repositori gcr.io secara manual jika Anda ingin menggunakan kunci enkripsi yang dikelola pelanggan (CMEK) untuk mengenkripsi konten repositori atau jika ada batasan lokasi di organisasi Google Cloud Anda yang memblokir pembuatan resource baru di lokasi tertentu.

Untuk membuat repositori gcr.io secara manual:

  1. Jika Anda menggunakan CMEK, buat kunci yang akan digunakan dengan repositori ini dan berikan izin untuk menggunakan kunci tersebut. Lihat Mengaktifkan kunci enkripsi yang dikelola pelanggan.

  2. Tambahkan repositori.

    Konsol

    1. Buka halaman Repositories di konsol Google Cloud.

      Buka halaman Repositori

    2. Klik Create Repository.

    3. Tentukan nama repositori.

      Nama host Container Registry Nama repositori Artifact Registry
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io

    4. Tentukan Docker sebagai format repositori.

    5. Di bagian Location Type, tentukan multi-region untuk repositori:

      Nama host Container Registry Lokasi repositori Artifact Registry Nama repositori Artifact Registry
      gcr.io us gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io europe eu.gcr.io
      us.gcr.io us us.gcr.io

    6. Tambahkan deskripsi untuk repositori. Jangan sertakan data sensitif, karena deskripsi repositori tidak dienkripsi.

    7. Di bagian Encryption, pilih mekanisme enkripsi untuk repositori.

      • Kunci yang dikelola Google - Mengenkripsi konten repositori dengan kunci milik dan dikelola Google.
      • Kunci yang dikelola pelanggan - Mengenkripsi konten repositori dengan kunci yang Anda kontrol melalui Cloud Key Management Service. Untuk petunjuk penyiapan kunci, lihat Menyiapkan CMEK untuk repositori.

    8. Klik Create.

    gcloud

    Jalankan perintah berikut untuk membuat repositori baru:

    gcloud artifacts repositories create REPOSITORY \
    --repository-format=docker \
    --location=LOCATION \
    --description=DESCRIPTION \
    --kms-key=KMS-KEY

    Ganti nilai berikut:

    • REPOSITORY adalah nama repositori.

      Nama host Container Registry Nama repositori Artifact Registry
      gcr.io gcr.io
      asia.gcr.io asia.gcr.io
      eu.gcr.io eu.gcr.io
      us.gcr.io us.gcr.io

    • LOCATION adalah multi-region untuk repositori:

      Nama host Container Registry Lokasi repositori Artifact Registry Nama repositori Artifact Registry
      gcr.io us gcr.io
      asia.gcr.io asia asia.gcr.io
      eu.gcr.io europe eu.gcr.io
      us.gcr.io us us.gcr.io

    • DESCRIPTION adalah deskripsi repositori. Jangan sertakan data sensitif, karena deskripsi repositori tidak dienkripsi.

    • KMS-KEY adalah jalur lengkap ke kunci enkripsi Cloud KMS, jika Anda menggunakan kunci enkripsi yang dikelola pelanggan untuk mengenkripsi konten repositori. Jalurnya dalam format:

      projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

      Ganti nilai berikut:

      • KMS-PROJECT adalah project tempat kunci Anda disimpan.
      • KMS-LOCATION adalah lokasi kunci.
      • KEY-RING adalah nama key ring.
      • KEY adalah nama kunci.

    Anda dapat mengonfirmasi bahwa repositori telah dibuat dengan mencantumkan repositori dengan perintah berikut:

    gcloud artifacts repositories list

Sebelum mengalihkan traffic ke repositori baru, Anda harus memastikan bahwa otomatisasi yang ada dapat mengakses repositori. Langkah berikutnya adalah mengonfigurasi izin untuk memberikan akses ke repositori.

Memberikan izin ke repositori

Container Registry menggunakan peran Cloud Storage untuk mengontrol akses. Artifact Registry memiliki peran IAM-nya sendiri dan peran ini memisahkan peran baca, tulis, dan administrasi repositori dengan lebih jelas daripada Container Registry.

Untuk memetakan izin yang ada yang diberikan di bucket penyimpanan ke peran Artifact Registry yang disarankan dengan cepat, gunakan alat pemetaan peran.

Atau, Anda dapat melihat daftar akun utama dengan akses ke bucket penyimpanan menggunakan konsol Google Cloud.

  1. Di Konsol Google Cloud, buka halaman Bucket Cloud Storage.

    Buka Bucket

  2. Klik bucket penyimpanan untuk host registry yang ingin Anda lihat. Dalam nama bucket, PROJECT-ID adalah project ID Google Cloud Anda.

    • gcr.io: artifacts.PROJECT-ID.appspot.com
    • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
    • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
    • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

  3. Klik tab Izin.

  4. Di tab Izin, klik subtab Lihat menurut peran.

  5. Luaskan peran untuk melihat akun utama yang memiliki peran tersebut.

Daftar ini mencakup peran IAM yang diberikan langsung di bucket dan peran yang diwarisi dari project induk. Berdasarkan peran, Anda dapat memilih peran Artifact Registry yang paling sesuai untuk diberikan.

Cloud Storage dan peran dasar

Berikan akses ke repositori Artifact Registry kepada pengguna dan akun layanan yang saat ini mengakses Container Registry. Untuk peran Cloud Storage yang diwarisi dari project induk, Anda harus memverifikasi bahwa akun utama saat ini menggunakan Container Registry. Beberapa akun utama mungkin hanya mengakses bucket Cloud Storage lain yang tidak terkait dengan Container Registry.

Peran dasar Pemilik, Editor, dan Viewer yang ada sebelum IAM memiliki akses terbatas ke bucket penyimpanan. Peran ini tidak secara intrinsik memberikan semua akses ke resource Cloud Storage yang disiratkan oleh namanya dan memberikan izin tambahan untuk layanan Google Cloud lainnya. Verifikasi pengguna dan akun layanan mana yang memerlukan akses ke Artifact Registry dan gunakan tabel pemetaan peran untuk membantu Anda memberikan peran yang tepat jika akses Artifact Registry sesuai.

Tabel berikut memetakan peran Artifact Registry berdasarkan izin yang diberikan oleh peran Cloud Storage bawaan untuk akses Container Registry.

Akses yang diperlukan Peran saat ini Peran Artifact Registry Tempat untuk memberikan peran
Hanya gambar pull (hanya baca) Storage Object Viewer
(roles/storage.objectViewer)		 Pembaca Artifact Registry
(roles/artifactregistry.reader) 		Repositori Artifact Registry atau project Google Cloud
  • Mengirim dan mengambil image (baca dan tulis)
  • Hapus beberapa gambar
 Storage Legacy Bucket Writer
(roles/storage.legacyBucketWriter)		 Administrator Repositori Artifact Registry
(roles/artifactregistry.repoAdmin)		 Repositori Artifact Registry atau project Google Cloud
Buat repositori gcr.io di Artifact Registry saat pertama kali image dikirim ke nama host gcr.io dalam project. Storage Admin
(roles/storage.admin)		 Administrator Repositori Create-on-push Artifact Registry
(roles/artifactregistry.createOnPushRepoAdmin)		 Project Google Cloud
Membuat, mengelola, dan menghapus repositori Storage Admin
(roles/storage.admin)		 Administrator Artifact Registry
(roles/artifactregistry.Admin)		 Project Google Cloud
Peran agen layanan yang diwariskan dari project

Akun layanan default untuk layanan Google Cloud memiliki perannya sendiri yang diberikan di tingkat project. Misalnya, agen layanan untuk Cloud Run memiliki peran Agen Layanan Cloud Run.

Pada umumnya, peran agen layanan ini berisi izin default yang setara untuk Container Registry dan Artifact Registry, dan Anda tidak perlu melakukan perubahan tambahan jika menjalankan Artifact Registry dalam project yang sama dengan layanan Container Registry yang ada.

Lihat referensi peran agen layanan untuk mengetahui detail tentang izin dalam peran agen layanan.

Peran khusus

Gunakan tabel pemetaan peran untuk membantu Anda menentukan peran yang akan diberikan kepada pengguna atau akun layanan berdasarkan tingkat akses yang mereka perlukan.

Untuk mengetahui petunjuk tentang cara memberikan peran Artifact Registry, lihat Mengonfigurasi peran dan izin.

Menyalin container dari Container Registry

Sebaiknya gunakan alat migrasi otomatis kami untuk menyalin image dari Container Registry ke Artifact Registry.

Jika Anda ingin menggunakan alat lain untuk menyalin image, lihat Menyalin image dari Container Registry

Menyiapkan fitur lainnya

Bagian ini menjelaskan konfigurasi untuk fitur lain yang mungkin telah Anda siapkan di Container Registry.

Artifact Analysis

Artifact Analysis mendukung Container Registry dan Artifact Registry. Kedua produk tersebut menggunakan Artifact Analysis API yang sama untuk metadata gambar dan pemindaian vulnerability, serta topik Pub/Sub yang sama untuk notifikasi Analisis Artefak.

Namun, tindakan berikut hanya terjadi jika pengalihan diaktifkan:

  • Pemindaian otomatis repositori gcr.io di Artifact Registry.
  • Menyertakan aktivitas repositori gcr.io dalam notifikasi Pub/Sub.

Anda dapat terus menggunakan perintah gcloud container images untuk mencantumkan catatan dan kemunculan yang terkait dengan jalur image gcr.io.

Container Registry Artifact Registry
Memindai kerentanan OS dan paket bahasa dengan pemindaian on demand dalam image dengan OS yang didukung. Pemindaian otomatis hanya menampilkan informasi kerentanan OS. Pelajari lebih lanjut jenis pemindaian.
Pemindaian on-demand
Pemindaian otomatis
  • Perintah Google Cloud CLI gcloud container images menyertakan flag untuk melihat hasil pemindaian, termasuk kerentanan dan metadata lainnya.
  • Pemindaian hanya menampilkan informasi kerentanan OS untuk image di Container Registry dengan sistem operasi yang didukung.
Memindai kerentanan paket bahasa dan OS dengan pemindaian on-demand dan otomatis. Pelajari lebih lanjut jenis pemindaian.
Pemindaian on-demand
Pemindaian otomatis
  • Perintah Google Cloud CLI gcloud artifacts docker images menyertakan flag untuk melihat hasil pemindaian, termasuk kerentanan dan metadata lainnya.
  • Pemindaian menampilkan informasi kerentanan OS untuk image di Artifact Registry dengan sistem operasi yang didukung dan informasi kerentanan paket bahasa untuk sistem operasi yang didukung dan tidak didukung.

Notifikasi Pub/Sub

Artifact Registry memublikasikan perubahan ke topik gcr yang sama dengan Container Registry. Tidak diperlukan konfigurasi tambahan jika Anda sudah menggunakan Pub/Sub dengan Container Registry dalam project yang sama dengan Artifact Registry. Namun, Artifact Registry tidak memublikasikan pesan untuk repositori gcr.io hingga Anda mengaktifkan pengalihan.

Jika Anda menyiapkan Artifact Registry dalam project terpisah, topik gcr mungkin tidak ada. Untuk petunjuk penyiapan, lihat Mengonfigurasi notifikasi Pub/Sub.

Mengaktifkan pengalihan traffic gcr.io

Setelah membuat repositori gcr.io dan mengonfigurasi izin serta autentikasi untuk klien pihak ketiga, Anda dapat mengaktifkan pengalihan traffic gcr.io.

Jika mengalami masalah setelah mengaktifkan pengalihan, Anda dapat merutekan traffic kembali ke Container Registry dengan menjalankan perintah gcloud artifacts settings disable-upgrade-redirection, lalu mengaktifkan pengalihan lagi setelah mengatasi masalah tersebut.

Memverifikasi izin untuk mengaktifkan pengalihan

Untuk mengaktifkan pengalihan, Anda harus memiliki izin berikut di tingkat project:

  • artifactregistry.projectsettings.update - Izin untuk memperbarui setelan project Registry Artefak. Izin ini ada dalam peran Administrator Artifact Registry (roles/artifactregistry.admin).
  • storage.buckets.update - Izin untuk memperbarui bucket penyimpanan di seluruh project. Izin ini ada dalam peran Storage Admin (roles/storage.admin).

Jika Anda tidak memiliki izin ini, minta administrator untuk memberikan izin tersebut di tingkat project.

Perintah berikut memberikan peran Artifact Registry Administrator dan Storage Admin pada project.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

Ganti nilai berikut:

  • PROJECT_ID adalah project ID Google Cloud.
  • PRINCIPAL adalah alamat email untuk akun yang Anda perbarui. Misalnya my-user@example.com

Memvalidasi penyiapan project

Untuk memvalidasi penyiapan project, jalankan perintah berikut:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

Ganti PROJECT_ID dengan project ID Google Cloud Anda.

Artifact Registry memeriksa repositori yang dipetakan ke nama host Container Registry.

Meskipun Artifact Registry dapat membuat repositori gcr.io yang tidak ada untuk Anda saat mengaktifkan pengalihan, sebaiknya buat repositori tersebut terlebih dahulu agar Anda dapat melakukan tindakan berikut sebelum mengaktifkan pengalihan:

Mengaktifkan pengalihan

Untuk mengaktifkan pengalihan traffic gcr.io:

Untuk mengaktifkan pengalihan, jalankan perintah berikut:

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Ganti PROJECT_ID dengan project ID Google Cloud Anda.

Artifact Registry mulai mengaktifkan pengalihan.

Untuk memeriksa status pengalihan saat ini, jalankan perintah berikut:

gcloud artifacts settings describe

Jika pengalihan diaktifkan, hasilnya adalah:

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

Semua traffic ke gcr.io, asia.gcr.io, eu.gcr.io, dan us.gcr.io akan dialihkan, meskipun Anda tidak membuat repositori gcr.io untuk semua nama host Container Registry. Jika Anda mendorong image ke nama host yang tidak memiliki repositori Artifact Registry yang sesuai, Artifact Registry akan membuat repositori jika Anda memiliki peran dengan izin artifactregistry.repositories.createOnPush. Peran bawaan Create-on-push Writer (artifactregistry.createOnPushWriter) dan Create-on-push Repository Administrator (artifactregistry.createOnPushRepoAdmin) memiliki izin ini.

Dengan mengaktifkan pengalihan, Anda dapat menguji otomatisasi dan memverifikasi bahwa Anda dapat mendorong dan menarik image menggunakan repositori gcr.io baru.

Memverifikasi pengalihan

Pastikan permintaan pull dan push ke nama host gcr.io berfungsi.

  1. Kirim image pengujian ke salah satu repositori gcr.io menggunakan jalur gcr.io-nya.

    1. Beri tag pada gambar menggunakan jalur gcr.io. Misalnya, perintah ini memberi tag pada gambar local-image sebagai us.gcr.io/my-project/test-image:

      docker tag local-image us.gcr.io/my-project/test-image

    2. Kirim gambar yang Anda beri tag. Misalnya, perintah ini mendorong gambar us.gcr.io/my-project/test-image:

      docker push us.gcr.io/my-project/test-image

  2. Cantumkan gambar di repositori untuk memverifikasi bahwa gambar berhasil diupload. Misalnya, untuk mencantumkan image di us.gcr.io/my-project, jalankan perintah:

    gcloud container images list --repository=us.gcr.io/my-project

  3. Tarik image dari repositori menggunakan jalur Container Registry-nya. Misalnya, perintah ini menarik gambar us.gcr.io/my-project/test-image.

    docker pull us.gcr.io/my-project/test-image

Setelah pengujian awal ini, verifikasi bahwa otomatisasi yang ada untuk mem-build dan men-deploy image berfungsi seperti yang diharapkan, termasuk:

  • Pengguna dan akun layanan yang menggunakan Container Registry masih dapat mendorong, menarik, dan men-deploy image saat pengalihan diaktifkan.
  • Otomatisasi Anda hanya mengirim image ke repositori yang ada.
  • Jika pemindaian kerentanan Artifact Analysis diaktifkan, pemindaian akan mengidentifikasi image dengan kerentanan di repositori gcr.io.
  • Jika Anda menggunakan Otorisasi Biner, kebijakan yang ada akan berfungsi dengan benar untuk image yang di-deploy dari repositori gcr.io.
  • Langganan Pub/Sub yang dikonfigurasi menyertakan notifikasi untuk perubahan di repositori gcr.io Anda.

Membersihkan image Container Registry

Jika pengalihan diaktifkan, perintah untuk menghapus image di jalur gcr.io akan menghapus image di repositori gcr.io Artifact Registry yang sesuai. Perintah hapus untuk menghapus image di jalur gcr.io tidak menghapus image yang disimpan di host Container Registry.

Untuk menghapus semua image Container Registry dengan aman, hapus bucket Cloud Storage untuk setiap nama host Container Registry.

Untuk menghapus setiap bucket penyimpanan Container Registry:

Konsol

  1. Buka halaman Cloud Storage di konsol Google Cloud.

  2. Pilih bucket penyimpanan yang akan dihapus. Dalam nama bucket, PROJECT-ID adalah project ID Google Cloud Anda.

    • gcr.io: artifacts.PROJECT-ID.appspot.com
    • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
    • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
    • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

  3. Klik Hapus. Kotak dialog konfirmasi akan muncul.

  4. Untuk mengonfirmasi penghapusan, masukkan nama bucket, lalu klik Hapus.

gcloud

Jika Anda ingin menghapus seratus ribu gambar atau lebih secara massal di bucket, hindari penggunaan gcloud CLI karena proses penghapusan memerlukan waktu lama untuk diselesaikan. Sebagai gantinya, gunakan Konsol Google Cloud untuk melakukan operasi tersebut. Untuk informasi selengkapnya, lihat menghapus objek Cloud Storage secara massal.

Untuk menghapus bucket, gunakan perintah gcloud storage rm dengan flag --recursive.

gcloud storage rm gs://BUCKET-NAME --recursive

Ganti BUCKET-NAME dengan nama bucket penyimpanan Container Registry. Dalam nama bucket, PROJECT-ID adalah project ID Google Cloud Anda.

  • gcr.io: artifacts.PROJECT-ID.appspot.com
  • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
  • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
  • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

Responsnya akan terlihat seperti contoh berikut:

Removing gs://artifacts.my-project.appspot.com/...

Jika layanan Google Cloud lainnya berjalan di project Google Cloud yang sama, biarkan Container Registry API diaktifkan. Jika Anda mencoba menonaktifkan Container Registry API. Container Registry menampilkan peringatan jika layanan lain dengan dependensi yang dikonfigurasi diaktifkan dalam project. Menonaktifkan Container Registry API akan otomatis menonaktifkan layanan apa pun dalam project yang sama dengan dependensi yang dikonfigurasi, meskipun saat ini Anda tidak menggunakan Container Registry dengan layanan tersebut.

Langkah selanjutnya