Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Upgrade di un cluster

L'upgrade della workstation di amministrazione, dei cluster utente e dei cluster di amministrazione per Google Distributed Cloud (solo software) per VMware consente di adottare release di Kubernetes, patch di sicurezza e funzionalità della piattaforma supportate. Questo documento illustra l'upgrade simultaneo del control plane e dei node pool di un cluster utente. Per eseguire l'upgrade separatamente, consulta Esegui l'upgrade dei node pool.

Prima di iniziare, consulta la panoramica dell'upgrade per la selezione degli strumenti e l'ordine di upgrade, le regole per la versione di upgrade per i requisiti del sistema operativo e della deviazione della versione specifici della release e le best practice per l'upgrade per gli elenchi di controllo pre-upgrade.

Prima di iniziare

Prima di iniziare l'upgrade, assicurati di avere un backup aggiornato dei cluster di amministrazione e utente. Per saperne di più, consulta Esegui il backup del cluster utente e di amministrazione.
Diagnostica il tuo cluster prima di eseguire l'upgrade. Esegui gkectl diagnose cluster per assicurarti che il cluster di amministrazione sia integro e risolvi eventuali problemi prima di iniziare l'upgrade.
Assicurati che gkectl e i cluster siano della versione appropriata per un upgrade e di aver scaricato il bundle appropriato. La variazione di versione tra i cluster di amministrazione e utente dipende dalla versione di Google Distributed Cloud. Per assicurarti di poter eseguire l'upgrade del cluster di amministrazione, consulta le regole di versione per la tua versione.
Assicurati che il campo bundlepath nel file di configurazione del cluster di amministrazione corrisponda al percorso del bundle di cui vuoi eseguire l'upgrade.

Se apporti altre modifiche ai campi nel file di configurazione del cluster di amministrazione, queste modifiche vengono ignorate durante l'upgrade. Per rendere effettive queste modifiche, devi prima eseguire l'upgrade del cluster, quindi eseguire un comando update cluster con le modifiche al file di configurazione per apportare altre modifiche al cluster.

Esamina le regole firewall

Nella versione 1.29 e successive, i controlli preflight lato server sono abilitati per impostazione predefinita. I controlli preflight lato server richiedono regole firewall aggiuntive. In Regole firewall per i cluster di amministrazione, cerca "Controlli preflight" e assicurati che tutte le regole firewall richieste siano configurate.

Con i controlli preflight lato server, quando esegui l'upgrade di un cluster utente utilizzando gkectl, i controlli preflight vengono eseguiti sul cluster di amministrazione anziché localmente sulla workstation di amministrazione. I controlli preflight lato server vengono eseguiti anche sul cluster di amministrazione quando utilizzi la console Google Cloud , Google Cloud CLI o Terraform per eseguire l'upgrade di un cluster.

Quando esegui l'upgrade di un cluster di amministrazione, Google Distributed Cloud esegue il deployment di un cluster Kubernetes in Docker (kind) per ospitare temporaneamente i controller Kubernetes necessari per eseguire l'upgrade del cluster di amministrazione. Questo cluster temporaneo è chiamato cluster di bootstrap. I controlli preflight lato server vengono eseguiti sul cluster di bootstrap quando esegui l'upgrade di un cluster di amministrazione.

Abilita `stackdriver`

Se hai creato il cluster utente utilizzando gkectl, prima di eseguire l'upgrade assicurati che la sezione stackdriver nel file di configurazione del cluster utente sia compilata, in modo da abilitare stackdriver (necessario per il logging e il monitoraggio). Se stackdriver non è abilitato, compila la sezione stackdriver nel file di configurazione del cluster utente e aggiorna il cluster prima di eseguire l'upgrade.

Se hai creato il cluster utilizzando Terraform, la console Google Cloud o gcloud CLI, stackdriver viene attivato automaticamente.

Abilita Dataplane V2

A partire dalla versione 1.31, Dataplane V2 deve essere abilitato su tutti i cluster utente. Prima di eseguire l'upgrade di un cluster utente alla versione 1.31, segui questi passaggi. Se hai dubbi sulla rimozione temporanea della specifica NetworkPolicy, contatta l'Assistenza Google.

Imposta enableDataplaneV2 su true nel file di configurazione del cluster utente.

Se il cluster utilizza un NetworkPolicy, rimuovi temporaneamente la sua specifica dal cluster, come segue:

Controlla se al tuo cluster è applicato un NetworkPolicy non di sistema:
```
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get networkpolicy -A -o wide \
    --field-selector metadata.namespace!=kube-system
```
Sostituisci USER_CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster utente.

Se esistono solo policy kube-system predefinite, il comando restituisce No resources found.
Se il comando precedente elenca oggetti NetworkPolicy, salva ogni specifica NetworkPolicy in un file in modo da poterla riapplicare dopo l'upgrade del cluster:
```
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG get networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE -o yaml > NETWORK_POLICY_NAME.yaml
```
Sostituisci quanto segue:
- NETWORK_POLICY_NAME: il nome della NetworkPolicy che stai salvando.
- NETWORK_POLICY_NAMESPACE: lo spazio dei nomi di NetworkPolicy.

Elimina NetworkPolicy utilizzando il seguente comando:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG delete networkpolicy NETWORK_POLICY_NAME -n NETWORK_POLICY_NAMESPACE

Continua con l'upgrade.
Al termine dell'upgrade, se hai rimosso le specifiche NetworkPolicy non di sistema, applicale nuovamente con questo comando:
```
kubectl --kubeconfig USER_CLUSTER_KUBECONFIG apply -f NETWORK_POLICY_NAME.yaml
```

Requisiti delle API di Google e di IAM

Per eseguire l'upgrade di un cluster alla versione 1.28 e successive, devi attivare kubernetesmetadata.googleapis.com e concedere il ruolo IAM kubernetesmetadata.publisher al service account di logging-monitoring. Queste modifiche sono necessarie per utilizzare Cloud Monitoring.

Attiva kubernetesmetadata.googleapis.com:
```
gcloud services enable --project PROJECT_ID  \
    kubernetesmetadata.googleapis.com
```
Sostituisci PROJECT_ID con l'ID del progetto host del parco risorse di cui il cluster utente è membro. Questo è il progetto che hai specificato al momento della creazione del cluster. Se hai creato il cluster utilizzando gkectl, questo è l'ID progetto nel campo gkeConnect.projectID nel file di configurazione del cluster.
Se la tua organizzazione ha configurato una lista consentita che consente al traffico proveniente dalle API di Google e da altri indirizzi di passare attraverso il server proxy, aggiungi kubernetesmetadata.googleapis.com alla lista consentita.
Concedi il ruolo kubernetesmetadata.publisher al account di servizio di logging-monitoring:
```
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:SERVICE_ACCOUNT_EMAIL" \
    --role "roles/kubernetesmetadata.publisher"
```
Sostituisci SERVICE_ACCOUNT_EMAIL con l'indirizzo email del tuo account di servizio di logging-monitoring.

Funzionalità legacy bloccate sugli upgrade

Le seguenti funzionalità legacy sono bloccate durante l'upgrade del cluster alla versione 1.32:

Dataplane V1 (Calico)
Configurazione del bilanciatore del carico F5 Big IP integrato
Cluster di amministrazione non ad alta disponibilità
Cluster utente Kubeception
Bilanciatore del carico Seesaw

Devi eseguire la migrazione dei cluster alle funzionalità consigliate prima di eseguire l'upgrade alla versione 1.32.

Requisiti IAM per l'upgrade dei cluster utente

Salta questa sezione se prevedi di utilizzare gkectl per l'upgrade del cluster utente.

Se vuoi utilizzare la console Google Cloud , Google Cloud CLI o Terraform per eseguire l'upgrade di un cluster utente e non sei un Project Owner, devi disporre del ruolo Identity and Access Management roles/gkeonprem.admin nel progetto Google Cloud in cui è stato creato il cluster. Per i dettagli sulle autorizzazioni incluse in questo ruolo, consulta Ruoli GKE on-prem nella documentazione di IAM.

Per utilizzare la console per eseguire l'upgrade del cluster, devi disporre almeno anche di quanto segue:

roles/container.viewer. Questo ruolo consente agli utenti di visualizzare la pagina dei cluster GKE e altre risorse container nella console. Per i dettagli sulle autorizzazioni incluse in questo ruolo o per concedere un ruolo con autorizzazioni di lettura/scrittura, consulta Ruoli di Kubernetes Engine nella documentazione di IAM.
roles/gkehub.viewer. Questo ruolo consente agli utenti di visualizzare i cluster nella console. Per i dettagli sulle autorizzazioni incluse in questo ruolo o per concedere un ruolo con autorizzazioni di lettura/scrittura, consulta Ruoli GKE Hub nella documentazione IAM.

Limitazioni relative ai cluster avanzati

Tieni presenti le seguenti limitazioni se hai attivato i cluster avanzati:

Quando esegui l'upgrade dei cluster dalla versione 1.32 alla 1.33, devi utilizzare gkectl. I client dell'API GKE On-Prem (la console, gcloud CLI e Terraform) non sono supportati per questo percorso di upgrade specifico, ma sono supportati per gli upgrade a partire dalla versione 1.33.
Per i cluster avanzati nella versione 1.31 in anteprima o quando converti un cluster di amministrazione non avanzato in un cluster di amministrazione avanzato, devi eseguire un upgrade sincrono. Nella versione 1.32 e successive, puoi utilizzare il flag --async con i comandi gkectl upgrade admin e gkectl upgrade cluster per i cluster Advanced esistenti.

Apporta modifiche alla configurazione prima o dopo un upgrade

Se devi apportare modifiche alla configurazione dei cluster, esegui l'aggiornamento del cluster prima o dopo l'upgrade. L'unica modifica alla configurazione del cluster per un upgrade deve essere la versione. A seconda della versione e del tipo di cluster, altre modifiche alla configurazione vengono ignorate senza preavviso o causano l'esito negativo dell'upgrade. Per saperne di più, consulta Rimuovi le modifiche non supportate per sbloccare l'upgrade.

Controlla le versioni disponibili per gli upgrade del cluster

Esegui questo comando per visualizzare le versioni disponibili per l'upgrade:

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Sostituisci ADMIN_CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster di amministrazione.

L'output mostra la versione attuale e le versioni disponibili per l'upgrade.

Se prevedi di utilizzare la console, gcloud CLI o Terraform per l'upgrade, sono necessari circa 7-14 giorni dopo una release affinché la versione sia disponibile nell'API GKE On-Prem in tutte le regioni Google Cloud . La console elenca solo le versioni disponibili per l'upgrade del cluster utente. I passaggi per eseguire l'upgrade di un cluster utente utilizzando gcloud CLI o Terraform includono un passaggio per eseguire gcloud container vmware clusters query-version-config per ottenere le versioni disponibili per l'upgrade.

Esegui l'upgrade della workstation di amministrazione

La modalità di upgrade della workstation di amministrazione dipende da come l'hai creata: gkeadm o gestita dall'utente.

gkeadm

Individua i file richiesti

Prima di creare la workstation di amministrazione, hai compilato un file di configurazione della workstation di amministrazione generato da gkeadm create config. Il nome predefinito di questo file è admin-ws-config.yaml.

Inoltre, la tua workstation ha un file di informazioni. Il nome predefinito di questo file corrisponde al nome della tua workstation di amministrazione.

Individua il file di configurazione della workstation di amministrazione e il file di informazioni. Ti serviranno per eseguire i passaggi di upgrade. Se questi file si trovano nella directory attuale e hanno i nomi predefiniti, non dovrai specificarli quando esegui i comandi di upgrade. Se questi file si trovano in un'altra directory o se hai modificato i nomi file, specificali utilizzando i flag --config e --info-file.

Se il file di informazioni di output non è presente, puoi ricrearlo. Consulta Ricrea un file di informazioni se mancante.

Esegui l'upgrade

Esegui l'upgrade della workstation di amministrazione:

Controlla il campo adminWorkstation.diskGB nel file di configurazione della workstation di amministrazione e assicurati che la dimensione specificata sia almeno 100, ad esempio:
```
adminWorkstation:
  diskGB: 100
```
Quando esegui l'upgrade alla versione 1.28 e successive, sono necessari 100 GB e l'upgrade del cluster non va a buon fine se la workstation di amministrazione non dispone di spazio su disco sufficiente.
Dal jump server, scarica gkeadm:
```
gkeadm upgrade gkeadm --target-version TARGET_VERSION
```
Sostituisci TARGET_VERSION con la versione di cui stai eseguendo l'upgrade. Devi specificare un numero di versione completo nel formato X.Y.Z-gke.N. Per un elenco delle versioni di Google Distributed Cloud, consulta Controllo delle versioni.

Esegui l'upgrade della workstation di amministrazione:

gkeadm upgrade admin-workstation --config AW_CONFIG_FILE \
  --info-file INFO_FILE

Sostituisci quanto segue:

AW_CONFIG_FILE: il percorso del file di configurazione della workstation di amministrazione. Puoi omettere questo flag se il file si trova nella directory attuale ed è denominato admin-ws-config.yaml.
INFO_FILE: il percorso del file delle informazioni. Puoi omettere questo flag se il file si trova nella directory attuale. Il nome predefinito di questo file corrisponde al nome della tua workstation di amministrazione.

Gestito dall'utente

Nella workstation di amministrazione, vai alla directory in cui vuoi installare una nuova versione di gkectl.

Scarica gkectl:
```
 gcloud storage cp gs://gke-on-prem-release/gkectl/TARGET_VERSION/gkectl ./
 chmod +x gkectl
 
```
Sostituisci TARGET_VERSION con la versione di cui stai eseguendo l'upgrade. Devi specificare un numero di versione completo nel formato X.Y.Z-gke.N. Per un elenco delle versioni di Google Distributed Cloud, consulta Controllo delle versioni.
Scarica il bundle Google Distributed Cloud. Assicurati che la versione corrisponda a quella che hai utilizzato per scaricare gkectl:
```
 gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz ./
 
```

Esegui l'upgrade del cluster di amministrazione

I passaggi per eseguire l'upgrade del cluster di amministrazione variano leggermente a seconda della versione secondaria di cui stai eseguendo l'upgrade (la versione di destinazione):

1.31 e successive

Se la versione di destinazione è 1.31 o successiva, prima di eseguire l'upgrade dei cluster utente alla versione secondaria successiva, devi eseguire l'upgrade del cluster di amministrazione. Nella versione 1.31 e successive, la versione del cluster di amministrazione, inclusa la versione patch, deve essere maggiore o uguale alla versione del cluster utente. Ad esempio, se un cluster di amministrazione è alla versione 1.31.1, la versione più recente a cui è possibile eseguire l'upgrade del cluster utente è la 1.31.1.

Esegui questo comando sulla workstation di amministrazione per importare le immagini sistema operativo in vSphere:

gkectl prepare \
    --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Sostituisci ADMIN_CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster di amministrazione.

1.30 e versioni precedenti

Se la versione di destinazione è 1.30 o precedente, devi eseguire l'upgrade di tutti i cluster utente prima di eseguire l'upgrade del cluster di amministrazione. La versione secondaria del cluster di amministrazione deve essere inferiore o uguale alla versione secondaria del cluster utente. La versione della patch non è importante. Ad esempio, se un cluster utente è alla versione 1.30.1, è possibile eseguire l'upgrade del cluster di amministrazione a una versione patch successiva, ad esempio 1.30.3.

Esegui l'upgrade

gkectl

Esegui i passaggi descritti in questa sezione sulla tua workstation di amministrazione. Esistono due varianti del comando gkectl upgrade admin:

Asincrono:
con la variante asincrona, il comando avvia l'upgrade e poi viene completato. Non è necessario osservare l'output del comando per l'intera durata dell'upgrade. Puoi invece controllare periodicamente l'avanzamento dell'upgrade eseguendo gkectl list admin e gkectl describe admin. Per utilizzare la variante asincrona, includi il flag --async nel comando.

