Esegui la migrazione dei nodi a containerd 2

I cluster Google Kubernetes Engine (GKE) utilizzano immagini dei nodi containerd con tutti i nodi worker che eseguono la versione 1.24 e successive. I nodi worker utilizzano una versione specifica di containerd, in base alla versione di GKE:

  • I nodi che eseguono GKE 1.32 o versioni precedenti, con immagini dei nodi containerd, utilizzano containerd 1.7 o versioni precedenti.
  • I nodi che eseguono GKE 1.33 utilizzano containerd 2.0.

Quando i nodi GKE vengono aggiornati dalla versione 1.32 alla 1.33, i nodi vengono migrati dall'utilizzo di containerd 1.7 alla nuova versione principale, containerd 2.0. Non puoi modificare la versione di Containerd utilizzata da una versione di GKE.

Puoi saltare la lettura di questa pagina se sai che i tuoi workload vengono eseguiti come previsto su containerd 2.

Come GKE sta eseguendo la transizione a containerd 2

Esamina la seguente cronologia per capire come GKE sta eseguendo la transizione dei cluster esistenti per utilizzare containerd 2:

  • Con la versione secondaria 1.32, GKE utilizza containerd 1.7. containerd 1.7 ha ritirato sia le immagini Docker Schema 1 sia l'API Container Runtime Interface (CRI) v1alpha2. Per scoprire di più sulle altre funzionalità ritirate nelle versioni precedenti, consulta Proprietà di configurazione ritirate.
  • Con la versione secondaria 1.33, GKE utilizza containerd 2.0, che rimuove il supporto per le immagini Docker schema 1 e l'API CRI v1alpha2.
  • Le seguenti proprietà di configurazione di containerd nel plug-in CRI sono ritirate e verranno rimosse in containerd 2.2, con una versione di GKE ancora da annunciare: registry.auths, registry.configs, registry.mirrors. registry.configs.tls, tuttavia, è già stato rimosso in containerd 2.0.

Per una tempistica approssimativa degli upgrade automatici alle versioni secondarie successive, ad esempio 1.33, consulta la pianificazione stimata per i canali di rilascio.

Impatto della transizione a containerd 2

Leggi la sezione seguente per comprendere l'impatto di questa transizione a containerd 2.

Upgrade automatici in pausa

GKE mette in pausa gli upgrade automatici alla versione 1.33 quando rileva che un cluster utilizza le funzionalità deprecate. Tuttavia, se i nodi del cluster utilizzano queste funzionalità, ti consigliamo di creare un'esclusione di manutenzione per impedire gli upgrade dei nodi. L'esclusione della manutenzione garantisce che i nodi non vengano sottoposti ad upgrade se GKE non rileva l'utilizzo.

Dopo la migrazione dall'utilizzo di queste funzionalità, GKE riprende gli upgrade secondari automatici alla versione 1.33 se sono vere le seguenti condizioni:

  • GKE non ha rilevato l'utilizzo di funzionalità deprecate per 14 giorni, o 3 giorni per le proprietà CRI registry.configs deprecate.
  • 1.33 è un target di upgrade automatico per i nodi del cluster.
  • Non esistono altri fattori di blocco. Per saperne di più, consulta Tempistiche degli upgrade automatici.

Per i pool di nodi del cluster Standard, puoi anche eseguire manualmente l'upgrade del pool di nodi.

Fine del supporto e impatto della mancata preparazione alla migrazione

GKE mette in pausa gli upgrade automatici fino alla fine dell'assistenza standard. Se il tuo cluster è registrato nel canale esteso, i tuoi nodi possono rimanere su una versione fino alla fine del supporto esteso. Per maggiori dettagli sugli upgrade automatici dei nodi alla fine del supporto, consulta Upgrade automatici alla fine del supporto.

