Dengan mengonfigurasi mirror registry lokal, Anda dapat membuat dan mengupgrade cluster dengan
menarik image container dari endpoint lokal, bukan registry upstream
seperti gcr.io. Pendekatan ini membantu mempercepat pembuatan pod, menghindari pembatasan kapasitas pull eksternal, dan melindungi alur kerja deployment Anda dari pemadaman layanan registry publik. Anda dapat mengaktifkan atau menonaktifkan pencerminan registry kapan saja selama siklus proses cluster.
Cara kerja mirror registry
Mirror registry adalah salinan lokal dari registry publik yang menyalin atau mencerminkan struktur file registry publik. Misalnya, anggaplah jalur
ke mirror registry lokal Anda adalah 172.18.0.20:5000. Saat containerd
menemukan permintaan untuk mengambil image seperti
gcr.io/kubernetes-e2e-test-images/nautilus:1.0, containerd akan mencoba mengambil
image tersebut, bukan dari gcr.io, tetapi dari registry lokal Anda di jalur
berikut: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0. Jika image tidak ada di jalur registry lokal ini, image akan ditarik secara otomatis dari registry publik gcr.io.
Menggunakan mirror registry memberikan manfaat berikut:
- Melindungi Anda dari pemadaman layanan registry publik.
- Mempercepat pembuatan pod.
- Memungkinkan Anda melakukan pemindaian kerentanan sendiri.
- Menghindari batasan yang diberlakukan oleh registry publik terkait frekuensi Anda dapat mengeluarkan perintah ke registry tersebut.
Sebelum memulai
- Anda harus menyiapkan server Artifact Registry di jaringan Anda.
- Jika server registry Anda menjalankan sertifikat TLS pribadi, Anda harus memiliki file certificate authority (CA).
- Jika server registry Anda memerlukan autentikasi, Anda harus memiliki kredensial login atau file konfigurasi Docker yang tepat.
- Jika Anda menggunakan registry Red Hat Quay, Anda mungkin perlu membuat struktur direktori registry lokal secara manual.
- Untuk menggunakan mirror registry, Anda harus menetapkan runtime container ke containerd.
Pastikan Anda memiliki kapasitas disk yang cukup di workstation admin untuk upload image. Perintah upload image,
bmctl push images, mendekompresi file paket image yang didownload, lalu mengekstrak semua file image secara lokal sebelum menguploadnya. Anda memerlukan setidaknya tiga kali ukuran file paket image yang didownload dalam kapasitas disk untuk upload image.Misalnya, file
bmpackages_1.33.0-gke.799.tar.xzyang dikompresi memerlukan kapasitas disk sekitar 12 GB, jadi Anda harus memiliki kapasitas disk kosong minimal 36 GB sebelum mendownload file.Jika Anda melakukan upgrade lewati (mengupgrade dua versi minor dalam satu operasi), Anda harus mengupload image dari file paket image untuk versi target (
N+2) dan versi perantara (N+1). Berdasarkan contoh ini, Anda memerlukan sekitar 72 GB kapasitas disk kosong untuk upload image. Untuk mengetahui informasi selengkapnya tentang versi perantara, lihat Persyaratan tambahan untuk mirror registry.
Mendownload semua image yang diperlukan untuk Google Distributed Cloud
Download versi terbaru alat bmctl dan paket image dari halaman Download.
Mengupload image container ke server registry Anda
Saat Anda menggunakan bmctl push images untuk mengupload image container ke server repositori, bmctl akan melakukan langkah-langkah berikut secara berurutan:
Dekompresi file tar terkompresi paket image yang didownload, seperti
bmpackages_1.36.300-gke.150.tar.xzke dalambmpackages_1.36.300-gke.150.tar.Ekstrak semua image dari file tar yang didekompresi ke dalam direktori bernama
bmpackages_1.36.300-gke.150.Kirim setiap file image ke registry pribadi yang ditentukan.
bmctlmenggunakan nilai--usernamedan--passworduntuk autentikasi dasar guna mengirim image ke registry pribadi Anda.
Bagian berikut mengilustrasikan beberapa variasi umum perintah bmctl push
images untuk mengupload image ke server repositori Anda.
Melakukan autentikasi dengan registry Anda dan membagikan sertifikat TLS
Perintah berikut menyertakan flag --username dan --password untuk autentikasi pengguna dengan server registry Anda. Perintah ini juga menyertakan flag --cacert untuk meneruskan sertifikat transport layer security (TLS) CA, yang digunakan untuk komunikasi server registry yang aman, termasuk push dan pull image. Flag ini memberikan keamanan dasar untuk server registry Anda.
Jika server registry Anda memerlukan autentikasi dan Anda tidak menggunakan flag --username dan --password, Anda akan diminta untuk memberikan kredensial saat menjalankan bmctl push images. Anda dapat mengetik sandi atau memilih file konfigurasi docker yang berisi kredensial.
Untuk mengupload image dengan autentikasi dan sertifikat CA pribadi, gunakan perintah seperti berikut:
bmctl push images \
--source IMAGES_TAR_FILE_PATH \
--private-registry REGISTRY_IP:PORT \
--username USERNAME \
--password PASSWORD \
--cacert CERT_PATH
Ganti kode berikut:
IMAGES_TAR_FILE_PATH: jalur file tar paket image yang didownload, sepertibmpackages_1.36.300-gke.150.tar.xz.REGISTRY_IP:PORT: alamat IP dan port server registry pribadi.USERNAME: nama pengguna yang memiliki izin akses untuk mengupload image ke server registry.PASSWORD: sandi pengguna untuk melakukan autentikasi dengan server registry.CERT_PATH: jalur file sertifikat CA, jika server registry Anda menggunakan sertifikat TLS pribadi.
Contoh:
bmctl push images \
--source bmpackages_1.36.300-gke.150.tar.xz \
--private-registry 172.18.0.20:5000 \
--username alex --password pa55w0rd \
--cacert /etc/pki/tls/certs/ca-bundle.crt
Mengupload image tanpa autentikasi atau sertifikat pengguna
Jika server registry Anda tidak memerlukan kredensial, seperti nama pengguna dan
sandi, tentukan --need-credential=false dalam perintah bmctl. Jika server registry Anda menggunakan sertifikat TLS publik, Anda tidak perlu menggunakan flag --cacert. Jenis perintah upload ini paling cocok untuk lingkungan pengujian, yang keamanannya tidak terlalu menjadi perhatian dibandingkan dalam produksi.
Untuk mengupload image tanpa autentikasi atau sertifikat CA pribadi, gunakan perintah seperti berikut:
bmctl push images \
--source IMAGES_TAR_FILE_PATH \
--private-registry REGISTRY_IP:PORT \
--need-credential=false
Contoh:
bmctl push images \
--source bmpackages_1.36.300-gke.150.tar.xz \
--private-registry 172.18.0.20:5000 \
--need-credential=false.
Menyesuaikan jumlah thread
Rutinitas upload image dapat memakan waktu karena ukuran dan jumlah image container dalam file tar paket image. Meningkatkan jumlah thread paralel akan membuat rutinitas berjalan lebih cepat. Anda dapat menggunakan flag --threads
untuk mengubah jumlah thread paralel yang digunakan bmctl push images.
Secara default, rutinitas upload gambar menggunakan 4 thread. Jika upload gambar Anda memerlukan waktu terlalu lama, tingkatkan nilai ini. Sebagai tolok ukur, di lingkungan pengujian Google, mengupload gambar dari workstation dengan 4 CPU memerlukan waktu sekitar 10 menit dengan 8 thread paralel.
bmctl push images \
--source IMAGES_TAR_FILE_PATH \
--private-registry REGISTRY_IP:PORT \
--cacert CERT_PATH \
--threads NUM_THREADS
Ganti NUM_THREADS dengan jumlah thread paralel yang digunakan untuk memproses upload gambar. Secara default, bmctl push images menggunakan empat thread paralel.
Perintah berikut meningkatkan jumlah thread untuk upload dari 4 menjadi
8 guna mengurangi waktu upload:
bmctl push images \
--source bmpackages_1.36.300-gke.150.tar.xz \
--private-registry 172.18.0.20:5000 \
--cacert ~/cert.pem \
--threads 8
Upload melalui proxy
Jika memerlukan proxy untuk mengupload image dari workstation ke server registry, Anda dapat menambahkan detail proxy sebelum perintah bmctl:
HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
--source=IMAGES_TAR_FILE_PATH \
--private-registry=REGISTRY_IP:PORT \
--cacert=CERT_PATH
Ganti kode berikut:
PROXY_IP:PORT: alamat IP dan port proxy.IMAGES_TAR_FILE_PATH: jalur file tar paket image yang didownload, sepertibmpackages_1.36.300-gke.150.tar.xz.REGISTRY_IP:PORT: alamat IP dan port server registry pribadi.CERT_PATH: jalur file sertifikat CA, jika server registry Anda menggunakan sertifikat TLS pribadi.
Masukkan nama pengguna dan sandi Anda saat diminta atau pilih file konfigurasi Docker.
Perintah berikut mengupload image melalui proxy:
HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
--source bmpackages_1.36.300-gke.150.tar.xz \
--private-registry 172.18.0.20:5000 \
--cacert ~/cert.pem
Menggunakan namespace Anda sendiri dengan bmctl push images
Jika Anda ingin menggunakan namespace Anda sendiri di server registry, bukan namespace root, containerd dapat mengambil dari namespace ini jika Anda menyediakan endpoint API untuk registry pribadi Anda di kolom registryMirrors.endpoint pada file konfigurasi cluster Anda. Endpoint biasanya dalam format
<REGISTRY_IP:PORT>/v2/<NAMESPACE>. Periksa panduan pengguna registry pribadi Anda untuk mengetahui detail spesifik. Untuk mengetahui informasi selengkapnya, lihat Tentang penggunaan v2 di endpoint registry.
bmctl push images \
--source=IMAGES_TAR_FILE_PATH \
--private-registry=REGISTRY_IP:PORT/NAMESPACE \
--cacert=CERT_PATH
Ganti NAMESPACE dengan nama namespace di server registry tempat Anda ingin mengupload image.
Misalnya, jika Anda hanya memiliki akses ke 198.51.20.1:5000/test-namespace/, Anda
dapat menggunakan perintah seperti berikut untuk mengupload semua image di bawah
namespace test-namespace:
bmctl push images \
--source=./bmpackages_1.36.300-gke.150.tar.xz \
--private-registry=198.51.20.1:5000/test-namespace \
--username=alex \
--password=pa55w0rd \
--cacert /etc/pki/tls/certs/ca-bundle.crt
Kemudian, dalam file konfigurasi cluster, Anda dapat menambahkan hal berikut untuk membuat
containerd mengambil dari namespace test-namespace:
registryMirrors:
- endpoint: https://198.51.20.1:5000/v2/test-namespace
Untuk mengetahui informasi selengkapnya tentang perintah bmctl push images, lihat referensi perintah bmctl.
Mengonfigurasi cluster untuk menggunakan mirror registry
Anda dapat mengonfigurasi mirror registry untuk cluster saat pembuatan cluster atau setiap kali Anda mengupdate cluster yang ada. Dua bagian berikut menjelaskan dua metode yang tersedia untuk mengonfigurasi mirror registry.
Menggunakan bagian header dalam file konfigurasi cluster
Mulai versi 1.35, Anda dapat mengonfigurasi atau mengupdate mirror registry dan registry pribadi untuk cluster admin dan pengguna dengan menentukannya di bagian header level teratas file konfigurasi cluster. Konfigurasi akan tetap ada di seluruh update.
Saat menjalankan bmctl update, konfigurasi registry apa pun di
bagian header akan otomatis menggantikan bagian spec.nodeConfig pada
file konfigurasi cluster.
Untuk versi 1.34 dan yang lebih lama, Anda harus menggunakan bagian nodeConfig.registryMirrors untuk menentukan registry mirror dan registry pribadi di cluster pengguna, bukan bagian header, karena bagian header tidak dipertahankan di seluruh update.
Contoh file konfigurasi cluster berikut menentukan bahwa image akan ditarik dari mirror registry lokal yang endpoint-nya adalah https://198.51.20.1:5000. Beberapa kolom yang muncul di awal
file konfigurasi ini dijelaskan di bagian berikut.
# Sample cluster config with registry mirror:
---
gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json
sshPrivateKeyPath: /root/ssh-key/id_rsa
registryMirrors:
- endpoint: https://198.51.20.1:5000
caCertPath: /root/ca.crt
pullCredentialConfigPath: /root/.docker/config.json
hosts:
- somehost.io
- otherhost.io
---
apiVersion: v1
kind: Namespace
metadata:
name: cluster-admin1
---
apiVersion: baremetal.cluster.gke.io/v1
kind: Cluster
metadata:
name: admin1
namespace: cluster-admin1
spec:
nodeConfig:
containerRuntime: containerd
...
Menggunakan bagian nodeConfig.registryMirrors dalam spesifikasi Cluster
Karena Anda dapat membagikan secret yang dibuat untuk cluster pengelolaan dengan cluster pengguna, Anda dapat menggunakan nodeConfig.registryMirrors dari admin pengelola atau cluster hybrid untuk menentukan duplikat registry dalam spesifikasi Cluster untuk cluster pengguna.
Untuk mengonfigurasi cluster pengguna agar menggunakan mirror registry yang sama dengan cluster admin, ikuti langkah-langkah berikut:
Dapatkan bagian
nodeConfig.registryMirror, termasuk referensi secret, darinodeConfig.registryMirrorsresource cluster admin:kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \ --kubeconfig ADMIN_KUBECONFIG \ -o yamlGanti kode berikut:
CLUSTER_NAME: nama cluster admin atau hybrid yang mengelola cluster pengguna.CLUSTER_NAMESPACE: nama namespace untuk cluster pengelola.ADMIN_KUBECONFIG: jalur file kubeconfig dari cluster pengelolaan.
Tambahkan konfigurasi
nodeConfig.registryMirrorsdari cluster admin ke file konfigurasi cluster dari cluster pengguna.Bagian
registryMirrorsdalam file konfigurasi cluster pengguna akan terlihat seperti contoh berikut:--- gcrKeyPath: /bmctl/bmctl-workspace/.sa-keys/my-gcp-project-anthos-baremetal-gcr.json sshPrivateKeyPath: /root/ssh-key/id_rsa --- apiVersion: v1 kind: Namespace metadata: name: cluster-user1 --- apiVersion: baremetal.cluster.gke.io/v1 kind: Cluster metadata: name: user1 namespace: cluster-user1 spec: nodeConfig: containerRuntime: containerd registryMirrors: - caCertSecretRef: name: the-secret-created-for-the-admin-cluster namespace: anthos-creds endpoint: https://172.18.0.20:5000 hosts: - somehost.io - otherhost.io pullCredentialSecretRef: name: the-image-pull-creds-created-for-the-admin-cluster namespace: anthos-creds ...
Untuk melakukan perubahan berikutnya pada konfigurasi mirror registry untuk cluster pengguna Anda, edit nodeConfig.registryMirrors di file konfigurasi cluster pengguna dan terapkan perubahan Anda dengan bmctl update.
Kolom hosts
containerd memeriksa bagian hosts dari file konfigurasi cluster untuk
menemukan host mana yang diduplikasi secara lokal. Host ini dipetakan ke endpoint mirror registry yang ditentukan dalam file konfigurasi cluster (registryMirror.endpoint). Dalam contoh file konfigurasi dari bagian sebelumnya, registry publik yang tercantum di bagian hosts adalah somehost.io dan otherhost.io. Karena registry publik ini muncul di bagian hosts, containerd akan memeriksa mirror registry pribadi terlebih dahulu saat menemukan permintaan pull untuk image dari somehost.io atau otherhost.io.
Misalnya, anggaplah containerd menerima perintah pull ke
somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Karena somehost.io tercantum sebagai salah satu host di bagian hosts pada file konfigurasi cluster, containerd akan mencari image kubernetes-e2e-test-images/nautilus:1.0 di mirror registry lokal. Jika somehost.io tidak tercantum
di bagian hosts, containerd tidak akan mengetahui bahwa mirror lokal
somehost.io ada. Dalam hal ini, containerd tidak memeriksa mirror untuk
image, dan mengambil image dari registry publik somehost.io.
Perhatikan bahwa secara default, Google Distributed Cloud otomatis menduplikasi image dari
gcr.io sehingga Anda tidak perlu mencantumkan gcr.io sebagai host di bagian hosts.
Nilai hosts dan nilai endpoint tidak boleh tumpang-tindih. Misalnya, contoh konfigurasi berikut menunjukkan host, europe-docker.pkg.dev, yang cocok dengan bagian domain dari nilai endpoint. Dalam hal ini, Anda tidak perlu
menentukan nilai hosts:
...
registryMirrors:
...
endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
hosts:
- europe-docker.pkg.dev
...
Kolom gcrKeyPath
Jika Anda ingin Google Distributed Cloud menggunakan Artifact Registry (gcr.io) secara otomatis untuk mengambil image yang tidak muncul di registry lokal, Anda harus menentukan jalur ke kunci akun layanan Artifact Registry.
Google Distributed Cloud tidak memiliki mekanisme untuk menyediakan kunci bagi registry publik lainnya.
Jika Anda tidak berencana menggunakan fitur yang menarik image dari gcr.io
saat image tidak muncul di registry lokal, Anda tidak perlu menambahkan
gcrKeyPath ke file konfigurasi cluster.
Kolom caCertPath
Jika registry Anda memerlukan sertifikat transport layer security (TLS) pribadi,
kolom ini akan mengambil jalur ke file sertifikat CA root server. File sertifikat ini harus berada di workstation admin, yaitu mesin yang menjalankan perintah bmctl. Jika registry Anda tidak memerlukan sertifikat TLS pribadi, Anda dapat mengosongkan kolom caCertPath.
Kolom pullCredentialConfigPath
Jika server registry Anda tidak memerlukan file konfigurasi Docker autentikasi, Anda dapat mengosongkan kolom pullCredentialConfigPath. Perhatikan bahwa
ini adalah jalur ke file konfigurasi pada mesin yang menjalankan perintah
bmctl.
Menggunakan mirror registry dengan cluster pengguna
Cluster pengguna tidak otomatis mengambil image dari mirror registry jika cluster adminnya telah dikonfigurasi untuk melakukannya. Agar cluster pengguna mengambil dari mirror registry, Anda harus mengonfigurasinya satu per satu seperti yang dijelaskan dalam Mengonfigurasi cluster untuk menggunakan mirror registry.
Memperbarui endpoint, sertifikat, dan kredensial pull registry mirror
Untuk memperbarui endpoint, sertifikat, atau kredensial pull registry mirror:
Dalam file konfigurasi cluster, perbarui endpoint, file sertifikat CA, dan jalur file konfigurasi kredensial pull.
Terapkan perubahan dengan menjalankan:
bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIGGanti kode berikut:
CLUSTER_NAMEdengan nama cluster yang ingin Anda update.ADMIN_KUBECONFIGdengan jalur file konfigurasi cluster adminnya.
Memverifikasi bahwa image ditarik dari mirror registry
Anda dapat menentukan apakah containerd mengambil image dari registry lokal dengan memeriksa konten file config.toml seperti yang ditunjukkan dalam langkah-langkah berikut:
Login ke node dan periksa konten file berikut:
/etc/containerd/config.tomlPeriksa bagian
plugins."io.containerd.grpc.v1.cri".registry.mirrorspada fileconfig.tomluntuk melihat apakah server registry Anda tercantum di kolomendpoint. Berikut adalah kutipan dari contoh fileconfig.tomlyang menampilkan kolomendpointdalam huruf tebal:version = 2 root = "/var/lib/containerd" state = "/run/containerd" ... [plugins."io.containerd.grpc.v1.cri".registry] [plugins."io.containerd.grpc.v1.cri".registry.configs] [plugins."io.containerd.grpc.v1.cri".registry.configs."gcr.io"] [plugins."io.containerd.grpc.v1.cri".registry.configs."privateregistry2.io".tls] ca_file = '/etc/containerd/certs.d/privateregistry2.io/ca.crt' [plugins."io.containerd.grpc.v1.cri".registry.mirrors] [plugins."io.containerd.grpc.v1.cri".registry.mirrors."gcr.io"] endpoint = ["http://privateregistry.io", "https://privateregistry2.io"] ...Jika mirror registry Anda muncul di kolom
endpoint, berarti node tersebut mengambil image dari mirror registry Anda, bukan dari registry publik.
Memecahkan masalah setelan mirror registry
Anda dapat menggunakan crictl, alat command line antarmuka runtime container, untuk menguji setelan registry dengan mendownload setiap file image. Setiap file image
diberi tag secara independen dengan string versi yang bermakna. Misalnya, image pengontrol API cluster diberi tag dengan versi rilis Google Distributed Cloud dan image etcd diberi tag dengan versi etcd yang sesuai.
Untuk rilis software Google Distributed Cloud khusus untuk bare metal versi 1.31.200-gke.59,
image pengontrol API cluster, cluster-api-controller, dan image etcd,
etcd, memiliki tag berikut:
cluster-api-controller:1.31.200-gke.59etcd:v3.4.30-0-gke.1
Mengambil image dari mirror registry
Jika mirror registry Anda tidak menggunakan namespace, gunakan perintah berikut untuk mengambil image:
crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG
Mengambil image dari mirror registry yang menggunakan namespace
Jika registry mirror Anda menggunakan namespace, gunakan perintah berikut untuk mengambil image:
crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG
Tentang penggunaan v2 di endpoint registry
Jika registry Anda menggunakan namespace kustom, Anda harus menambahkan namespace di endpoint registry (registryMirror.endpoint) dalam file konfigurasi cluster dengan v2/. Jika Anda tidak menggunakan namespace, jangan gunakan v2. Dalam kedua kasus tersebut,
jangan gunakan v2 dalam nilai flag --private-registry atau dalam perintah pull image:
Tanpa namespace
- Valid:
endpoint: https://172.18.0.20:5000crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
- Tidak valid:
endpoint: https://172.18.0.20:5000/v2crictl pull 172.18.0.20:5000/v2/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
Dengan namespace
- Valid:
endpoint: https://172.18.0.21:5000/v2/namespacecrictl 172.18.0.21:5000/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
- Tidak valid:
endpoint: https://172.18.0.21:5000/namespacecrictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1