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 ai registri delle immagini privati. Per impostare queste opzioni, devi creare un file YAML chiamato file di configurazione di runtime e passarlo a GKE quando crei o aggiorni un cluster.

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 del runtime, GKE ricrea i nodi e aggiorna il file config.toml containerd su ogni nodo con la tua configurazione. La configurazione persiste durante la terminazione, gli upgrade e le ricreazioni dei nodi.

Il file di configurazione del runtime consente solo di configurare 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 dei nodi. Per maggiori dettagli, vedi Personalizzare la 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 runtime.

privateRegistryAccessConfig

Accedi ai registri di 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 dei registri privati. Puoi utilizzare anche indirizzi IPv4, ma ti consigliamo di utilizzare l'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 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 di 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 IPv4.
  • hosts: un elenco di configurazioni specifiche dell'host per server.
  • host: il nome host di un mirror del registro (ad esempio mirror.example.com). Devono essere nomi di dominio completi o indirizzi IPv4.
  • 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 funzionalità di push di blob e manifest.
    Se non specificato, tutte le funzionalità sono attivate.
  • 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 i 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 delle configurazioni dei certificati per l'autorità di certificazione (CA) dell'host del registro. 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 il secret per i certificati e configurare le autorizzazioni richieste, consulta 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 le versioni di GKE 1.34.1-gke.2541000 o successive.

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

writableCgroups:
  enabled: true

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 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 attivare la configurazione di containerd sui nuovi cluster standard eseguendo il comando gcloud container clusters create con le stesse opzioni.

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 di containerd a cluster e nodi esistenti.

Controllare gli ambiti di accesso

Per utilizzare questa funzionalità, i cluster esistenti devono disporre dell'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 registro privato 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 il tuo cluster non ha l'https://www.googleapis.com/auth/cloud-platform ambito di accesso, 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 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 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 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 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 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 istruzioni, vedi Applicare la configurazione di containerd ai cluster esistenti.