Risolvere i problemi di upgrade dei cluster

Se l'upgrade del piano di controllo o pool di nodi di Google Kubernetes Engine (GKE) non va a buon fine, si blocca o causa un comportamento imprevisto del workload, potrebbe essere necessario risolvere i problemi relativi al processo. Mantenere aggiornati il control plane e i node pool è essenziale per la sicurezza e le prestazioni e la risoluzione di eventuali problemi contribuisce a garantire la stabilità dell'ambiente.

Per risolvere i problemi di upgrade più comuni, un buon primo passo è monitorare la procedura di upgrade del cluster. Puoi quindi trovare consigli su come risolvere il problema:

Queste informazioni sono importanti per gli amministratori e gli operatori della piattaforma che vogliono diagnosticare le cause principali degli upgrade bloccati o non riusciti, gestire le norme di manutenzione e risolvere le incompatibilità di versione. Gli sviluppatori di applicazioni possono trovare indicazioni su come risolvere i problemi dei workload post-upgrade e capire come le configurazioni dei workload, ad esempio PodDisruptionBudgets, possono influire sulla durata dell'upgrade. Per maggiori informazioni sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti di Trusted Cloud by S3NS , consulta Ruoli utente e attività comuni di GKE.

Monitora il processo di upgrade del cluster

Per risolvere i problemi di upgrade in modo più efficace, inizia a capire cosa è successo durante il processo di upgrade. GKE fornisce diversi strumenti che ti offrono visibilità su questo processo.

Nella console Trusted Cloud , la dashboard di upgrade offre una visualizzazione a livello di progetto di tutti gli upgrade dei cluster in corso, una cronologia degli eventi recenti e avvisi relativi a potenziali blocchi, come esclusioni di manutenzione attive o ritiro di versioni imminenti. Per i controlli da riga di comando o automatizzati, puoi utilizzare il comando gcloud container operations list per ottenere lo stato di operazioni di upgrade specifiche. Per saperne di più, consulta Ottenere visibilità sugli upgrade dei cluster.

Per un'analisi più dettagliata, Cloud Logging è la tua fonte principale di informazioni. GKE registra informazioni dettagliate sui processi di upgrade del control plane e del pool di nodi in Cloud Logging. Sono inclusi log di controllo di alto livello che monitorano le principali operazioni di upgrade, nonché log più granulari come gli eventi Kubernetes e i log dei componenti dei nodi, che possono mostrare maggiori informazioni su errori specifici.

Le sezioni seguenti spiegano come eseguire query su questi log utilizzando Esplora log o gcloud CLI. Per ulteriori informazioni, vedi Controllare i log di upgrade.

Identificare l'operazione di upgrade con gli audit log

Se non sai quale operazione di upgrade non è riuscita, puoi utilizzare i log di controllo di GKE. Gli audit log monitorano le azioni amministrative e forniscono un record autorevole di quando è stato avviato un upgrade e del suo stato finale. Utilizza le seguenti query in Esplora log per trovare l'operazione pertinente.

Tipo di evento Query sul log
Upgrade automatico del control plane 
resource.type="gke_cluster"
protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.metadata.operationType="UPGRADE_MASTER"
resource.labels.cluster_name="CLUSTER_NAME"

Sostituisci CLUSTER_NAME con il nome del cluster che vuoi esaminare.

Questa query mostra la versione del control plane di destinazione e la versione precedente del control plane.
Upgrade manuale del control plane 
resource.type="gke_cluster"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.response.operationType="UPGRADE_MASTER"
resource.labels.cluster_name="CLUSTER_NAME"

 
Upgrade automatico del node pool (solo versione di destinazione) 
resource.type="gke_nodepool"
protoPayload.methodName="google.container.internal.ClusterManagerInternal.UpdateClusterInternal"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.metadata.operationType="UPGRADE_NODES"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.nodepool_name="NODEPOOL_NAME"

Sostituisci NODEPOOL_NAME con il nome del pool di nodi appartenente al cluster.
Upgrade manuale del node pool 
resource.type="gke_nodepool"
protoPayload.methodName="google.container.v1.ClusterManager.UpdateNodePool"
log_id("cloudaudit.googleapis.com/activity")
protoPayload.response.operationType="UPGRADE_NODES"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.nodepool_name="NODEPOOL_NAME"

