Upgrade di un cluster

Questo documento spiega come eseguire l'upgrade dei cluster in Google Distributed Cloud (solo software) per VMware. Questo documento illustra i passaggi per eseguire l'upgrade della workstation di amministrazione, dei cluster utente e dei cluster di amministrazione. I passaggi per eseguire l'upgrade di un cluster utente mostrano come eseguire l'upgrade del piano di controllo e di tutti i pool di nodi. Se vuoi eseguire l'upgrade del control plane e dei pool di nodi del cluster utente separatamente, consulta Eseguire l'upgrade dei pool di nodi.

Questa pagina è rivolta agli amministratori IT e agli operatori che gestiscono il ciclo di vita dell'infrastruttura tecnologica di base. Per scoprire di più sui ruoli comuni e sulle attività di esempio a cui facciamo riferimento nei contenuti di Google Cloud, consulta Ruoli e attività comuni degli utenti di GKE Enterprise.

Prima di procedere, ti consigliamo di leggere la seguente documentazione:

  • Panoramica dell'upgrade
    Tra le altre cose, questo documento descrive lo scarto di versione e le regole di versione supportate per gli upgrade, che sono cambiate per la versione 1.28 e successive.

  • Best practice per l'upgrade
    Questo documento fornisce elenchi di controllo e best practice per l'upgrade dei cluster.

Esamina le regole del firewall

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

Con i controlli preliminari lato server, quando esegui l'upgrade di un cluster utente utilizzando gkectl, i controlli preliminari vengono eseguiti sul cluster di amministrazione anziché localmente sulla workstation di amministrazione. I controlli preliminari lato server vengono eseguiti anche sul cluster amministrativo 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 (kind) Kubernetes in Docker per ospitare temporaneamente i controller Kubernetes necessari per l'upgrade del cluster di amministrazione. Questo cluster transitorio è chiamato cluster di bootstrap. I controlli preflight lato server vengono eseguiti sul cluster di bootstrap quando esegui l'upgrade di un cluster di amministrazione.

Requisiti dell'API 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 all'account di servizio logging-monitoring. Queste modifiche sono necessarie per utilizzare Cloud Monitoring.

  1. 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 fa parte il cluster di utenti. Si tratta del progetto 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.

  2. Se la tua organizzazione ha configurato una lista consentita che consente il passaggio del traffico proveniente dalle API di Google e da altri indirizzi tramite il server proxy, aggiungi kubernetesmetadata.googleapis.com alla lista consentita.

  3. Concedi il ruolo kubernetesmetadata.publisher all'account di servizio 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 monitoraggio e generazione di log.

Requisiti IAM per l'upgrade dei cluster utente

Ignora 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 di utenti e non sei un proprietario del progetto, devi disporre del ruolo Identity and Access Management roles/gkeonprem.admin nel progetto Google Cloud in cui è stato creato il cluster. Per informazioni dettagliate sulle autorizzazioni incluse in questo ruolo, consulta la sezione Ruoli GKE on-premise nella documentazione IAM.

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

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

  • roles/gkehub.viewer. Questo ruolo consente agli utenti di visualizzare i cluster nella console. Per informazioni dettagliate sulle autorizzazioni incluse in questo ruolo o per concedere un ruolo con autorizzazioni di lettura/scrittura, consulta Ruoli GKE Hub nella documentazione IAM.

Apportare 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 dovrebbe essere la versione. A seconda della versione e del tipo di cluster, altre modifiche alla configurazione vengono ignorate silenziosamente o causano l'errore dell'upgrade. Per ulteriori informazioni, consulta Rimuovere le modifiche non supportate per sbloccare l'upgrade.

Controllare le versioni disponibili per gli upgrade del cluster

Esegui il seguente comando per vedere quali versioni sono disponibili per l'upgrade:

gkectl version --kubeconfig ADMIN_CLUSTER_KUBECONFIG

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

Se prevedi di utilizzare la console, l'interfaccia a riga della 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 di utenti. 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

Devi eseguire l'upgrade della workstation di amministrazione se prevedi di utilizzare gkectl per eseguire l'upgrade di un cluster utente.

