Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Utilizzare un mirror del registro per le immagini container

La configurazione di un mirror del registry locale consente di creare ed eseguire l'upgrade dei cluster eseguendo il pull delle immagini container da un endpoint locale anziché da registry upstream come gcr.io. Questo approccio aiuta ad accelerare la creazione dei pod, evitare limiti di frequenza di pull esterni e proteggere i flussi di lavoro di deployment dalle interruzioni del registry pubblico. Puoi attivare o disattivare il mirroring del registry in qualsiasi momento durante il ciclo di vita del cluster.

Come funziona un mirror del registry

Un mirror del registry è una copia locale di un registry pubblico che copia o rispecchia la struttura dei file del registry pubblico. Ad esempio, supponiamo che il percorso del mirror del registry 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 tuo registry locale nel seguente percorso: 172.18.0.20:5000/kubernetes-e2e-test-images/nautilus:1.0. Se l'immagine non si trova in questo percorso del registry locale, viene estratta automaticamente dal registry pubblico gcr.io.

L'utilizzo di un mirror del registry offre i seguenti vantaggi:

Ti protegge dalle interruzioni del registry pubblico.
Velocizza la creazione dei pod.
Ti consente di eseguire l'analisi delle vulnerabilità.
Evita i limiti imposti dai registry pubblici sulla frequenza con cui puoi inviare comandi.

Prima di iniziare

Nella tua rete deve essere configurato un server Artifact Registry.
Se il server del registry esegue un certificato TLS privato, devi avere il file dell'autorità di certificazione (CA).
Se il server del registry richiede l'autenticazione, devi disporre delle credenziali di accesso o del file di configurazione Docker appropriati.
Se utilizzi un registry Red Hat Quay, potrebbe essere necessario creare manualmente la struttura di directory del registry locale.
Per utilizzare un mirror del registry, 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, quindi 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 bmpackages_1.33.0-gke.799.tar.xz compresso occupa circa 12 GB di spazio su disco, quindi devi avere almeno 36 GB di spazio libero su disco prima di scaricare il file.