Per trovare la versione precedente del pool di nodi, controlla i log dell'API Kubernetes:

resource.type="k8s_cluster"
resource.labels.cluster_name="CLUSTER_NAME"
protoPayload.methodName="nodes.patch"

Trovare messaggi di errore dettagliati nei log GKE

Dopo che il log di controllo mostra l'operazione non riuscita e quando, puoi cercare messaggi di errore più dettagliati dai componenti GKE nello stesso periodo di tempo. Questi log possono contenere i motivi specifici di un errore di upgrade, ad esempio un oggetto PodDisruptionBudget configurato in modo errato.

Ad esempio, dopo aver trovato un'operazione UPGRADE_NODES non riuscita nei log di controllo, puoi utilizzare il relativo timestamp per restringere la ricerca. In Esplora log, inserisci la seguente query e poi utilizza il selettore intervallo di tempo per concentrarti sul momento in cui si è verificato l'errore:

resource.type="k8s_node"
resource.labels.cluster_name="CLUSTER_NAME"
resource.labels.node_name="NODE_NAME"
severity=ERROR

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del tuo cluster.
  • NODE_NAME: il nome del nodo all'interno del cluster per cui vuoi verificare la presenza di errori.

Utilizzare gcloud CLI per visualizzare gli eventi di upgrade

Oltre a Esplora log, puoi utilizzare i comandi gcloud CLI per esaminare gli eventi di upgrade.

Per cercare gli upgrade del control plane, esegui questo comando:

gcloud container operations list --filter="TYPE=UPGRADE_MASTER"

L'output è simile al seguente:

NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_MASTER
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z

Questo output include i seguenti valori:

  • LOCATION: la regione o la zona di Compute Engine (ad esempio us-central1 o us-central1-a) per il cluster.
  • CLUSTER_NAME: il nome del tuo cluster.

Per cercare gli upgrade del pool di nodi, esegui questo comando:

gcloud container operations list --filter="TYPE=UPGRADE_NODES"

L'output è simile al seguente:

NAME: operation-1748588803271-cfd407a2-bfe7-4b9d-8686-9f1ff33a2a96
TYPE: UPGRADE_NODES
LOCATION: LOCATION
TARGET: CLUSTER_NAME
STATUS_MESSAGE:
STATUS: DONE
START_TIME: 2025-05-30T07:06:43.271089972Z
END_TIME: 2025-05-30T07:18:02.639579287Z

Esempio: utilizzare i log per risolvere i problemi relativi agli upgrade del control plane

Il seguente esempio mostra come utilizzare i log per risolvere i problemi relativi a un upgrade del control plane non riuscito:

  1. Nella console Trusted Cloud , vai alla pagina Esplora log.

    Vai a Esplora log

  2. Nel riquadro della query, filtra i log di upgrade del control plane inserendo la seguente query:

    resource.type="gke_cluster"
protoPayload.metadata.operationType=~"(UPDATE_CLUSTER|UPGRADE_MASTER)"
resource.labels.cluster_name="CLUSTER_NAME"

    Sostituisci CLUSTER_NAME con il nome del cluster che vuoi esaminare.

  3. Fai clic su Esegui query.

  4. Esamina l'output del log per trovare le seguenti informazioni:

  5. Verifica che l'upgrade sia iniziato: cerca eventi UPGRADE_MASTER recenti intorno all'ora in cui hai avviato l'upgrade. La presenza di questi eventi conferma che l'upgrade è stato attivato da te o da GKE.

    • Verifica le versioni: controlla i seguenti campi per confermare le versioni precedente e di destinazione:

      • protoPayload.metadata.previousMasterVersion: mostra la versione del control plane prima dell'upgrade.

      • protoPayload.metadata.currentMasterVersion: mostra la versione a cui GKE ha tentato di eseguire l'upgrade del control plane.

        Ad esempio, se intendevi eseguire l'upgrade alla versione 1.30.1-gke.1234, ma hai specificato per errore 1.30.2-gke.4321 (una versione più recente, potenzialmente incompatibile con i tuoi workload), la revisione di questi due campi evidenzierebbe questa discrepanza. In alternativa, se il campo currentMasterVersion continua a mostrare la versione precedente dopo un periodo prolungato, questo risultato indica che l'upgrade non è riuscito ad applicare la nuova versione.

    • Cerca errori: controlla la presenza di eventi UPGRADE_MASTER ripetuti o di altri messaggi di errore. Se il log delle operazioni si interrompe senza indicare il completamento o l'esito negativo, questo risultato indica un problema.