Se prevedi di utilizzare la console, l'interfaccia alla gcloud CLI o Terraform per eseguire l'upgrade di un cluster utente, per il momento puoi saltare l'upgrade della workstation di amministrazione. Tuttavia, dovrai eseguire l'upgrade della workstation di amministrazione quando sarà tutto pronto per l'upgrade del cluster di amministrazione, perché solo gkectl supporta gli upgrade del cluster di amministrazione.

Il modo in cui esegui l'upgrade della workstation di amministrazione dipende da come l'hai creata: gkeadm o gestita dall'utente.

gkeadm

Individuare 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 amministrativa e il file di informazioni. Devi eseguire i passaggi di upgrade. Se questi file si trovano nella directory corrente 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 dei file, devi specificarli utilizzando i flag --config e --info-file.

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

Esegui l'upgrade

Per eseguire l'upgrade della workstation di amministrazione:

  1. Controlla il campo adminWorkstation.diskGB nel file di configurazione della workstation amministrativa e assicurati che la dimensione specificata sia almeno 100, ad esempio:

    adminWorkstation:
  diskGB: 100

    Per 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.

  2. Scarica gkeadm:

    gkeadm upgrade gkeadm --target-version TARGET_VERSION

    Sostituisci TARGET_VERSION con la versione di destinazione dell'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.

  3. 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.

Gestita dall'utente

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

Scarica gkectl:

gcloud storage cp gs://gke-on-prem-release/gkectl/VERSION/gkectl ./
chmod +x gkectl

Sostituisci VERSION con la versione di destinazione dell'upgrade. Ad esempio: 1.30.300-gke.84.

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/VERSION/gke-onprem-vsphere-VERSION.tgz ./

Eseguire l'upgrade di un cluster utente

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

gkectl

Prepararsi a eseguire l'upgrade di un cluster utente

Esegui i seguenti passaggi sulla workstation di amministrazione:

  1. Esegui gkectl prepare per importare le immagini del sistema operativo in vSphere:

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

  2. Se il 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 Eseguire l'upgrade del cluster utente con pool di nodi Windows.

  3. 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

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

Esegui gkectl upgrade cluster

Esistono due varianti del comando gkectl upgrade cluster:

  • Asincrono: (opzione consigliata)
    Con la variante asincrona, il comando avvia l'upgrade e poi lo completa. Non è necessario monitorare l'output del comando per l'intera durata dell'upgrade. In alternativa, puoi 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.

  • Sincrona:
    con la variante sincrona, il comando gkectl upgrade cluster genera messaggi di stato sulla workstation di amministrazione man mano che l'upgrade avanza.

Upgrade asincrono

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

    Se utilizzi credenziali preparate e un registro privato per il cluster di utenti, assicurati che la credenziale del registry privato sia preparata prima di eseguire l'upgrade del cluster di utenti. Per informazioni su come preparare la credenziale del registry privato, vedi Configurare le credenziali preparate per i cluster di utenti.

  2. 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 workstation di amministrazione durante l'upgrade.

  3. Per visualizzare lo stato dell'upgrade:

    gkectl list clusters --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    L'output mostra un valore per il cluster STATE. Se l'upgrade del cluster è ancora in corso, il valore di STATE è UPGRADING. Ad esempio:

    NAMESPACE             NAME    READY   STATE       AGE   VERSION
my-uc-gkeonprem-mgmt  my-uc   False   UPGRADING   9h    1.30.0-gke.1

    I valori possibili per STATE sono PROVISIONING, UPGRADING, DELETING, UPDATING, RUNNING, RECONCILING, ERROR e UNKNOWN.

  4. Per ulteriori 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 di utenti specificato, che include lo stato, le condizioni e gli eventi del cluster.

    Registriamo gli eventi relativi all'inizio e alla fine di ogni fase critica dell'upgrade, tra cui:

    • ControlPlaneUpgrade
    • MasterNodeUpgrade
    • AddonsUpgrade
    • NodePoolsUpgrade

    Output di esempio:

    Events:
Type    Reason                      Age    From                            Message
----     ------                     ----   ----                            -------
Normal  NodePoolsUpgradeStarted     22m    onprem-user-cluster-controller  Creating or updating node pools: pool-2: Creating or updating node pool
Normal  AddonsUpgradeStarted        22m    onprem-user-cluster-controller  Creating or updating addon workloads
Normal  ControlPlaneUpgradeStarted  25m    onprem-user-cluster-controller  Creating or updating cluster control plane workloads: deploying user-kube-apiserver-base, ...: 14/15 pods are ready
Normal  ControlPlaneUpgradeFinished 23m    onprem-user-cluster-controller  Control plane is running

  5. Al termine dell'upgrade, gkectl list clusters mostra un STATUS di RUNNING:

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

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

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