Se non esegui la migrazione da queste funzionalità, quando la versione 1.32 raggiungerà la fine del supporto e i nodi del cluster verranno aggiornati automaticamente alla versione 1.33, potresti riscontrare i seguenti problemi con i tuoi cluster:

  • I workload che utilizzano immagini Docker schema 1 non vanno a buon fine.
  • Le applicazioni che chiamano l'API CRI v1alpha2 riscontrano errori durante la chiamata dell'API.

Identificare i cluster interessati

GKE monitora i tuoi cluster e utilizza il servizio Recommender per fornire indicazioni tramite approfondimenti e suggerimenti per identificare i nodi del cluster che utilizzano queste funzionalità ritirate.

Requisiti della versione

I cluster ricevono questi approfondimenti e suggerimenti se eseguono le seguenti versioni o versioni successive:

  • 1.28.15-gke.1159000
  • 1.29.9-gke.1541000
  • 1.30.5-gke.1355000
  • 1.31.1-gke.1621000

Visualizzare approfondimenti e consigli

Segui le istruzioni per visualizzare approfondimenti e consigli. Puoi ottenere approfondimenti utilizzando la console Google Cloud . Puoi anche utilizzare Google Cloud CLI o l'API Recommender filtrando con i seguenti sottotipi:

  • DEPRECATION_CONTAINERD_V1_SCHEMA_IMAGES: Immagini Docker schema 1
  • DEPRECATION_CONTAINERD_V1ALPHA2_CRI_API: API CRI v1alpha2
  • DEPRECATION_CONTAINERD_V2_CONFIG_REGISTRY_CONFIGS: Proprietà CRI ritirate registry.configs, tra cui registry.configs.auth e registry.configs.tls

Eseguire la migrazione dalle funzionalità ritirate

Esamina i seguenti contenuti per capire come eseguire la migrazione dalle funzionalità ritirate con containerd 2.

Esegui la migrazione dalle immagini Docker schema 1

Identifica i workload che utilizzano immagini di cui è necessario eseguire la migrazione, quindi esegui la migrazione di questi workload.

Trovare le immagini da migrare

Puoi utilizzare diversi strumenti per trovare le immagini che devono essere migrate.

Utilizzare insight e suggerimenti o Cloud Logging

Come spiegato nella sezione Identificare i cluster interessati, puoi utilizzare approfondimenti e consigli per trovare i cluster che utilizzano immagini Docker Schema 1 se il tuo cluster esegue una versione minima o successiva. Inoltre, puoi utilizzare la seguente query in Cloud Logging per controllare i log di containerd e trovare le immagini Docker Schema 1 nel tuo cluster:

jsonPayload.SYSLOG_IDENTIFIER="containerd"
"conversion from schema 1 images is deprecated"

Se sono trascorsi più di 30 giorni dal recupero dell'immagine, potresti non visualizzare i log per un'immagine.

Utilizza il comando ctr direttamente su un nodo

Per eseguire una query su un nodo specifico per restituire tutte le immagini non eliminate che sono state estratte come Schema 1, esegui questo comando su un nodo:

  ctr --namespace k8s.io images list 'labels."io.containerd.image/converted-docker-schema1"'

Questo comando può essere utile, ad esempio, se stai risolvendo i problemi di un nodo specifico e non vedi voci di log in Cloud Logging perché sono trascorsi più di 30 giorni dal pull dell'immagine.

Utilizza lo strumento open source crane

Puoi anche utilizzare strumenti open source come crane per cercare immagini.

Esegui questo comando crane per controllare la versione dello schema di un'immagine:

crane manifest $tagged_image | jq .schemaVersion

Preparare i workload

Per preparare i workload che eseguono immagini Docker schema 1, devi eseguire la migrazione di questi workload alle immagini Docker schema 2 o alle immagini Open Container Initiative (OCI). Valuta le seguenti opzioni per la migrazione:

  • Trova un'immagine sostitutiva:potresti riuscire a trovare un'immagine open source o fornita dal fornitore disponibile pubblicamente.
  • Converti l'immagine esistente:se non riesci a trovare un'immagine sostitutiva, puoi convertire le immagini Docker schema 1 esistenti in immagini OCI seguendo questi passaggi:
    1. Estrai l'immagine Docker in containerd, che la converte automaticamente in un'immagine OCI.
    2. Esegui il push della nuova immagine OCI nel registro.