Requisiti per l'upgrade asincrono:
- Supportato solo per i cluster di amministrazione ad alta affidabilità con versione 1.29 o successive.
- Tutti i cluster utente devono avere Controlplane V2 abilitato.
- Versione 1.31: non supportata sui cluster avanzati.
- Versione 1.32 e successive: disponibile sui cluster avanzati.
Sincrono:
Con la variante sincrona, il comando gkectl upgrade admin genera messaggi di stato nella workstation di amministrazione man mano che l'upgrade procede.

Upgrade asincrono

Nella workstation di amministrazione, esegui la diagnostica del cluster prima di eseguire l'upgrade:
```
gkectl diagnose cluster \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Se il comando segnala errori o avvisi, consulta Diagnostica i problemi del cluster e risolvili prima di procedere.
Avvia un upgrade asincrono:
```
gkectl upgrade admin \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config ADMIN_CLUSTER_CONFIG_FILE \
   --async
```
Sostituisci quanto segue:
- ADMIN_CLUSTER_KUBECONFIG: il percorso del file kubeconfig del cluster di amministrazione.
- ADMIN_CLUSTER_CONFIG_FILE: il percorso del file di configurazione del cluster di amministrazione.
Il comando precedente viene completato e puoi continuare a utilizzare la tua workstation di amministrazione mentre l'upgrade è in corso.
Per visualizzare lo stato dell'upgrade:
```
gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
L'output mostra un valore per il cluster STATE. Se il cluster è ancora in fase di upgrade, il valore di STATE è UPGRADING. Ad esempio:
```
NAME              STATE         AGE    VERSION
gke-admin-test    UPGRADING     9h     1.36.100-gke.144
```
I valori possibili per STATE sono RUNNING, UPGRADING, RECONCILING, ERROR e UNKNOWN.

Per maggiori dettagli sull'avanzamento dell'upgrade e sugli eventi del cluster:

gkectl describe admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG

L'output mostra la risorsa personalizzata OnPremAdminCluster per il cluster di amministrazione specificato, che include lo stato e le condizioni del cluster.

Fai clic per visualizzare l'output di esempio

Status:
 Cluster State:  RUNNING
 Conditions:
   Last Transition Time:    2026-08-10T20:22:58Z
   Message:                 Operator NodePool is ready
   Observed Generation:     2
   Reason:                  OperatorNodePoolReady
   Status:                  True
   Type:                    ControlPlaneReady
   Last Transition Time:    2026-08-10T20:22:59Z
   Message:                 Cluster is running
   Observed Generation:     2
   Reason:                  ClusterRunning
   Status:                  True
   Type:                    Ready
   Last Transition Time:    2026-08-10T20:23:00Z
   Message:
   Observed Generation:     2
   Reason:                  Reconciling
   Status:                  False
   Type:                    OperatorClusterKubeProxyCleanedUp
   Last Transition Time:    2026-08-10T20:22:58Z
   Message:
   Observed Generation:     2
   Reason:                  PreflightCheckPassed
   Status:                  True
   Type:                    OperatorClusterPreflightCheckSuccessful
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  ProvisioningStarted
   Status:                  True
   Type:                    OperatorClusterProvisioningStarted
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  RemoteTrackerSetupComplete
   Status:                  True
   Type:                    OperatorClusterRemoteTrackerSetupSuccessful
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  Reconciling
   Status:                  False
   Type:                    OperatorClusterStalled
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:
   Observed Generation:     2
   Reason:                  NotPresent
   Status:                  False
   Type:                    OperatorClusterWaitingOnPendingClusterID
   Last Transition Time:    2026-08-10T20:22:59Z
   Message:                 Operator Cluster is ready
   Observed Generation:     2
   Reason:                  OperatorClusterReady
   Status:                  True
   Type:                    OperatorClusterReady
   Last Transition Time:    2026-08-10T15:56:50Z
   Message:                 Component provisioner job is completed
   Observed Generation:     2
   Reason:                  ComponentProvisionerJobCompleted
   Status:                  True
   Type:                    ComponentProvisionerSystemProfileInstalled
   Last Transition Time:    2026-08-10T15:58:20Z
   Message:                 Component provisioner job is completed
   Observed Generation:     2
   Reason:                  ComponentProvisionerJobCompleted
   Status:                  True
   Type:                    ComponentProvisionerAdminProfileInstalled
 Gke On Prem Version:       1.36.0-gke.527
 Last Gke On Prem Version:  1.35.300-gke.87
 Management Conditions:
   Last Transition Time:  2026-08-10T15:58:20Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ManagementProfilesReady
   Last Transition Time:  2026-08-10T15:56:29Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ComponentProvisionerSystemManagementProfileInstalled
   Last Transition Time:  2026-08-10T15:58:20Z
   Message:               Component provisioner job is completed
   Observed Generation:   2
   Reason:                ComponentProvisionerJobCompleted
   Status:                True
   Type:                  ComponentProvisionerManagementProfileInstalled
 Operator Cluster Status:
   Control Plane Node Pool Status:
     Anthos Bare Metal Version:  1.36.0-gke.527
     Anthos Bare Metal Versions:
       1.36.0-gke.527:  3
     Conditions:
       Last Transition Time:  2026-08-10T20:18:20Z
       Observed Generation:   11
       Reason:                PreflightCheckPassed
       Status:                True
       Type:                  PreflightCheckSuccessful
       Last Transition Time:  2026-08-10T20:22:58Z
       Observed Generation:   11
       Reason:                NodepoolReady
       Status:                True
       Type:                  Ready
       Last Transition Time:  2026-08-10T20:22:22Z
       Observed Generation:   11
       Reason:                ReconciliationCompleted
       Status:                False
       Type:                  Reconciling
     Gke Versions:
       v1.36.0-gke.2800:        3
     Last Reconciliation Time:  2026-08-10T20:25:07Z
     Maintenance Nodes:         0
     Managed Fields:
       Label Keys:
         kubernetes.googleapis.com/cluster-name
         node.kubernetes.io/control-plane
         node.kubernetes.io/master
       Node Label Keys:
         vsphere://abcdef-1:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
         vsphere://abcdef-2:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
         vsphere://abcdef-3:
           onprem.gke.io/failure-domain-name
           vmware.cluster.gke.io/machine-name
       Taints:
         Effect:         PreferNoSchedule
         Key:            node-role.kubernetes.io/control-plane
     Ready Nodes:        3
     Ready Timestamp:    2026-08-10T15:54:01Z
     Reconciling Nodes:  0
     Stalled Nodes:      0
     Unknown Nodes:      0
   Data Plane Load Balancer Status:
     Conditions:
       Last Transition Time:  2026-08-10T15:39:16Z
       Observed Generation:   1
       Reason:                ReconciliationCompleted
       Status:                False
       Type:                  Reconciling
     Node Pool Location:      control-plane-nodepool
   External Manifests Conditions:
     Last Transition Time:  2026-08-10T15:56:32Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Connect Conditions:
     Last Transition Time:  2026-08-10T20:13:39Z
     Observed Generation:   2
     Reason:                AnthosBareMetalVersion
     Status:                True
     Type:                  1.36.0-gke.527
     Last Transition Time:  2026-08-10T20:13:39Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Connect Dependent System Service Conditions:
     Last Transition Time:  2026-08-10T15:56:32Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling
   Gke Hub Registration Status:
     Membership:
       Description:  description
       Name:         name
   Gke Versions:
     v1.36.0-gke.2800:  3
   Kernel Version Conditions:
     Last Transition Time:  2026-08-10T15:39:23Z
     Reason:                kernelVersionCheckPassed
     Status:                True
     Type:                  kernelVersionCheckSuccessful
   System Service Conditions:
     Last Transition Time:  2026-08-10T20:12:26Z
     Observed Generation:   2
     Reason:                ReconciliationCompleted
     Status:                False
     Type:                  Reconciling

Al termine dell'upgrade, gkectl list admin mostra un STATE di RUNNING:

NAME              STATE         AGE    VERSION
gke-admin-test    RUNNING       9h     1.36.100-gke.144

Inoltre, al termine dell'upgrade, gkectl describe admin mostra un campo Last GKE On Prem Version in Status. Ad esempio:

Status:
  Cluster State:  RUNNING
  Last GKE On Prem Version:  1.36.0-gke.1

Risolvi i problemi relativi all'upgrade asincrono