Risolvere i problemi relativi all'upgrade asincrono

Per un upgrade asincrono, la durata del timeout si basa sul numero di nodi del cluster. Se l'upgrade richiede più tempo rispetto alla durata del timeout, lo stato del cluster passa da UPGRADING a ERROR e viene generato un evento che indica che l'operazione di upgrade ha superato il timeout. Tieni presente che lo stato ERROR qui indica che l'upgrade sta richiedendo più tempo del previsto, ma non è stato interrotto. Il controller continua la riconciliazione e continua a riprovare l'operazione.

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

Evento di esempio:

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 il team di assistenza di Anthos 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 nel seguente modo sulla workstation di amministrazione:

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

    Se utilizzi credenziali preparate e un registro privato per il cluster di utenti, assicurati che la credenziale del registry privato sia preparata prima di eseguire l'upgrade del cluster di utenti. Per informazioni su come preparare la credenziale del registry privato, vedi Configurare le credenziali preparate per i cluster di utenti.

  2. Esegui l'upgrade del cluster:

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

  3. Se esegui l'upgrade alla versione 1.14.0 o successiva, viene generato un nuovo file kubeconfig per il cluster utente che sovrascrive qualsiasi file esistente. Per visualizzare i dettagli del cluster nel file, esegui il seguente comando:

    kubectl config view --kubeconfig USER_CLUSTER_KUBECONFIG

Riprendere un upgrade

Se un upgrade del 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_FILE \
  --skip-validation-all

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 a quella 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:

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

    Vai ai cluster GKE

  2. Seleziona il progetto Google Cloud e poi il cluster di cui vuoi eseguire l'upgrade.

  3. Nel riquadro Dettagli, fai clic su Più dettagli.

  4. Nella sezione Impostazioni di base del cluster, fai clic su Esegui upgrade.

  5. Nell'elenco Scegli la versione di destinazione, seleziona la versione a cui vuoi eseguire l'upgrade. L'elenco selezionato contiene solo le patch più recenti.

  6. 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.

Interfaccia a riga di comando gcloud

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

  • 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 a quella 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:

  1. Aggiorna i componenti di Google Cloud CLI:

    gcloud components update

  2. Per un elenco delle versioni a cui puoi eseguire l'upgrade:

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

    L'output del 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 a cui esegui l'upgrade è installata sul cluster amministrativo. Il comando upgrade scarica e esegue il deployment di un bundle di componenti corrispondente alla versione specificata nel comando upgrade.

  3. 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 di cui vuoi eseguire l'upgrade. Specifica una versione dall'output del comando precedente. Ti consigliamo di eseguire l'upgrade alla versione della 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. Per conoscere lo stato dell'operazione, esegui il seguente comando in un'altra finestra del terminale:

    gcloud container vmware operations describe OPERATION_ID \
  --project=PROJECT_ID \
  --location=REGION

Terraform

  1. Aggiorna i componenti di Google Cloud CLI:

    gcloud components update

  2. 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.

  3. Per un elenco delle versioni a cui puoi eseguire 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 di utenti.

    • PROJECT_ID: l'ID del progetto del parco risorse di cui fa parte il cluster di utenti. Si tratta del progetto 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 viene eseguita l'API GKE On-Prem e in cui vengono archiviati i relativi 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 del 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

  4. Scarica la nuova versione dei componenti ed esegui il deployment nel cluster amministrativo:

    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 e poi esegue il deployment dei componenti. Questi componenti consentono al cluster di amministrazione di gestire i cluster di utenti in quella versione.

  5. Nel file main.tf utilizzato per creare il cluster di utenti, modifica on_prem_version nella risorsa del cluster con la nuova versione.

  6. Inizializza e crea il piano Terraform:

    terraform init

    Terraform installa le librerie necessarie, ad esempio il fornitore Google Cloud.

  7. Esamina la configurazione e apporta le modifiche necessarie:

    terraform plan

  8. Applica il piano Terraform per creare il cluster utente:

    terraform apply