Esegui la migrazione dall'API CRI v1alpha2

L'API CRI v1alpha2 è stata rimossa in Kubernetes 1.26. Devi identificare i workload che accedono al socket containerd e aggiornare queste applicazioni per utilizzare l'API v1.

Identificare i workload potenzialmente interessati

Puoi utilizzare diverse tecniche per identificare i workload che potrebbero dover essere migrati. Queste tecniche potrebbero generare falsi positivi che devi esaminare ulteriormente per determinare che non è necessario alcun intervento.

Utilizzare approfondimenti e consigli

Puoi utilizzare approfondimenti e consigli per trovare i cluster che utilizzano l'API v1alpha2 se il tuo cluster esegue una versione minima o successiva. Per maggiori dettagli, vedi Identificare i cluster interessati.

Quando visualizzi gli approfondimenti nella console Google Cloud , consulta il riquadro della barra laterale Esegui la migrazione dei workload dall'API CRI v1alpha2 deprecata. La tabella Workload da verificare in questo riquadro elenca i workload che potrebbero essere interessati. Questo elenco include tutti i carichi di lavoro non gestiti da GKE che hanno volumi hostPath contenenti il percorso del socket containerd (ad esempio, /var/run/containerd/containerd.sock o /run/containerd/containerd.sock).

È importante comprendere quanto segue:

  • L'elenco dei workload da verificare può contenere falsi positivi. Utilizzalo solo per le indagini. Un workload visualizzato in questo elenco non significa necessariamente che utilizza l'API ritirata e la presenza di un falso positivo non sospenderà gli upgrade automatici. La sospensione si basa solo sull'utilizzo effettivamente osservato dell'API deprecata.
  • Questo elenco potrebbe essere vuoto o incompleto. Un elenco vuoto o incompleto può verificarsi se i workload che utilizzano l'API ritirata sono stati di breve durata e non erano in esecuzione quando GKE ha eseguito il controllo periodico. La presenza del consiglio stesso indica che è stato rilevato l'utilizzo dell'API CRI v1alpha2 su almeno un nodo del cluster. Gli upgrade automatici riprendono dopo che l'utilizzo dell'API deprecata non è stato rilevato per 14 giorni.

Pertanto, ti consigliamo di eseguire ulteriori indagini utilizzando i seguenti metodi per confermare l'utilizzo effettivo dell'API.

Controlla i carichi di lavoro di terze parti interessati

Per il software di terze parti di cui è stato eseguito il deployment nei cluster, verifica che questi workload non utilizzino l'API CRI v1alpha2. Potresti dover contattare i rispettivi fornitori per verificare quali versioni del loro software sono compatibili.

Utilizza kubectl

Il seguente comando ti aiuta a trovare i workload potenzialmente interessati cercando quelli che accedono al socket containerd. Utilizza una logica simile a quella utilizzata per la tabella Carichi di lavoro da verificare nel consiglio della console Google Cloud . Restituisce i carichi di lavoro non gestiti da GKE che hanno volumi hostPath, incluso il percorso del socket. Come il suggerimento, questa query potrebbe restituire falsi positivi o non rilevare i workload di breve durata.

Esegui questo comando:

kubectl get pods --all-namespaces -o json | \
jq -r '
  [
    "/", "/var", "/var/","/var/run", "/var/run/",
    "/var/run/containerd", "/var/run/containerd/", "/var/run/containerd/containerd.sock",
    "/run", "/run/", "/run/containerd", "/run/containerd/",
    "/run/containerd/containerd.sock"
  ] as $socket_paths |
  [
    "kube-system", "kube-node-lease", "istio-system", "asm-system",
    "gatekeeper-system", "config-management-system", "config-management-monitoring",
    "cnrm-system", "hnc-system", "gke-managed-system", "gke-gmp-system",
    "gmp-system", "gke-managed-cim"
  ] as $excluded_namespaces |
  .items[] |
  select(
    (.spec.volumes[]?.hostPath.path as $p | $socket_paths | index($p))
    and
    ([.metadata.namespace] | inside($excluded_namespaces) | not)
  ) |
  .metadata.namespace + "/" + .metadata.name
'
Utilizza la tracciatura eBPF per identificare i chiamanti API

Per un modo più definitivo per identificare quali workload chiamano l'API CRI v1alpha2, puoi eseguire il deployment di due DaemonSet specializzati:

  • containerd-socket-tracer registra qualsiasi processo che apre una connessione al socket containerd, insieme ai dettagli del pod e del container.
  • cri-v1alpha2-api-deprecation-reporter registra l'ultima volta che è stata chiamata l'API CRI v1alpha2.

Questi strumenti utilizzano Extended Berkeley Packet Filter (eBPF) per tracciare le connessioni al socket containerd e correlare le connessioni con le chiamate API deprecate effettive.

Correlare i timestamp di questi due strumenti ti consente di individuare il carico di lavoro esatto che effettua la chiamata API ritirata. Questo metodo offre un grado di confidenza maggiore rispetto al solo controllo dei volumi hostPath, perché osserva le connessioni socket effettive e l'utilizzo dell'API.

Per istruzioni dettagliate su come eseguire il deployment e utilizzare questi strumenti e su come interpretare i relativi log, consulta Tracciamento delle connessioni socket di containerd.

Se, dopo aver utilizzato questi strumenti, non riesci ancora a identificare l'origine delle chiamate API ritirate, ma il consiglio rimane attivo, consulta Richiedi assistenza.

Dopo aver identificato un workload che utilizza l'API CRI v1alpha2, tramite i metodi precedenti o ispezionando la base di codice, devi aggiornare il codice per utilizzare l'API v1.

Aggiorna codice applicazione

Per aggiornare l'applicazione, rimuovi il punto in cui l'applicazione importa la libreria client k8s.io/cri-api/pkg/apis/runtime/v1alpha2 e modifica il codice per utilizzare la versione v1 dell'API. Questo passaggio prevede la modifica del percorso di importazione e l'aggiornamento del modo in cui il codice chiama l'API.

Ad esempio, vedi il seguente codice Golang, che utilizza la libreria ritirata:

  package main

  import (
    ...

    runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"
  )

  func foo() {
    ...

    client := runtimeapi.NewRuntimeServiceClient(conn)
    version, err := client.Version(ctx, &runtimeapi.VersionRequest{})

    ...
  }

Qui, l'applicazione importa la libreria v1alpha2 e la utilizza per inviare RPC. Se le RPC utilizzano la connessione al socket containerd, questa applicazione fa sì che GKE metta in pausa gli upgrade automatici per il cluster.

Per cercare e aggiornare il codice dell'applicazione:

  1. Identifica le applicazioni Golang problematiche eseguendo questo comando per cercare il percorso di importazione v1alpha2:

      grep -r "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"

    Se l'output di questo comando mostra che la libreria v1alpha2 viene utilizzata nel file, devi aggiornarlo.

    Ad esempio, sostituisci il seguente codice dell'applicazione:

      runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1alpha2"

  2. Aggiorna il codice per utilizzare la versione 1:

      runtimeapi "k8s.io/cri-api/pkg/apis/runtime/v1"

Esegui la migrazione dalle proprietà di configurazione di containerd deprecate

Le proprietà di configurazione di containerd registry.auths, registry.configs e registry.mirrors nel plug-in CRI sono deprecate e verranno rimosse in containerd 2.2, con una versione di GKE ancora da annunciare. registry.configs.tls, tuttavia, è già stato rimosso in containerd 2.0.