Se esegui un upgrade con salto (upgrade di due versioni secondarie in un'unica 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, hai bisogno di circa 72 GB di spazio libero su disco per il caricamento dell'immagine. Per saperne di più sulla versione intermedia, consulta Requisito aggiuntivo per i mirror del registry.

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 registry

Quando utilizzi bmctl push images per caricare immagini container sul server del repository, bmctl esegue i seguenti passaggi in ordine:

Decomprimi un file tar compresso del pacchetto di immagini scaricato, ad esempio bmpackages_1.36.200-gke.118.tar.xz in bmpackages_1.36.200-gke.118.tar.
Estrai tutte le immagini dal file tar decompresso in una directory denominata bmpackages_1.36.200-gke.118.
Esegui il push di ogni file immagine nel registry privato specificato.

bmctl utilizza i valori --username e --password per l'autenticazione di base per eseguire il push delle immagini nel tuo registry privato.

Le sezioni seguenti illustrano alcune varianti comuni del comando bmctl push images per caricare le immagini sul server del repository.

Il seguente comando include i flag --username e --password per l'autenticazione utente con il server del registry. 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 registry, inclusi i push e i pull delle immagini. Questi flag forniscono una sicurezza di base per il server del registry.

Se il server del registry 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 Docker che contiene le credenziali.

Per caricare immagini con autenticazione e un certificato CA privato, utilizza un comando come il 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 esempio bmpackages_1.36.200-gke.118.tar.xz.
REGISTRY_IP:PORT: l'indirizzo IP e la porta del server del registry privato.
USERNAME: il nome utente di un utente con autorizzazioni di accesso per caricare immagini sul server del registry.
PASSWORD: la password dell'utente per l'autenticazione con il server del registry.
CERT_PATH: il percorso del file del certificato CA, se il server del registry utilizza un certificato TLS privato.

Ad esempio:

bmctl push images \
    --source bmpackages_1.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --username alex --password pa55w0rd \
    --cacert /etc/pki/tls/certs/ca-bundle.crt

Carica immagini senza autenticazione utente o certificati

Se il server del registry non richiede credenziali, come nome utente e password, specifica --need-credential=false nel comando bmctl. Se il tuo server del registry utilizza un certificato TLS pubblico, non devi utilizzare il flag --cacert. Questo tipo di comando di caricamento è più adatto agli ambienti di test, dove la sicurezza è meno importante rispetto alla produzione.

Per caricare 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.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --need-credential=false.

Regola 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 l'esecuzione della 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.36.200-gke.118.tar.xz \
    --private-registry 172.18.0.20:5000 \
    --cacert ~/cert.pem \
    --threads 8

Caricamento tramite proxy

Se hai bisogno di un proxy per caricare le immagini dalla tua workstation al server del registry, 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 esempio bmpackages_1.36.200-gke.118.tar.xz.
REGISTRY_IP:PORT: l'indirizzo IP e la porta del server del registry privato.
CERT_PATH: il percorso del file del certificato CA, se il server del registry utilizza un certificato TLS privato.

Inserisci il tuo nome utente e la tua password quando richiesto o seleziona un file di configurazione Docker.

Il seguente comando carica le immagini tramite un proxy:

HTTPS_PROXY=http://10.128.0.136:3128 bmctl push images \
    --source bmpackages_1.36.200-gke.118.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 registry anziché lo spazio dei nomi root, containerd può eseguire il pull da questo spazio dei nomi se fornisci l'endpoint API per il tuo registry privato nel campo registryMirrors.endpoint del file di configurazione del cluster. L'endpoint è in genere nel formato <REGISTRY_IP:PORT>/v2/<NAMESPACE>. Per i dettagli specifici, consulta la guida dell'utente del tuo registry privato. Per saperne di più, consulta Informazioni sull'utilizzo di v2 nell'endpoint del registry.

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 registry in cui vuoi caricare le immagini.

Ad esempio, se hai accesso solo a 198.51.20.1:5000/test-namespace/, puoi utilizzare un comando come il seguente per caricare tutte le immagini nello spazio dei nomi test-namespace:

bmctl push images \
    --source=./bmpackages_1.36.200-gke.118.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 ulteriori informazioni sul comando bmctl push images, consulta il riferimento al comando bmctl.

Configura i cluster per l'utilizzo di un mirror del registry

Puoi configurare un mirror del registry per un cluster al momento della 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 registry.

Utilizza la sezione dell'intestazione nel file di configurazione del cluster

A partire dalla versione 1.35, puoi configurare o aggiornare i mirror del registry e i registry privati per i cluster di amministrazione e utente definendoli nella sezione dell'intestazione di primo livello del file di configurazione del cluster. La configurazione viene mantenuta tra gli aggiornamenti.

Quando esegui bmctl update, qualsiasi configurazione del registry 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 registry e i registry privati nei cluster utente, non la sezione dell'intestazione, perché quest'ultima non viene mantenuta tra gli aggiornamenti.

Il seguente file di configurazione del cluster di esempio specifica che le immagini devono essere estratte da un mirror del registry 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 del cluster di amministrazione o ibrido di gestione per specificare il mirror del registry nella specifica del cluster per il cluster utente.

Per configurare un cluster utente in modo che utilizzi lo stesso mirror del registry del cluster di amministrazione, segui questi passaggi:

Recupera la sezione nodeConfig.registryMirror, inclusi i riferimenti ai secret, da nodeConfig.registryMirrors della risorsa del cluster di amministrazione:
```
kubectl get cluster CLUSTER_NAME -n CLUSTER_NAMESPACE \
    --kubeconfig ADMIN_KUBECONFIG \
    -o yaml
```
Sostituisci 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.registryMirrors dal cluster di amministrazione al file di configurazione del cluster utente.

La sezione registryMirrors nel file di configurazione del cluster utente dovrebbe essere simile al seguente esempio:

---
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 registry per il tuo 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 sono sottoposti a mirroring locale. Questi host sono mappati all'endpoint del mirror del registry specificato nel file di configurazione del cluster (registryMirror.endpoint). Nel file di configurazione di esempio della sezione precedente, i registry 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.

Ad esempio, supponiamo 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 registry 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 il mirror per l'immagine e la estrae dal registry pubblico somehost.io.

Tieni presente che, per impostazione predefinita, Google Distributed Cloud esegue automaticamente il mirroring delle immagini da gcr.io, quindi non è necessario elencare gcr.io come host nella sezione hosts.

I valori hosts e il valore endpoint non devono sovrapporsi. Ad esempio, l'esempio di configurazione seguente mostra un host, europe-docker.pkg.dev, che corrisponde alla parte del dominio del valore dell'endpoint. In questo caso, non è necessario 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 tuo registry locale, devi specificare il percorso della chiave del account di servizio Artifact Registry. Google Distributed Cloud non dispone di un meccanismo per fornire chiavi per altri registry pubblici.

Se non prevedi di utilizzare la funzionalità in cui le immagini vengono estratte da gcr.io quando non vengono visualizzate nel registry locale, non devi aggiungere un gcrKeyPath al file di configurazione del cluster.

Campo `caCertPath`

Se il registry richiede un certificato TLS (Transport Layer Security) privato, questo campo accetta il percorso del file del certificato CA radice del server. Questo file del certificato deve trovarsi sulla workstation di amministrazione, la macchina che esegue i comandi bmctl. Se il registry non richiede un certificato TLS privato, puoi lasciare vuoto il campo caCertPath.

Campo `pullCredentialConfigPath`

Se il server del registry non richiede un file di configurazione Docker di 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 registry con i cluster utente

I cluster utente non estraggono automaticamente le immagini da un mirroring del registry, se il cluster di amministrazione è stato configurato per farlo. Per fare in modo che i cluster utente eseguano il pull da un mirroring del registry, devi configurarli singolarmente come descritto in Configura i cluster per l'utilizzo di un mirroring del registry.

Aggiorna gli endpoint, i certificati e le credenziali di pull del mirror del registry

Per aggiornare gli endpoint, i certificati o le credenziali di pull del mirror del registry:

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.
Applica le modifiche eseguendo questo comando:
```
bmctl update cluster -c CLUSTER_NAME --kubeconfig=ADMIN_KUBECONFIG
```
Sostituisci quanto segue:
- CLUSTER_NAME con il nome del cluster che vuoi aggiornare.
- ADMIN_KUBECONFIG con il percorso del file di configurazione del cluster di amministrazione.

Verifica che le immagini vengano estratte dal mirror del registry

Puoi determinare se containerd sta estraendo immagini dal tuo registry locale esaminando i contenuti di un file config.toml come mostrato nei passaggi seguenti:

Accedi a un nodo ed esamina i contenuti del seguente file: /etc/containerd/config.toml

Controlla la sezione plugins."io.containerd.grpc.v1.cri".registry.mirrors del file config.toml per verificare se il server del registry è elencato nel campo endpoint. Ecco un estratto di un file config.toml di esempio in cui il campo endpoint è visualizzato 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 registry viene visualizzato nel campo endpoint, il nodo estrae le immagini dal mirror del registry anziché da un registry pubblico.

Risolvi i problemi relativi alle impostazioni del mirror del registry

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. Ogni file immagine è taggato in modo indipendente con una stringa di versione significativa. Ad esempio, l'immagine del controller API del cluster è contrassegnata con la versione di release di Google Distributed Cloud e l'immagine etcd è contrassegnata con la versione etcd corrispondente.

Per la versione 1.31.200-gke.59 di Google Distributed Cloud per bare metal, l'immagine del controller API del cluster, cluster-api-controller, e l'immagine etcd, etcd, hanno i seguenti tag:

cluster-api-controller:1.31.200-gke.59
etcd:v3.4.30-0-gke.1

Estrai un'immagine dal mirror del registry

Se il mirror del registry non utilizza gli spazi dei nomi, utilizza il seguente comando per eseguire il pull di un'immagine:

crictl pull REGISTRY_IP:PORT/IMAGE_PATH:IMAGE_TAG

Estrai un'immagine da un mirror del registry che utilizza gli spazi dei nomi

Se il mirror del registry utilizza spazi dei nomi, utilizza il seguente comando per eseguire il pull di un'immagine:

crictl pull REGISTRY_IP:PORT/NAMESPACE/IMAGE_PATH:IMAGE_TAG

Informazioni sull'utilizzo di `v2` nell'endpoint del registry

Quando il registry utilizza spazi dei nomi personalizzati, devi anteporre lo spazio dei nomi nell'endpoint del registry (registryMirror.endpoint) nel file di configurazione del cluster con v2/. Se non utilizzi gli spazi dei nomi, non utilizzare v2. In entrambi i casi, non utilizzare v2 nel valore del flag --private-registry o nei comandi di pull delle immagini:

Senza spazi dei nomi

Valido:
- endpoint: https://172.18.0.20:5000
- crictl pull 172.18.0.20:5000/anthos-baremetal-release/etcd:v3.4.30-0-gke.1
Non valido:
- 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

Con spazi dei nomi

Valido:
- 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
Non valido:
- 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