Questa pagina è stata tradotta dall'API Cloud Translation.

Accesso ai registry 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 private utilizzando la chiave pubblica dell'autorità di certificazione (CA) che ha emesso il certificato per il registro.

Come funziona

Puoi archiviare in Secret Manager la chiave pubblica della CA utilizzata per emettere certificati per i tuoi registri privati e configurare i nomi di dominio completi (FQDN) del registro che utilizzano questa chiave pubblica per la convalida del certificato. GKE recupera automaticamente la chiave e aggiorna la configurazione del registro di runtime dei container durante il bootstrap dei nodi. Quando esegui il deployment di un carico di lavoro che utilizza un'immagine container del tuo registro privato, si verificano i seguenti passaggi:

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 registro in modo crittografico e verifica che il nome di dominio completo corrisponda a quello specificato.
Se la convalida ha esito positivo, GKE estrae l'immagine e pianifica il carico di lavoro.

Vantaggi

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

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

Prezzi

In questo documento, utilizzi i seguenti componenti fatturabili di Google Cloud:

GKE
Secret Manager
Logging: GKE genera audit log delle attività di amministrazione e, se abilitato, 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 in base all'utilizzo previsto, utilizza il Calcolatore prezzi.

Prima di iniziare

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

Abilita l'API Google Kubernetes Engine.

Abilita l'API Google Kubernetes Engine

Se vuoi utilizzare Google Cloud CLI per questa attività, installa e initialize gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente eseguendo gcloud components update.
Nota: per le installazioni esistenti dell'interfaccia a riga di comando gcloud, assicurati di impostare le proprietà compute/region e compute/zone. Impostando le località predefinite, puoi evitare errori nellgcloud CLI come segue: One of [--zone, --region] must be supplied: Please specify location.

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

Requisiti

Per utilizzare chiavi pubbliche della CA privata per accedere ai registri privati, devi soddisfare i seguenti requisiti:

I cluster devono utilizzare GKE versione 1.27.3-gke.1700 o successiva.
Devi utilizzare un'immagine del nodo Container-Optimized OS con containerd, che è l'impostazione predefinita per tutti i cluster GKE. Le immagini dei nodi Ubuntu con containerd non sono supportate. Le immagini dei nodi Windows Server non sono supportate.
I pool di nodi devono avere l'ambito di accesso cloud-platform affinché i nodi possano scaricare i certificati. Per maggiori informazioni, consulta Ambiti di accesso predefiniti in GKE. Questo documento include le istruzioni per impostare l'ambito di accesso quando crei un cluster o un 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 i registri privati.
Ogni certificato può avere fino a 25 nomi di dominio completi (FQDN).
Ogni dominio può essere utilizzato in un solo file di certificato. Tuttavia, sono supportati i bundle di certificati.
I certificati devono essere con codifica PEM.
Il server non ruota automaticamente i certificati. Per ulteriori informazioni, consulta Ruotare i certificati CA privati in questo documento.
I nomi di dominio completi presentano le seguenti limitazioni:
- La lunghezza massima del nome di dominio completo è di 255 caratteri, inclusi i caratteri speciali.
- I nomi di dominio completi possono contenere 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 di DaemonSet con privilegi per modificare la configurazione del runtime dei container. Questo metodo modifica direttamente la configurazione containerd su ciascun nodo.

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

L'archiviazione di chiavi pubbliche della CA privata in Secret Manager configura solo l'access ai registri privati. Altra configurazione relativa al registro non è supportata.
L'attivazione di questa funzionalità fa sì che il cluster utilizzi il modello di configurazione del percorso host CRI di containerd, che non è compatibile con il modello di configurazione precedente. Se sono presenti DaemonSet che modificano la configurazione host containerd, ad esempio per registry privati, mirror o proxy non sicuri, aggiorna i DaemonSet in modo da utilizzare il modello hostpath CRI.

Per i campi disponibili nel modello host CRI, consulta Configurazione del registro nel repository GitHub di containerd.

Nota: se disabiliti questa funzionalità in un secondo momento, i nodi ripristinano il modello precedente per la configurazione del registro in containerd. Per utilizzare il modello precedente, devi modificare i DaemonSet. Per informazioni sul modello di configurazione precedente, consulta Configurare le credenziali del registro.

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

Aggiornamento dei DaemonSet per supportare entrambi i modelli di configurazione

Per ridurre il rischio che i DaemonSet di configurazione non funzionino sui nodi che supportano un modello di configurazione specifico, assicurati che i DaemonSet utilizzino in modo condizionale un modello di configurazione specifico a seconda dei file di configurazione containerd sul nodo. Per un DaemonSet di esempio che implementa questa logica condizionale, nel repository GitHub di GoogleCloudPlatform/k8s-node-tools, consulta il manifest insecure-registry-config.yaml.

Archivia le chiavi pubbliche della CA in Secret Manager

Archivia le chiavi pubbliche delle CA private che emettono i certificati di registro privati come secret in Secret Manager. Per le istruzioni, nella documentazione di Secret Manager, vedi Creare un secret.

Configura l'accesso a Secret Manager da GKE

Per assicurarti che l'account di servizio IAM del cluster disponga delle autorizzazioni necessarie per eseguire il pull dei secret da Secret Manager, chiedi all'amministratore di concedere all'account di servizio IAM del cluster i seguenti ruoli IAM sul secret:

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

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

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

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 concedere queste autorizzazioni all'account di servizio IAM del cluster con ruoli personalizzati o altri ruoli predefiniti.

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

Crea un file di configurazione di runtime

Per abilitare la possibilità di utilizzare certificati CA privati per i registry privati in GKE, devi creare un file YAML per modificare la configurazione containerd.

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

Per una descrizione di questi campi, consulta privateRegistryAccessConfig nella tabella delle opzioni di configurazione containerd disponibili.

Applica la configurazione containerd a 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 nuovo cluster.
PATH_TO_CONFIG_FILE: il percorso del file di configurazione che hai creato, ad esempio ~/containerd-configuration.yaml.

Puoi abilitare la configurazione del registro privato sui nuovi cluster Standard eseguendo il comando 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 utilizzare questa funzionalità. Questa sezione mostra come controllare gli ambiti di accesso e aggiornare un cluster esistente con un file di configurazione del registro privato nuovo o modificato.

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

Controlla gli ambiti di accesso di 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'ambito di accesso https://www.googleapis.com/auth/cloud-platform, crea un nuovo cluster con questo ambito di accesso.

Controlla gli ambiti di accesso standard

Per verificare gli ambiti di accesso standard ai cluster, 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 l'ambito di accesso https://www.googleapis.com/auth/cloud-platform, 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 upgrade automatici, devi ricreare manualmente i pool di nodi per applicare la nuova configurazione. Per attivare la ricreazione manuale dei nodi, esegui l'upgrade del cluster alla stessa versione GKE che utilizza già.

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

Sostituisci VERSION con la stessa versione della patch GKE già in uso nel cluster.

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 del tuo 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 i certificati CA privati in Secret Manager. Per eseguire una rotazione dei certificati, segui questi passaggi. Questi passaggi richiedono la ricreazione dei nodi esistenti due volte. Ti consigliamo di eseguire le rotazione dei certificati durante il tempo di inattività pianificato per ridurre al minimo l'impatto delle interruzioni dei carichi di lavoro.

Crea un bundle di certificati con codifica PEM contenente i certificati vecchi e nuovi.
Aggiungi il bundle come nuova versione del secret in Secret Manager.
Aggiorna il campo del file di configurazione secretURI del runtime con il nuovo numero di versione del secret.
Aggiorna il cluster per utilizzare la nuova versione del secret.

Recupera 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 del passaggio precedente.

L'output è un elenco di nomi di nodi che non sono stati ricreati con la configurazione aggiornata. Quando l'output è vuoto, vai al passaggio successivo.
Crea una nuova versione del secret in Secret Manager solo con il nuovo certificato.
Ripeti i passaggi precedenti per aggiornare il cluster, ottenere il timestamp dell'operazione e verificare 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 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 sarà simile al seguente:

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

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

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

Best practice

Quando utilizzi questa funzionalità, ti consigliamo di attenerti alle seguenti best practice:

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

Disattiva le opzioni di configurazione containerd

Per rimuovere la configurazione personalizzata:

Aggiorna il file di configurazione per specificare enabled: false nell'elemento di configurazione che vuoi disattivare ed elimina eventuali altri campi nell'elemento, come nell'esempio seguente:
```
privateRegistryAccessConfig:
  enabled: false
```
Applica il file di configurazione aggiornato al cluster. Per le istruzioni, consulta Applicare la configurazione containerd ai cluster esistenti.

Risolvere i problemi

Per la procedura di risoluzione dei problemi, consulta Risoluzione dei problemi relativi al runtime dei container.