Identificare i workload

Puoi utilizzare diverse tecniche per identificare i carichi di lavoro di cui deve essere eseguita la migrazione.

Utilizzare approfondimenti e consigli

Come approccio iniziale, puoi utilizzare approfondimenti e consigli per trovare cluster che utilizzano le proprietà di configurazione di containerd ritirate. È richiesta una versione minima di GKE. Per saperne di più su questo approccio, vedi Identificare i cluster interessati.

Quando visualizzi gli approfondimenti nella console Google Cloud , vedi il riquadro della barra laterale Esegui la migrazione della configurazione containerd dal campo "auths" del registro CRI deprecato o Esegui la migrazione della configurazione containerd dal campo "mirrors" del registro CRI deprecato. Per trovare i workload che potrebbero accedere alla configurazione di containerd, controlla la sezione Workload da verificare.

Utilizza kubectl

In alternativa, puoi utilizzare kubectl per identificare i carichi di lavoro.

Individua i workload che modificano la configurazione di containerd controllando i workload con i seguenti attributi:

  • Carichi di lavoro che contengono un volume hostPath che include la configurazione di containerd
  • Carichi di lavoro con un container con accesso privilegiato (spec.containers.securityContext.privileged: true) e che utilizzano lo spazio dei nomi dell'ID processo (PID) host (spec.hostPID: true)

Questo comando potrebbe restituire falsi positivi perché il carico di lavoro potrebbe accedere ad altri file in queste directory che non sono la configurazione di containerd. In alternativa, questo comando potrebbe non restituire i workload che accedono al file di configurazione di containerd in altri modi meno comuni.

Esegui questo comando per verificare la presenza di DaemonSet:

kubectl get daemonsets --all-namespaces -o json | \
jq -r '
  [
    "/", "/etc", "/etc/",
    "/etc/containerd", "/etc/containerd/",
    "/etc/containerd/config.toml"
  ] as $host_paths |
  [
    "kube-system", "kube-node-lease", "istio-system", "asm-system",
    "gatekeeper-system", "config-management-system", "config-management-monitoring",
    "cnrm-system", "hnc-system", "gke-managed-system", "gke-gmp-system",
    "gmp-system", "gke-managed-cim"
  ] as $excluded_namespaces |
  .items[] |
  select(
    ([.metadata.namespace] | inside($excluded_namespaces) | not)
    and
    (
      (any(.spec.template.spec.volumes[]?.hostPath.path; IN($host_paths[])))
      or
      (
        .spec.template.spec.hostPID == true and
        any(.spec.template.spec.containers[]; .securityContext?.privileged == true)
      )
    )
  ) |
  .metadata.namespace + "/" + .metadata.name
'

Esegui la migrazione dalle proprietà del registro CRI auths o configs.auth

Se i tuoi carichi di lavoro utilizzano le proprietà auths o configs.auth nella configurazione di containerd per l'autenticazione a un registro privato per il pull delle immagini container, devi eseguire la migrazione dei carichi di lavoro che utilizzano queste immagini al campo imagePullSecrets. Per saperne di più, vedi Recuperare un'immagine da un registro privato.

Per identificare ed eseguire la migrazione dei carichi di lavoro che utilizzano le proprietà auths o configs.auth ritirate, consulta le seguenti istruzioni.

Individua i dettagli di autenticazione per il tuo registro

Puoi trovare i dettagli di autenticazione per il tuo registro in uno dei seguenti modi:

  • Esamina le sezioni auths e configs.auth del registro CRI nel file /etc/containerd/config.toml connettendoti a un nodo GKE.
  • Trova il workload che modifica il file di configurazione di containerd e scopri quali dettagli di autenticazione sono inclusi utilizzando i metodi descritti in precedenza per identificare i workload. GKE non utilizza queste impostazioni per i carichi di lavoro di sistema.