Dopo aver identificato un errore o un comportamento specifico dai log, puoi utilizzare queste informazioni per trovare la soluzione appropriata in questa guida.

Risolvi i problemi relativi agli upgrade pool di nodi che richiedono più tempo del solito

Se l'upgrade del pool di nodi richiede più tempo del previsto, prova le seguenti soluzioni:

  1. Controlla il valore di terminationGracePeriodSeconds nel manifest dei tuoi pod. Questo valore definisce il tempo massimo di attesa di Kubernetes per l'arresto normale di un pod. Un valore elevato (ad esempio, alcuni minuti) può estendere notevolmente la durata degli upgrade perché Kubernetes attende l'intero periodo per ogni pod. Se questo ritardo sta causando problemi, valuta la possibilità di ridurre il valore.

  2. Controlla gli oggetti PodDisruptionBudget. Quando un nodo viene svuotato, GKE attende al massimo un'ora per nodo per eseguire l'espulsione controllata dei relativi carichi di lavoro. Se l'oggetto PodDisruptionBudget è troppo restrittivo, può impedire che un'espulsione controllata vada a buon fine. In questo scenario, GKE utilizza l'intero periodo di tolleranza di un'ora per tentare di svuotare il nodo prima che scada il timeout e forzi l'avanzamento dell'upgrade. Questo ritardo, se ripetuto su più nodi, è una causa comune di un upgrade del cluster complessivo lento. Per verificare se un oggetto PodDisruptionBudget restrittivo è la causa dei tuoi upgrade lenti, utilizza Esplora log:

    1. Nella console Trusted Cloud , vai alla pagina Esplora log.

      Vai a Esplora log

    2. Nel riquadro della query, inserisci la seguente query:

      resource.type=("gke_cluster" OR "k8s_cluster")
resource.labels.cluster_name="CLUSTER_NAME"
protoPayload.response.message="Cannot evict pod as it would violate the pod's disruption budget."
log_id("cloudaudit.googleapis.com/activity")

    3. Fai clic su Esegui query.

    4. Rivedi l'output del log. Se l'oggetto PodDisruptionBudget è la causa del problema, l'output è simile al seguente:

      resourceName: "core/v1/namespaces/istio-system/pods/POD_NAME/eviction"

response: {
  @type: "core.k8s.io/v1.Status"
  apiVersion: "v1"
  code: 429
  details: {
  causes: [
    0: {
    message: "The disruption budget istio-egressgateway needs 1 healthy pods and has 1 currently"
    reason: "DisruptionBudget"
    }
  ]
  }
  kind: "Status"
  message: "Cannot evict pod as it would violate the pod's disruption budget."
  metadata: {
  }
  reason: "TooManyRequests"
  status: "Failure"
}

    5. Dopo aver confermato che la causa è un oggetto PodDisruptionBudget, elenca tutti gli oggetti PodDisruptionBudget e assicurati che le impostazioni siano appropriate:

      kubectl get pdb --all-namespaces

      L'output è simile al seguente:

      NAMESPACE        NAME          MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS   AGE
example-app-one  one_pdb       3               0                 1                     12d

      In questo esempio, PodDisruptionBudget denominato one_pdb richiede un minimo di tre pod disponibili. Poiché l'eliminazione di un pod durante l'upgrade lascerebbe disponibili solo due pod, l'azione viola il budget e causa l'interruzione dell'upgrade.

      Se l'oggetto PodDisruptionBudget funziona come previsto, non devi fare nulla. In caso contrario, valuta la possibilità di allentare le impostazioni di PodDisruptionBudget durante la finestra di upgrade.

  3. Controlla le affinità dei nodi. Le regole restrittive possono rallentare gli upgrade impedendo la riprogrammazione dei pod sui nodi disponibili se questi nodi non corrispondono alle etichette richieste. Questo problema è particolarmente problematico durante gli upgrade inattivi perché le affinità dei nodi possono limitare il numero di nodi che possono essere aggiornati contemporaneamente se i nodi con le etichette corrette non hanno capacità del cluster sufficiente per ospitare i nuovi pod.

  4. Controlla se utilizzi la strategia di upgrade di breve durata. GKE utilizza la strategia di upgrade di breve durata per i nodi flex-start e per i nodi che utilizzano solo il provisioning in coda sui cluster che eseguono GKE versione 1.32.2-gke.1652000 o successive. Se utilizzi questa strategia di upgrade, l'operazione può richiedere fino a sette giorni.

  5. Controlla se utilizzi pod di durata estesa (disponibili per i cluster Autopilot). Durante un upgrade, GKE deve svuotare tutti i pod di un nodo prima che il processo possa essere completato. Tuttavia, durante un upgrade avviato da GKE, GKE non esegue l'espulsione dei pod di lunga durata fino a sette giorni. Questa protezione impedisce lo svuotamento del nodo. GKE termina forzatamente il pod solo al termine di questo periodo e questo ritardo significativo di più giorni per un singolo nodo può ritardare ulteriori upgrade dei nodi nel cluster Autopilot.

  6. I Persistent Volume collegati possono causare un processo di upgrade più lungo del solito, a causa del tempo necessario per gestire il ciclo di vita di questi volumi.

  7. Controlla lo stato dell'upgrade automatico del cluster. Se il motivo è SYSTEM_CONFIG, gli upgrade automatici sono temporaneamente in pausa per motivi tecnici o aziendali. Se visualizzi questo motivo, ti consigliamo di non eseguire un upgrade manuale a meno che non sia necessario.

Risolvi i problemi relativi agli upgrade incompleti dei pool di nodi

A volte, GKE non riesce a completare l'upgrade di un pool di nodi, lasciandolo parzialmente aggiornato. Esistono diversi motivi per cui gli upgrade non vengono completati:

  • L'upgrade è stato annullato manualmente.
  • L'upgrade non è riuscito a causa di un problema, ad esempio la mancata registrazione di nuovi nodi, l'esaurimento degli indirizzi IP o quote di risorse insufficienti.
  • GKE ha messo in pausa l'upgrade. Questa pausa può verificarsi, ad esempio, per impedire un upgrade a una versione con problemi noti o durante determinati periodi di manutenzione avviati da Google.
  • Se utilizzi gli upgrade automatici, un periodo di manutenzione è terminato prima che l'upgrade potesse essere completato. In alternativa, è iniziato un periodo di esclusione della manutenzione prima che l'upgrade potesse essere completato. Per maggiori informazioni, vedi Periodo di manutenzione che impedisce il completamento dell'aggiornamento del nodo.

Quando un pool di nodi viene aggiornato parzialmente, i nodi vengono eseguiti su versioni diverse. Per risolvere questo problema e verificare che tutti i nodi del pool di nodi vengano eseguiti sulla stessa versione, puoi riprendere l'upgrade o eseguire il rollback dell'upgrade.

Tuttavia, la strategia di upgrade di picco e la strategia di upgrade blu/verde interagiscono in modo diverso con i periodi di manutenzione:

  • Upgrade di picco: l'operazione di upgrade viene sospesa se viene eseguita oltre il periodo di manutenzione. L'upgrade viene ripreso automaticamente durante il prossimo periodo di manutenzione pianificato.
  • Upgrade blu/verde: l'operazione di upgrade continua fino al completamento, anche se supera la periodo di manutenzione. Gli upgrade blu/verde offrono un controllo granulare sul ritmo di upgrade con funzionalità come i tempi di attesa per batch e node pool e il pool di nodi aggiuntivo contribuisce a garantire che i carichi di lavoro rimangano operativi.

Risolvere i problemi relativi a comportamenti imprevisti dell'upgrade automatico

A volte, gli upgrade automatici dei cluster non avvengono nel modo in cui potresti aspettarti. Le seguenti sezioni ti aiutano a risolvere i seguenti problemi:

L'upgrade dei cluster non riesce quando l'upgrade automatico dei nodi è abilitato

Se non hai disattivato l'upgrade automatico dei nodi, ma non viene eseguito, prova le seguenti soluzioni:

  1. Se utilizzi un canale di rilascio, verifica che gli upgrade automatici dei nodi non siano bloccati. Per i cluster registrati in un canale di rilascio, maintenancePolicy è il modo principale per controllare gli upgrade automatici. Può impedire l'avvio di un upgrade o interromperne uno già in corso. Un'esclusione dalla manutenzione attiva può bloccare completamente un upgrade e la tempistica di un periodo di manutenzione può causare un'interruzione. Controlla le maintenancePolicy per determinare se una di queste impostazioni è la causa del problema:

    gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID  \
    --location LOCATION

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del cluster del pool di nodi da descrivere.
    • PROJECT_ID: l'ID progetto del cluster.
    • LOCATION: la regione o la zona di Compute Engine (ad esempio us-central1 o us-central1-a) per il cluster.

    L'output è simile al seguente:

    …
maintenancePolicy:
  maintenanceExclusions:
  - exclusionName: critical-event-q4-2025
    startTime: '2025-12-20T00:00:00Z'
    endTime: '2026-01-05T00:00:00Z'
    scope:
      noUpgrades: true # This exclusion blocks all upgrades
  window:
    dailyMaintenanceWindow:
      startTime: 03:00 # Daily window at 03:00 UTC
…

    Nell'output, esamina la sezione maintenancePolicy per le seguenti due condizioni:

    • Per verificare se un upgrade è bloccato, cerca un maintenanceExclusion attivo con un ambito NO_MINOR_OR_NODE_UPGRADES. Questa impostazione in genere impedisce a GKE di avviare un nuovo upgrade.
    • Per verificare se un upgrade è stato interrotto, controlla la pianificazione del tuo dailyMaintenanceWindow o maintenanceExclusions. Se un upgrade viene eseguito oltre la finestra pianificata, GKE lo mette in pausa, con conseguente upgrade parziale. Per saperne di più sugli upgrade parziali, consulta la sezione Risolvere i problemi relativi agli upgrade incompleti.

    Per risolvere questi problemi, puoi attendere la fine di un'esclusione, rimuoverla o modificare i periodi di manutenzione per consentire il completamento degli upgrade.

  2. Se non utilizzi un canale di rilascio, verifica che l'upgrade automatico sia ancora abilitato per ilpool di nodil:

    gcloud container node-pools describe NODE_POOL_NAME \
    --cluster CLUSTER_NAME \
    --location LOCATION

    Sostituisci NODE_POOL_NAME con il nome del pool di nodi da descrivere.

    Se gli upgrade automatici del pool di nodi sono abilitati per questo pool di nodi, l'output nel campo autoUpgrade è il seguente:

    management:
  autoUpgrade: true

    Se autoUpgrade è impostato su false o il campo non è presente, attiva gli upgrade automatici.

  3. L'upgrade potrebbe non essere stato implementato nella regione o nella zona in cui si trova il cluster, anche se è stato menzionato nelle note di rilascio. Gli upgrade di GKE vengono implementati progressivamente in più giorni (in genere quattro o più). Una volta che l'upgrade raggiunge la tua regione o zona, l'upgrade inizia solo durante i periodi di manutenzione approvati. Ad esempio, un rollout potrebbe raggiungere la zona del cluster il primo giorno del rollout, ma la successiva periodo di manutenzionene del cluster non è prevista prima del settimo giorno. In questo scenario, GKE non eseguirà l'upgrade del cluster fino al settimo giorno. Per saperne di più, consulta la programmazione delle release di GKE.

I cluster vengono aggiornati automaticamente quando l'upgrade automatico non è abilitato

Per contribuire a mantenere l'affidabilità, la disponibilità, la sicurezza e le prestazioni del tuo ambiente GKE, GKE potrebbe eseguire automaticamente l'upgrade dei tuoi cluster, anche se non utilizzi gli upgrade automatici.

GKE potrebbe ignorare i periodi di manutenzione, le esclusioni o gli upgrade automatici dei pool di nodi disabilitati per eseguire gli upgrade necessari per diversi motivi critici, ad esempio:

  • Cluster i cui control plane eseguono una versione GKE che ha raggiunto la data di fine del supporto. Per verificare che il tuo cluster si stia avvicinando alla data di fine del supporto, consulta Programma stimato per i canali di rilascio.
  • Nodi all'interno di un cluster che eseguono una versione GKE che ha raggiunto la data di fine del supporto.
  • Cluster in stato di esecuzione, ma che non mostrano attività per un periodo prolungato. Ad esempio, GKE potrebbe considerare abbandonato un cluster senza chiamate API, senza traffico di rete e senza utilizzo attivo di subnet.
  • Cluster che mostrano un'instabilità persistente che si ripete negli stati operativi. Ad esempio, stati che passano da in esecuzione a degradato, riparazione o sospensione e di nuovo a in esecuzione senza una risoluzione.

Se noti un upgrade automatico imprevisto e hai dubbi sull'effetto che questo upgrade potrebbe avere sul tuo cluster, contatta l'assistenza clienti Google Cloud per ricevere assistenza.

Risolvere i problemi relativi agli upgrade non riusciti

Quando l'upgrade non va a buon fine, GKE genera messaggi di errore. Le seguenti sezioni spiegano le cause e le soluzioni per i seguenti errori:

Errore: kube-apiserver non è integro

A volte, potresti visualizzare il seguente messaggio di errore quando avvii un upgrade manuale del control plane della versione GKE del tuo cluster:

FAILED: All cluster resources were brought up, but: component
"KubeApiserverReady" from endpoint "readyz of kube apiserver is not successful"
is unhealthy.

Questo messaggio viene visualizzato in gcloud CLI e nelle voci di log dei tipi di risorse gke_cluster e gke_nodepool.

Questo problema si verifica quando alcuni webhook di controllo dell'ammissione implementati dall'utente impediscono ai componenti di sistema di creare i ruoli RBAC permissivi necessari per funzionare correttamente.

Durante un upgrade del control plane, GKE ricrea il componente del server API Kubernetes (kube-apiserver). Se un webhook blocca il ruolo RBAC per il componente API server, l'API server non si avvia e l'upgrade del cluster non viene completato. Anche se un webhook funziona correttamente, può causare l'upgrade del cluster non riuscito perché il control plane appena creato potrebbe non essere in grado di raggiungere il webhook.

Kubernetes riconcilia automaticamente i ruoli RBAC di sistema predefiniti con i criteri predefiniti nell'ultima versione secondaria. A volte, le norme predefinite per i ruoli di sistema cambiano nelle nuove versioni di Kubernetes.

Per eseguire questa riconciliazione, GKE crea o aggiorna i ClusterRole e i ClusterRoleBinding nel cluster. Se hai un webhook che intercetta e rifiuta le richieste di creazione o aggiornamento a causa dell'ambito delle autorizzazioni utilizzate dalle norme RBAC predefinite, il server API non può funzionare nella nuova versione secondaria.

Per identificare il webhook non riuscito, controlla i log di controllo di GKE per le chiamate RBAC con le seguenti informazioni:

protoPayload.resourceName="RBAC_RULE"
protoPayload.authenticationInfo.principalEmail="system:apiserver"

In questo output, RBAC_RULE è il nome completo del ruolo RBAC, ad esempio rbac.authorization.k8s.io/v1/clusterroles/system:controller:horizontal-pod-autoscaler.

Il nome del webhook non riuscito viene visualizzato nel log nel seguente formato:

admission webhook WEBHOOK_NAME denied the request

Per risolvere il problema, prova le seguenti soluzioni:

  1. Esamina i tuoi ClusterRole per assicurarti che non siano eccessivamente restrittivi. I tuoi criteri non devono bloccare le richieste di GKE per creare o aggiornare i ClusterRole con il prefisso system: predefinito.
  2. Modifica il webhook in modo che non intercetti le richieste di creazione e aggiornamento dei ruoli RBAC di sistema.
  3. Disattiva il webhook.

Errore: DeployPatch non riuscito

A volte, l'operazione di upgrade del cluster non va a buon fine e viene visualizzato il seguente errore:

DeployPatch failed

Questo errore può verificarsi se il control plane Kubernetes rimane in stato non integro per più di 20 minuti.

Questo errore è spesso temporaneo perché il piano di controllo ripete l'operazione finché non va a buon fine. Se l'upgrade continua a non riuscire con questo errore, contatta l'assistenza clienti Google Cloud.

Risolvere i problemi dopo un upgrade completato

Se riscontri un comportamento imprevisto dopo il completamento dell'upgrade, le seguenti sezioni offrono indicazioni per la risoluzione dei problemi comuni seguenti:

Comportamento imprevisto dovuto a modifiche che provocano errori

Se l'upgrade è stato completato correttamente, ma noti un comportamento imprevisto dopo un upgrade, consulta le note di rilascio di GKE per informazioni su bug e modifiche che causano interruzioni correlate alla versione a cui è stato eseguito l'upgrade del cluster.

Carichi di lavoro eliminati dopo l'upgrade del cluster standard

I tuoi workload potrebbero essere a rischio di espulsione dopo un upgrade del cluster se sono vere tutte le seguenti condizioni:

  • I workload di sistema richiedono più spazio quando il control plane del cluster esegue la nuova versione di GKE.
  • I nodi esistenti non dispongono di risorse sufficienti per eseguire i nuovi carichi di lavoro di sistema e quelli esistenti.
  • Il gestore della scalabilità automatica dei cluster è disabilitato per il cluster.

Per risolvere il problema, prova le seguenti soluzioni:

  1. Abilita la scalabilità automatica per i pool di nodi esistenti.
  2. Abilita provisioning automatico dei nodi.
  3. Crea un nuovo node pool.
  4. Aumenta le dimensioni di un node pool esistente.

I pod bloccati nello stato Pending dopo la configurazione di Node Allocatable

Se hai configurato Node Allocatable, a volte l'upgrade di una versione del nodo può causare il blocco dei pod che avevano uno stato Running in uno stato Pending. Questa modifica in genere si verifica perché il nodo aggiornato consuma risorse di sistema leggermente diverse o perché i pod riprogrammati devono ora rientrare nei limiti di allocazione dei nodi sui nodi nuovi o modificati, potenzialmente in condizioni più restrittive.

Se lo stato dei tuoi pod è Pending dopo un upgrade, prova le seguenti soluzioni:

  1. Verifica che le richieste di CPU e memoria per i pod non superino il loro utilizzo di picco. Poiché GKE riserva CPU e memoria per l'overhead, i pod non possono richiedere queste risorse. I pod che richiedono più CPU o memoria di quella che utilizzano impediscono ad altri pod di richiedere queste risorse e potrebbero lasciare il cluster sottoutilizzato. Per saperne di più, consulta la sezione Come vengono pianificati i pod con richieste di risorse nella documentazione di Kubernetes.
  2. Valuta la possibilità di aumentare le dimensioni del cluster.
  3. Per verificare se l'upgrade è la causa di questo problema, ripristina la versione precedente eseguendo il downgrade dei tuoi node pool.
  4. Configura il cluster per inviare le metriche dello scheduler Kubernetes a Cloud Monitoring e visualizzare le metriche dello scheduler. Monitorando queste metriche, puoi determinare se sono disponibili risorse sufficienti per l'esecuzione dei pod.

Risolvere i problemi di versione e compatibilità

Il mantenimento di versioni supportate e compatibili per tutti i componenti del cluster è essenziale per la stabilità e le prestazioni. Le sezioni seguenti forniscono indicazioni su come identificare e risolvere i problemi di controllo delle versioni e compatibilità che possono influire sul processo di upgrade.

