Sequenziare l'implementazione degli upgrade dei cluster con fasi personalizzate

Questo documento mostra come gestire gli upgrade dei cluster Google Kubernetes Engine (GKE) che utilizzano il sequenziamento dell'implementazione con fasi personalizzate. Crea una sequenza di implementazione utilizzando gruppi di cluster organizzati in parchi risorse e, facoltativamente, sottoinsiemi di cluster di questi parchi risorse. Puoi scegliere la durata del test di stress che vuoi dopo il completamento degli upgrade del cluster in un gruppo (massimo 30 giorni). Puoi includere cluster Autopilot e Standard. Per ulteriori informazioni sul funzionamento di questa funzionalità, consulta Informazioni sul sequenziamento dell'implementazione con fasi personalizzate.

Se gestisci i rollout su più flotte, ti consigliamo di utilizzare un progetto dedicato per ospitare gli oggetti RolloutSequence. Questo progetto funge da genitore e coordinatore per le implementazioni nella sequenza. Questo progetto in genere non fa parte della sequenza, ovvero non contiene flotte o cluster che fanno parte della sequenza.

Prima di iniziare

  • Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente: 

    gcloud init

    Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

  • Assicurati di avere cluster Autopilot o Standard esistenti. Per creare un nuovo cluster, vedi Crea un cluster Autopilot.

  • (Facoltativo) Se non hai già un progetto Google Cloud dedicato per ospitare la configurazione RolloutSequence, creane uno utilizzando la console Google Cloud o un altro metodo.

  • Assicurati di aver attivato le API richieste per le flotte. Queste API devono essere abilitate nei progetti host del parco risorse per creare qualsiasi tipo di sequenza di rollout. Per il progetto host della sequenza di implementazione, abilita l'API gkehub.googleapis.com.

Ruoli obbligatori

Per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come assegnare ruoli.

Per creare o modificare una sequenza di implementazione, devi disporre del ruolo IAM di editor del parco risorse (roles/gkehub.editor) in ogni progetto host del parco risorse nella sequenza di implementazione e nel progetto host della sequenza di implementazione. Questo ruolo fornisce le seguenti autorizzazioni:

  • gkehub.rolloutsequences.create
  • gkehub.rolloutsequences.get
  • gkehub.rolloutsequences.list
  • gkehub.rolloutsequences.update
  • gkehub.rolloutsequences.delete
  • gkehub.fleet.get

Queste autorizzazioni ti consentono di creare, accedere e modificare gli oggetti RolloutSequence e utilizzare le flotte nella sequenza di implementazione.

Se devi registrare o annullare la registrazione di cluster in un parco risorse, devi disporre di tutte le seguenti autorizzazioni:

Per saperne di più sui ruoli IAM con privilegi minimi richiesti per le diverse attività, consulta Ricevere suggerimenti sui ruoli predefiniti con l'assistenza di Gemini.

Configurare una sequenza di implementazione

Per creare una sequenza di implementazione, i cluster devono essere organizzati in gruppi di parchi risorse. Puoi anche creare fasi granulari che possono essere indirizzate a sottoinsiemi specifici di cluster all'interno di un parco risorse utilizzando le etichette Kubernetes. Per indicazioni su come organizzare i cluster, consulta l'esempio di banca della community. Dopo aver organizzato i cluster in gruppi e averli etichettati, se vuoi, crea una sequenza di implementazione definendo l'elenco ordinato delle fasi e il periodo di prova per ogni gruppo.

Organizza i cluster in parchi risorse

In una sequenza di implementazione, ti consigliamo di registrare tutti i cluster nello stesso canale di rilascio. Se i cluster non sono registrati nello stesso canale, GKE seleziona una versione dal canale più conservativo della sequenza. Ad esempio, se i cluster sono registrati sia nel canale stabile che in quello regolare, GKE sceglie la versione del canale stabile. Inoltre, consigliamo di eseguire la stessa versione secondaria in tutti i cluster per poter essere idonei per la stessa versione di destinazione dell'upgrade automatico.

Se hai già organizzato i cluster in parchi risorse, puoi saltare i passaggi seguenti e passare alla sezione Crea sottoinsiemi di cluster.

  1. Raggruppa i cluster in parchi risorse. Puoi organizzare i cluster in base agli ambienti di deployment, ad esempio test, gestione temporanea e produzione (consigliato).
  2. Registra ogni cluster in un parco risorse in base al raggruppamento scelto.

