Halaman ini menjelaskan cara membuat dan mengupgrade cluster menggunakan image yang ditarik dari mirror registry, bukan dari registry publik seperti gcr.io
. Fitur ini dapat diaktifkan atau dinonaktifkan kapan saja dalam siklus proses cluster.
Halaman ini ditujukan bagi Operator dan spesialis Penyimpanan yang mengonfigurasi dan mengelola performa, penggunaan, dan biaya penyimpanan. Untuk mempelajari lebih lanjut peran umum dan contoh tugas yang kami referensikan dalam konten, lihat Peran dan tugas pengguna GKE umum. Google Cloud
Mirror registri adalah salinan lokal dari registri publik yang menyalin atau mencerminkan
struktur file registri publik. Misalnya, anggaplah jalur
ke mirror registri lokal Anda adalah 172.18.0.20:5000
. Saat containerd
menemukan permintaan untuk menarik image seperti
gcr.io/kubernetes-e2e-test-images/nautilus:1.0
, containerd
akan mencoba menarik
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 otomatis ditarik dari registry publik gcr.io
.
Menggunakan mirror registri memberikan manfaat berikut:
- Melindungi Anda dari gangguan registri publik.
- Mempercepat pembuatan pod.
- Memungkinkan Anda melakukan pemindaian kerentanan sendiri.
- Menghindari batasan yang diberlakukan oleh pendaftaran publik tentang seberapa sering Anda dapat mengeluarkan perintah kepada mereka.
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 yang tepat atau file konfigurasi Docker.
- Jika Anda menggunakan registry Red Hat Quay, Anda mungkin perlu membuat struktur direktori registry lokal secara manual.
- Untuk menggunakan mirror registry, Anda harus menyetel runtime container ke containerd.
- Pastikan Anda memiliki ruang disk yang cukup di workstation admin untuk mendukung upload gambar. Perintah upload gambar,
bmctl push images
, mendekompresi file paket gambar yang didownload, lalu mengekstrak semua file gambar secara lokal sebelum menguploadnya. Anda harus memiliki ruang disk setidaknya tiga kali lebih besar dari ukuran file paket gambar yang didownload untuk mengakomodasi upload gambar. Misalnya, filebmpackages_1.31.200-gke.59.tar.xz
yang dikompresi memerlukan ruang disk sekitar 8,5 GB, jadi Anda harus memiliki ruang disk kosong minimal 25,5 GB sebelum mendownload file.
Download semua gambar yang diperlukan untuk Google Distributed Cloud
Download versi terbaru alat bmctl
dan paket gambar 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:
Mendekompresi file tar terkompresi paket gambar yang didownload, seperti
bmpackages_1.32.200-gke.104.tar.xz
menjadibmpackages_1.32.200-gke.104.tar
.Ekstrak semua gambar dari file tar yang didekompresi ke dalam direktori bernama
bmpackages_1.32.200-gke.104
.Kirim setiap file image ke registry pribadi yang ditentukan.
bmctl
menggunakan nilai--username
dan--password
untuk autentikasi dasar guna mengirim image ke registry pribadi Anda.
Bagian berikut mengilustrasikan beberapa variasi umum perintah bmctl push
images
untuk mengupload gambar ke server repositori Anda.
Lakukan autentikasi dengan registry Anda dan bagikan sertifikat TLS
Perintah berikut menyertakan flag --username
dan --password
untuk autentikasi pengguna dengan server registry Anda. Perintah ini juga menyertakan tanda
--cacert
untuk meneruskan sertifikat CA Transport Layer Security (TLS),
yang digunakan untuk komunikasi server registry yang aman, termasuk push
dan pull image. Flag ini memberikan keamanan dasar untuk server registry Anda.
Jika server registri Anda memerlukan autentikasi dan Anda tidak menggunakan tanda
--username
dan --password
, Anda akan dimintai kredensial saat menjalankan
bmctl push images
. Anda dapat mengetikkan sandi atau memilih file konfigurasi Docker yang berisi kredensial.
Untuk mengupload gambar 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 gambar yang didownload, sepertibmpackages_1.32.200-gke.104.tar.xz
.REGISTRY_IP:PORT
: alamat IP dan port server registri pribadi.USERNAME
: nama pengguna dengan izin akses untuk mengupload gambar ke server registry.PASSWORD
: sandi pengguna untuk mengautentikasi dengan server registry.CERT_PATH
: jalur file sertifikat CA, jika server registri Anda menggunakan sertifikat TLS pribadi.
Contoh:
bmctl push images \
--source bmpackages_1.32.200-gke.104.tar.xz \
--private-registry 172.18.0.20:5000 \
--username alex --password pa55w0rd \
--cacert /etc/pki/tls/certs/ca-bundle.crt
Mengupload gambar tanpa autentikasi atau sertifikat pengguna
Jika server registri Anda tidak memerlukan kredensial, seperti nama pengguna dan sandi, tentukan --need-credential=false
dalam perintah bmctl
. Jika server
registri 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 di lingkungan produksi.
Untuk mengupload gambar 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.32.200-gke.104.tar.xz \
--private-registry 172.18.0.20:5000 \
--need-credential=false.
Menyesuaikan jumlah thread
Rutinitas upload gambar dapat memakan waktu karena ukuran dan jumlah
image container dalam file tar paket gambar. Meningkatkan jumlah thread paralel akan membuat rutinitas berjalan lebih cepat. Anda dapat menggunakan tanda --threads
untuk mengubah jumlah thread paralel yang digunakan bmctl push images
.
Secara default, rutin 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
untuk mengurangi waktu upload:
bmctl push images \
--source bmpackages_1.32.200-gke.104.tar.xz \
--private-registry 172.18.0.20:5000 \
--cacert ~/cert.pem \
--threads 8
Mengupload melalui proxy
Jika Anda memerlukan proxy untuk mengupload gambar dari workstation ke server
registri, 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 gambar yang didownload, sepertibmpackages_1.32.200-gke.104.tar.xz
.REGISTRY_IP:PORT
: alamat IP dan port server registri pribadi.CERT_PATH
: jalur file sertifikat CA, jika server registri Anda menggunakan sertifikat TLS pribadi.
Masukkan nama pengguna dan sandi Anda saat diminta atau pilih file konfigurasi Docker.
Perintah berikut mengupload gambar melalui proxy:
HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
--source bmpackages_1.32.200-gke.104.tar.xz \
--private-registry 172.18.0.20:5000 \
--cacert ~/cert.pem
Menggunakan namespace Anda sendiri dengan bmctl push images
Jika ingin menggunakan namespace sendiri di server registri, bukan namespace
root, containerd
dapat menarik dari namespace ini jika Anda memberikan endpoint API
untuk registri pribadi di kolom registryMirrors.endpoint
pada
file konfigurasi cluster. 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 registri.
bmctl push images \
--source=IMAGES_TAR_FILE_PATH \
--private-registry=REGISTRY_IP:PORT/NAMESPACE \
--cacert=CERT_PATH
Ganti NAMESPACE
dengan nama namespace di server
registri tempat Anda ingin mengupload image.
Misalnya, jika hanya memiliki akses ke 198.51.20:5000/test-namespace/
, Anda
dapat menggunakan perintah seperti berikut untuk mengupload semua gambar di namespace
test-namespace
:
bmctl push images \
--source=./bmpackages_1.32.200-gke.104.tar.xz \
--private-registry=198.51.20:5000/test-namespace \
--username=alex \
--password=pa55w0rd \
--cacert /etc/pki/tls/certs/ca-bundle.crt
Kemudian, di file konfigurasi cluster, Anda dapat menambahkan berikut ini agar
containerd
menarik dari namespace test-namespace
:
registryMirrors:
- endpoint: https://198.51.20:5000/v2/test-namespace
Untuk mengetahui informasi selengkapnya tentang perintah bmctl push images
, lihat referensi perintah bmctl
.
Mengonfigurasi cluster untuk menggunakan mirror registri
Anda dapat mengonfigurasi mirror registry untuk cluster saat pembuatan cluster atau kapan pun Anda mengupdate cluster yang ada. Metode konfigurasi yang Anda gunakan bergantung pada jenis cluster dan, untuk cluster pengguna, apakah Anda membuat cluster atau memperbarui cluster. Dua bagian berikut menjelaskan dua metode yang tersedia untuk mengonfigurasi mirror registri.
Menggunakan bagian header dalam file konfigurasi cluster
Google Distributed Cloud memungkinkan Anda menentukan mirror registry di luar spesifikasi Cluster, di bagian header file konfigurasi cluster:
Untuk cluster admin, hybrid, dan mandiri, satu-satunya cara untuk mengonfigurasi mirror registry adalah dengan menggunakan bagian header dalam file konfigurasi cluster. Metode ini berlaku untuk pembuatan atau update cluster.
Untuk cluster pengguna, Anda dapat menggunakan metode ini untuk mengonfigurasi mirror registry hanya selama pembuatan cluster. Atau, untuk mengonfigurasi mirror registry untuk cluster pengguna yang ada, Anda menggunakan bagian
nodeConfig.registryMirrors
dalam spesifikasi Cluster.
File konfigurasi cluster contoh berikut menentukan bahwa image akan
ditarik dari mirror registry lokal yang endpoint-nya adalah
https://198.51.20: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: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
Metode pembuatan atau pembaruan mirror registri ini hanya berlaku untuk cluster pengguna. Karena Anda dapat membagikan secret yang dibuat untuk cluster pengelolaan dengan
cluster pengguna, Anda dapat menggunakan nodeConfig.registryMirrors
dari
admin pengelolaan atau cluster hybrid untuk menentukan mirror 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.registryMirrors
resource cluster admin:kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \ --kubeconfig ADMIN_KUBECONFIG \ -o yaml
Ganti 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 pengelola.
Tambahkan konfigurasi
nodeConfig.registryMirrors
dari cluster admin ke file konfigurasi cluster pengguna.Bagian
registryMirrors
dalam file konfigurasi cluster pengguna akan terlihat mirip dengan 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 membuat 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
.
Anda tidak dapat menggunakan bagian header file konfigurasi cluster untuk memperbarui konfigurasi mirror registri untuk cluster pengguna.
Kolom hosts
containerd
memeriksa bagian hosts
pada file konfigurasi cluster untuk
menemukan host mana yang dicerminkan 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 penarikan untuk image dari somehost.io
atau otherhost.io
.
Misalnya, anggap 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
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 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 mencerminkan 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 otomatis menggunakan Artifact Registry
(gcr.io
) untuk menarik image yang tidak muncul di registry lokal Anda, 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 gambar dari gcr.io
saat gambar tidak muncul di registry lokal, Anda tidak perlu menambahkan
gcrKeyPath
ke file konfigurasi cluster.
Kolom caCertPath
Jika registri Anda memerlukan sertifikat keamanan lapisan transport (TLS) pribadi,
kolom ini akan mengambil jalur ke file sertifikat CA root server. File sertifikat ini harus ada di workstation admin, yaitu komputer yang menjalankan perintah bmctl
. Jika registry Anda tidak memerlukan sertifikat TLS pribadi, Anda
dapat mengosongkan kolom caCertPath
.
Kolom pullCredentialConfigPath
Jika server registri Anda tidak memerlukan file konfigurasi Docker autentikasi, Anda dapat mengosongkan kolom pullCredentialConfigPath
. Perhatikan bahwa
ini adalah jalur ke file konfigurasi di komputer yang menjalankan perintah bmctl
.
Menggunakan mirror registry dengan cluster pengguna
Cluster pengguna tidak otomatis menarik image dari mirror registry jika cluster adminnya telah dikonfigurasi untuk melakukannya. Agar cluster pengguna menarik dari mirror registry, Anda harus mengonfigurasinya satu per satu seperti yang dijelaskan dalam Mengonfigurasi cluster untuk menggunakan mirror registry.
Memperbarui endpoint mirror registry, sertifikat, dan kredensial penarikan
Untuk memperbarui endpoint mirror registri, sertifikat, atau kredensial penarikan:
Di 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_KUBECONFIG
Ganti kode berikut:
CLUSTER_NAME
dengan nama cluster yang ingin Anda perbarui.ADMIN_KUBECONFIG
dengan jalur file konfigurasi cluster admin-nya.
Memverifikasi bahwa image ditarik dari mirror registry
Anda dapat menentukan apakah containerd
menarik gambar dari registry lokal Anda dengan memeriksa konten file config.toml
seperti yang ditunjukkan dalam langkah-langkah berikut:
Login ke node dan periksa konten file berikut:
/etc/containerd/config.toml
Periksa bagian
plugins."io.containerd.grpc.v1.cri".registry.mirrors
pada fileconfig.toml
untuk melihat apakah server registri Anda tercantum di kolomendpoint
. Berikut adalah kutipan dari contoh fileconfig.toml
yang kolomendpoint
-nya ditampilkan dengan 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 menarik image dari mirror registry Anda, bukan dari registry publik.
Memecahkan masalah setelan mirror registri
Anda dapat menggunakan crictl
, alat command line antarmuka runtime penampung, untuk menguji setelan registry Anda dengan mendownload file image satu per satu. 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 Google Distributed Cloud 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.59
etcd:v3.4.30-0-gke.1
Mengambil image dari mirror registry
Jika mirror registri Anda tidak menggunakan namespace, gunakan perintah berikut untuk menarik image:
crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG
Mengambil image dari mirror registry yang menggunakan namespace
Jika mirror registri Anda menggunakan namespace, gunakan perintah berikut untuk menarik 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 awalan 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 penarikan image:
Tanpa namespace
- Valid:
endpoint: https://172.18.0.20:5000
crictl 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/v2
crictl 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/namespace
crictl 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/namespace
crictl pull 172.18.0.21:5000/v2/namespace/anthos-baremetal-release/etcd:v3.4.30-0-gke.1