Esegui l'upgrade del cluster di amministrazione

Dopo aver eseguito l'upgrade dei cluster utente, puoi eseguire l'upgrade del cluster di amministrazione.

Prima di iniziare:

  1. Se esegui l'upgrade alla versione 1.13 o successiva, devi prima registrare il cluster di amministrazione compilando la sezione gkeConnect nel file di configurazione del cluster di amministrazione. Esegui il comando gkectl update cluster con le modifiche al file di configurazione.

  2. Assicurati che gkectl e i cluster siano della versione appropriata per un upgrade e che tu abbia scaricato il bundle appropriato. Il ribaltamento della 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 Eccesso di versioni dei cluster di amministrazione e utente.

  3. 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 amministrativo, queste modifiche vengono ignorate durante l'upgrade. Affinché queste modifiche vengano applicate, devi prima eseguire l'upgrade del cluster e poi un comando update cluster con le modifiche al file di configurazione per apportare altre modifiche al cluster.

Esegui gkectl upgrade admin

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

  • Asincrono:
    con la variante asincrona, il comando avvia e poi completa l'upgrade. Non è necessario monitorare l'output del comando per l'intera durata dell'upgrade. In alternativa, puoi controllare periodicamente l'avanzamento dell'upgrade eseguendo gkectl list admin e gkectl describe admin. Per utilizzare la variazione asincrona, includi il flag --async nel comando.

    Requisiti per l'upgrade asincrono:

    • Supportato solo per i cluster di amministrazione HA con versione 1.29 o successive.
    • In tutti i cluster utente deve essere abilitato Controlplane V2.

  • Sincrona:
    con la variante sincrona, il comando gkectl upgrade admin genera messaggi di stato sulla workstation di amministrazione man mano che l'upgrade avanza.

Upgrade asincrono

  1. Sulla workstation di amministrazione, 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 workstation di amministrazione durante l'upgrade.

    con gkectl upgrade admin, esegui il seguente comando:

    gkectl upgrade admin -h

  2. Per visualizzare lo stato dell'upgrade:

    gkectl list admin --kubeconfig ADMIN_CLUSTER_KUBECONFIG

    L'output mostra un valore per il cluster STATE. Se l'upgrade del cluster è ancora in corso, il valore di STATE è UPGRADING. Ad esempio:

    NAME              STATE         AGE    VERSION
gke-admin-test    UPGRADING     9h     1.30.300-gke.84

    I valori possibili per STATE sono RUNNING, UPGRADING, RECONCILING, ERROR e UNKNOWN.

  3. Per ulteriori 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 amministrativo specificato, che include lo stato, le condizioni e gli eventi del cluster.

    Registriamo gli eventi relativi all'inizio e alla fine di ogni fase critica dell'upgrade.

    Output di esempio:

    Events:
Type    Reason                             Age   From                             Message
----       ------                                  ----     ----                                -------
Normal  ControlPlaneUpgradeStarted         40m   onprem-admin-cluster-controller  Creating or updating admin cluster API Controller
Normal  ControlPlaneMachineUpgradeStarted  40m   onprem-admin-cluster-controller  Creating or updating control plane machine
Normal  StatusChanged                      40m   onprem-admin-cluster-controller  OnPremAdminCluster status changed:
- New ClusterState condition: UPGRADING
- New Ready condition: False, CreateOrUpdateControlPlaneMachine, Creating or updating control plane machine
Normal   StatusChanged      2m                onprem-admin-cluster-controller  OnPremAdminCluster status changed:
- New ClusterState condition: RUNNING
- New Ready condition: True, ClusterRunning, Cluster is running

  4. Al termine dell'upgrade, gkectl list admin mostra un STATUS di RUNNING:

    NAME              STATE         AGE    VERSION
gke-admin-test    RUNNING       9h     1.30.300-gke.84

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

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

Risolvere 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 e viene generato un evento che indica che l'operazione di upgrade ha superato il timeout. Tieni presente che lo stato ERROR indica che l'upgrade sta richiedendo più tempo del previsto, ma non è stato interrotto. Il controller continua la riconciliazione e continua a riprovare 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'assistenza Google Cloud per ulteriore assistenza.