(Facoltativo) Creare sottoinsiemi di cluster

Per fare in modo che una fase della sequenza di implementazione abbia come target cluster specifici, devi etichettare questi cluster.

Ad esempio, per testare una nuova versione su un piccolo sottoinsieme di cluster prima di un'implementazione completa, puoi applicare un'etichetta canary a questi cluster. Per aggiungere l'etichetta canary con il valore true a un cluster utilizzando Google Cloud CLI, esegui questo comando:

gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION\
    --update-labels=canary=true

Sostituisci quanto segue:

Il flag --update-labels=canary=true indica a GKE di applicare l'etichetta canary al cluster .

Per ulteriori informazioni sull'aggiunta di un'etichetta a un cluster, vedi Aggiungere o aggiornare le etichette per i cluster esistenti.

Creare una sequenza di implementazione con fasi personalizzate

Una sequenza di implementazione definisce l'ordine degli upgrade utilizzando le fasi. Per creare una sequenza di implementazione, devi prima creare un file YAML che definisca le fasi e poi creare un RolloutSequence.

Per garantire che la sequenza acquisisca tutti i cluster, ogni flotta deve includere una fase catch-all (una fase senza un selettore di etichette). Questa fase generica acquisisce tutti i cluster rimanenti che GKE non ha selezionato nelle fasi precedenti. Se assegni un singolo cluster a più fasi all'interno di un unico RolloutSequence, per risolvere i conflitti, GKE assegna implicitamente il cluster solo alla prima fase.

La seguente configurazione di esempio crea tre fasi:

  • La prima fase ha come target tutti i cluster nel parco risorse dev. Una volta completato l'upgrade, è previsto un periodo di rodaggio di 7 giorni (un valore di 604800 secondi).
  • La seconda fase ha come target i cluster nel parco risorse prod che hanno l'etichetta canary=true. Una volta completato l'upgrade, è previsto un periodo di assestamento di 7 giorni.
  • La terza fase ha come target i cluster rimanenti nel parco risorse prod. Una volta completato l'upgrade, è previsto un periodo di rodaggio di 7 giorni.

  1. Salva il seguente manifest come rollout-sequence.yaml:

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: resource.labels.canary=='true'
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

    Tieni presente quanto segue:

    • stage: include un parco risorse o un sottoinsieme di cluster all'interno di un parco risorse. I cluster nelle fasi precedenti devono essere completamente sottoposti a upgrade e testati prima che la sequenza proceda alla fase successiva. Tuttavia, se un cluster non ha completato l'upgrade 30 giorni dopo l'inizio della procedura di upgrade, GKE inizia il periodo di sospensione.
    • fleet-projects: un elenco di flotte da cui selezionare i cluster per questa fase. È possibile fare riferimento a un massimo di una flotta per fase. Un parco risorse è identificato dal progetto in cui è ospitato. Questo progetto può essere un progetto diverso da quello in cui si trovano i cluster, se il parco risorse contiene appartenenze tra progetti. Il formato per specificare un progetto del parco risorse è projects/PROJECT_ID.
    • label-selector (facoltativo): seleziona un sottoinsieme di cluster dalle flotte specificate. Questo campo utilizza la sintassi Common Expression Language (CEL) e deve iniziare con resource.labels.
    • soak-duration: il tempo di attesa dopo l'upgrade di tutti i cluster in una fase precedente prima di procedere alla fase successiva. Espresso in secondi.

  2. Per creare la sequenza di implementazione definita nel manifest rollout-sequence.yaml, esegui questo comando:

    gcloud beta container fleet rolloutsequences create ROLLOUT_SEQUENCE_NAME \
    --display-name=DISPLAY_NAME \
    --stage-config=rollout-sequence.yaml

    Sostituisci quanto segue:

    • ROLLOUT_SEQUENCE_NAME: un identificatore immutabile conforme alle specifiche RFC-1034, ad esempio test-rollout-sequence.
    • DISPLAY_NAME: una stringa leggibile per la sequenza di implementazione.

Controllare lo stato di un'implementazione

Dopo aver configurato una sequenza di implementazione, il sistema crea automaticamente oggetti Rollout per gestire gli upgrade. Puoi osservare e monitorare l'avanzamento di questi oggetti utilizzando i comandi Google Cloud CLI.

Elenco implementazioni

Per elencare tutte le implementazioni attive e storiche nel progetto host della sequenza di implementazione, esegui questo comando:

gcloud beta container fleet rollouts list --project=HOST_PROJECT_ID

Sostituisci HOST_PROJECT_ID con l'ID del progetto host della sequenza di implementazione.

Puoi omettere il flag --project=HOST_PROJECT_ID se ti trovi già nel progetto in cui è ospitata la sequenza di implementazione.

L'output è simile al seguente:

NAME                                              STATE      CREATE_TIME
05eb251e4f19269e23-node-1-33-5-gke-1201000-t7mqd  COMPLETED  2025-10-30T20:07:46
05eb251e4f19269e23-kcp-1-33-5-gke-1201000-djwst   COMPLETED  2025-10-30T18:07:06
05eb251e4f19269e23-node-1-33-5-gke-1125000-6bxvu  COMPLETED  2025-10-23T17:46:54
05eb251e4f19269e23-kcp-1-33-5-gke-1125000-2f6ct   RUNNING    2025-10-23T16:41:33

Nell'output precedente, i nomi di implementazione che contengono kcp si riferiscono agli upgrade del piano di controllo, mentre i nomi che contengono node si riferiscono agli upgrade dei nodi. Il segmento del nome dell'implementazione dopo kcp o node deriva dalla versione di GKE.

Descrivere un'implementazione

Per ottenere informazioni dettagliate su un particolare rollout, inclusi la versione di destinazione, lo stato e i cluster che sono stati aggiornati, utilizza il comando describe con l'ID rollout ottenuto dal comando precedente:

gcloud beta container fleet rollouts describe ROLLOUT_ID \
  --project=HOST_PROJECT_ID

Sostituisci quanto segue:

  • ROLLOUT_ID: l'ID del rollout che hai ottenuto quando hai elencato i rollout.
  • HOST_PROJECT_ID: l'ID progetto in cui è ospitata la sequenza di implementazione.

Ad esempio:

gcloud beta container fleet rollouts describe 927e9a989930cf3b55-kcp-1-32-4-gke-1106006 \
  --project=my-hostfleet

L'output è simile al seguente:

createTime: '2025-05-26T11:47:29.909959672Z'
membershipStates:
  projects/dev-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T12:20:55.601542481Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-1234567890-abcdefg-hijklm-nopqrst
      state: SUCCEEDED
    stageAssignment: 1
  projects/dev-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T12:22:57.151203493Z'
    targets:
    - cluster:   projects/dev-project-id/locations/us-central1/clusters/c-2
      operation: //container.googleapis.com/v1/projects/dev-project-id/locations/us-central1/operations/operation-987654321-ghijkl-mno-pqr-stu-vwxyz
      state: SUCCEEDED
    stageAssignment: 1
  projects/prod-project-id/locations/us-central1/memberships/c-1:
    lastUpdateTime: '2025-05-26T13:03:34.134308942Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-567891234-efghij-klm-nopq-rstu-vwxyz
      state: SUCCEEDED
    stageAssignment: 2
  projects/prod-project-id/locations/us-central1/memberships/c-2:
    lastUpdateTime: '2025-05-26T13:06:34.025261641Z'
    targets:
    - cluster: projects/prod-project-id/locations/us-central1/clusters/c-1
      operation: //container.googleapis.com/v1/projects/prod-project-id/locations/us-central1/operations/operation-765432198-01a7b896-67c2-523-6fjjh4-icmdydh
      state: SUCCEEDED
    stageAssignment: 2
name: projects/user-hostfleet/locations/global/rollouts/05eb251e4f19269e23-kcp-1-32-4-gke-1106006
rolloutSequence: projects/project-id/locations/global/rolloutSequences/my-sequence
state: COMPLETED
updateTime: '2025-07-22T07:36:51.052691989Z'
versionUpgrade:
  desiredVersion: 1.32.4-gke.1106006
  type: TYPE_CONTROL_PLANE
stages:
- state: COMPLETED
  endTime: '2025-05-26T12:22:28.828506491Z'
  stageNumber: 1
  startTime: '2025-05-26T11:48:28.772658427Z'
  soakDuration: 600s
- state: COMPLETED
  endTime: '2025-05-26T13:06:20.026390832Z'
  stageNumber: 2
  startTime: '2025-05-26T12:32:38.419372153Z'
  soakDuration: 600s

Informazioni sullo stato di un'implementazione

Quando descrivi un rollout, i campi stages e membershipStates dell'output forniscono lo stato di avanzamento di ogni fase e cluster all'interno di quella fase, rispettivamente.

La tabella seguente elenca i potenziali stati di una fase:

Stato Descrizione
PENDING L'upgrade non è ancora iniziato per questa fase.
RUNNING L'upgrade è in corso per questa fase. Se hai configurato un periodo di manutenzione per i cluster nello stage, GKE attende l'apertura del periodo prima di eseguire l'upgrade dei cluster.
SOAKING Tutti i cluster in questa fase hanno completato gli upgrade e la fase si trova nel periodo di assorbimento configurato.
FORCED_SOAKING L'upgrade ha richiesto più tempo di quello massimo (30 giorni), pertanto GKE ha avviato forzatamente la fase di sospensione. L'upgrade continua sui cluster rimanenti.
COMPLETED La fase di test è terminata e l'implementazione procede alla fase successiva.

La tabella seguente elenca i potenziali stati di un cluster all'interno di una sequenza:

Stato Descrizione
PENDING L'upgrade è in attesa su questo cluster.
INELIGIBLE Questo cluster non è idoneo per l'upgrade, probabilmente a causa di una discrepanza di versione. Il motivo di non idoneità è indicato nell'output.
RUNNING L'upgrade è in corso su questo cluster.
SUCCEEDED L'upgrade è stato completato correttamente su questo cluster.
FAILED L'upgrade non è riuscito su questo cluster. I target non riusciti vengono ritentati all'infinito mentre la fase è attiva (in stato RUNNING o FORCED_SOAKING).

Gestisci una sequenza di implementazione

Puoi controllare gli upgrade automatici dei cluster con la sequenza di implementazione in diversi modi, come spiegato nelle sezioni seguenti.

Elenca le sequenze di implementazione

Per elencare tutte le sequenze di implementazione nel progetto host, esegui questo comando:

gcloud beta container fleet rolloutsequences list --project=HOST_PROJECT_ID

Sostituisci HOST_PROJECT_ID con l'ID del progetto host della sequenza di implementazione.

Descrivere una sequenza di implementazione

Per visualizzare i dettagli di una sequenza di implementazione specifica, esegui questo comando:

gcloud beta container fleet rolloutsequences describe ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Sostituisci quanto segue:

  • ROLLOUT_SEQUENCE_NAME: il nome della sequenza di implementazione.
  • HOST_PROJECT_ID: l'ID del progetto host della sequenza di implementazione.

L'output è simile al seguente:

createTime: '2025-10-23T16:40:16.403871189Z'
displayName: my-display-name
name: projects/HOST_PROJECT_ID/locations/global/rolloutSequences/ROLLOUT_SEQUENCE_NAME
stages:
- clusterSelector:
    labelSelector: resource.labels.canary=='true'
  fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 600s
- fleetProjects:
  - projects/FLEET_PROJECT_ID
  soakDuration: 300s
uid: 5c5b2ac8-9d76-45f9-92ca-5e6bd3fbcaef
updateTime: '2025-10-23T17:11:57.285678399Z'

Modifica una sequenza di implementazione

Puoi modificare una sequenza di implementazione esistente modificando il file di configurazione YAML in cui hai definito la sequenza. Ad esempio, puoi aggiornare il tempo di ammollo per una fase o aggiornare la fase per modificare l'ordine degli upgrade. Dopo aver modificato il file, applica le modifiche.

Ad esempio, se hai definito la sequenza di implementazione originale in un file denominato rollout-sequence.yaml, modificalo in base alle esigenze. Quindi, esegui il comando seguente:

gcloud beta container fleet rolloutsequences update test-rollout-sequence \
  --display-name="My Updated Rollout Sequence" \
  --stage-config=rollout-sequence.yaml

Elimina una sequenza di implementazione

Per eliminare una sequenza di implementazione, esegui questo comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME \
  --project=HOST_PROJECT_ID

