Accedi ai registri privati con certificati CA privati

Autopilota 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 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 e aggiorna la configurazione del registry di runtime del container durante l'avvio iniziale del nodo. Quando esegui il deployment di un carico di lavoro che utilizza un'immagine container dal tuo registro privato, vengono eseguiti i seguenti passaggi:

1. Kubelet sul nodo tenta di estrarre l'immagine dal registry privato.
2. Il registry presenta un certificato TLS lato server.
3. 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.
4. 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:

1. Migliora l'affidabilità della configurazione in fase di esecuzione del contenitore: l'utilizzo di metodi come i DaemonSet per impostare la configurazione di containerd aumenta il rischio che si verifichi una condizione di concorrenza, in cui altri DaemonSet potrebbero essere eseguiti prima del DaemonSet di configurazione.
2. Riduci la vulnerabilità agli attacchi con escalation dei privilegi: elimina la necessità per eseguire DaemonSet con privilegi che modificano il runtime del container configurazione.
3. Riduci il sovraccarico di gestione: Secret Manager consente di archiviare le chiavi pubbliche CA in un'unica posizione, gestire l'accesso alle chiavi utilizzando IAM e implementare il controllo delle versioni e le annotazioni. Per ulteriori informazioni, consulta la panoramica del prodotto Secret Manager.
4. Migliora la verificabilità: Cloud Logging raccoglie già i log, ad esempio quando i certificati vengono aggiunti a un cluster e quando i nodi GKE estraggono le 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 in base all'utilizzo previsto, utilizza il calcolatore prezzi.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti operazioni:

• Attiva l'API Google Kubernetes Engine.
Attiva l'API Google Kubernetes Engine
• Se vuoi utilizzare Google Cloud CLI per questa attività, installa e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente eseguendo gcloud components update.
  Nota: per le installazioni esistenti di gcloud CLI, assicurati di impostare le proprietà compute/region e compute/zone. Se imposti le posizioni predefinite, puoi evitare errori in gcloud CLI come il seguente: One of [--zone, --region] must be supplied: Please specify location.

• Enable the Secret Manager API.

  Enable the API

• Devi già disporre di un registro privato e di certificati CA privati per per accedere al registro. Questa guida non tratta della configurazione di un registry privato o della creazione di certificati.

Requisiti

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

• I cluster devono utilizzare GKE 1.27.3-gke.1700 o versioni successive.
• Devi utilizzare un sistema operativo ottimizzato per i container con containerd nodo, che è l'impostazione predefinita per tutti i cluster GKE. Le immagini del nodo 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 scaricare i certificati. Per ulteriori informazioni, vedi Ambiti di accesso predefiniti in GKE. Questo documento include istruzioni per impostare l'ambito di accesso quando crei un cluster o un pool di nodi.

Limitazioni

Tieni presenti le seguenti limitazioni:

• Non puoi utilizzare certificati CA privati nelle immagini dei nodi Ubuntu.
• Non puoi utilizzare certificati CA privati nei nodi Windows Server.
• Ogni cluster supporta fino a cinque certificati CA privati per registri.
• 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 pacchetti di certificati.
• I certificati devono essere codificati in PEM.
• Il server non ruota automaticamente i certificati. Per ulteriori informazioni, consulta la sezione Eseguire la rotazione dei 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 di DaemonSet con privilegi per modificare la configurazione di runtime del contenitore. Questo metodo modifica direttamente la configurazione di containerd su ogni nodo.

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

• La memorizzazione delle chiavi pubbliche della CA privata in Secret Manager consente di configurare solo l'accesso ai registry privati. Altri problemi relativi al registry non è supportata.

• Se attivi questa funzionalità, il cluster utilizzerà il modello di configurazione del percorso host CRI di containerd, che non è compatibile con il modello di configurazione precedente. Se hai DaemonSet che modificano la configurazione dell'host containerd, ad esempio per registry, mirror o proxy privati non sicuri, aggiorna i DaemonSet in modo che utilizzino 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 modello di configurazione, consulta Configurare le credenziali del registry.

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 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 condizionatamente un modello di configurazione specifico in base ai file di configurazione di containerd 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.

Memorizza le chiavi pubbliche della 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

Per assicurarti che l'account di servizio IAM del cluster disponga delle autorizzazioni necessarie per estrarre i 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 secret: Funzione di accesso ai secret di Secret Manager (roles/secretmanager.secretAccessor)
• Accedi ai metadati dei segreti: Secret Manager Viewer (roles/secretmanager.viewer)

Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

Questi ruoli predefiniti contengono le autorizzazioni necessarie per estrarre i secret da Secret Manager. Per visualizzare le autorizzazioni esatte richieste, espandi la sezione Autorizzazioni richieste:

Autorizzazioni obbligatorie

Per estrarre i 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 al tuo 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 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.

1. Ottieni il numero del tuo progetto Google Cloud:

   gcloud projects describe PROJECT_ID \
       --format="value(projectNumber)"
   

   L'output è il numero di progetto numerico.

2. 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 visualizzato nel passaggio precedente.
   • SECRET_VERSION: il numero di versione del segreto in Secret Manager. Se vuoi, puoi utilizzare un alias di versione, ma consigliamo di utilizzare il numero di versione per evitare complessità di gestione.
   • FQDN1, FQDN2: i nomi di dominio completamente qualificati per i tuoi registry 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 nella tabella delle opzioni di configurazione di containerd disponibili.

Applica la configurazione di 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, ad esempio ~/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 illustra come applicare una configurazione di containerd a cluster e nodi esistenti.

Nota: l'aggiornamento di un cluster con una configurazione containerd ricrea i nodi per applicare la configurazione. Ciò potrebbe causare interruzioni temporanee dei carichi di lavoro in esecuzione. GKE ricrea i nodi solo se sono abilitati gli upgrade automatici. Questa ricreazione rispetta qualsiasi periodi di manutenzione che hai impostato. Nei cluster standard in cui non sono abilitati gli upgrade automatici, devi rielaborare manualmente i nodi per applicare la configurazione.

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 informazioni dettagliate sugli ambiti di accesso predefiniti nei nuovi cluster, consulta Ambiti di accesso 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 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 in modo che utilizzi 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 una ricreazione manuale dei nodi, esegui l'upgrade del cluster alla stessa versione GKE già in uso.

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

Sostituisci VERSION con la stessa versione della patch GKE utilizzata già utilizzato da un cluster Kubernetes.

Verifica che il cluster possa accedere al registry 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.

1. 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 dell'immagine privata.

2. 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 una rotazione dei certificati, svolgi i seguenti passaggi. Questi passaggi richiedono di rielaborare 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.

1. Crea un bundle di certificati con codifica PEM contenente sia i certificati vecchi che quelli nuovi.
2. Aggiungi il bundle come nuova versione del secret in Secret Manager.
3. Aggiorna il campo secretURI del file di configurazione di runtime con il nuovo numero di versione del segreto.
4. Aggiorna il cluster in modo che utilizzi la nuova versione del segreto.

5. 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
   

6. 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.

7. Crea una nuova versione del tuo secret in Secret Manager con solo il nuovo certificato.

8. Ripeti i passaggi precedenti per aggiornare il cluster, ottieni timestamp dell'operazione e verifica che i nodi utilizzino la nuova versione del secret.

9. Elimina la vecchia versione del secret da Secret Manager.

Visualizzare gli audit log in Logistica

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

1. Vai alla pagina Esplora log nella console Google Cloud:

   Vai a Esplora log

2. Specifica la seguente query:

   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 gli alias per le versioni dei secret di Secret Manager. Utilizza il numero di versione generato automaticamente per ogni versione del secret. Un alias potrebbe indicare una versione del certificato diversa nel tempo, il che potrebbe causare complessità nel monitoraggio delle versioni specifiche utilizzate dai tuoi carichi di lavoro.
• Utilizza periodi di manutenzione ed esclusioni per controllare quando GKE può ricreare i tuoi nodi per applicare le configurazioni aggiornate di containerd.
• Fornisci l'accesso ai secret a livello di secret, non a livello di progetto.

Disattivare le opzioni di configurazione di containerd

Per rimuovere la configurazione personalizzata:

1. 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

2. 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.