Mendorong dan menarik gambar

Halaman ini menjelaskan pengiriman dan pengambilan image container dengan Docker. Panduan ini juga memberikan informasi tentang cara mengambil image dengan alat crictl jika Anda memecahkan masalah di Google Kubernetes Engine.

Untuk informasi tentang cara men-deploy ke lingkungan runtime Google Cloud, lihat Men-deploy ke Google Cloud.

Untuk mendapatkan petunjuk tentang mencantumkan, memberi tag, dan menghapus gambar, lihat Mengelola gambar.

Sebelum memulai

1. Jika repositori target tidak ada, buat repositori baru.
2. Anda harus memiliki setidaknya access Artifact Registry Writer ke repositori.
3. Instal Docker jika belum terinstal.

Peran yang diperlukan

Untuk mendapatkan izin yang diperlukan untuk mengirim dan mengambil image, minta administrator untuk memberi Anda peran IAM berikut pada repositori:

• Ambil image: Artifact Registry Reader (roles/artifactregistry.reader)
• Memberi tag dan mengirim image: Artifact Registry Writer (roles/artifactregistry.writer)

Untuk mengetahui informasi selengkapnya tentang pemberian peran, lihat Mengelola akses.

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

Mengautentikasi ke repositori

Anda harus melakukan autentikasi ke repositori setiap kali menggunakan Docker atau klien pihak ketiga lainnya dengan repositori Docker. Bagian ini memberikan ringkasan singkat tentang hal yang Anda perlukan agar autentikasi berhasil. Untuk mengetahui petunjuk selengkapnya, lihat Menyiapkan autentikasi untuk Docker.

Menggunakan helper kredensial

Untuk gcloud CLI credential helper atau pembantu kredensial mandiri, host Artifact Registry yang Anda gunakan harus ada di file konfigurasi Docker.

Artifact Registry tidak otomatis menambahkan semua host registry ke file konfigurasi Docker. Waktu respons Docker menjadi jauh lebih lambat jika ada banyak registry yang dikonfigurasi. Untuk meminimalkan jumlah registry dalam file konfigurasi, Anda dapat menambahkan host yang diperlukan ke file tersebut.

Untuk mengonfirmasi host mana yang dikonfigurasi, jalankan perintah berikut untuk menampilkan konten file konfigurasi:

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

Bagian credHelpers mencantumkan host Docker Artifact Registry yang dikonfigurasi. Nama host berakhiran -docker.pkg.dev. Contoh berikut menunjukkan beberapa host yang dikonfigurasi untuk helper kredensial gcloud CLI.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

Jika host yang ingin Anda gunakan tidak ada dalam daftar, jalankan lagi helper kredensial untuk menambahkan host. Misalnya, perintah berikut menambahkan us-east1-docker.pkg.dev.

• pembantu kredensial gcloud CLI:

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

• Helper kredensial mandiri

  docker-credential-gcr configure-docker us-east1-docker.pkg.dev
  

Menggunakan token akses

Untuk autentikasi token akses, Anda membuat token dan menggunakannya sebagai sandi dengan perintah docker login. Token berlaku selama 60 menit, jadi sebaiknya Anda melakukan autentikasi sesaat sebelum memberi tag, mengirim, atau menarik image.

Contoh berikut menghasilkan token akses menggunakan peniruan akun layanan, lalu melakukan autentikasi ke Artifact Registry. Anda harus memiliki izin pada peran Service Account Token Creator (roles/iam.serviceAccountTokenCreator) untuk membuat token dengan cara ini.

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

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

Jika tidak memiliki izin untuk meniru identitas akun layanan, Anda dapat mengaktifkan akun layanan di sesi gcloud CLI, lalu mendapatkan token. Untuk mengetahui detailnya, lihat petunjuk untuk menyiapkan autentikasi token akses.

Menggunakan kunci akun layanan

Untuk kunci akun layanan, gunakan kunci tersebut sebagai sandi dengan perintah docker login.

Misalnya, perintah berikut menggunakan kunci akun layanan berenkode base64 dalam file key.json untuk melakukan autentikasi ke us-east1-docker.pkg.dev.

Linux

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

Windows

docker login -u _json_key_base64 --password-stdin https://us-east1-docker.pkg.dev < key.json

Untuk mengetahui detailnya, lihat petunjuk untuk menyiapkan autentikasi kunci akun layanan.

Mengirim gambar

Mode repositori: standar

Untuk mengirim image lokal ke repositori Docker standar, Anda harus memberinya tag dengan nama repositori, lalu mengirim image tersebut.

Jika repositori Docker Artifact Registry mengaktifkan ketetapan tag, tag harus selalu merujuk ringkasan image yang sama dalam repositori. Anda tidak dapat menggunakan tag pada versi lain dari image yang sama yang Anda kirim ke repositori. Untuk mengetahui informasi selengkapnya tentang ringkasan image, tag, dan immutabilitas tag, lihat Versi image container.

Untuk gambar besar, batas berikut berlaku:

Waktu upload

Jika Anda melakukan autentikasi ke Artifact Registry menggunakan token akses, token hanya valid selama 60 menit. Jika Anda memperkirakan waktu upload akan lebih dari 60 menit, gunakan metode autentikasi yang lain.

Ukuran gambar

Ukuran artefak maksimum adalah 5 TB.

Artifact Registry tidak mendukung potongan upload Docker. Beberapa alat mendukung upload gambar berukuran besar dengan upload potongan atau satu upload monolitik. Anda harus menggunakan upload monolitik untuk mengirim image ke Artifact Registry.

Memberi tag pada foto lokal

1. Pastikan Anda diautentikasi ke repositori.

2. Tentukan nama gambar. Format nama gambar lengkap adalah:

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   Ganti nilai berikut:

   • LOCATION adalah lokasi regional atau multi-regional dari repositori tempat gambar disimpan, misalnya us-east1 atau us.

   • PROJECT-ID adalah project ID Konsol Google Cloud Anda. Jika project ID Anda berisi titik dua (:), lihat Project cakupan domain.

   • REPOSITORY adalah nama repositori tempat gambar disimpan.

   • IMAGE adalah nama gambar. Nama ini bisa berbeda dari nama lokal gambar.

   Misalnya, perhatikan gambar dengan karakteristik berikut:

   • Lokasi repositori: us-east1
   • Nama repositori: my-repo
   • Project ID: my-project
   • Nama gambar lokal: my-image
   • Nama image target: test-image

   Nama gambar untuk contoh ini adalah:

   us-east1-docker.pkg.dev/my-project/my-repo/test-image
   

   Catatan: Nama untuk image yang akan Anda simpan di repositori dapat berbeda dengan nama image di komputer lokal Anda.

   Untuk mengetahui detail tentang format nama image, termasuk menangani project cakupan domain, lihat Nama repositori dan image.

3. Beri tag pada image lokal dengan nama repositori.

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   Ganti SOURCE-IMAGE dengan nama gambar atau ID gambar lokal dan TAG dengan tag. Jika Anda tidak menentukan tag, Docker akan menerapkan tag latest default.

   Jika setelan tag gambar yang tidak dapat diubah diaktifkan, tag harus unik untuk setiap versi gambar, termasuk tag latest. Anda tidak dapat mengirim image ke repositori jika tag sudah digunakan oleh versi lain dari image yang sama dalam repositori. Untuk memastikan apakah setelan diaktifkan untuk repositori, jalankan perintah:

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

   Untuk contoh gambar dari langkah sebelumnya, Anda akan menggunakan perintah berikut jika gambar lokal my-image berada di direktori saat ini:

   docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image
   

   Jika Anda ingin menerapkan tag tertentu, gunakan perintah:

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   Untuk menggunakan tag staging dengan gambar contoh, Anda menambahkan :staging ke perintah:

   docker tag my-image us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Mengirim image yang diberi tag ke Artifact Registry

Catatan: Artifact Registry tidak mendukung potong upload Docker. Beberapa alat image container mendukung upload image container besar dengan upload terpotong atau upload monolitik tunggal. Anda harus menggunakan upload monolitik saat mengirim image container ke Artifact Registry.

1. Pastikan Anda diautentikasi ke repositori.

   Jika Anda menggunakan gcloud auth configure-docker atau docker-credential-gcr configure-docker untuk mengonfigurasi klien Docker, pastikan nama host target ada di file konfigurasi Docker.

2. Kirim gambar yang diberi tag dengan perintah:

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   Perintah ini mendorong image yang memiliki tag latest. Jika Anda ingin mengirim gambar yang memiliki tag yang berbeda, gunakan perintah:

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

Saat Anda mengirim image, image tersebut akan disimpan di repositori yang ditentukan.

Setelah mengirim gambar, Anda dapat:

• Buka Google Cloud Console untuk melihat gambar.

• Jalankan perintah gcloud untuk melihat tag gambar dan ringkasan yang dibuat secara otomatis:

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  Contoh output berikut menunjukkan ringkasan gambar yang terpotong, tetapi perintah selalu menampilkan ringkasan gambar lengkap.

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

Menarik image dengan Docker

Mode repositori: standar, jarak jauh, virtual

1. Pastikan Anda diautentikasi ke repositori.

   Jika Anda menggunakan gcloud auth configure-docker atau docker-credential-gcr configure-docker untuk mengonfigurasi klien Docker, pastikan nama host target ada di file konfigurasi Docker.

2. Untuk mengambil dari repositori, gunakan perintah:

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   atau

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

   Ganti nilai berikut:

   • LOCATION adalah lokasi regional atau multi-regional dari repositori tempat gambar disimpan, misalnya us-east1 atau us.
   • PROJECT adalah project ID Konsol Google Cloud Anda. Jika project ID Anda berisi titik dua (:), lihat Project cakupan domain.
   • REPOSITORY adalah nama repositori tempat gambar disimpan.
   • IMAGE adalah nama image di repositori.
   • TAG adalah tag untuk versi gambar yang ingin Anda tarik.
   • IMAGE-DIGEST adalah nilai hash sha256 dari konten gambar. Setiap versi gambar memiliki ringkasan gambar yang unik. Di Konsol Google Cloud, klik gambar tertentu untuk melihat metadatanya. Ringkasan tercantum sebagai Ringkasan gambar.

   Misalnya, perhatikan gambar dengan karakteristik berikut:

   • Lokasi repositori: us-east1
   • Nama repositori: my-repo
   • Project ID: my-project
   • Nama image: test-image
   • Tag: staging

   Perintah untuk menarik gambar ini adalah:

   docker pull us-east1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Docker mendownload image yang ditentukan.

Jika Anda meminta image dari repositori jarak jauh, repositori jarak jauh akan mendownload dan men-cache image dari sumber upstream jika salinan yang di-cache tidak ada.

Jika Anda meminta image dari repositori virtual, Artifact Registry akan menelusuri repositori upstream untuk menemukan image yang diminta. Jika Anda meminta versi yang tersedia di lebih dari satu repositori upstream, Artifact Registry akan memilih repositori upstream yang akan digunakan berdasarkan setelan prioritas yang dikonfigurasi untuk repositori virtual.

Misalnya, pertimbangkan repositori virtual dengan setelan prioritas berikut untuk repositori upstream:

• main-repo: Prioritas ditetapkan ke 100
• secondary-repo1: Prioritas ditetapkan ke 80.
• secondary-repo2: Prioritas ditetapkan ke 80.
• test-repo: Prioritas ditetapkan ke 20.

main-repo memiliki nilai prioritas tertinggi, sehingga repositori virtual selalu menelusurinya terlebih dahulu.

secondary-repo1 dan secondary-repo2 memiliki prioritas yang ditetapkan ke 80. Jika image yang diminta tidak tersedia di main-repo, Artifact Registry akan menelusuri repositori ini berikutnya. Karena keduanya memiliki nilai prioritas yang sama, Artifact Registry dapat memilih untuk menyalurkan image dari salah satu repositori jika versi tersebut tersedia di keduanya.

test-repo memiliki nilai prioritas terendah dan akan menayangkan artefak tersimpan jika tidak ada repositori upstream lain yang memilikinya.

Mengambil gambar dengan crictl

crictl adalah alat command line yang berguna bagi developer runtime CRI untuk men-debug runtime mereka tanpa perlu menyiapkan komponen Kubernetes. Jika node Google Kubernetes Engine Anda menggunakan runtime dalam container, Anda dapat mengambil image dari Artifact Registry menggunakan crictl.

Karena crictl pada dasarnya merupakan alat pemecahan masalah, beberapa perintah docker seperti mengirim atau memberi tag pada gambar tidak tersedia.

Untuk mengambil image dari Artifact Registry:

1. Di Konsol Google Cloud, buka halaman VM Instances.

   Buka Instance VM

2. SSH ke node yang sedang Anda pecahkan masalahnya.

3. Mendapatkan token akses untuk autentikasi dengan repositori.

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. Ambil gambar menggunakan crictl pull --creds dan nilai access_token

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   atau

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   Outputnya akan terlihat seperti berikut:

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

Langkah selanjutnya

• Pelajari cara mengelola tag dan menghapus gambar.
• Jika Anda ingin menjalankan container di Compute Engine, pelajari container di Compute Engine.
• Menggunakan crictl untuk men-debug node Kubernetes
• Pelajari cara menggunakan crictl untuk mengambil image dari repositori Artifact Registry pribadi
• Pelajari lebih lanjut cara mengonfigurasi registry gambar crictl