Sostituisci quanto segue:

  • ROLLOUT_SEQUENCE_NAME con il nome della sequenza di implementazione.
  • HOST_PROJECT_ID: l'ID del progetto host della sequenza di implementazione.

Quando elimini una sequenza di implementazione, vengono annullate tutte le implementazioni in corso per quella sequenza. I cluster che facevano parte della sequenza tornano al comportamento di upgrade automatico predefinito per il canale di rilascio registrato.

Eseguire la migrazione di una sequenza di implementazione esistente per utilizzare fasi personalizzate

Se utilizzi la versione di implementazione basata sulla flotta disponibile a livello generale di sequenziamento, puoi eseguire la migrazione a una sequenza che utilizza fasi personalizzate creando un nuovo RolloutSequence che fa riferimento alle tue flotte esistenti.

Prima di eseguire la migrazione della sequenza, ti consigliamo di creare una copia della configurazione della sequenza di implementazione attuale.

Per eseguire la migrazione della sequenza di implementazione:

  1. Crea un progetto Google Cloud dedicato per ospitare la sequenza di implementazione. Questo progetto in genere non fa parte della sequenza, ovvero non contiene parchi risorse o cluster che fanno parte della sequenza.
  2. Se vuoi che la sequenza di implementazione includa cluster specifici all'interno di un parco risorse, aggiungi etichette a questi cluster. Questo passaggio è facoltativo.

  3. Segui le istruzioni riportate in Creare una sequenza di implementazione con fasi personalizzate.

    Ad esempio, il seguente manifest, denominato rollout-sequence-migrate.yaml, fa riferimento alle flotte esistenti in una sequenza di implementazione precedente. Questo manifest descrive tre fasi, tra cui una fase canary nel parco risorse prod:

    - stage:
  fleet-projects:
  - projects/dev
  soak-duration: 604800s
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s
  label-selector: canary=true
- stage:
  fleet-projects:
  - projects/prod
  soak-duration: 604800s

Subito dopo aver definito un nuovo RolloutSequence per i tuoi parchi risorse, GKE inizia l'upgrade dei parchi risorse in base alla nuova sequenza e rimuove la configurazione precedente.

Eseguire la migrazione di una sequenza di implementazione con fasi personalizzate alla sequenza di implementazione precedente

Questa sezione descrive come ripristinare la sequenza di implementazione con fasi personalizzate al modello di sequenza basato sul parco risorse generalmente disponibile. Questo processo prevede l'eliminazione del nuovo RolloutSequence e il ripristino della configurazione originale basata sulla flotta.

Impedire l'upgrade fuori sequenza durante la migrazione

Per evitare upgrade involontari o fuori sequenza durante la riconfigurazione della sequenza, applica un'esclusione dalla manutenzione ai cluster di produzione. Questo passaggio mette temporaneamente in pausa tutti gli upgrade automatici su questi cluster. Ad esempio, puoi configurare un'esclusione dalla manutenzione di tipo no upgrades sui cluster di produzione.

Elimina la sequenza di implementazione

Elimina l'oggetto RolloutSequence che gestisce i tuoi cluster. Questa eliminazione disattiva la funzionalità delle fasi personalizzate.

Per eliminare RolloutSequence, esegui questo comando:

gcloud beta container fleet rolloutsequences delete ROLLOUT_SEQUENCE_NAME

Sostituisci ROLLOUT_SEQUENCE_NAME con il nome della sequenza di implementazione.

Ripristina la configurazione della sequenza di implementazione precedente (senza fasi personalizzate)

Dopo aver eliminato RolloutSequence, puoi ripristinare la configurazione originale basata sul parco risorse. Questa procedura prevede la ricreazione delle funzionalità clusterupgrade con i relativi parametri originali, inclusi i link upstreamFleet e i tempi di immersione per ogni flotta nella sequenza. Per saperne di più, vedi Creare una sequenza di implementazione.

Rimuovi le esclusioni dalla manutenzione

Dopo aver ripristinato la configurazione originale della sequenza di implementazione basata sulla flotta, rimuovi l'esclusione per la manutenzione che hai applicato nel primo passaggio di questa sezione. GKE riprende gli upgrade automatici, ora regolati dalla sequenza basata sul parco risorse ripristinata.

Passaggi successivi