Upgrade sincrono

  1. Esegui questo comando:

    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.

  2. Se esegui l'upgrade alla versione 1.14.0 o successiva, viene generato un nuovo file kubeconfig per il cluster di amministrazione che sovrascrive eventuali file esistenti. Per visualizzare i dettagli del cluster nel file, esegui il seguente comando:

    kubectl config view --kubeconfig ADMIN_CLUSTER_KUBECONFIG

Rimuovere il bundle completo

Se hai scaricato un bundle completo ed hai eseguito correttamente i comandi gkectl prepare e gkectl upgrade admin, devi eliminare il bundle completo per risparmiare spazio su disco sulla workstation di amministrazione. Esegui il seguente comando per eliminare il bundle completo:

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

Riavviare un upgrade del cluster di amministrazione

Se l'upgrade di un cluster di amministrazione viene interrotto o non riesce, l'upgrade può essere ripreso se il controllo del cluster di amministrazione contiene lo stato necessario per ripristinare lo stato precedente all'interruzione.

Avviso: non riparare il database principale dell'amministratore con gkectl repair admin-master dopo un tentativo di upgrade non riuscito. Ciò causerà un cattivo stato del cluster di amministrazione.

Segui questi passaggi:

  1. Prima di iniziare il tentativo di upgrade iniziale, controlla se il piano di controllo dell'amministratore è in stato operativo. Consulta Diagnostica dei problemi relativi ai cluster. Come discusso in quell'argomento, esegui il comando gkectl diagnose cluster per il cluster di amministrazione.

  2. Se il piano di controllo amministrativo non è in stato operativo prima del tentativo di upgrade iniziale, ripara il piano di controllo amministrativo con il comando gkectl repair admin-master.

  3. Quando esegui di nuovo il comando di upgrade dopo che un upgrade è stato interrotto o non è riuscito, utilizza lo stesso bundle e la stessa versione di destinazione utilizzati nel tentativo di upgrade precedente.

Quando esegui di nuovo il comando di upgrade, l'upgrade ripreso ricrea lo stato del cluster di amministrazione dal checkpoint ed esegue di nuovo l'intero upgrade. A partire dalla versione 1.12.0, se il piano di controllo dell'amministratore non è in stato operativo, il processo di upgrade eseguirà direttamente l'upgrade alla versione di destinazione senza tentare di ripristinare il cluster di amministrazione nella versione di origine prima di procedere con l'upgrade.

L'upgrade riprenderà dal punto in cui non è riuscito o è stato interrotto se è disponibile il checkpoint del cluster amministrativo. Se il checkpoint non è disponibile, l'upgrade tornerà a utilizzare il piano di controllo amministrativo e, pertanto, quest'ultimo deve essere in stato operativo per poter procedere con l'upgrade. Dopo un upgrade riuscito, il checkpoint viene rigenerato.

Se gkectl esce in modo imprevisto durante l'upgrade di un cluster di amministrazione, il cluster di tipo non viene ripulito. Prima di eseguire di nuovo il comando di upgrade per riprendere l'upgrade, elimina il cluster di tipo:

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

Dopo aver eliminato il cluster di tipo, esegui di nuovo il comando di upgrade.

Eseguire 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 è admin-ws-config.yaml predefinito. In caso contrario, sostituisci AW_CONFIG_FILE con il percorso del file di configurazione della workstation amministrativa.

Il comando di rollback esegue i seguenti passaggi:

  1. Scarica la versione di rollback di gkeadm.
  2. Esegue il backup della home directory della workstation di amministrazione corrente.
  3. Crea una nuova workstation di amministrazione utilizzando la versione di rollback di gkeadm.
  4. Viene eliminata la workstation di amministrazione originale.

Installare 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, la versione a cui vuoi eseguire l'upgrade.

  1. 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.

  2. In base all'output visualizzato, cerca i seguenti problemi e risolvili in base alle necessità.

    • Se la versione attuale del cluster di amministrazione è inferiore di più di una versione secondaria rispetto a TARGET_VERSION, esegui l'upgrade di tutti i cluster in modo che siano inferiori di una versione secondaria rispetto a 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 a 1.11.x, quindi segui le istruzioni riportate in questo argomento.

    • Se la versione gkectl è precedente alla TARGET_VERSION, esegui l'upgrade della workstation di amministrazione alla TARGET_VERSION.

  3. Una volta stabilito che le versioni di gkectl e del cluster sono appropriate per un upgrade, scarica il bundle.

    Controlla se il file tarball del bundle esiste già sulla workstation di amministrazione.

    stat /var/lib/gke/bundles/gke-onprem-vsphere-TARGET_VERSION.tgz

    Se il bundle non è presente 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/

  4. 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.

  5. Elenca le versioni del cluster disponibili e assicurati che la versione di destinazione sia inclusa nelle versioni del 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.

Risolvere i problemi del 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 stia procedendo con la procedura di upgrade consigliata.

Vedi anche Risoluzione dei problemi relativi alla creazione e all'upgrade dei cluster

Risoluzione dei problemi di upgrade del cluster utente

Supponiamo che tu stia eseguendo l'upgrade di un cluster utente e riscontri un problema con la versione di upgrade. Dall'Assistenza Google viene stabilito che il problema verrà risolto in una release di patch imminente. Procedi nel seguente modo:

  1. Continua a utilizzare la versione corrente per la produzione.
  2. Testa la release della patch in un cluster non di produzione quando viene rilasciata.
  3. Esegui l'upgrade di tutti i cluster utente di produzione alla versione della release della patch quando hai la certezza che funzioni.
  4. Esegui l'upgrade del cluster di amministrazione alla versione della release con patch.

Risolvere un problema di upgrade del cluster di amministrazione

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

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

  1. Esegui l'upgrade dei cluster utente di produzione alla versione 1.12.x.
  2. Mantieni il cluster di amministrazione nella versione precedente e continua a ricevere le patch di sicurezza.
  3. Testa l'upgrade del cluster di amministrazione dalla versione 1.11.x alla versione 1.12.x in un ambiente di test e segnala eventuali problemi.
  4. Se il problema viene risolto da una release con patch 1.12.x, puoi scegliere di eseguire l'upgrade del cluster di amministrazione di produzione a questa release con 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 di dati è quasi pieno, perché il sistema tenta di eseguire il backup della workstation di amministrazione attuale localmente durante l'upgrade a una nuova workstation di amministrazione. Se non riesci a liberare spazio sufficiente sul disco di dati, utilizza il comando gkectl upgrade admin-workstation con il flag aggiuntivo --backup-to-local=false per impedire di eseguire un backup locale della stazione di lavoro di amministrazione corrente.

Interruzione per i carichi di lavoro con PodDisruptionBudget

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

I nodi non riescono a completare il processo di upgrade

Se hai configurato oggetti PodDisruptionBudget che non sono in grado di consentire ulteriori interruzioni, l'upgrade dei nodi alla versione del control plane potrebbe non riuscire dopo ripetuti tentativi. Per evitare questo errore, consigliamo di eseguire l'upgrade di Deployment o HorizontalPodAutoscaler per consentire lo svuotamento del nodo rispettando al contempo la configurazione di PodDisruptionBudget.

Per visualizzare tutti gli oggetti PodDisruptionBudget che non consentono interruzioni:

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

Appendice

Informazioni sulle regole DRS di VMware 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 distribuirli su almeno tre host fisici del data center. A partire dalla versione 1.1.0-gke.6, questa funzionalità viene attivata automaticamente per i nuovi cluster e per quelli esistenti.

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

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 di antiaffinità. 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 e i workload dei cluster utente continuano a funzionare, 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 piani di controllo dei cluster utente. Tuttavia, le connessioni di lunga durata al server API Kubernetes potrebbero interrompersi e dover essere ristabilite. In questi casi, l'autore della chiamata all'API deve riprovare fino a quando non viene stabilita una connessione. Nel peggiore dei casi, può verificarsi un tempo di inattività massimo di un minuto durante un upgrade.
Nodi del cluster utente

Se un upgrade richiede una modifica ai nodi del cluster utente, Google Distributed Cloud ricrea i nodi in modo incrementale e riprogramma i pod in esecuzione su questi nodi. Puoi evitare l'impatto sui tuoi workload configurando PodDisruptionBudgets e regole di anti-affinità appropriati.

Ricrea un file di informazioni, se mancante

Se il file di informazioni di output per la 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: /usr/local/google/home/janedoe/.ssh/gke-admin-workstation
Upgraded from (rollback version): v1.10.0-gke.194
To access your admin workstation:
ssh -i /usr/local/google/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 che corrisponda 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