Questa pagina spiega come creare ed eseguire l'upgrade dei cluster utilizzando le immagini estratte da un mirror del registro anziché da un registro pubblico come gcr.io. Questa funzionalità può essere attivata o disattivata in qualsiasi momento durante il ciclo di vita del cluster.
Questa pagina è rivolta agli operatori e agli specialisti dello spazio di archiviazione che configurano e gestiscono le prestazioni, l'utilizzo e le spese dello spazio di archiviazione. Per saperne di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei Google Cloud contenuti, consulta Ruoli e attività comuni degli utenti GKE.
Un mirror del registro è una copia locale di un registro pubblico che copia o esegue il mirroring della struttura dei file del registro pubblico. Supponiamo, ad esempio, che il percorso del mirror del registro locale sia 172.18.0.20:5000. Quando containerd
rileva una richiesta di pull di un'immagine come
gcr.io/kubernetes-e2e-test-images/nautilus:1.0, containerd tenta di eseguire il pull
dell'immagine non da gcr.io, ma dal registro locale nel seguente
percorso: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0. Se l'immagine non è presente in questo percorso del registro locale, viene estratta automaticamente dal registro pubblico gcr.io.
L'utilizzo di un mirror del registro offre i seguenti vantaggi:
- Ti protegge dalle interruzioni del registro pubblico.
- Velocizza la creazione dei pod.
- Ti consente di eseguire la tua analisi delle vulnerabilità.
- Evita i limiti imposti dai registri pubblici sulla frequenza con cui puoi inviare loro i comandi.
Prima di iniziare
- Devi aver configurato un server Artifact Registry nella tua rete.
- Se il server del registro esegue un certificato TLS privato, devi avere il file dell'autorità di certificazione (CA).
- Se il server del registro richiede l'autenticazione, devi disporre delle credenziali di accesso corrette o del file di configurazione di Docker.
- Se utilizzi un registro Red Hat Quay, potrebbe essere necessario creare manualmente la struttura delle directory del registro locale.
- Per utilizzare un mirror del registro, devi impostare il runtime del container su containerd.
Assicurati di avere spazio su disco sufficiente sulla workstation di amministrazione per i caricamenti delle immagini. Il comando di caricamento delle immagini,
bmctl push images, decomprime il file del pacchetto di immagini scaricato e poi estrae tutti i file immagine localmente prima di caricarli. Per il caricamento delle immagini è necessario uno spazio su disco pari ad almeno tre volte le dimensioni del file del pacchetto di immagini scaricato.Ad esempio, il file compresso
bmpackages_1.33.0-gke.799.tar.xzoccupa circa 12 GB di spazio su disco, quindi devi avere almeno 36 GB di spazio su disco libero prima di scaricare il file.Se esegui un upgrade con salto di versione (upgrade di due versioni secondarie in una singola operazione), devi caricare le immagini dai file del pacchetto di immagini sia per la versione di destinazione (
N+2) sia per la versione intermedia (N+1). In base a questo esempio, per il caricamento delle immagini sono necessari circa 72 GB di spazio su disco libero. Per saperne di più sulla versione intermedia, consulta Requisito aggiuntivo per i mirror del registro.
Scarica tutte le immagini richieste per Google Distributed Cloud
Scarica l'ultima versione dello strumento bmctl e del pacchetto di immagini dalla pagina
Download.
Carica le immagini container sul server del registro
Quando utilizzi bmctl push images per caricare le immagini container sul server del repository, bmctl esegue i seguenti passaggi in ordine:
Decomprime un file tar compresso del pacchetto di immagini scaricato, ad esempio
bmpackages_1.35.0-gke.525.tar.xzinbmpackages_1.35.0-gke.525.tar.Estrae tutte le immagini dal file tar decompresso in una directory denominata
bmpackages_1.35.0-gke.525.Esegue il push di ogni file immagine nel registro privato specificato.
bmctlutilizza i valori--usernamee--passwordper l'autenticazione di base per eseguire il push delle immagini nel registro privato.
Le sezioni seguenti illustrano alcune varianti comuni del comando bmctl push
images per caricare le immagini sul server del repository.
Esegui l'autenticazione con il registro e condividi il certificato TLS
Il seguente comando include i flag --username e --password per l'autenticazione utente con il server del registro. Il comando include anche il flag --cacert per passare il certificato TLS (Transport Layer Security) della CA, che viene utilizzato per la comunicazione sicura con il server del registro, inclusi i push e i pull delle immagini. Questi flag forniscono una sicurezza di base per il server del registro.
Se il server del registro richiede l'autenticazione e non utilizzi i flag --username e --password, ti verrà chiesto di inserire le credenziali quando esegui bmctl push images. Puoi digitare la password o scegliere il file di configurazione di Docker che contiene le credenziali.
Per caricare le immagini con l'autenticazione e un certificato CA privato, utilizza un comando simile al seguente:
bmctl push images \
--source IMAGES_TAR_FILE_PATH \
--private-registry REGISTRY_IP:PORT \
--username USERNAME \
--password PASSWORD \
--cacert CERT_PATH
Sostituisci quanto segue:
IMAGES_TAR_FILE_PATH: il percorso del file tar del pacchetto di immagini scaricato, ad esempiobmpackages_1.35.0-gke.525.tar.xz.REGISTRY_IP:PORT: l'indirizzo IP e la porta del server del registro privato.USERNAME: il nome utente di un utente con autorizzazioni di accesso per caricare le immagini sul server del registro.PASSWORD: la password dell'utente per l'autenticazione con il server del registro.CERT_PATH: il percorso del file del certificato CA, se il server del registro utilizza un certificato TLS privato.
Ad esempio:
bmctl push images \
--source bmpackages_1.35.0-gke.525.tar.xz \
--private-registry 172.18.0.20:5000 \
--username alex --password pa55w0rd \
--cacert /etc/pki/tls/certs/ca-bundle.crt
Carica le immagini senza autenticazione utente o certificati
Se il server del registro non richiede credenziali, come un nome utente e una password, specifica --need-credential=false nel comando bmctl. Se il server del registro utilizza un certificato TLS pubblico, non devi utilizzare il flag --cacert. Questo tipo di comando di caricamento è più adatto agli ambienti di test, in cui la sicurezza è meno importante rispetto alla produzione.
Per caricare le immagini senza autenticazione o un certificato CA privato, utilizza un comando simile al seguente:
bmctl push images \
--source IMAGES_TAR_FILE_PATH \
--private-registry REGISTRY_IP:PORT \
--need-credential=false
Ad esempio:
bmctl push images \
--source bmpackages_1.35.0-gke.525.tar.xz \
--private-registry 172.18.0.20:5000 \
--need-credential=false.
Modifica il numero di thread
La routine di caricamento delle immagini può richiedere molto tempo a causa delle dimensioni e della quantità di immagini container nel file tar del pacchetto di immagini. L'aumento del numero di thread paralleli velocizza la routine. Puoi utilizzare il flag --threads per modificare il numero di thread paralleli utilizzati da bmctl push images.
Per impostazione predefinita, la routine di caricamento delle immagini utilizza 4 thread. Se i caricamenti delle immagini richiedono troppo tempo, aumenta questo valore. Come benchmark, in un ambiente di test di Google, il caricamento delle immagini da una workstation con 4 CPU richiede circa 10 minuti con 8 thread paralleli.
bmctl push images \
--source IMAGES_TAR_FILE_PATH \
--private-registry REGISTRY_IP:PORT \
--cacert CERT_PATH \
--threads NUM_THREADS
Sostituisci NUM_THREADS con il numero di thread paralleli utilizzati per elaborare i caricamenti delle immagini. Per impostazione predefinita, bmctl push images utilizza quattro thread paralleli.
Il seguente comando aumenta il numero di thread per il caricamento da 4 a 8 per ridurre il tempo di caricamento:
bmctl push images \
--source bmpackages_1.35.0-gke.525.tar.xz \
--private-registry 172.18.0.20:5000 \
--cacert ~/cert.pem \
--threads 8
Carica tramite proxy
Se hai bisogno di un proxy per caricare le immagini dalla workstation al server del registro, puoi aggiungere i dettagli del proxy prima del comando bmctl:
HTTPS_PROXY=http://PROXY_IP:PORT bmctl push images \
--source=IMAGES_TAR_FILE_PATH \
--private-registry=REGISTRY_IP:PORT \
--cacert=CERT_PATH
Sostituisci quanto segue:
PROXY_IP:PORT: l'indirizzo IP e la porta del proxy.IMAGES_TAR_FILE_PATH: il percorso del file tar del pacchetto di immagini scaricato, ad esempiobmpackages_1.35.0-gke.525.tar.xz.REGISTRY_IP:PORT: l'indirizzo IP e la porta del server del registro privato.CERT_PATH: il percorso del file del certificato CA, se il server del registro utilizza un certificato TLS privato.
Inserisci il nome utente e la password quando richiesto o seleziona un file di configurazione di Docker.
Il seguente comando carica le immagini tramite un proxy:
HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
--source bmpackages_1.35.0-gke.525.tar.xz \
--private-registry 172.18.0.20:5000 \
--cacert ~/cert.pem
Utilizza il tuo spazio dei nomi con bmctl push images
Se vuoi utilizzare il tuo spazio dei nomi nel server del registro anziché lo spazio dei nomi radice, containerd può eseguire il pull da questo spazio dei nomi se fornisci l'endpoint API per il registro privato nel campo registryMirrors.endpoint del file di configurazione del cluster. L'endpoint è in genere nel formato di
<REGISTRY_IP:PORT>/v2/<NAMESPACE>. Consulta la guida utente del registro privato per dettagli specifici. Per saperne di più, consulta Informazioni sull'utilizzo di v2 nell'
endpoint del registro.
bmctl push images \
--source=IMAGES_TAR_FILE_PATH \
--private-registry=REGISTRY_IP:PORT/NAMESPACE \
--cacert=CERT_PATH
Sostituisci NAMESPACE con il nome dello spazio dei nomi nel server del registro in cui vuoi caricare le immagini.
Ad esempio, se hai accesso solo a 198.51.20.1:5000/test-namespace/, puoi utilizzare un comando simile al seguente per caricare tutte le immagini nello spazio dei nomi test-namespace:
bmctl push images \
--source=./bmpackages_1.35.0-gke.525.tar.xz \
--private-registry=198.51.20.1:5000/test-namespace \
--username=alex \
--password=pa55w0rd \
--cacert /etc/pki/tls/certs/ca-bundle.crt
Poi, nel file di configurazione del cluster, puoi aggiungere quanto segue per fare in modo che containerd esegua il pull dallo spazio dei nomi test-namespace:
registryMirrors:
- endpoint: https://198.51.20.1:5000/v2/test-namespace
Per saperne di più sul comando bmctl push images, consulta il bmctl
riferimento ai comandi.
Configura i cluster per utilizzare un mirror del registro
Puoi configurare un mirror del registro per un cluster durante la creazione del cluster o ogni volta che aggiorni un cluster esistente. Le due sezioni seguenti descrivono i due metodi disponibili per la configurazione dei mirror del registro.
Utilizza la sezione dell'intestazione nel file di configurazione del cluster
A partire dalla versione 1.35, puoi configurare o aggiornare i mirror del registro e i registri privati sia per i cluster di amministrazione sia per i cluster utente definendoli nella sezione dell'intestazione di primo livello del file di configurazione del cluster. La configurazione rimane invariata durante gli aggiornamenti.
Quando esegui bmctl update, qualsiasi configurazione del registro nella sezione dell'intestazione sostituisce automaticamente la sezione spec.nodeConfig del file di configurazione del cluster.
Per la versione 1.34 e precedenti, devi utilizzare la sezione nodeConfig.registryMirrors per specificare i mirror del registro e i registri privati nei cluster utente e non la sezione dell'intestazione, perché quest'ultima non rimane invariata durante gli aggiornamenti.
Il seguente file di configurazione del cluster di esempio specifica che le immagini devono essere estratte da un mirror del registro locale il cui endpoint è https://198.51.20.1:5000. Alcuni dei campi visualizzati all'inizio di questo file di configurazione sono descritti nelle sezioni seguenti.
# 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
...
Utilizza la sezione nodeConfig.registryMirrors nella specifica del cluster
Poiché puoi condividere i secret creati per il cluster di gestione con il cluster utente, puoi utilizzare nodeConfig.registryMirrors dal cluster di amministrazione o ibrido di gestione per specificare il mirror del registro nella specifica del cluster per il cluster utente.
Per configurare un cluster utente in modo che utilizzi lo stesso mirror del registro del cluster di amministrazione:
Ottieni la sezione
nodeConfig.registryMirror, inclusi i riferimenti ai secret, danodeConfig.registryMirrorsdella risorsa del cluster di amministrazione:kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \ --kubeconfig ADMIN_KUBECONFIG \ -o yamlSostituisci quanto segue:
CLUSTER_NAME: il nome del cluster di amministrazione o ibrido che gestisce il cluster utente.CLUSTER_NAMESPACE: il nome dello spazio dei nomi per il cluster di gestione.ADMIN_KUBECONFIG: il percorso del file kubeconfig del cluster di gestione.
Aggiungi la configurazione
nodeConfig.registryMirrorsdal cluster di amministrazione al file di configurazione del cluster utente.La sezione
registryMirrorsnel file di configurazione del cluster utente dovrebbe essere simile all'esempio seguente:--- 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 ...
Per apportare modifiche successive alla configurazione del mirror del registro per il cluster utente, modifica nodeConfig.registryMirrors nel file di configurazione del cluster utente e applica le modifiche con bmctl update.
Campo hosts
containerd controlla la sezione hosts del file di configurazione del cluster per scoprire quali host vengono sottoposti a mirroring in locale. Questi host vengono mappati all'endpoint del mirror del registro specificato nel file di configurazione del cluster (registryMirror.endpoint). Nel file di configurazione di esempio della sezione precedente, i registri pubblici elencati nella sezione hosts sono somehost.io e otherhost.io. Poiché questi registri pubblici vengono visualizzati nella sezione hosts, containerd controlla prima il mirror del registro privato quando rileva richieste di pull per le immagini da somehost.io o otherhost.io.
Supponiamo, ad esempio, che containerd riceva un comando pull per somehost.io/kubernetes-e2e-test-images/nautilus:1.0. Poiché somehost.io è elencato come uno degli host nella sezione hosts del file di configurazione del cluster, containerd cerca l'immagine kubernetes-e2e-test-images/nautilus:1.0 nel mirror del registro locale. Se somehost.io non è elencato nella sezione hosts, containerd non sa che esiste un mirror locale di somehost.io. In questo caso, containerd non controlla l'immagine nel mirror ed esegue il pull dell'immagine dal registro pubblico somehost.io.
Tieni presente che, per impostazione predefinita, Google Distributed Cloud esegue automaticamente il mirroring delle immagini da gcr.io, quindi non devi elencare gcr.io come host nella sezione hosts.
I valori hosts e endpoint non devono sovrapporsi. Ad esempio, la seguente configurazione di esempio mostra un host, europe-docker.pkg.dev, che corrisponde alla parte del dominio del valore dell'endpoint. In questo caso, non devi specificare un valore hosts:
...
registryMirrors:
...
endpoint: https://europe-docker.pkg.dev:5000/v2/cloud-data-fusion-images
hosts:
- europe-docker.pkg.dev
...
Campo gcrKeyPath
Se vuoi che Google Distributed Cloud utilizzi automaticamente Artifact Registry (gcr.io) per eseguire il pull delle immagini che non vengono visualizzate nel registro locale, devi specificare il percorso della chiave del account di servizio di Artifact Registry.
Google Distributed Cloud non dispone di un meccanismo per fornire le chiavi per altri registri pubblici.
Se non prevedi di utilizzare la funzionalità in cui le immagini vengono estratte da gcr.io quando non vengono visualizzate nel registro locale, non devi aggiungere un gcrKeyPath al file di configurazione del cluster.
Campo caCertPath
Se il registro richiede un certificato TLS (Transport Layer Security) privato, questo campo accetta il percorso del file del certificato CA radice del server. Questo file di certificato deve trovarsi sulla workstation di amministrazione, la macchina che esegue i comandi bmctl. Se il registro non richiede un certificato TLS privato, puoi lasciare vuoto il campo caCertPath.
Campo pullCredentialConfigPath
Se il server del registro non richiede un file di configurazione di Docker per l'autenticazione, puoi lasciare vuoto il campo pullCredentialConfigPath. Tieni presente che questo è il percorso del file di configurazione sulla macchina che esegue i comandi bmctl.
Utilizza un mirror del registro con i cluster utente
I cluster utente non estraggono automaticamente le immagini da un mirroring del Registro di sistema, se il loro cluster di amministrazione è stato configurato. Per fare in modo che i cluster utente eseguano il pull da un mirroring del Registro di sistema, devi configurarli singolarmente come descritto in Configurare i cluster per l'utilizzo di un mirroring del Registro di sistema.
Per fare in modo che i cluster utente eseguano il pull da un mirror del registro, devi configurarli singolarmente come descritto in Configura i cluster per utilizzare un mirror del registro.
Aggiorna gli endpoint, i certificati e le credenziali di pull del mirror del registro
Nel file di configurazione del cluster, aggiorna l'endpoint, il file del certificato CA e il percorso del file di configurazione delle credenziali di pull.
Nel file di configurazione del cluster, aggiorna l'endpoint, il file del certificato CA e il percorso del file di configurazione delle credenziali di pull.
bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIGApplica le modifiche eseguendo:
Sostituisci quanto segue:
CLUSTER_NAMEcon il nome del cluster che desideri aggiornare.ADMIN_KUBECONFIGcon il percorso del suo file di configurazione del cluster di amministrazione.
`ADMIN_KUBECONFIG` con il percorso del file di configurazione del cluster di amministrazione.
Verifica che le immagini vengano estratte dal mirror del registro containerd by examining the contents of a config.toml file as shown in the
following steps:
Accedi a un nodo ed esamina il contenuto del seguente file:
/etc/containerd/config.tomlAccedi a un nodo ed esamina i contenuti del seguente file: `/etc/containerd/config.toml`
plugins."io.containerd.grpc.v1.cri".registry.mirrorsconfig.tomlendpointEcco un estratto da un fileconfig.tomldi esempio in cui il campoendpointappare in grassetto: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"] ...Se il mirror del tuo registry appare nel campo
endpoint, il nodo esegue il pull delle immagini dal mirror del tuo registry anziché da un registry pubblico.
Se il mirror del registro viene visualizzato nel campo `endpoint`, il nodo sta estraendo le immagini dal mirror del registro anziché da un registro pubblico.
Puoi utilizzare crictl, lo strumento a riga di comando dell'interfaccia di runtime del container, per testare
le impostazioni del registry scaricando singoli file immagine. Puoi utilizzare `crictl`, lo strumento a riga di comando dell'interfaccia del runtime del container, per testare le impostazioni del registro scaricando i singoli file immagine. Ad esempio, l'immagine del controller del cluster viene taggata con la versione di release di Google Distributed Cloud e l'immagine di etcd viene taggata con la versione di etcd corrispondente.
Ad esempio, l'immagine del controller dell'API del cluster viene taggata con la versione di rilascio di Google Distributed Cloud e l'immagine etcd viene taggata con la versione etcd corrispondente.cluster-api-controlleretcd
cluster-api-controller:1.31.200-gke.59etcd:v3.4.30-0-gke.1
Per la versione 1.31.200-gke.59 di Google Distributed Cloud per bare metal, l'immagine del controller dell'API del cluster, `cluster-api-controller`, e l'immagine etcd, `etcd`, hanno i seguenti tag:
Estrai un'immagine dal mirror del registro
crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG
Se il mirror del registro non utilizza spazi dei nomi, utilizza il seguente comando per estrarre un'immagine:
Estrai un'immagine da un mirror del registro che utilizza spazi dei nomi
crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG
Se il mirror del registro utilizza spazi dei nomi, utilizza il seguente comando per estrarre un'immagine:v2
Quando il registro utilizza spazi dei nomi personalizzati, è necessario anteporre lo spazio dei nomi nell'endpoint del registro (registryMirror.endpoint) nel file di configurazione del cluster con v2/. Quando il registro utilizza spazi dei nomi personalizzati, devi anteporre `v2/` allo spazio dei nomi nell'endpoint del registro (`registryMirror.endpoint`) nel file di configurazione del cluster.v2 In entrambi i casi,
non utilizzare v2 nel valore del flag --private-registry o nei comandi di pull delle immagini:
In entrambi i casi, non utilizzare `v2` nel valore del flag `--private-registry` o nei comandi di pull delle immagini:
- Senza spazi dei nomi
endpoint: https://172.18.0.20:5000crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
- Valido:
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
Non valido:
- Con spazi dei nomi
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
- Valido:
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