Per un upgrade asincrono, la durata del timeout si basa sul numero di nodi nel cluster. Se l'upgrade richiede più tempo della durata del timeout, lo stato del cluster passa da UPGRADING a ERROR, con un evento che indica che l'operazione di upgrade è scaduta. Tieni presente che lo stato ERROR indica che l'upgrade sta richiedendo più tempo del previsto, ma non è stato terminato. Il controller continua la riconciliazione e riprova l'operazione. Quando un upgrade è bloccato o non va a buon fine, puoi eseguire gkectl diagnose per verificare la presenza di problemi comuni del cluster. In base al risultato, puoi decidere se eseguire una correzione manuale o contattare l'assistenzaGoogle Cloud per ulteriore supporto.

Upgrade sincrono

Nella workstation di amministrazione, esegui la diagnostica del cluster prima di eseguire l'upgrade:
```
gkectl diagnose cluster \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Se il comando segnala errori o avvisi, consulta Diagnostica i problemi del cluster e risolvili prima di procedere.
Esegui l'upgrade del cluster di amministrazione:
```
gkectl upgrade admin \
   --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
   --config ADMIN_CLUSTER_CONFIG_FILE
```
Sostituisci quanto segue:
- ADMIN_CLUSTER_KUBECONFIG: il percorso del file kubeconfig del cluster di amministrazione.
- ADMIN_CLUSTER_CONFIG_FILE: il percorso del file di configurazione del cluster di amministrazione.
Il comando gkectl upgrade esegue i controlli preflight. Se i controlli preflight non vanno a buon fine, il comando viene bloccato. Devi correggere gli errori o utilizzare il flag --skip-preflight-check-blocking con il comando per sbloccarlo.
Se esegui l'upgrade alla versione 1.14.0 o successive, viene generato un nuovo file kubeconfig per il cluster di amministrazione che sovrascrive qualsiasi file esistente. Per visualizzare i dettagli del cluster nel file, esegui questo comando:
```
kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```

gcloud CLI

Esegui l'upgrade del cluster di amministrazione utilizzando gcloud CLI.

Aggiorna la versione della piattaforma alla versione di destinazione:
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
    --location=REGION \
    --required-platform-version=VERSION \
    --async
```
Sostituisci quanto segue:
- ADMIN_CLUSTER_NAME: il nome del cluster di amministrazione.
- REGION: la regione Google Cloud in cui viene gestito il cluster di amministrazione.
- VERSION: la versione di destinazione per cui stai eseguendo l'upgrade.
Questo comando restituisce un ID operazione. Puoi monitorare l'avanzamento utilizzando gcloud container vmware operations describe.
Dopo aver completato l'aggiornamento della versione della piattaforma, aggiorna la versione del cluster di amministrazione:
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
    --location=REGION \
    --version=VERSION \
    --async
```
Questo passaggio completa l'upgrade del cluster di amministrazione alla versione di destinazione.

Esegui l'upgrade di un cluster utente

Per eseguire l'upgrade di un cluster utente, puoi utilizzare gkectl, la console, gcloud CLI o Terraform. Per informazioni su come decidere quale strumento utilizzare, consulta Scegli uno strumento per eseguire l'upgrade dei cluster.

Console

L'upgrade di un cluster utente richiede alcune modifiche al cluster di amministrazione. La console esegue automaticamente le seguenti operazioni:

Registra il cluster di amministrazione nell'API GKE On-Prem, se non è già registrato.
Scarica ed esegue il deployment di un bundle di componenti nel cluster di amministrazione. La versione dei componenti corrisponde alla versione specificata per l'upgrade. Questi componenti consentono al cluster di amministrazione di gestire i cluster utente in quella versione.

Per eseguire l'upgrade di un cluster utente:

Nella console, vai alla pagina Panoramica dei cluster Google Kubernetes Engine.

Vai ai cluster GKE
Seleziona il progetto Google Cloud , quindi seleziona il cluster di cui vuoi eseguire l'upgrade.
Nel riquadro Dettagli, fai clic su Altri dettagli.
Nella sezione Impostazioni di base del cluster, fai clic su Esegui l'upgrade.
Nell'elenco Scegli la versione di destinazione, seleziona la versione di cui vuoi eseguire l'upgrade. L'elenco selezionato contiene solo le release di patch più recenti.
Fai clic su Esegui upgrade.

Prima dell'upgrade del cluster, vengono eseguiti controlli preflight per convalidare lo stato del cluster e l'integrità del nodo. Se i controlli preflight vengono superati, viene eseguito l'upgrade del cluster utente. Il completamento dell'upgrade richiede circa 30 minuti.

Per visualizzare lo stato dell'upgrade, fai clic su Mostra dettagli nella scheda Dettagli cluster.

gcloud CLI

L'upgrade di un cluster utente richiede alcune modifiche al cluster di amministrazione. Il comando gcloud container vmware clusters upgrade esegue automaticamente le seguenti operazioni:

Registra il cluster di amministrazione nell'API GKE On-Prem, se non è già registrato.
Scarica ed esegue il deployment di un bundle di componenti nel cluster di amministrazione. La versione dei componenti corrisponde alla versione specificata per l'upgrade. Questi componenti consentono al cluster di amministrazione di gestire i cluster utente in quella versione.

Per eseguire l'upgrade di un cluster utente:

Aggiorna i componenti di Google Cloud CLI:
```
gcloud components update
```

Ottieni un elenco delle versioni disponibili per l'upgrade:

gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

L'output di questo comando è simile al seguente:

versions:
- version: 1.16.3-gke.45
- version: 1.16.2-gke.28
- version: 1.16.1-gke.45
- version: 1.16.0-gke.669
- version: 1.15.6-gke.25
- version: 1.15.5-gke.41

An Anthos version must be made available on the admin cluster ahead of the user
cluster creation or upgrade. Versions annotated with isInstalled=true are
installed on the admin cluster for the purpose of user cluster creation or
upgrade whereas other version are released and will be available for upgrade
once dependencies are resolved.

To install the version in the admin cluster, run:
$ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION

Puoi ignorare il messaggio dopo l'elenco delle versioni. Non importa se la versione di cui stai eseguendo l'upgrade è installata nel cluster di amministrazione. Il comando upgrade scarica ed esegue il deployment di un bundle dei componenti corrispondente alla versione specificata nel comando upgrade.

Esegui l'upgrade del cluster.
```
gcloud container vmware clusters upgrade USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --version=VERSION
```
Sostituisci VERSION con la versione di Google Distributed Cloud a cui vuoi eseguire l'upgrade. Specifica una versione dall'output del comando precedente. Ti consigliamo di eseguire l'upgrade alla versione patch più recente.

L'output del comando è simile al seguente:
```
Waiting for operation [projects/example-project-12345/locations/us-west1/operations/operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179] to complete.
```
Nell'output di esempio, la stringa operation-1679543737105-5f7893fd5bae9-942b3f97-75e59179 è il OPERATION_ID dell'operazione a lunga esecuzione. Puoi scoprire lo stato dell'operazione eseguendo questo comando in un'altra finestra del terminale:
```
gcloud container vmware operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION
```

gkectl

Preparati a eseguire l'upgrade di un cluster utente

Esegui questi passaggi sulla workstation di amministrazione:

Prima di iniziare il tentativo di upgrade iniziale, verifica che il cluster utente sia integro. Consulta Diagnostica i problemi del cluster. Esegui gkectl diagnose cluster sul cluster utente e risolvi eventuali problemi.
Esegui questo passaggio solo se TARGET_VERSION è 1.30 o precedente o se stai eseguendo l'upgrade del cluster utente a una versione diversa da quella del cluster di amministrazione. Esegui gkectl prepare per importare le immagini sistema operativo in vSphere:
```
gkectl prepare \
  --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Se il tuo cluster ha un pool di nodi Windows, esegui gkectl prepare windows e aggiorna il campo osImage per il pool di nodi. Per istruzioni dettagliate, consulta Esegui l'upgrade del cluster utente con i pool di nodi Windows.
Nel file di configurazione del cluster utente, imposta gkeOnPremVersion sulla versione di destinazione dell'upgrade.

Esecuzione di controlli preliminari

Quando esegui l'upgrade alla versione 1.29 e successive, puoi eseguire i controlli preflight prima di eseguire l'upgrade di un cluster utente:

gkectl upgrade cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG \
    --dry-run

Sostituisci USER_CLUSTER_CONFIG con il percorso del file di configurazione del cluster utente.

Con il flag --dry-run, gkectl upgrade cluster esegue i controlli preflight, ma non avvia il processo di upgrade. Sebbene le versioni precedenti di Google Distributed Cloud eseguano controlli preflight, questi non possono essere eseguiti separatamente dall'upgrade. Aggiungendo il flag --dry-run, puoi trovare e risolvere eventuali problemi rilevati dai controlli preflight nel cluster utente prima dell'upgrade.

Esegui `gkectl upgrade cluster`

Esistono due varianti del comando gkectl upgrade cluster:

Asincrono: (consigliato)
Con la variante asincrona, il comando avvia l'upgrade e poi viene completato. Non è necessario osservare l'output del comando per l'intera durata dell'upgrade. Puoi invece controllare periodicamente l'avanzamento dell'upgrade eseguendo gkectl list clusters e gkectl describe clusters. Per utilizzare la variante asincrona, includi il flag --async nel comando.
- Versione 1.31: non disponibile sui cluster avanzati.
- Versione 1.32 e successive: disponibile sui cluster avanzati.
Sincrono:
Con la variante sincrona, il comando gkectl upgrade cluster genera messaggi di stato nella workstation di amministrazione man mano che l'upgrade procede.

Upgrade asincrono

Salta questo passaggio se stai eseguendo l'upgrade a una versione successiva alla 1.16.

Se utilizzi credenziali preparate e un registry privato per il cluster utente, assicurati che la credenziale del registry privato sia preparata prima di eseguire l'upgrade del cluster utente. Per informazioni su come preparare la credenziale del registry privato, consulta Configura le credenziali preparate per i cluster utente.
Esegui la diagnostica del cluster per assicurarti che sia integro:
```
gkectl diagnose cluster \
    --kubeconfig <var>ADMIN_CLUSTER_KUBECONFIG</var>
```
Se il comando segnala errori o avvisi, consulta Diagnostica i problemi del cluster e risolvili prima di procedere.
Sulla workstation di amministrazione, avvia un upgrade asincrono:
```
gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG \
  --async
```
Il comando precedente viene completato e puoi continuare a utilizzare la tua workstation di amministrazione mentre l'upgrade è in corso.
Per visualizzare lo stato dell'upgrade:
```
gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
L'output mostra un valore per il cluster STATE. Se il cluster è ancora in fase di upgrade, il valore di STATE è UPGRADING. Ad esempio:
```
NAMESPACE             NAME    READY   STATE       AGE   VERSION
my-uc-gkeonprem-mgmt  my-uc   False   UPGRADING   9h    1.36.0-gke.1
```
I valori possibili per STATE sono UPGRADING, DELETING, UPDATING, RUNNING, RECONCILING, ERROR e UNKNOWN.

Per maggiori dettagli sull'avanzamento dell'upgrade e sugli eventi del cluster:

gkectl describe clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --cluster USER_CLUSTER_NAME -v 5

L'output mostra la risorsa personalizzata OnPremUserCluster per il cluster utente specificato, che include lo stato, le condizioni e gli eventi del cluster.

Fai clic per visualizzare l'output di esempio

Status: Cluster State: RUNNING Conditions: Last Transition Time: 2026-08-10T21:29:07Z Message: Cluster is running Observed Generation: 2 Reason: ClusterRunning Status: True Type: Ready Last Transition Time: 2026-08-10T21:12:05Z Message: Operator NodePool is ready Observed Generation: 2 Reason: OperatorNodePoolReady Status: True Type: ControlPlaneReady Last Transition Time: 2026-08-10T16:25:08Z Message: Component provisioner job is completed Observed Generation: 2 Reason: ComponentProvisionerJobCompleted Status: True Type: ComponentProvisionerUserProfileInstalled Last Transition Time: 2026-08-10T21:29:07Z Message: Node pools are running Observed Generation: 2 Reason: NodePoolsRunning Status: True Type: NodePoolsReady Last Transition Time: 2026-08-10T21:29:56Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterKubeProxyCleanedUp Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: PreflightCheckPassed Status: True Type: OperatorClusterPreflightCheckSuccessful Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: ProvisioningStarted Status: True Type: OperatorClusterProvisioningStarted Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: RemoteTrackerSetupComplete Status: True Type: OperatorClusterRemoteTrackerSetupSuccessful Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: Reconciling Status: False Type: OperatorClusterStalled Last Transition Time: 2026-08-10T16:27:48Z Message: Observed Generation: 2 Reason: NotPresent Status: False Type: OperatorClusterWaitingOnPendingClusterID Last Transition Time: 2026-08-10T18:23:16Z Message: Operator Cluster is ready Observed Generation: 2 Reason: OperatorClusterReady Status: True Type: OperatorClusterReady Gke On Prem Version: 1.36.0-gke.527 Last Gke On Prem Version: 1.35.300-gke.87 Operator Cluster Status: Control Plane Node Pool Status: Anthos Bare Metal Version: 1.36.0-gke.527 Anthos Bare Metal Versions: 1.36.0-gke.527: 3 Conditions: Last Transition Time: 2026-08-10T21:07:22Z Observed Generation: 11 Reason: PreflightCheckPassed Status: True Type: PreflightCheckSuccessful Last Transition Time: 2026-08-10T21:12:05Z Observed Generation: 11 Reason: NodepoolReady Status: True Type: Ready Last Transition Time: 2026-08-10T21:11:24Z Observed Generation: 11 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Versions: v1.36.0-gke.2800: 3 Last Reconciliation Time: 2026-08-10T21:28:02Z Maintenance Nodes: 0 Managed Fields: Label Keys: node.kubernetes.io/control-plane node.kubernetes.io/master Node Label Keys: vsphere://abcdef-1: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-2: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name vsphere://abcdef-3: onprem.gke.io/failure-domain-name vmware.cluster.gke.io/machine-name Ready Nodes: 3 Ready Timestamp: 2026-08-10T16:24:02Z Reconciling Nodes: 0 Stalled Nodes: 0 Unknown Nodes: 0 Data Plane Load Balancer Status: Conditions: Last Transition Time: 2026-08-10T16:08:47Z Observed Generation: 1 Reason: ReconciliationCompleted Status: False Type: Reconciling Node Pool Location: load-balancer-nodepool External Manifests Conditions: Last Transition Time: 2026-08-10T16:12:25Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Conditions: Last Transition Time: 2026-08-10T21:11:33Z Observed Generation: 2 Reason: AnthosBareMetalVersion Status: True Type: 1.36.0-gke.527 Last Transition Time: 2026-08-10T21:11:33Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Connect Dependent System Service Conditions: Last Transition Time: 2026-08-10T16:25:26Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Gke Hub Registration Status: Membership: Description: description Name: name Gke Versions: v1.36.0-gke.2800: 6 Kernel Version Conditions: Last Transition Time: 2026-08-10T16:08:53Z Reason: kernelVersionCheckPassed Status: True Type: kernelVersionCheckSuccessful System Service Conditions: Last Transition Time: 2026-08-10T21:04:39Z Observed Generation: 2 Reason: ReconciliationCompleted Status: False Type: Reconciling Events: Type Reason Age From Message

Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:

New ClusterState condition: UPGRADING Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:53 +0000 UTC Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:43:54 +0000 UTC Normal ControlPlaneUpgradeStarted 58m onprem-user-cluster-controller Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC Normal StatusChanged 58m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:44:38 +0000 UTC Normal StatusChanged 56m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:46:33 +0000 UTC Normal StatusChanged 54m (x2 over 56m) onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePoolClaim is currently in the progress of rolling update: Condition "NodeRecreationUpdateInProgress" ready, reason: "NodeRecreationUpdateInProgress", message: "Cannot further mark old InventoryMachines for recreation due to MinReadyNodesRequired requirement. Current process: There are still old InventoryMachines: [my-uc-cp-99cc4wxzvx8ww829-2 my-uc-cp-99cc4wxzvx8ww829-1]; New ready count (0) does not match desired count (3)" Normal StatusChanged 53m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" generation 7 hasn't been observed Normal StatusChanged 53m onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateOperatorNodePool, Creating or updating operator NodePool: NodePool is not ready: Condition "Ready" status "False" is not "True", reason: "Reconciling", message: "", lastTransitionTime: 2026-08-10 20:48:58 +0000 UTC Normal StatusChanged 30m (x3 over 58m) onprem-user-cluster-controller OnPremUserCluster status changed:
New Ready condition: True, ClusterRunning, Cluster is running Normal ControlPlaneUpgradeFinished 30m (x3 over 58m) onprem-user-cluster-controller Operator NodePool is ready Normal StatusChanged 29m (x9 over 47m) onprem-user-cluster-controller (combined from similar events): OnPremUserCluster status changed:
New Ready condition: False, CreateOrUpdateNodePools, Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: [] Normal NodePoolsUpgradeStarted 29m onprem-user-cluster-controller Creating or updating node pools, unready node pools: [my-uc-gke-onprem-mgmt/my-uc], in deletion node pools: [] Normal StatusChanged 13m onprem-user-cluster-controller OnPremUserCluster status changed:
New GKEOnPremVersion: "1.36.0-gke.527"
New ClusterState condition: RUNNING
New Ready condition: True, ClusterRunning, Cluster is running

Al termine dell'upgrade, gkectl list clusters mostra un STATE di RUNNING:

NAMESPACE             NAME    READY   STATE     AGE     VERSION
my-uc-gkeonprem-mgmt  my-uc   True    RUNNING   9h      1.36.0-gke.1

Inoltre, al termine dell'upgrade, gkectl describe clusters mostra un campo Last GKE On Prem Version in Status. Ad esempio:

Status:
Cluster State:  RUNNING
Last GKE On Prem Version:  1.36.0-gke.1

Risolvi i problemi relativi all'upgrade asincrono

In genere, un timeout è il risultato di un deadlock causato da un PodDisruptionBudget (PDB). In questo caso, i pod non possono essere rimossi dai nodi precedenti e questi ultimi non possono essere svuotati. Se l'eviction del pod richiede più di 10 minuti, scriviamo un evento nell'oggetto OnPremUserCluster. Puoi acquisire l'evento eseguendo gkectl describe clusters. A questo punto, puoi modificare il PDB per consentire lo svuotamento del nodo. Dopodiché, l'upgrade può procedere e, infine, essere completato.

Esempio di evento:

Warning  PodEvictionTooLong  96s (x2 over 4m7s)  onprem-user-cluster-controller
Waiting too long(>10m0.00000003s) for (kube-system/coredns-856d6dbfdf-dl6nz) eviction.

Inoltre, quando un upgrade è bloccato o non va a buon fine, puoi eseguire gkectl diagnose per verificare la presenza di problemi comuni del cluster. In base al risultato, puoi decidere se eseguire una correzione manuale o contattare l'assistenzaGoogle Cloud per ulteriore supporto.

Upgrade sincrono

Il comando gkectl upgrade esegue i controlli preflight. Se i controlli preflight non vanno a buon fine, il comando viene bloccato. Devi correggere gli errori o utilizzare il flag --skip-preflight-check-blocking. Dovresti saltare i controlli preflight solo se hai la certezza che non ci siano errori critici.

Procedi con questi passaggi sulla workstation di amministrazione:

Salta questo passaggio se stai eseguendo l'upgrade a una versione successiva alla 1.16.

Se utilizzi credenziali preparate e un registry privato per il cluster utente, assicurati che la credenziale del registry privato sia preparata prima di eseguire l'upgrade del cluster utente. Per informazioni su come preparare la credenziale del registry privato, consulta Configura le credenziali preparate per i cluster utente.
Esegui la diagnostica del cluster per assicurarti che sia integro:
```
gkectl diagnose cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG
```
Se il comando segnala errori o avvisi, consulta Diagnostica i problemi del cluster e risolvili prima di procedere.

Esegui l'upgrade del cluster:

gkectl upgrade cluster \
  --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
  --config USER_CLUSTER_CONFIG

Se esegui l'upgrade alla versione 1.14.0 o successive, viene generato un nuovo file kubeconfig per il cluster utente che sovrascrive qualsiasi file esistente. Per visualizzare i dettagli del cluster nel file, esegui questo comando:
```
kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG
```

Riprendi un upgrade

Se l'upgrade di un cluster utente viene interrotto, puoi riprenderlo eseguendo lo stesso comando di upgrade con il flag --skip-validation-all:

gkectl upgrade cluster \
    --kubeconfig ADMIN_CLUSTER_KUBECONFIG \
    --config USER_CLUSTER_CONFIG \
    --skip-validation-all

Terraform

Aggiorna i componenti di Google Cloud CLI:
```
gcloud components update
```
Se non l'hai ancora fatto, registra il cluster di amministrazione nell'API GKE On-Prem. Una volta registrato il cluster nell'API GKE On-Prem, non è necessario ripetere questo passaggio.

Ottieni un elenco delle versioni disponibili per l'upgrade:

gcloud container vmware clusters query-version-config \
  --cluster=USER_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION

Sostituisci quanto segue:

USER_CLUSTER_NAME: il nome del cluster utente.
PROJECT_ID: l'ID del progetto del parco risorse di cui è membro il cluster utente. Questo è il progetto che hai specificato al momento della creazione del cluster. Se hai creato il cluster utilizzando gkectl, questo è l'ID progetto nel campo gkeConnect.projectID nel file di configurazione del cluster.
REGION: la regione Google Cloud in cui l'API GKE On-Prem viene eseguita e archivia i suoi metadati. Nel file main.tf che hai utilizzato per creare il cluster utente, la regione si trova nel campo location della risorsa del cluster.

L'output di questo comando è simile al seguente:

versions:
- version: 1.16.3-gke.45
- version: 1.16.2-gke.28
- version: 1.16.1-gke.45
- version: 1.16.0-gke.669
- version: 1.15.6-gke.25
- version: 1.15.5-gke.41

An Anthos version must be made available on the admin cluster ahead of the user
cluster creation or upgrade. Versions annotated with isInstalled=true are
installed on the admin cluster for the purpose of user cluster creation or
upgrade whereas other version are released and will be available for upgrade
once dependencies are resolved.

To install the version in the admin cluster, run:
$ gcloud container vmware admin-clusters update my-admin-cluster --required-platform-version=VERSION

Scarica la nuova versione dei componenti ed eseguine il deployment nel cluster di amministrazione:
```
gcloud container vmware admin-clusters update ADMIN_CLUSTER_NAME \
  --project=PROJECT_ID \
  --location=REGION \
  --required-platform-version=VERSION
