Questa pagina è stata tradotta dall'API Cloud Translation.

Accedi ai registri privati con certificati CA privati

Autopilot . . Standard

Questa pagina mostra come consentire ai carichi di lavoro in esecuzione in Google Kubernetes Engine (GKE) di accedere ai registri di immagini privati utilizzando la chiave pubblica dell'autorità di certificazione (CA) che ha rilasciato il certificato per il registry.

Come funziona

Archivia la chiave pubblica della CA utilizzata per emettere i certificati per i tuoi registri in Secret Manager e configurare quale registro i nomi di dominio completi (FQDN) utilizzano la chiave pubblica per il certificato dei dati. GKE recupera automaticamente la chiave aggiorna la configurazione del registro di runtime dei container durante il bootstrap del nodo. Quando esegui il deployment di un carico di lavoro che utilizza un'immagine container dal tuo privato , devi procedere come segue:

Il kubelet sul nodo tenta di eseguire il pull dell'immagine dal registro privato.
Il registro presenta un certificato TLS lato server.
Il runtime del container convalida il certificato del registry in modo crittografico e per assicurarti che il nome di dominio completo corrisponda a quello specificato.
Se la convalida ha esito positivo, GKE esegue il pull dell'immagine e delle pianificazioni per il tuo carico di lavoro.

Vantaggi

Questo metodo di accesso ai registri privati offre vantaggi come i seguenti:

Migliorare l'affidabilità della configurazione del runtime dei container: utilizzo dei metodi come gli oggetti DaemonSet per impostare la configurazione containerd, aumenta il rischio in cui potrebbero essere eseguiti altri DaemonSet prima configurazione DaemonSet.
Riduci la vulnerabilità agli attacchi con escalation dei privilegi: elimina la necessità per eseguire DaemonSet con privilegi che modificano il runtime del container configurazione.
Riduci l'overhead di gestione: Secret Manager consente di archiviare le chiavi pubbliche CA in una posizione centrale; gestire l'accesso al le chiavi utilizzando IAM; e implementare il controllo della versione annotazioni. Per ulteriori informazioni, consulta Panoramica del prodotto Secret Manager.
Migliora la verificabilità: Cloud Logging raccoglie già i log, tra cui Quando vengono aggiunti certificati a un cluster e quando i nodi GKE eseguire il pull delle immagini.

Prezzi

In questo documento vengono utilizzati i seguenti componenti fatturabili di Google Cloud:

GKE
Secret Manager
Logging: GKE genera gli audit log per le attività di amministrazione e, se abilitato, Audit log degli accessi ai dati per questa funzionalità. Per informazioni sui diversi tipi di audit log, consulta Audit logging di GKE.

Per generare una stima dei costi basata sull'utilizzo previsto, utilizza Calcolatore prezzi.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

Attiva l'API Google Kubernetes Engine.

Abilita l'API Google Kubernetes Engine

Se vuoi utilizzare Google Cloud CLI per questa attività, install e poi initialize con gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente eseguendo gcloud components update.
Nota: per gcloud CLI esistente di installazione, assicurati di impostare compute/region e compute/zone proprietà. Se imposti località predefinite, puoi evitare errori in gcloud CLI come i seguenti: One of [--zone, --region] must be supplied: Please specify location.

Attiva l'API Secret Manager.
Abilita l'API
Devi già disporre di un registro privato e di certificati CA privati per per accedere al registro. Questa guida non tratta la configurazione di un registro privato la creazione dei certificati.

Requisiti

Per utilizzare le chiavi pubbliche delle CA private per accedere ai registri privati, devi soddisfare i requisiti i seguenti requisiti:

I cluster devono utilizzare GKE versione 1.27.3-gke.1700 o successiva.
Devi utilizzare un sistema operativo ottimizzato per i container con containerd nodo, che è l'impostazione predefinita per tutti i cluster GKE. Ubuntu le immagini dei nodi con containerd non sono supportate. Immagini dei nodi Windows Server non sono supportati.
I pool di nodi devono avere l'ambito di accesso cloud-platform affinché i nodi scaricare i certificati. Per ulteriori informazioni, vedi Ambiti di accesso predefiniti in GKE. Questo documento include le istruzioni per impostare l'ambito di accesso quando crei un cluster o pool di nodi.

Limitazioni

Considera le seguenti limitazioni:

Non puoi utilizzare certificati CA privati nelle immagini dei nodi Ubuntu.
Non puoi utilizzare certificati CA privati nei nodi di Windows Server.
Ogni cluster supporta fino a cinque certificati CA privati per registri.
Ogni certificato può avere fino a 25 nomi di dominio completi.
Ogni dominio può essere utilizzato in un solo file di certificato. Tuttavia, sono supportati i pacchetti di certificati.
I certificati devono essere Con codifica PEM.
Il server non ruota automaticamente i certificati. Per ulteriori informazioni, consulta Ruota i certificati CA privati in questo documento.
I nomi di dominio completi hanno le seguenti limitazioni:
- La lunghezza massima del nome di dominio completo è di 255 caratteri, inclusi i caratteri speciali.
- I nomi di dominio completi possono utilizzare solo lettere, numeri e trattini (-).
- Punycode non è supportato.
- I caratteri jolly non sono supportati.

Esegui la migrazione dai DaemonSet di configurazione

Nei cluster GKE Standard, puoi eseguire il deployment DaemonSet per modificare la configurazione del runtime del container. Questo metodo modifica la configurazione containerd su ciascun nodo.

Se usi DaemonSet con privilegi per configurare l'accesso ai registri privati, tieni presente quanto segue prima di utilizzare questo documento:

Archiviazione delle chiavi pubbliche delle CA private solo in Secret Manager configura l'accesso ai registri privati. Altri problemi relativi al registry non è supportata.
L'abilitazione di questa funzionalità fa sì che il cluster utilizzi modello di configurazione del percorso host CRI, che non è compatibile con il precedente modello di configurazione. Se ne hai DaemonSet che modificano la configurazione dell'host containerd, ad esempio registri privati, mirror o proxy non sicuri, aggiorna i DaemonSet in il modello hostpath CRI.

Per i campi disponibili nel modello di percorso host CRI, vedi Configurazione del Registro di sistema nel repository GitHub containerizzato.

Nota: se disabiliti questa funzionalità in un secondo momento, i nodi torneranno alla versione precedente per la configurazione del registry in containerd. Devi modificare le DaemonSet per utilizzare il modello precedente. Per informazioni sul precedente di configurazione del deployment, consulta Configura le credenziali del registro.

Quando abiliti questa funzionalità, GKE applica il percorso host CRI di configurazione dei nodi su nuovi nodi nel cluster. I nodi esistenti continuano utilizzano il modello di configurazione precedente finché non vengono ricreati durante eventi come upgrade.

Aggiorna i DaemonSet per supportare entrambi i modelli di configurazione

Per ridurre il rischio che gli oggetti DaemonSet di configurazione non funzionino sui nodi che supportano un modello di configurazione specifico, assicurati che i tuoi oggetti DaemonSet utilizzare in modo condizionale un modello di configurazione specifico a seconda di configurazione YAML sul nodo. Per un esempio DaemonSet che implementa questo comando logica condizionale nel file GitHub GoogleCloudPlatform/k8s-node-tools di Cloud Shell, consulta manifest insecure-registry-config.yaml.

Archivia le chiavi pubbliche CA in Secret Manager

Archivia le chiavi pubbliche delle CA private che emettono il tuo registro privato come secret in Secret Manager. Per le istruzioni, nella documentazione di Secret Manager, vedi Crea un secret.

Configura l'accesso a Secret Manager da GKE

Assicurarsi che l'account di servizio IAM del cluster abbia i requisiti necessari autorizzazioni per eseguire il pull dei secret da Secret Manager, chiedi all'amministratore di concedere all'account di servizio IAM del cluster la seguenti ruoli IAM sul secret:

Accedi ai contenuti secret: Funzione di accesso ai secret di Secret Manager (roles/secretmanager.secretAccessor)
Accedi ai metadati del secret: Visualizzatore Secret Manager (roles/secretmanager.viewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso.

Questi ruoli predefiniti le autorizzazioni necessarie per eseguire il pull dei secret da Secret Manager. Per vedere le autorizzazioni esatte obbligatorie, espandi la sezione Autorizzazioni obbligatorie:

Autorizzazioni obbligatorie

Per eseguire il pull dei secret da Secret Manager, sono necessarie le seguenti autorizzazioni:

resourcemanager.projects.get
resourcemanager.projects.list
secretmanager.secrets.get
secretmanager.secrets.list
secretmanager.versions.get
secretmanager.versions.list
secretmanager.versions.access

L'amministratore potrebbe anche essere in grado di fornire l'account di servizio IAM del cluster queste autorizzazioni con ruoli personalizzati e altri ruoli predefiniti.

Se non hai associato un account di servizio IAM personalizzato al tuo o pool di nodi, che è il nostro approccio consigliato, il cluster utilizza Account di servizio predefinito Compute Engine. Se possibile, ti consigliamo di configurare i cluster e i pool di nodi con un un account di servizio IAM con privilegi minimi. Per istruzioni, vedi Utilizza account di servizio con privilegi minimi.

Crea un file di configurazione del runtime

ad abilitare la possibilità di utilizzare i certificati CA privati per i registri privati in GKE, creerai un file YAML per modificare configurazione.

Ottieni il numero del tuo progetto Google Cloud:
```
gcloud projects describe PROJECT_ID \
    --format="value(projectNumber)"
```
L'output è il numero numerico del progetto.
Salva la seguente configurazione come containerd-configuration.yaml:
```
privateRegistryAccessConfig:
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
      secretURI: "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION"
    fqdns:
      - "FQDN1"
      - "FQDN2"
  enabled: true
```
Sostituisci quanto segue:
- PROJECT_NUMBER: il numero del progetto che hai inserito al passaggio precedente.
- SECRET_VERSION: il numero di versione del secret in tramite Secret Manager. Facoltativamente, puoi utilizzare un alias di versione, ti consigliamo di utilizzare il numero di versione per evitare complessità di gestione.
- FQDN1, FQDN2: il valore nomi di dominio completi per i registri privati. Puoi anche utilizzare un indirizzo IPv4 se è stato rilasciato un certificato per quell'indirizzo, ma non consiglialo.

Per una descrizione di questi campi, consulta privateRegistryAccessConfig nel Tabella delle opzioni di configurazione containerd disponibili.

Applica la configurazione containerd ai nuovi cluster

Questa sezione mostra come applicare un file di configurazione containerd quando crei un nuovo cluster GKE.

Esegui questo comando:

gcloud container clusters create-auto CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Sostituisci quanto segue:

CLUSTER_NAME: il nome del nuovo cluster.
LOCATION: la località di Compute Engine del tuo nuovo cluster.
PATH_TO_CONFIG_FILE: il percorso del file di configurazione che hai creato, come ~/containerd-configuration.yaml.

Puoi abilitare la configurazione del registro privato sui nuovi cluster Standard eseguendo gcloud container clusters create con le stesse opzioni.

Applica la configurazione containerd ai cluster esistenti

Questa sezione mostra come applicare una configurazione containerd a cluster e nodi esistenti.

Controlla gli ambiti di accesso

I cluster esistenti devono avere l'ambito di accesso cloud-platform per poter essere utilizzati questa funzionalità. Questa sezione mostra come controllare gli ambiti di accesso e aggiornare una con un file di configurazione del registro privato nuovo o modificato.

Per maggiori dettagli sugli ambiti di accesso predefiniti nei nuovi cluster, consulta Accedi agli ambiti in GKE.

Controlla gli ambiti di accesso Autopilot

Esegui questo comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Se il tuo cluster non ha l'oggetto https://www.googleapis.com/auth/cloud-platform di accesso, crea un nuovo cluster con questo ambito di accesso.

Controlla gli ambiti di accesso standard

Per controllare gli ambiti di accesso ai cluster Standard, controlla un pool di nodi:

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --flatten=nodeConfig \
    --format='csv[delimiter="\\n",no-heading](oauthScopes)'

Sostituisci NODE_POOL_NAME con il nome del pool di nodi.

Se il tuo cluster non ha https://www.googleapis.com/auth/cloud-platform ambito di accesso, crea un nuovo pool di nodi con l'ambito di accesso cloud-platform ed elimina il pool di nodi esistente.

Aggiorna il cluster per utilizzare il file di configurazione

Esegui questo comando:

gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Ricrea i nodi nei cluster Standard

Se il tuo cluster Standard non utilizza gli upgrade automatici, devi ricreare manualmente nei pool di nodi per applicare la nuova configurazione. Per attivare la ricreazione manuale dei nodi, esegui l'upgrade del tuo alla stessa versione GKE che già utilizza.

gcloud container clusters upgrade CLUSTER_NAME \
    --location=LOCATION \
    --cluster-version=VERSION

Sostituisci VERSION con la stessa versione della patch GKE utilizzata di un cluster Kubernetes.

Verifica che il cluster possa accedere al registro privato

Esegui questo comando:

gcloud container clusters describe CLUSTER_NAME \
    --location=LOCATION \
    --flatten="nodePoolDefaults.nodeConfigDefaults.containerdConfig"

L'output è simile al seguente:

    containerdConfig:
      privateRegistryAccessConfig:
        certificateAuthorityDomainConfig:
        - fqdns:
          - 203.0.113.105
          gcpSecretManagerCertificateConfig:
            secretUri: projects/123456789012/secrets/example-secret-name/versions/1
        enabled: true

Esegui il deployment di un carico di lavoro che accede a un'immagine privata

In questa sezione eseguirai il deployment di un pod statico che fa riferimento a un'immagine dalla tua registro privato.

Salva il seguente manifest come private-registry-pod.yaml:

apiVersion: v1
kind: Pod
metadata:
  name: private-registry-pod
spec:
  containers:
  - name: private-image
    image: IMAGE_NAME

Sostituisci IMAGE_NAME con il nome della tua immagine privata.

Esegui il deployment del pod:

kubectl create -f private-registry-pod.yaml

Ruota i certificati CA privati

Secret Manager e GKE non possono ruotare automaticamente certificati CA privati in Secret Manager. Per eseguire un la rotazione dei certificati, procedi nel seguente modo. Questi passaggi richiedono di ricreare i nodi esistenti due volte. Ti consigliamo di eseguire il certificato rotazioni durante il tempo di inattività pianificato per ridurre al minimo l'impatto del carico di lavoro o interruzioni del servizio.

Crea un pacchetto di certificati con codifica PEM che contenga sia il vecchio che il nuovo certificati.
Aggiungi il bundle come nuova versione del secret in Secret Manager.
Aggiorna il campo secretURI del file di configurazione del runtime con il nuovo numero di versione del secret.
Aggiorna il cluster per utilizzare la nuova versione del secret.

Ottieni il timestamp dell'operazione di aggiornamento:

gcloud container operations list \
    --filter="operationType ~ UPDATE_CLUSTER AND targetLink ~ CLUSTER_NAME" \
    --sort-by=startTime \
    --limit=1 \
    --format='value(endTime)'

L'output è simile al seguente:

2024-01-31T09:27:30.864308964Z

Cerca i nodi creati prima del termine dell'operazione di aggiornamento:
```
kubectl get nodes -o json | jq ".items[] |
select(.metadata.creationTimestamp | fromdateiso8601 < $(date -d
CLUSTER_UPDATE_TIMESTAMP +%s)) | .metadata.name"
```
Sostituisci CLUSTER_UPDATE_TIMESTAMP con il timestamp dal passaggio precedente.

L'output è un elenco di nomi di nodi che non sono stati ricreati con configurazione aggiornata. Quando l'output è vuoto, vai alla successiva passaggio.
Crea una nuova versione del tuo secret in Secret Manager con solo il nuovo certificato.
Ripeti i passaggi precedenti per aggiornare il cluster, ottieni timestamp dell'operazione e verifica che i nodi utilizzino la nuova versione del secret.
Elimina la versione precedente del secret da Secret Manager.

Visualizza audit log in Logging

Questa sezione mostra come utilizzare Logging per verificare se GKE ha installato la versione del secret sui tuoi nodi.

Vai alla pagina Esplora log nella console Google Cloud:

Vai a Esplora log

Specifica la query seguente:

resource.type="gce_instance"
textPayload:"Installed certificate \\\"projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION\\\""

Se l'installazione del certificato è riuscita, l'output è simile al seguenti:

"Installed certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

Se l'installazione del certificato non è riuscita, l'output è simile al seguenti:

"Failed to install certificate "projects/PROJECT_NUMBER/secrets/SECRET_NAME/versions/SECRET_VERSION""

Best practice

Ti consigliamo di adottare le seguenti best practice quando utilizzi questo funzionalità:

Non utilizzare alias per le versioni dei secret di Secret Manager. Utilizza la generato automaticamente per ogni versione del secret. Un alias potrebbe indirizzare a una versione del certificato diversa nel tempo, il che potrebbe causare complessità nel monitoraggio delle versioni specifiche utilizzate dai carichi di lavoro.
Utilizza le funzionalità di periodi di manutenzione ed esclusioni per controllare quando GKE può ricreare i nodi per applicare configurazioni containerd.
Fornisci l'accesso ai secret a livello di secret, non a livello di progetto.

Disabilita le opzioni di configurazione containerd

Per rimuovere la configurazione personalizzata:

Aggiorna il file di configurazione per specificare enabled: false nella configurazione dell'elemento che vuoi disattivare ed eliminare eventuali altri campi nell'elemento, come nell'esempio seguente esempio:
```
privateRegistryAccessConfig:
  enabled: false
```
Applica il file di configurazione aggiornato al cluster. Per istruzioni, vedi Applica la configurazione in container ai cluster esistenti.

Risoluzione dei problemi

Per conoscere la procedura di risoluzione dei problemi, vedi Risoluzione dei problemi relativi al runtime del container.