Verifica l'incompatibilità tra la versione del piano di controllo e quella del nodo

La differenza di versione tra il control plane e i nodi può causare instabilità del cluster. I criteri di asimmetria delle versioni di GKE indicano che un control plane è compatibile solo con i nodi fino a due versioni secondarie precedenti. Ad esempio, un control plane 1.19 funziona con i nodi 1.19, 1.18 e 1.17.

Se i tuoi nodi non rientrano in questo intervallo supportato, rischi di riscontrare problemi di compatibilità critici. Questi problemi sono spesso correlati alle API. Ad esempio, un workload su un nodo precedente potrebbe utilizzare una versione dell'API che è stata ritirata o rimossa nel control plane più recente. Questa incompatibilità può anche causare errori più gravi, come un percorso di rete interrotto che impedisce ai nodi di registrarsi al cluster se un carico di lavoro incompatibile interrompe la comunicazione.

Periodicamente, il team GKE esegue gli upgrade del control plane del cluster per tuo conto. I control plane vengono aggiornati a versioni stabili più recenti di Kubernetes. Per garantire che i nodi rimangano compatibili con il piano di controllo aggiornato, devono essere mantenuti aggiornati. Per impostazione predefinita, GKE gestisce questo upgrade perché i nodi di un cluster hanno l'upgrade automatico abilitato e ti consigliamo di non disabilitarlo. Se l'upgrade automatico è disattivato per i nodi di un cluster e non esegui l'upgrade manuale, il control plane alla fine diventa incompatibile con i nodi.

Per verificare se le versioni del control plane e dei nodi sono incompatibili, controlla la versione di Kubernetes in esecuzione sul control plane e sui node pool del cluster:

gcloud container clusters describe CLUSTER_NAME \
    --project PROJECT_ID  \
    --location LOCATION

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster del pool di nodi da descrivere.
  • PROJECT_ID: l'ID progetto del cluster.
  • LOCATION: la regione o la zona di Compute Engine (ad esempio us-central1 o us-central1-a) per il cluster.

L'output è simile al seguente:

…
currentMasterVersion: 1.32.3-gke.1785003
…
currentNodeVersion: 1.26.15-gke.1090000
…

In questo esempio, la versione del control plane e quella del pool di nodi sono incompatibili.

Per risolvere il problema, esegui manualmente l'upgrade della versione del node pool a una versione compatibile con il control plane.

Se ti preoccupa che la procedura di upgrade possa causare interruzioni ai carichi di lavoro in esecuzione sui nodi interessati, completa i seguenti passaggi per eseguire la migrazione dei carichi di lavoro a un nuovo pool di nodi:

  1. Crea un nuovo node pool con una versione compatibile.
  2. Contrassegna i nodi del pool di nodi esistente come non pianificabili.
  3. (Facoltativo) Aggiorna i carichi di lavoro in esecuzione sul pool di nodi esistente per aggiungere un nodeSelector per l'etichetta cloud.google.com/gke-nodepool:NEW_NODE_POOL_NAME. Sostituisci NEW_NODE_POOL_NAME con il nome del nuovo pool di nodi. Questa azione garantisce che GKE posizioni questi carichi di lavoro sui nodi del nuovo pool di nodi.
  4. Svuota il pool di nodi esistente.
  5. Verifica che i workload vengano eseguiti correttamente nel nuovo pool di nodi. Se lo sono, puoi eliminare il vecchio pool di nodi. Se noti interruzioni dei workload, riprogramma i workload sui nodi esistenti rimuovendo il contrassegno dai nodi del pool di nodi esistente e svuotando i nuovi nodi.

L'utilizzo della CPU del nodo è superiore al previsto

Potresti riscontrare un problema per cui alcuni nodi utilizzano più CPU del previsto dai pod in esecuzione.

Questo problema può verificarsi se utilizzi gli upgrade manuali e i tuoi cluster o nodi non sono stati aggiornati per eseguire una versione supportata. Consulta le note di rilascio per assicurarti che le versioni che utilizzi siano disponibili e supportate.

Passaggi successivi