```
Questo comando scarica la versione dei componenti specificata in --required-platform-version nel cluster di amministrazione, quindi esegue il deployment dei componenti. Questi componenti consentono al cluster di amministrazione di gestire i cluster utente in quella versione.
Nel file main.tf che hai utilizzato per creare il cluster utente, modifica on_prem_version nella risorsa del cluster con la nuova versione.
Inizializza e crea il piano Terraform:
```
terraform init
```
Terraform installa tutte le librerie necessarie, come il provider Google Cloud.
Esamina la configurazione e apporta modifiche, se necessario:
```
terraform plan
```
Applica il piano Terraform per creare il cluster utente:
```
terraform apply
```

Rimuovi l'intero pacchetto

Se hai scaricato un bundle completo e hai eseguito correttamente gkectl prepare ed eseguito l'upgrade del cluster di amministrazione e di tutti i cluster utente, devi eliminare il bundle completo per risparmiare spazio su disco sulla workstation di amministrazione. Esegui questo comando per eliminare il bundle completo:

rm /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION-full.tgz

Ripristino di un upgrade del cluster di amministrazione

Se un upgrade del cluster di amministrazione viene interrotto o non va a buon fine, può essere ripreso se il checkpoint del cluster di amministrazione contiene lo stato richiesto per ripristinare lo stato precedente all'interruzione.

Avviso: non riparare il control plane di amministrazione con gkectl repair admin-master dopo un tentativo di upgrade non riuscito. In questo modo, il cluster di amministrazione entra in uno stato non valido.

Segui questi passaggi:

Prima di iniziare il primo tentativo di upgrade, verifica che il control plane di amministrazione sia integro. Consulta Diagnosi dei problemi del cluster. Come descritto in quell'argomento, esegui il comando gkectl diagnose cluster per il cluster di amministrazione.
Se il control plane di amministrazione non è integro prima del tentativo di upgrade iniziale, riparalo con il comando gkectl repair admin-master.
Quando esegui nuovamente il comando di upgrade dopo che un upgrade è stato interrotto o non è riuscito, utilizza lo stesso bundle e la stessa versione di destinazione del tentativo di upgrade precedente.

Quando esegui nuovamente il comando di upgrade, l'upgrade ripreso ricrea lo stato del cluster di amministrazione dal checkpoint ed esegue nuovamente l'intero upgrade. A partire dalla versione 1.12.0, se il control plane di amministrazione non è integro, il processo di upgrade eseguirà direttamente l'upgrade alla versione di destinazione senza tentare di ripristinare il cluster di amministrazione alla versione di origine prima di procedere con l'upgrade.

L'upgrade riprenderà dal punto in cui non è riuscito o è stato interrotto se il checkpoint del cluster di amministrazione è disponibile. Se il checkpoint non è disponibile, l'upgrade si baserà sul control plane di amministrazione, che deve essere integro per procedere con l'upgrade. Dopo un upgrade riuscito, il checkpoint viene rigenerato.

Se gkectl si chiude in modo imprevisto durante l'upgrade di un cluster di amministrazione, il cluster kind non viene ripulito. Prima di eseguire nuovamente il comando di upgrade per riprendere l'upgrade, elimina il cluster kind:

docker stop gkectl-control-plane && docker rm gkectl-control-plane

Dopo aver eliminato il cluster kind, esegui nuovamente il comando di upgrade.

Esegui il rollback di una workstation di amministrazione dopo un upgrade

Puoi eseguire il rollback della workstation di amministrazione alla versione utilizzata prima dell'upgrade.

Durante l'upgrade, gkeadm registra la versione precedente all'upgrade nel file di informazioni di output. Durante il rollback, gkeadm utilizza la versione elencata per scaricare il file precedente.

Per eseguire il rollback della workstation di amministrazione alla versione precedente:

gkeadm rollback admin-workstation --config=AW_CONFIG_FILE

Puoi omettere --config=AW_CONFIG_FILE se il file di configurazione della workstation di amministrazione è quello predefinito admin-ws-config.yaml. In caso contrario, sostituisci AW_CONFIG_FILE con il percorso del file di configurazione della workstation di amministrazione.

Il comando di rollback esegue questi passaggi:

Scarica la versione di rollback di gkeadm.
Esegue il backup della home directory della workstation di amministrazione attuale.
Crea una nuova workstation di amministrazione utilizzando la versione di rollback di gkeadm.
Elimina la workstation di amministrazione originale.

Installa il bundle con una versione diversa per l'upgrade

Se esegui l'upgrade della workstation, viene installato un bundle con una versione corrispondente per l'upgrade dei cluster. Se vuoi una versione diversa, segui questi passaggi per installare un bundle per TARGET_VERSION, ovvero la versione a cui vuoi eseguire l'upgrade.

Per controllare le versioni attuali di gkectl e del cluster, esegui questo comando. Utilizza il flag --details/-d per informazioni più dettagliate.
```
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
```
L'output fornisce informazioni sulle versioni del cluster.
In base all'output ottenuto, cerca i seguenti problemi e correggili in base alle esigenze.
- Se la versione attuale del cluster di amministrazione è inferiore di più di una versione secondaria rispetto alla TARGET_VERSION, esegui l'upgrade di tutti i cluster in modo che siano inferiori di una versione secondaria rispetto alla TARGET_VERSION.
- Se la versione di gkectl è precedente alla 1.11 e vuoi eseguire l'upgrade alla 1.12.x, dovrai eseguire più upgrade. Esegui l'upgrade di una versione secondaria alla volta fino ad arrivare alla versione 1.11.x, quindi procedi con le istruzioni riportate in questo argomento.
- Se la versione gkectl è precedente alla TARGET_VERSION, esegui l'upgrade della workstation di amministrazione alla TARGET_VERSION.
Dopo aver stabilito che le versioni di gkectl e del cluster sono appropriate per un upgrade, scarica il bundle.

Controlla se il tarball del bundle esiste già sulla workstation di amministrazione.
```
stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz
```
Se il bundle non si trova sulla workstation di amministrazione, scaricalo.
```
gcloud storage cp gs://gke-on-prem-release/gke-onprem-bundle/TARGET_VERSION/gke-onprem-vsphere-TARGET_VERSION.tgz /var/lib/gke/bundles/
```
Installa il bundle.
```
gkectl prepare --bundle-path /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz --kubeconfig ADMIN_CLUSTER_KUBECONFIG
```
Sostituisci ADMIN_CLUSTER_KUBECONFIG con il percorso del file kubeconfig. Puoi omettere questo flag se il file si trova nella directory attuale ed è denominato kubeconfig.

Nota: per impostazione predefinita, viene scaricato il bundle normale, non quello completo. Il bundle completo contiene tutte le immagini container e VM, mentre il bundle normale scarica le immagini container e VM dalla Google Cloud Platform sulla workstation di amministrazione durante l'installazione. Per utilizzare invece il bundle completo, il percorso del bundle nel comando di installazione è gke-onprem-vsphere-TARGET_VERSION-full.tgz.
Elenca le versioni dei cluster disponibili e assicurati che la versione di destinazione sia inclusa tra le versioni dei cluster utente disponibili.
```
gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG --details
```

Ora puoi creare un cluster utente nella versione di destinazione o eseguire l'upgrade di un cluster utente alla versione di destinazione.

Risoluzione dei problemi relativi al processo di upgrade

Se riscontri un problema durante la procedura di upgrade consigliata, segui questi consigli per risolverlo. Questi suggerimenti presuppongono che tu abbia iniziato con una configurazione della versione 1.11.x e che tu stia procedendo con il processo di upgrade consigliato.

Vedi anche: Risoluzione dei problemi di creazione e upgrade dei cluster

Risoluzione dei problemi di un upgrade del cluster utente

Supponiamo che tu riscontri un problema con la versione di upgrade durante l'upgrade di un cluster utente. L'Assistenza Google ti informa che il problema verrà risolto in una release di patch imminente. Puoi procedere nel seguente modo:

Continuare a utilizzare la versione attuale per la produzione.
Testa la release della patch in un cluster non di produzione quando viene rilasciata.
Esegui l'upgrade di tutti i cluster utente di produzione alla versione di patch release quando ritieni che sia il momento giusto.
Esegui l'upgrade del cluster di amministrazione alla versione della patch release.

Risoluzione dei problemi di upgrade di un cluster di amministrazione

Se riscontri un problema durante l'upgrade del cluster di amministrazione, devi contattare l'Assistenza Google per risolverlo.

Nel frattempo, con il nuovo flusso di upgrade, puoi comunque usufruire delle nuove funzionalità del cluster utente senza essere bloccato dall'upgrade del cluster di amministrazione, il che ti consente di ridurre la frequenza di upgrade del cluster di amministrazione, se vuoi. La procedura di upgrade può procedere come segue:

Esegui l'upgrade dei cluster utente di produzione alla versione 1.12.x.
Mantieni il cluster di amministrazione nella versione precedente e continua a ricevere patch di sicurezza.
Esegui l'upgrade del cluster di amministrazione di test dalla versione 1.11.x alla 1.12.x in un ambiente di test e segnala eventuali problemi.
Se il problema viene risolto da una release patch 1.12.x, puoi scegliere di eseguire l'upgrade del cluster di amministrazione di produzione a questa release patch, se vuoi.

Problemi noti per le versioni recenti

I seguenti problemi noti potrebbero influire sugli upgrade se esegui l'upgrade dalla versione 1.7 o successive.

Vedi anche: Problemi noti

L'upgrade della workstation di amministrazione potrebbe non riuscire se il disco dati è quasi pieno

Se esegui l'upgrade della workstation di amministrazione con il comando gkectl upgrade admin-workstation, l'upgrade potrebbe non riuscire se il disco dati è quasi pieno, perché il sistema tenta di eseguire il backup della workstation di amministrazione corrente localmente durante l'upgrade a una nuova workstation di amministrazione. Se non riesci a liberare spazio sufficiente sul disco dati, utilizza il comando gkectl upgrade admin-workstation con il flag aggiuntivo --backup-to-local=false per impedire l'esecuzione di un backup locale della workstation di amministrazione attuale.

Interruzione per i workload con PodDisruptionBudget

L'upgrade dei cluster può causare interruzioni o tempi di inattività per i workload che utilizzano PodDisruptionBudgets (PDB).

I nodi non riescono a completare il processo di upgrade

Se hai configurato PodDisruptionBudget oggetti che non possono consentire ulteriori interruzioni, i nodi potrebbero non riuscire a eseguire l'upgrade alla versione del control plane dopo ripetuti tentativi. Per evitare questo errore, ti consigliamo di fare lo scale up di Deployment o HorizontalPodAutoscaler per consentire lo svuotamento del nodo rispettando comunque la configurazione di PodDisruptionBudget.

Elenca tutti gli oggetti PodDisruptionBudget nel cluster utente che non consentono interruzioni:

kubectl --kubeconfig USER_CLUSTER_KUBECONFIG \
    get poddisruptionbudget --all-namespaces \
    -o jsonpath='{range .items[?(@.status.disruptionsAllowed==0)]}{.metadata.namespace}/{.metadata.name}{"\n"}{end}'

Sostituisci USER_CLUSTER_KUBECONFIG con il percorso del file kubeconfig del cluster utente.

I PDB predefiniti kube-system/log-aggregator e kube-system/prometheus vengono visualizzati nell'output con disruptionsAllowed: 0 quando non hanno pod corrispondenti e status.expectedPods è 0. Poiché questi PDB non bloccano lo svuotamento dei nodi, puoi ignorarli.

Ulteriori informazioni sull'upgrade

Informazioni sulle regole VMware DRS abilitate nella versione 1.1.0-gke.6

A partire dalla versione 1.1.0-gke.6, Google Distributed Cloud crea automaticamente regole anti-affinità Distributed Resource Scheduler (DRS) di VMware per i nodi del cluster utente, in modo da distribuirle in almeno tre host fisici del data center. A partire dalla versione 1.1.0-gke.6, questa funzionalità viene attivata automaticamente per i cluster nuovi ed esistenti.

Prima di eseguire l'upgrade, assicurati che l'ambiente vSphere soddisfi le seguenti condizioni:

VMware DRS è abilitato. VMware DRS richiede la versione della licenza vSphere Enterprise Plus. Per scoprire come attivare DRS, consulta Attivazione di VMware DRS in un cluster.
Il nome utente vSphere fornito nel file di configurazione delle credenziali dispone dell'autorizzazione Host.Inventory.EditCluster.
Sono disponibili almeno tre host fisici.

Se il tuo ambiente vSphere non soddisfa le condizioni precedenti, puoi comunque eseguire l'upgrade, ma per eseguire l'upgrade di un cluster utente dalla versione 1.3.x alla versione 1.4.x, devi disattivare i gruppi anti-affinità. Per saperne di più, consulta questo problema noto nelle note di rilascio di Google Distributed Cloud.

Informazioni sul tempo di inattività durante gli upgrade

Risorsa	Descrizione
Cluster di amministrazione	Quando un cluster di amministrazione non è attivo, i control plane dei cluster utente e i workload sui cluster utente continuano a essere eseguiti, a meno che non siano stati interessati da un errore che ha causato il tempo di inattività.
Control plane del cluster utente	In genere, non dovresti aspettarti tempi di inattività significativi per i control plane dei cluster utente. Tuttavia, le connessioni di lunga durata al server API Kubernetes potrebbero interrompersi e dover essere ristabilite. In questi casi, il chiamante dell'API deve riprovare finché non stabilisce una connessione. Nel peggiore dei casi, durante un upgrade può verificarsi un tempo di inattività di un minuto. Nota: se i nodi del cluster utente non riescono a raggiungere il control plane utente durante l'upgrade, non vengono pianificati nuovi workload per il cluster. I workload esistenti non sono interessati.
Nodi del cluster utente	Se un upgrade richiede una modifica ai nodi del cluster utente, Google Distributed Cloud ricrea i nodi in modo graduale e ripianifica i pod in esecuzione su questi nodi. Puoi evitare l'impatto sui tuoi workload configurando i PodDisruptionBudgets e le regole di anti-affinità appropriati.

Ricrea un file di informazioni se mancante

Se il file delle informazioni di output per la tua workstation di amministrazione non è presente, devi ricrearlo per poter procedere con l'upgrade. Questo file è stato creato quando hai creato inizialmente la workstation e, se hai eseguito un upgrade, è stato aggiornato con nuove informazioni.

Il file di informazioni di output ha questo formato:

Admin workstation version: GKEADM_VERSION
Created using gkeadm version: GKEADM_VERSION
VM name: ADMIN_WS_NAME
IP: ADMIN_WS_IP
SSH key used: FULL_PATH_TO_ADMIN_WS_SSH_KEY
To access your admin workstation:
ssh -i FULL-PATH-TO-ADMIN-WS-SSH-KEY ubuntu@ADMIN-WS-IP

Ecco un file di informazioni di output di esempio:

Admin workstation version: v1.10.3-gke.49
Created using gkeadm version: v1.10.3-gke.49
VM name: admin-ws-janedoe
IP: 172.16.91.21
SSH key used: /home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /home/janedoe/.ssh/gke-admin-workstation ubuntu@172.16.91.21

Crea il file in un editor, sostituendo i parametri appropriati. Salva il file con un nome file uguale al nome della VM nella directory da cui viene eseguito gkeadm. Ad esempio, se il nome della VM è admin-ws-janedoe, salva il file come admin-ws-janedoe.

Passaggi successivi

Documentazione di riferimento di gcloud CLI
Documentazione di riferimento di Terraform
- google_gkeonprem_vmware_cluster
- google_gkeonprem_vmware_node_pool

Upgrade di un cluster Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Prima di iniziare

Esamina le regole firewall

Abilita stackdriver

Abilita Dataplane V2

Requisiti delle API di Google e di IAM

Funzionalità legacy bloccate sugli upgrade

Requisiti IAM per l'upgrade dei cluster utente

Limitazioni relative ai cluster avanzati

Apporta modifiche alla configurazione prima o dopo un upgrade

Controlla le versioni disponibili per gli upgrade del cluster

Esegui l'upgrade della workstation di amministrazione

gkeadm

Individua i file richiesti

Esegui l'upgrade

Gestito dall'utente

Esegui l'upgrade del cluster di amministrazione

1.31 e successive

1.30 e versioni precedenti

Esegui l'upgrade

gkectl

Upgrade asincrono

Risolvi i problemi relativi all'upgrade asincrono

Upgrade sincrono

gcloud CLI

Esegui l'upgrade di un cluster utente

Console

gcloud CLI

gkectl

Preparati a eseguire l'upgrade di un cluster utente

Esecuzione di controlli preliminari

Esegui gkectl upgrade cluster

Upgrade asincrono

Risolvi i problemi relativi all'upgrade asincrono

Upgrade sincrono

Riprendi un upgrade

Terraform

Rimuovi l'intero pacchetto

Ripristino di un upgrade del cluster di amministrazione

Esegui il rollback di una workstation di amministrazione dopo un upgrade

Installa il bundle con una versione diversa per l'upgrade

Risoluzione dei problemi relativi al processo di upgrade

Risoluzione dei problemi di un upgrade del cluster utente

Risoluzione dei problemi di upgrade di un cluster di amministrazione

Problemi noti per le versioni recenti

L'upgrade della workstation di amministrazione potrebbe non riuscire se il disco dati è quasi pieno

Interruzione per i workload con PodDisruptionBudget

I nodi non riescono a completare il processo di upgrade

Ulteriori informazioni sull'upgrade

Informazioni sulle regole VMware DRS abilitate nella versione 1.1.0-gke.6

Informazioni sul tempo di inattività durante gli upgrade

Ricrea un file di informazioni se mancante

Passaggi successivi

Upgrade di un cluster

Abilita `stackdriver`

Esegui `gkectl upgrade cluster`