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 conoscere il significato di runtime del container e il motivo per cui 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 ai registri di immagini private. Per impostare queste opzioni, crea un file YAML chiamato file di configurazione del runtime e lo passi a GKE quando crei o aggiorni un cluster.

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

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 chiamato file di configurazione del sistema dei nodi. Per maggiori dettagli, consulta Personalizzazione della configurazione del sistema dei nodi.

Limitazioni

Non puoi utilizzare un file di configurazione del 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 del runtime.

privateRegistryAccessConfig

Accedi ai registri di immagini private con credenziali private che archivi in Secret Manager.

Questa opzione è disponibile con le versioni 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, consulta 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 abilitare 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 anche utilizzare indirizzi IPv4, ma ti consigliamo di utilizzare il FQDN.

registryHosts

Configura le impostazioni avanzate per i registri containerd, come funzionalità, intestazioni personalizzate e certificati. Corrisponde a hosts.toml di containerd.

Questa opzione è disponibile per le versioni GKE 1.34.1-gke.2980000 o 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 registro (ad esempio example.com). Viene utilizzato per denominare il 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 il server.
  • host: il nome host di un mirror del registro (ad esempio https://mirror.example.com:8000/1234, 1.2.3.4:80). Devono essere nomi di dominio completi o indirizzi 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 i seguenti:
    • HOST_CAPABILITY_PULL: rappresenta la funzionalità per recuperare manifest e blob tramite digest.
    • HOST_CAPABILITY_RESOLVE: rappresenta la funzionalità per recuperare i manifest per nome.
    • HOST_CAPABILITY_PUSH: rappresenta la funzionalità per eseguire il push di blob e manifest.
    Se non specificato, tutte le funzionalità sono abilitate.
  • overridePath: un valore booleano. Se true, indica che l'endpoint root dell'API dell'host è definito nel percorso dell'URL anziché dalla specifica dell'API. Può essere utilizzato con registri OCI non conformi a 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 registro. Per creare un secret per i certificati e configurare le autorizzazioni richieste, consulta le istruzioni in Archiviare 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, consulta le istruzioni in Archiviare 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 le versioni GKE 1.34.1-gke.2541000 o successive.

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

writableCgroups:
  enabled: true

Applicare la configurazione di containerd ai nuovi cluster

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

Esegui il comando seguente 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 località 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 di containerd sui nuovi cluster standard eseguendo il gcloud container clusters create comando con le stesse opzioni.

Applicare la configurazione di containerd ai nuovi pool di nodi

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.

Applicare la configurazione di containerd ai cluster esistenti

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

Controllare gli ambiti di accesso

Se il file di configurazione utilizza 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 del runtime nuovo o modificato.

Per informazioni dettagliate 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 secret di Secret Manager e il cluster non ha l'ambito di accesso https://www.googleapis.com/auth/cloud-platform, crea un nuovo cluster con questo ambito di accesso.

Controllare gli 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 secret di Secret Manager e il 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.

Aggiornare 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"

Ricreare 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 ricreazione manuale dei nodi, esegui l'upgrade del tuo 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.

Disattivare le opzioni di configurazione di containerd

Disattivare privateRegistryAccessConfig

  1. Aggiorna il file di configurazione in modo da 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 cluster. Per istruzioni, consulta Applicare la configurazione di containerd ai cluster esistenti.

Disattivare registryHosts

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

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