Se utilizzi la proprietà registry.configs.auth, i dettagli di autenticazione potrebbero avere il seguente aspetto:

  [plugins."io.containerd.grpc.v1.cri".registry.configs."$REGISTRY_DOMAIN".auth]
    username = "example-user"
    password = "example-password"

Raccogli questi dettagli di autenticazione per ogni dominio del registro specificato nella configurazione.

Aggiorna il workload per utilizzare il campo imagePullSecrets
  1. Crea un secret con i dettagli di autenticazione della sezione precedente seguendo le istruzioni per estrarre un'immagine da un registro privato.

  2. Identifica i carichi di lavoro di cui è necessario eseguire la migrazione al campo imagePullSecrets eseguendo questo comando:

    kubectl get pods -A -o json |
jq -r ".items[] |
  select(.spec.containers[] |
        .image | startswith(\"$REGISTRY_DOMAIN\")) |
  .metadata.namespace + \"/\" + .metadata.name"

    Devi creare un secret per ogni spazio dei nomi utilizzato dai carichi di lavoro con immagini di questo dominio del registro.

  3. Aggiorna i tuoi carichi di lavoro in modo che utilizzino il campo imagePullSecrets con i secret che hai creato nel passaggio precedente.

    In alternativa, se devi eseguire la migrazione di un numero elevato di carichi di lavoro, puoi implementare un MutatingAdmissionWebhook per aggiungere il campo imagePullSecrets.

Aggiorna la configurazione di containerd per interrompere l'impostazione delle autenticazioni del registro

Dopo aver eseguito la migrazione dei workload in modo che utilizzino il campo imagePullSecrets, devi aggiornare i workload che modificano la configurazione containerd per interrompere l'impostazione delle autenticazioni del registro. Per tutti i workload che hai identificato come modificanti la configurazione, modificali in modo che non impostino più le autenticazioni del registro.

Esegui il test con un nuovo pool di nodi ed esegui la migrazione dei workload al nuovo pool di nodi

Per ridurre il rischio di causare problemi con i workload, procedi nel seguente modo:

  1. Crea un nuovo pool di nodi.
  2. Pianifica il workload aggiornato che modifica la configurazione di containerd per i nodi nel nuovo pool di nodi.
  3. Esegui la migrazione dei workload rimanenti al nuovo pool di nodi seguendo le istruzioni per eseguire la migrazione dei workload tra i node pool.

Esegui la migrazione dalla proprietà configs.tls del registro CRI

Se i tuoi workload utilizzano la proprietà registry.configs.tls, devi eseguire la migrazione di questi workload per accedere ai registri privati con certificati CA privati.

Segui le istruzioni per eseguire la migrazione da DaemonSet di configurazione. Questa procedura viene eseguita con i seguenti passaggi:

  1. Aggiorna i workload che modificano la configurazione di containerd per interrompere l'impostazione dei dettagli TLS.
  2. Archivia i certificati in Secret Manager.
  3. Crea un file di configurazione di runtime che rimandi ai tuoi certificati.
  4. Crea un nuovo pool di nodi e verifica che i tuoi workload che utilizzano immagini ospitate dal registro privato funzionino come previsto.
  5. Applica la configurazione a un nuovo cluster e inizia a eseguire i carichi di lavoro su quel cluster oppure applica la configurazione al cluster esistente. L'applicazione della configurazione al cluster esistente potrebbe potenzialmente interrompere altri carichi di lavoro esistenti. Per saperne di più su questi due approcci, consulta Creare un file di configurazione runtime.

Dopo la migrazione, assicurati di interrompere l'applicazione di modifiche al campo registry.configs o potresti riscontrare problemi con containerd.

Assistenza

Se ancora non riesci a determinare l'origine delle chiamate API ritirate e i suggerimenti rimangono attivi, valuta il seguente passaggio successivo: