Configura periodi di manutenzione ed esclusioni

Utilizza i periodi di manutenzione e le esclusioni dalla manutenzione per controllare quando può essere eseguita la manutenzione automatica dei cluster, ad esempio gli upgrade automatici, nei cluster Google Kubernetes Engine (GKE). Prima di configurare queste policy di manutenzione, assicurati di esaminare le modifiche che rispettano e non rispettano le policy di manutenzione di GKE.

Prima di iniziare

Prima di iniziare, assicurati di aver eseguito le seguenti attività:

  • Abilita l'API Google Kubernetes Engine.
    • Abilita l'API Google Kubernetes Engine
  • Se vuoi utilizzare Google Cloud CLI per questa attività, installala e poi inizializza gcloud CLI. Se hai già installato gcloud CLI, scarica l'ultima versione eseguendo il gcloud components update comando. Le versioni precedenti di gcloud CLI potrebbero non supportare l'esecuzione dei comandi in questo documento.

Configurare un periodo di manutenzione

Per configurare un periodo di manutenzione, specifica quando inizia, quanto dura e con quale frequenza si ripete. Ad esempio, puoi configurare un periodo di manutenzione che si ripete settimanalmente dal lunedì al venerdì per quattro ore al giorno.

Puoi configurare un periodo di manutenzione utilizzando la Google Cloud console o la Google Cloud CLI.

Considerazioni sulla configurazione di un periodo di manutenzione

Quando configuri un periodo di manutenzione, segui queste indicazioni:

  • Scopri quali tipi di eventi di manutenzione rispettano e non rispettano i periodi di manutenzione di GKE. Per saperne di più, consulta Manutenzione automatica che rispetta le policy di manutenzione di GKE e Manutenzione automatica che non rispetta le policy di manutenzione di GKE.
  • Puoi configurare un solo periodo di manutenzione per un cluster e la configurazione di un nuovo periodo sovrascrive quello precedente.
  • Devi consentire almeno 48 ore di disponibilità per la manutenzione in una finestra temporale continua di 32 giorni. Sono considerate soltanto finestre di disponibilità contigue di almeno quattro ore.
  • Quando utilizzi la Google Cloud console, le ore vengono sempre visualizzate utilizzando il fuso orario locale.
  • Le ricorrenze dei giorni della settimana sono sempre basate sul fuso orario UTC. Di conseguenza, ti consigliamo di impostare i periodi di manutenzione che coinvolgono tali ricorrenze interamente in UTC, tramite gcloud CLI. Sebbene sia possibile utilizzare l'ora locale quando imposti i flag, il fuso orario non verrà memorizzato. Ad esempio, se il tuo fuso orario è UTC+6 e vuoi che un periodo di manutenzione inizi alle 02:00 di mercoledì nel tuo fuso orario, specifica un valore UTC di 20:00 di martedì. Per saperne di più, consulta Fusi orari per i periodi di manutenzione.

Configurare un periodo di manutenzione

Puoi configurare un periodo di manutenzione su un cluster esistente utilizzando la Google Cloud console o gcloud CLI.

gcloud

Crea o aggiorna un periodo di manutenzione per un cluster esistente:

gcloud container clusters update CLUSTER_NAME \
    --maintenance-window-start START_TIME \
    --maintenance-window-end END_TIME \
    --maintenance-window-recurrence RRULE

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster.
  • START_TIME: la data e l'ora in cui è abilitato il periodo di manutenzione ricorrente, espresso come valore DTSTART RFC-5545. Dopo questo orario, il periodo di manutenzione si ripete in base a RRULE. START_TIME indica anche l'ora del giorno in cui inizia il periodo di manutenzione.
  • END_TIME: l'ora di fine per il calcolo della durata del periodo di manutenzione, espressa come quantità di tempo dopo START_TIME, nello stesso formato. Il valore di END_TIME deve essere nel futuro, rispetto a START_TIME. Questa operazione calcola solo la durata del periodo e non imposta quando il periodo di manutenzione smette di ripetersi. I periodi di manutenzione smettono di ripetersi solo quando vengono rimossi.
  • RRULE: la ricorrenza del periodo di manutenzione, espressa da una RFC-5545 RFC-5545. Si tratta di un formato flessibile con diversi modi per specificare le regole di ricorrenza, che determinano il giorno in cui inizia il periodo di manutenzione. Ad esempio, puoi specificare una ricorrenza di determinate ore a settimana o al mese. Se la data END_TIME è successiva alla data START_TIME, il periodo di manutenzione si estende su più giorni. Ad esempio, un periodo di manutenzione che inizia di domenica continua fino a lunedì.

Ad esempio, il seguente comando modifica un cluster denominato my-cluster con un periodo di manutenzione abilitato alle 02:00 UTC di venerdì 23 agosto 2024. Questo periodo di manutenzione si ripete settimanalmente ogni lunedì e venerdì e termina 30 ore dopo. La prima occorrenza del periodo di manutenzione inizia venerdì 23 agosto alle 02:00 e termina sabato 24 agosto alle 08:00. Scopri di più sulla formattazione di date e ore.

gcloud container clusters update my-cluster \
    --maintenance-window-start 2024-08-23T02:00:00Z \
    --maintenance-window-end 2024-08-24T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,FR'

Per altri scenari, consulta gli esempi di periodi di manutenzione.

Console

Per creare o modificare un periodo di manutenzione per un cluster esistente:

  1. Vai alla pagina Google Kubernetes Engine nella Google Cloud console.

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. In Automazione, fai clic su Modifica policy di manutenzione accanto al campo Periodo di manutenzione.

  4. Seleziona la casella di controllo Abilita periodo di manutenzione.

  5. Seleziona l'ora di inizio e la durata, quindi seleziona i giorni della settimana in cui si verifica il periodo di manutenzione. Per modificare direttamente RRule, seleziona Editor personalizzato.

  6. Fai clic su Salva modifiche.

Completare manualmente la manutenzione incompleta

Se un upgrade o un'altra manutenzione automatica richiede più tempo del periodo di manutenzione per essere completata, GKE tenta di interrompere le attività di manutenzione in corso e le riprende durante la successiva occorrenza del periodo di manutenzione. Se un upgrade automatico viene annullato e hai abilitato gli upgrade automatici dei nodi, i nodi potrebbero essere in uno stato di versione mista, ma il cluster dovrebbe funzionare normalmente.

Per eseguire l'upgrade manuale del cluster o annullare o eseguire il rollback di un upgrade parziale, visita Eseguire l'upgrade manuale di un cluster.

Rimuovere un periodo di manutenzione

gcloud

Rimuovi un periodo di manutenzione da un cluster:

gcloud container clusters update CLUSTER_NAME --clear-maintenance-window

Sostituisci CLUSTER_NAME con il nome del cluster esistente.

Console

Per rimuovere un periodo di manutenzione:

  1. Vai alla pagina Google Kubernetes Engine nella Google Cloud console.

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. In Automazione, fai clic su Modifica policy di manutenzione accanto al campo Periodo di manutenzione.

  4. Deseleziona la casella di controllo Abilita periodo di manutenzione.

  5. Fai clic su Salva modifiche.

Esempi di periodi di manutenzione

Gli esempi seguenti illustrano alcuni dei diversi modi in cui puoi configurare un periodo di manutenzione. Vengono mostrati solo i flag pertinenti, perché i flag utilizzano la stessa sintassi per creare un nuovo cluster o aggiornarne uno esistente.

Fine settimana, a partire dal 22 agosto 2026

In questo esempio, la differenza tra i timestamp di inizio e fine è di due giorni interi, quindi il periodo di manutenzione viene eseguito per l'intero fine settimana, durante il sabato e la domenica. Se vuoi che il periodo abbia una durata diversa da esattamente 48 ore, modifica -start per cambiare l'inizio del periodo o -end per modificare la durata totale del periodo.

  --maintenance-window-start 2026-08-22T00:00:00Z \
  --maintenance-window-end 2026-08-24T00:00:00Z \
  --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=SA'

Tutti i giorni nei giorni feriali dalle 09:00 alle 17:00 UTC-4

Questo esempio mostra come avere un periodo di manutenzione giornaliero, ma saltare i fine settimana. Questo esempio specifica un fuso orario non UTC.

   --maintenance-window-start 2026-09-02T09:00:00-04:00 \
   --maintenance-window-end 2026-09-02T17:00:00-04:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR'

Settimanalmente alle 16:00 per 8 ore, UTC-7

Se non specifichi un fuso orario per --maintenance-window-start, viene utilizzata l'ora locale, come configurato nel tuo Google Cloud account. La Google Cloud console utilizza sempre l'ora locale.

   --maintenance-window-start 2026-08-13T16:00:00-7:00 \
   --maintenance-window-end 2026-08-14T00:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY'

Giorni feriali di notte

Questo esempio mostra un periodo di manutenzione giornaliero che viene eseguito durante la notte tra i giorni lavorativi nel fuso orario UTC-7. In questo esempio, il periodo viene eseguito dalle 20:00 di sera alle 04:00 del mattino successivo.

   --maintenance-window-start 2026-08-15T20:00:00-7:00 \
   --maintenance-window-end 2026-08-16T04:00:00-7:00 \
   --maintenance-window-recurrence 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH'

Configurare un'esclusione dalla manutenzione

Per configurare un'esclusione dalla manutenzione per il cluster, devi specificare quanto segue:

  • Nome: il nome dell'esclusione (facoltativo).
  • Ora di inizio: la data e l'ora in cui deve iniziare il periodo di esclusione. L'ora di inizio deve essere ora o in futuro.
  • Ora di fine: la data e l'ora in cui deve terminare il periodo di esclusione. Consulta la tabella seguente per le limitazioni relative alla durata di un periodo di esclusione per ciascuno degli ambiti disponibili. Per determinati ambiti di esclusione dalla manutenzione, puoi impostare l'ora di fine per monitorare la data di fine dell'assistenza per la versione secondaria del cluster.
  • Ambito: l'ambito degli upgrade automatici da limitare. Consulta la tabella seguente che elenca gli ambiti di esclusione disponibili.
Ambito Control plane Nodi Durata massima dell'esclusione
Upgrade secondario automatico Upgrade automatico delle patch Upgrade secondario automatico Upgrade automatico delle patch
Nessun upgrade (impostazione predefinita) Non consentito Non consentito Non consentito Non consentito Non può superare i 30 giorni.
Nessun upgrade secondario Non consentito Consentito Non consentito Consentito Per i cluster registrati nei canali Rapido, Regolare o Stabile, non può estendersi oltre la fine dell'assistenza standard. Per i cluster registrati nel canale Esteso, non può estendersi oltre la fine dell'assistenza estesa della versione secondaria. Puoi configurare l'ora di fine per monitorare la fine dell' assistenza per la versione secondaria del cluster. L'esclusione dalla manutenzione termina quando la versione secondaria del cluster raggiunge la fine dell'assistenza. Per saperne di più, consulta In che modo un'esclusione dalla manutenzione monitora la fine dell'assistenza.
Nessun upgrade secondario o di nodi Non consentito Consentito Non consentito Non consentito Per i cluster registrati nei canali Rapido, Regolare o Stabile, non può estendersi oltre la fine dell'assistenza standard. Per i cluster registrati nel canale Esteso, non può estendersi oltre la fine dell'assistenza estesa della versione secondaria. Puoi configurare l'ora di fine per monitorare la fine dell' assistenza per la versione secondaria del cluster. L'esclusione dalla manutenzione termina quando la versione secondaria del cluster raggiunge la fine dell'assistenza. Per saperne di più, consulta In che modo un'esclusione dalla manutenzione monitora la fine dell'assistenza.

Come configurare un'esclusione dalla manutenzione

Puoi creare un cluster con un'esclusione dalla manutenzione utilizzando la Google Cloud console, oppure configurare un'esclusione dalla manutenzione per un cluster esistente utilizzando la Google Cloud console o gcloud CLI.

Con gcloud CLI, puoi facoltativamente configurare l'ora di fine di un'esclusione dalla manutenzione per monitorare la data di fine dell'assistenza della versione secondaria del cluster.

Creare un cluster con un'esclusione dalla manutenzione

Puoi configurare un'esclusione dalla manutenzione quando crei un nuovo cluster utilizzando la Google Cloud console. Questa attività non può essere eseguita in gcloud CLI.

Per creare un nuovo cluster con un'esclusione dalla manutenzione:

  1. Nella Google Cloud console, vai alla pagina Crea un cluster Autopilot.

    Vai a Crea un cluster Autopilot

    Puoi completare questa attività anche creando un cluster Standard.

  2. Configura il cluster.

  3. Nel riquadro di navigazione, in Cluster, fai clic su Automazione.

  4. In Esclusioni dalla manutenzione, fai clic su Aggiungi esclusione dalla manutenzione.

  5. Seleziona l'ambito, un'ora di inizio e un'ora di fine.

  6. Fai clic su Crea.

Puoi vedere un esempio di esclusione dalla manutenzione per il Black Friday.

Configurare un'esclusione dalla manutenzione per un cluster esistente

Puoi configurare un'esclusione dalla manutenzione su un cluster esistente utilizzando la Google Cloud console o gcloud CLI. Con gcloud CLI, puoi facoltativamente configurare l'ora di fine di un'esclusione dalla manutenzione per monitorare la data di fine dell'assistenza della versione secondaria del cluster.

gcloud

  • Ora di fine fissa: configura un'esclusione dalla manutenzione per un cluster esistente con un'ora di fine fissa:

    gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    [--add-maintenance-exclusion-start START_DATE_TIME \]
    --add-maintenance-exclusion-end END_DATE_TIME \
    --add-maintenance-exclusion-scope SCOPE

    Sostituisci quanto segue:

    • CLUSTER_NAME: il nome del tuo cluster.
    • EXCLUSION_NAME: il nome dell'esclusione dalla manutenzione.
    • START_DATE_TIME: facoltativamente, imposta la data e l'ora di inizio dell'esclusione per un'ora futura. Se ometti questo flag, l'esclusione dalla manutenzione inizia immediatamente.
    • END_DATE_TIME: la data e l'ora di fine dell'esclusione.
    • SCOPE: l'ambito dell'upgrade da escludere, che può essere uno dei seguenti valori: no_upgrades, no_minor_upgrades o no_minor_or_node_upgrades.

    Per visualizzare i formati di data e ora supportati, esegui gcloud topic datetimes.

  • Termina alla fine dell'assistenza: configura un'esclusione dalla manutenzione che monitora la data di fine dell'assistenza della versione secondaria del cluster:

    gcloud container clusters update CLUSTER_NAME \
    --add-maintenance-exclusion-name EXCLUSION_NAME \
    [--add-maintenance-exclusion-start START_DATE_TIME \]
    --add-maintenance-exclusion-until-end-of-support \
    --add-maintenance-exclusion-scope SCOPE

Console

Per configurare un'esclusione dalla manutenzione per un cluster esistente:

  1. Vai alla pagina Google Kubernetes Engine nella Google Cloud console.

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. In Automazione, accanto al campo Esclusioni dalla manutenzione, fai clic su Modifica esclusioni dalla manutenzione.

  4. In Esclusioni dalla manutenzione, fai clic su Aggiungi esclusione dalla manutenzione.

  5. Seleziona l'ambito, un'ora di inizio e un'ora di fine.

  6. Fai clic su Salva modifiche.

Rimuovere un'esclusione dalla manutenzione

Puoi rimuovere le esclusioni dalla manutenzione utilizzando la Google Cloud console o la gcloud CLI.

gcloud

Rimuovi un'esclusione dalla manutenzione esistente:

gcloud container clusters update CLUSTER_NAME \
    --remove-maintenance-exclusion EXCLUSION_NAME

Sostituisci quanto segue:

  • CLUSTER_NAME: il nome del cluster esistente.
  • EXCLUSION_NAME: il nome dell'esclusione dalla manutenzione da rimuovere.

Console

Per rimuovere un'esclusione dalla manutenzione da un cluster esistente:

  1. Vai alla pagina Google Kubernetes Engine nella Google Cloud console.

    Vai a Google Kubernetes Engine

  2. Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.

  3. In Automazione, accanto al campo Esclusioni dalla manutenzione, fai clic su Modifica esclusioni dalla manutenzione.

  4. In Esclusioni dalla manutenzione, fai clic su Elimina elemento accanto al campo Ora di fine per l'esclusione che vuoi rimuovere.

  5. Fai clic su Salva modifiche.

Per visualizzare tutte le esclusioni dalla manutenzione su un cluster, puoi visualizzare la policy di manutenzione del cluster.

Esempio di esclusione dalla manutenzione

L'esempio seguente impedisce la manutenzione nei quattro giorni che vanno dal Black Friday al Cyber Monday, il periodo di vendita con il volume più alto dell'anno per molte attività di vendita al dettaglio. Questo esempio mostra come impedire che si verifichi un periodo di manutenzione dal Black Friday 2021 (26 novembre 2021) al Cyber Monday 2021 (29 novembre 2021), da mezzanotte Eastern (UTC-5) alle 23:59:59 Pacific (UTC-8).

gcloud container clusters update sample-cluster \
    --add-maintenance-exclusion-name black-friday \
    --add-maintenance-exclusion-start 2021-11-26T00:00:00-05:00 \
    --add-maintenance-exclusion-end 2021-11-29T23:59:59-08:00 \
    --add-maintenance-exclusion-scope no_upgrades

Visualizzare la policy di manutenzione di un cluster

Per visualizzare la policy di manutenzione di un cluster, incluso se ha un periodo di manutenzione e tutte le relative esclusioni dalla manutenzione, utilizza il seguente comando:

gcloud container clusters describe CLUSTER_NAME

Identificare i cluster senza un periodo di manutenzione configurato

GKE identifica i cluster per i quali non hai configurato un periodo di manutenzione in modo che tu possa scegliere un periodo ricorrente in cui GKE può eseguire la manutenzione del cluster. Ti consigliamo di configurare un periodo di manutenzione per assicurarti che GKE esegua gli upgrade automatici e altre attività di manutenzione del cluster che rispettano le policy di manutenzione quando è più conveniente per il tuo ambiente cluster.

GKE fornisce queste indicazioni con un approfondimento e un suggerimento tramite il servizio Recommender. Per saperne di più su come gestire approfondimenti e suggerimenti di Recommender, consulta Ottimizzare l'utilizzo di GKE con approfondimenti e suggerimenti.

Per trovare i cluster senza un periodo di manutenzione configurato, puoi utilizzare uno dei seguenti metodi:

  • Utilizza la Google Cloud console.
  • Utilizza gcloud CLI o l'API Recommender, specificando il CLUSTER_MAINTENANCE_WINDOW_AND_EXCLUSIONS sottotipo di recommender.

Per istruzioni, consulta Visualizzare approfondimenti e suggerimenti.

Per implementare questo suggerimento, configura un periodo di manutenzione window.

Risoluzione dei problemi

Utilizza le seguenti informazioni per risolvere i problemi comuni relativi a periodi di manutenzione ed esclusioni.

Il periodo di manutenzione impedisce il completamento dell'aggiornamento dei nodi

Se il cluster non riesce a completare gli aggiornamenti dei nodi, ad esempio gli upgrade della versione dei nodi, entro il periodo di manutenzione pianificato, la velocità degli upgrade può rallentare o il completamento delle modifiche ai nodi può essere ritardato. Potresti dover sperimentare con la configurazione per trovare l'equilibrio ottimale tra velocità e interruzione per il tuo ambiente. I fattori che possono influire sulla velocità di upgrade includono:

La limitazione dell'ambito delle esclusioni dalla manutenzione può essere applicata solo ai canali di rilascio

Quando limiti l'ambito degli upgrade automatici in un'esclusione dalla manutenzione, il cluster deve essere registrato in un canale di rilascio, altrimenti potresti riscontrare i seguenti errori:

ERROR: (gcloud.container.clusters.update) INVALID_ARGUMENT: Cannot update to
STATIC channel since following maintenancePolicy.maintenanceExclusions can only
apply to release channels. Please remove those maintenance exclusions.

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=MaintenancePolicy.maintenanceExclusions["no"] could not apply to cluster
in STATIC channel, only no_upgrades exclusions are allowed in STATIC channel.

Le esclusioni dalla manutenzione superano il limite

Puoi specificare un massimo di 3 esclusioni dalla manutenzione che escludono tutti gli upgrade (ovvero un ambito di "nessun upgrade"), altrimenti riceverai il seguente errore:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of active maintenance exclusions exceeds limit (3).

Puoi specificare un massimo di 20 esclusioni dalla manutenzione in totale, altrimenti riceverai il seguente errore:

ERROR: (gcloud.container.clusters.update) ResponseError: code=400,
message=Number of total maintenance exclusions exceeds limit (20).

Passaggi successivi