Personalizza la configurazione di containerd nei nodi GKE

Questa pagina mostra come personalizzare la configurazione del runtime del container containerd sui nodi Google Kubernetes Engine (GKE). Prima di leggere questo documento, assicurati di sapere cos'è un runtime del container e perché potresti volerlo personalizzare.

Informazioni sulla configurazione di containerd in GKE

Puoi configurare manualmente un insieme di opzioni nel runtime containerd sui nodi GKE che eseguono un sistema operativo come Container-Optimized OS. La personalizzazione del runtime ti consente di configurare requisiti speciali, come l'accesso a registry di immagini privati. Per impostare queste opzioni, devi creare un file YAML denominato file di configurazione di runtime e passarlo a GKE quando crei o aggiorni un cluster o un pool di nodi.

Questo metodo di personalizzazione di containerd ti consente di evitare il deployment di DaemonSet privilegiati, che rappresentano un rischio per la sicurezza. Quando fornisci a GKE un file di configurazione di runtime, GKE ricrea i nodi e aggiorna il file config.toml di containerd su ogni nodo con la tua configurazione. La configurazione persiste durante la terminazione, gli upgrade e le ricreazioni dei nodi.

Puoi configurare le impostazioni di containerd a livello di cluster o di pool di nodi. Una configurazione a livello di pool di nodi sostituisce una configurazione a livello di cluster per queste opzioni. Quando aggiorni un'opzione di configurazione di containerd a livello di cluster (ad esempio registryHosts o writableCgroups), GKE aggiorna e ricrea i nodi solo nei pool di nodi che non hanno impostazioni a livello di pool di nodi per queste opzioni. I pool di nodi con configurazioni a livello di pool di nodi proprie per l'opzione non verranno aggiornati o ricreati e continueranno a utilizzare le proprie impostazioni.

Il file di configurazione del runtime consente di configurare solo le opzioni in containerd. GKE supporta anche la configurazione di opzioni kubelet specifiche e opzioni del kernel Linux di basso livello utilizzando un file separato denominato file di configurazione del sistema del nodo. Per maggiori dettagli, vedi Personalizzazione della configurazione del sistema dei nodi.

Limitazioni

Non puoi utilizzare un file di configurazione di runtime per modificare le impostazioni di containerd nelle immagini dei nodi Windows.

Opzioni di configurazione di containerd disponibili

Le sezioni seguenti descrivono le opzioni che puoi configurare utilizzando un file di configurazione runtime.

privateRegistryAccessConfig

Accedi ai registri delle immagini privati con credenziali private che memorizzi in Secret Manager.

Questa opzione è disponibile con le versioni di GKE 1.27.3-gke.1700 o successive per le immagini dei nodi Container-Optimized OS e 1.33 o successive per le immagini dei nodi Ubuntu.

Per istruzioni, vedi Accedere ai registri privati con certificati CA privati.

privateRegistryAccessConfig:
  enabled: true
  certificateAuthorityDomainConfig:
  - gcpSecretManagerCertificateConfig:
    secretURI: "SECRET_LOCATION"
  fqdns:
  - "FQDN1"
  - "FQDN2"

Questa configurazione ha i seguenti campi:

  • enabled: un valore booleano per attivare la configurazione del registro privato. Se imposti enabled: false, elimina tutti gli altri campi nell'elemento privateRegistryAccessConfig.
  • certificateAuthorityDomainConfig: contiene fino a cinque definizioni di certificati e FQDN.
  • gcpSecretManagerCertificateConfig: contiene un certificato archiviato in Secret Manager e un array di FQDN.
  • secretURI: la posizione del certificato in Secret Manager. privateRegistryAccessConfig supporta i secret globali solo in secretURI.
  • fqdns: un elenco di nomi di dominio completi di registri privati. Puoi utilizzare anche indirizzi IPv4, ma ti consigliamo di utilizzare il FQDN.

registryHosts

Configura le impostazioni avanzate per i registri containerd, come funzionalità, intestazioni personalizzate e certificati. Questo corrisponde al file hosts.toml di containerd.

Questa opzione è disponibile per GKE 1.34.1-gke.2980000 o versioni successive.

registryHosts:
- server: "REGISTRY_SERVER_FQDN"
  hosts:
  - host: "MIRROR_FQDN"
    capabilities:
    - "HOST_CAPABILITY_PULL"
    - "HOST_CAPABILITY_RESOLVE"
    - "HOST_CAPABILITY_PUSH"
    overridePath: false
    dialTimeout: "30s"
    header:
    - key: "HEADER_KEY"
      value:
      - "HEADER_VALUE_1"
      - "HEADER_VALUE_2"
    ca:
    - gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CA_SECRET/versions/VERSION"
    client:
    - cert:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_CERT_SECRET/versions/VERSION"
      key:
        gcpSecretManagerSecretUri: "projects/PROJECT_ID_OR_NUMBER/secrets/CLIENT_KEY_SECRET/versions/VERSION"

Questa configurazione ha i seguenti campi:

  • server: il nome host del server del registry (ad esempio example.com). Viene utilizzato per assegnare un nome al file di configurazione sul nodo. Deve essere un nome di dominio completo o un indirizzo IP senza schema, porta o percorso.
  • hosts: un elenco di configurazioni specifiche dell'host per server.
  • host: il nome host di un mirror del registry (ad esempio https://mirror.example.com:8000/1234, 1.2.3.4:80). Deve essere un nome di dominio completo o un indirizzo IP. Sono supportati schema, porta e percorso. Lo schema può essere solo http o https.
  • capabilities: un elenco di funzionalità che specificano le operazioni che un host è in grado di eseguire. I valori supportati sono uno qualsiasi dei seguenti:
    • HOST_CAPABILITY_PULL: rappresenta la funzionalità di recupero di manifest e blob tramite digest.
    • HOST_CAPABILITY_RESOLVE: rappresenta la funzionalità di recupero dei manifest per nome.
    • HOST_CAPABILITY_PUSH: rappresenta la capacità di eseguire il push di blob e manifest.
    Se non specificate, tutte le funzionalità sono attive.
  • overridePath: un valore booleano. Se true, indica che l'endpoint radice dell'API dell'host è definito nel percorso URL anziché dalla specifica API. Può essere utilizzato con registry OCI non conformi in cui manca il prefisso /v2. Il valore predefinito è false.
  • dialTimeout: una stringa di durata (ad esempio "30s") che specifica la durata massima consentita per il completamento di un tentativo di connessione. Il valore massimo consentito è "180s". Se non viene impostato, containerd imposta un valore predefinito di "30s". Il valore deve essere un numero decimale di secondi con un suffisso s.
  • header: un elenco di intestazioni HTTP personalizzate da inviare all'host del registro.
    • key: la chiave dell'intestazione.
    • value: un elenco di valori di intestazione.
  • ca: un elenco di configurazioni dei certificati per l'autorità di certificazione (CA) dell'host del registry. Per creare il secret per i certificati e configurare le autorizzazioni richieste, consulta le istruzioni riportate in Archivia le chiavi pubbliche della CA in Secret Manager.
    • gcpSecretManagerSecretUri: l'URI di un secret in Secret Manager contenente il certificato CA. Supporta sia i secret globali che quelli regionali. I formati sono i seguenti, per i rispettivi tipi di secret:
      • Formato del secret globale: projects/PROJECT_ID_OR_NUMBER/secrets/SECRET_NAME/versions/VERSION.
      • Formato del secret regionale: projects/PROJECT_ID_OR_NUMBER/locations/REGION/secrets/SECRET_NAME/versions/VERSION.
  • client: un elenco di coppie di chiavi e certificati client per l'autenticazione all'host del registro. Per creare un secret per i certificati e configurare le autorizzazioni richieste, segui le istruzioni riportate in Archivia le chiavi pubbliche della CA in Secret Manager.
    • cert: la configurazione del certificato client.
      • gcpSecretManagerSecretUri: l'URI di un secret in Secret Manager contenente il certificato client. Supporta sia i secret globali che quelli regionali.
    • key: la configurazione della chiave privata del client.
      • gcpSecretManagerSecretUri: l'URI di un secret in Secret Manager contenente la chiave client. Supporta sia i secret globali che quelli regionali.

writableCgroups

Monta il file system /sys/fs/cgroup in modalità di lettura/scrittura in modo che i carichi di lavoro possano gestire le risorse dei processi secondari.

Questa opzione è disponibile per GKE 1.34.1-gke.2541000 o versioni successive.

Per saperne di più, consulta Configura i cgroup scrivibili per i container.

writableCgroups:
  enabled: true

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 per creare cluster Autopilot:

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 posizione 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 attivare la configurazione di containerd sui nuovi cluster standard eseguendo il comando gcloud container clusters create con le stesse opzioni. A meno che tu non specifichi una configurazione di containerd diversa, i nuovi node pool creati nel cluster ereditano la configurazione di containerd predefinita a livello di cluster.

Applica la configurazione di containerd ai nuovi node pool

Puoi applicare la configurazione di containerd a un nuovo pool di nodi GKE con il seguente comando:

gcloud container node-pools create NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --scopes="cloud-platform" \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Sostituisci quanto segue:

  • NODE_POOL_NAME: il nome del nuovo pool di nodi.
  • CLUSTER_NAME: il nome del cluster esistente.
  • LOCATION: la località Compute Engine del nuovo pool di nodi.
  • PATH_TO_CONFIG_FILE: il percorso del file di configurazione che hai creato, ad esempio ~/containerd-configuration.yaml.

Applica la configurazione di containerd ai cluster esistenti

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

L'aggiornamento della configurazione di containerd a livello di cluster si applica solo ai node pool che non hanno impostazioni proprie definite a livello di pool di nodi (ad esempio registryHosts o writableCgroups). GKE ricrea i nodi in questi node pool per applicare la nuova configurazione. I node pool con impostazioni a livello di pool di nodi continuano a utilizzare la propria configurazione e i relativi nodi non vengono ricreati. L'aggiornamento di un cluster o di un pool di nodi con una configurazione containerd ricrea i nodi per applicare la configurazione. Ciò potrebbe causare interruzioni temporanee nell'esecuzione dei workload. GKE ricrea i nodi solo se sono abilitati gli upgrade automatici. Questa nuova creazione rispetta i periodi di manutenzione che hai impostato. Nei cluster Standard in cui non sono attivi gli upgrade automatici, devi ricreare manualmente i nodi per applicare la configurazione.

Controlla gli ambiti di accesso

Se il file di configurazione utilizza i secret di Secret Manager, il cluster o il pool di nodi deve avere l'ambito di accesso cloud-platform. Questa sezione mostra come controllare gli ambiti di accesso e aggiornare un cluster esistente con un file di configurazione di runtime nuovo o modificato.

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

Controllare 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 utilizzi i secret di Secret Manager e il tuo cluster non dispone dell'ambito di accesso https://www.googleapis.com/auth/cloud-platform, crea un nuovo cluster con questo ambito di accesso.

Seleziona Ambiti di accesso standard

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

gcloud container node-pools describe NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --format='value[delimiter="\\n"](config.oauthScopes)'

Sostituisci NODE_POOL_NAME con il nome del pool di nodi.

Se utilizzi i secret di Secret Manager e il cluster non ha l'ambito di accesso https://www.googleapis.com/auth/cloud-platform, crea un nuovo node pool 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"

Aggiorna un pool di nodi in modo che utilizzi un file di configurazione

Per aggiornare la configurazione di containerd per un pool di nodi, esegui questo comando:

gcloud container node-pools update NODE_POOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=LOCATION \
    --containerd-config-from-file="PATH_TO_CONFIG_FILE"

Sostituisci quanto segue:

  • NODE_POOL_NAME: il nome del pool di nodi che vuoi aggiornare.
  • CLUSTER_NAME: il nome del cluster esistente.
  • LOCATION: la località di Compute Engine del cluster.
  • PATH_TO_CONFIG_FILE: il percorso del file di configurazione che hai creato, ad esempio ~/containerd-configuration.yaml.

Ricrea i nodi nei cluster Standard

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

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

Sostituisci VERSION con la stessa versione patch di GKE già utilizzata dal cluster.

Disattiva le opzioni di configurazione di containerd

Disabilita privateRegistryAccessConfig

  1. Aggiorna il file di configurazione per specificare enabled: false in privateRegistryAccessConfig ed elimina tutti gli altri campi nell'elemento, come nell'esempio seguente:

    privateRegistryAccessConfig:
  enabled: false
  2. Applica il file di configurazione aggiornato al tuo cluster. Per le istruzioni, vedi Applicare la configurazione di containerd ai cluster esistenti.

Disabilita registryHosts

  1. Aggiorna il file di configurazione per specificare un array vuoto nell'elemento registryHosts, come nell'esempio seguente:

    registryHosts: []
  2. Applica il file di configurazione aggiornato al tuo cluster. Per le istruzioni, vedi Applicare la configurazione di containerd ai cluster esistenti.