Configura periodi di manutenzione ed esclusioni

Autopilot Standard

Utilizza periodi di manutenzione ed esclusioni di manutenzione per controllare quando può essere eseguita la manutenzione automatica dei cluster, ad esempio gli upgrade automatici, sui cluster Google Kubernetes Engine (GKE). Prima di configurare questi criteri di manutenzione, assicurati di rivedere quali modifiche fanno e non rispettano i criteri 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à, installa e initialize gcloud CLI. Se hai già installato gcloud CLI, scarica la versione più recente eseguendo gcloud components update.
Nota: per le installazioni esistenti dell'interfaccia a riga di comando gcloud, assicurati di impostare le proprietà compute/region e compute/zone. Impostando le località predefinite, puoi evitare errori nellgcloud CLI come segue: One of [--zone, --region] must be supplied: Please specify location.

Configura un periodo di manutenzione

Per configurare un periodo di manutenzione, specifica quando inizia, la relativa durata e la frequenza con cui 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 console Google Cloud o 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 scoprire di più, consulta Manutenzione automatica che rispetta i criteri di manutenzione di GKE e Manutenzione automatica che non rispetta i criteri di manutenzione di GKE.
Puoi configurare un solo periodo di manutenzione per un cluster e configurare una nuova finestra sovrascriverà quello precedente.
Devi consentire almeno 48 ore di disponibilità per la manutenzione in una finestra temporale di 32 giorni. Sono considerate soltanto finestre di disponibilità contigue di almeno quattro ore.
Quando si utilizza la console Google Cloud, gli orari sono sempre visualizzati nel fuso orario locale.
Le occorrenze dei giorni della settimana sono sempre basate sul fuso orario UTC. Di conseguenza, ti consigliamo di impostare i periodi di manutenzione che coinvolgono queste ricorrenza interamente in UTC, tramite gcloud CLI. Per l'impostazione dei flag puoi usare l'ora locale, ma il fuso orario non viene memorizzato. Ad esempio, se il tuo fuso orario è UTC+6 e vuoi che il periodo di manutenzione inizi alle 02:00 del mercoledì nel tuo fuso orario, specifica un valore UTC pari alle 20:00 il martedì. Per scoprire di più, consulta Fusi orari per i periodi di manutenzione.
Se il cluster non riesce a completare gli upgrade dei nodi nella finestra di manutenzione pianificata, la frequenza degli upgrade potrebbe rallentare. Potrebbe essere necessario sperimentare la configurazione per trovare l'equilibrio ottimale tra velocità e interruzione per il tuo ambiente. I fattori che possono influire sulla frequenza di upgrade includono:
- Disponibilità di manutenzione ridotta (ad es. periodi di manutenzione brevi).
- Pool di nodi standard di grandi dimensioni.
- La configurazione della strategia di upgrade dei nodi che dà la priorità alle interruzioni minime rispetto alla velocità.
- Alcune scelte di configurazione dei pod. Per ulteriori informazioni, consulta Considerazioni sulla durata dell'upgrade del nodo.

Crea un cluster Standard con un periodo di manutenzione semplice

Puoi creare un semplice periodo di manutenzione nellgcloud CLI specificando il flag --maintenance-window. Questo flag consente di specificare un periodo di manutenzione giornaliera di 4 ore utilizzando un formato semplificato. Per creare un cluster Autopilot con un periodo di manutenzione, utilizza la console Google Cloud.

Crea un nuovo cluster Standard con un semplice periodo di manutenzione:

gcloud container clusters create CLUSTER_NAME \
    --maintenance-window START_TIME

Sostituisci quanto segue:

CLUSTER_NAME: il nome del nuovo cluster.
START_TIME: un timestamp di 24 ore nel fuso orario UTC, ad esempio 16:00.

Il periodo di manutenzione viene eseguito ogni giorno al START_TIME specificato e per quattro ore.

Crea un periodo di manutenzione personalizzato

Puoi creare un periodo di manutenzione che si verifica in determinati momenti della settimana o del mese utilizzando parametri aggiuntivi spiegati in questa sezione.

Ad esempio, il seguente comando crea un cluster denominato my-cluster con un periodo di manutenzione abilitato alle 02:00 UTC di mercoledì 19 agosto 2026. Questo periodo di manutenzione inizia il lunedì e il venerdì e termina 30 ore dopo. La prima edizione del periodo di manutenzione inizia venerdì 21 agosto alle ore 02:00 e termina sabato 22 agosto alle ore 08:00. Scopri di più sulla formattazione di date e ore.

gcloud container clusters create my-cluster \
    --maintenance-window-start 2026-08-19T02:00:00Z \
    --maintenance-window-end 2026-08-20T08:00:00Z \
    --maintenance-window-recurrence 'FREQ=WEEKLY:BYDAY=MO,FR'

Per altri scenari, consulta i periodi di manutenzione di esempio.

Crea un cluster con un periodo di manutenzione

Puoi creare un nuovo cluster Standard con un periodo di manutenzione utilizzando gcloud CLI o la console Google Cloud. Per creare un nuovo cluster Autopilot con un periodo di manutenzione, utilizza la console Google Cloud.

gcloud

Crea un nuovo cluster Standard con un periodo di manutenzione:

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

Sostituisci quanto segue:

CLUSTER_NAME: il nome del nuovo cluster.
START_TIME: data e ora in cui è abilitata la periodo di manutenzione ricorrente, espresse come valore DTSTART RFC-5545. Dopo questo periodo di tempo, il periodo di manutenzione si ripete in base alle RRULE. L'START_TIME indica anche a che ora del giorno inizia il periodo di manutenzione.
END_TIME: l'ora di fine per il calcolo della durata del periodo di manutenzione, come espressa dalla quantità di tempo successiva al giorno START_TIME, nello stesso formato. Il valore di END_TIME deve essere nel futuro, relativo a START_TIME.
RRULE: la ricorrenza del periodo di manutenzione, come espressa da una RRULE RFC-5545. Si tratta di un formato flessibile con vari modi per specificare le regole di ricorrenza, determinando il giorno di inizio del periodo di manutenzione. Ad esempio, puoi specificare una ricorrenza in determinati momenti di una settimana o di un mese. Se la data END_TIME è successiva alla data START_TIME, il periodo di manutenzione comprende più giorni. Ad esempio, un periodo di manutenzione da domenica continua fino a lunedì.

Console

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Fai clic su Crea.
Configura il cluster.
Nel riquadro di navigazione, in Cluster, fai clic su Automazione.
Seleziona la casella di controllo Attiva il periodo di manutenzione.
Seleziona l'ora di inizio e la durata, poi seleziona i giorni della settimana in cui si verifica il periodo di manutenzione. Per modificare direttamente la specifica della regola di ricorrenza (RRule), seleziona Editor personalizzato.
Fai clic su Crea.

Configura un periodo di manutenzione per un cluster esistente

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 nuovo cluster.
START_TIME: data e ora in cui è abilitata la periodo di manutenzione ricorrente, espresse come valore DTSTART RFC-5545. Dopo questo periodo di tempo, il periodo di manutenzione si ripete in base alle RRULE. L'START_TIME indica anche a che ora del giorno inizia il periodo di manutenzione.
END_TIME: l'ora di fine per il calcolo della durata del periodo di manutenzione, come espressa dalla quantità di tempo successiva al giorno START_TIME, nello stesso formato. Il valore di END_TIME deve essere nel futuro, relativo a START_TIME.
RRULE: la ricorrenza del periodo di manutenzione, come espressa da una RRULE RFC-5545. Si tratta di un formato flessibile con vari modi per specificare le regole di ricorrenza, determinando il giorno di inizio del periodo di manutenzione. Ad esempio, puoi specificare una ricorrenza in determinati momenti di una settimana o di un mese. Se la data END_TIME è successiva alla data START_TIME, il periodo di manutenzione comprende più giorni. Ad esempio, un periodo di manutenzione da domenica continua fino a lunedì.

Console

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

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.
In Automazione, fai clic su Modifica criterio di manutenzione accanto al campo Periodo di manutenzione.
Seleziona la casella di controllo Attiva il periodo di manutenzione.
Seleziona l'ora di inizio e la durata, poi seleziona i giorni della settimana in cui si verifica il periodo di manutenzione. Per modificare direttamente la regola RRule, seleziona Editor personalizzato.
Fai clic su Salva modifiche.

Termina manualmente la manutenzione incompleta

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

Per eseguire manualmente l'upgrade del cluster oppure annullare o eseguire il rollback di un upgrade parziale, consulta 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:

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.
In Automazione, fai clic su Modifica criterio di manutenzione accanto al campo Periodo di manutenzione.
Deseleziona la casella di controllo Attiva periodo di manutenzione.
Fai clic su Salva modifiche.

Esempi di periodi di manutenzione

I seguenti esempi 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 di fine è di due giorni interi, quindi il periodo di manutenzione dura tutto il fine settimana, il sabato e la domenica. Se vuoi che la durata della finestra sia diversa dalle 48 ore esatte, modifica il valore -start per cambiare il momento in cui viene avviata la finestra o -end per modificare la lunghezza totale della finestra.

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

Ogni giorno, nei giorni feriali, dalle 9:00 alle 17:00 UTC-4

Questo esempio mostra come avere un periodo di manutenzione giornaliera, 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'

Ogni settimana 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 account Google Cloud. La console Google Cloud 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 giornaliera che viene eseguito durante la notte tra i giorni lavorativi nel fuso orario UTC-7. In questo esempio, la finestra va dalle 20:00 di sera alle 4: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 di manutenzione per il tuo cluster, devi specificare quanto segue:

Nome: il nome dell'esclusione (facoltativo).
Start time (Ora di inizio): la data e l'ora di inizio del periodo di esclusione.
End time (Ora di fine): la data e l'ora di fine del periodo di esclusione. Fai riferimento alla tabella seguente per le limitazioni relative alla durata di un periodo di esclusione per ciascuno degli ambiti disponibili.
Ambito: l'ambito degli upgrade automatici da limitare. Fai riferimento alla seguente tabella che elenca gli ambiti di esclusione disponibili.

Ambito	Descrizione	Lunghezza massima dell'esclusione
Nessun upgrade (impostazione predefinita)	Sono esclusi tutti gli upgrade di patch e secondari. Evita interruzioni delle VM per il piano di controllo del cluster e i nodi durante gli upgrade.	Non può superare i 30 giorni.
Nessun upgrade secondario	Sono esclusi tutti gli upgrade minori. Possono verificarsi interruzioni delle VM al piano di controllo e ai nodi del cluster a causa degli upgrade delle patch.	Non può terminare più di 180 giorni dopo la data di creazione dell'esclusione o estendersi oltre la data di fine del ciclo di vita della versione secondaria.
Nessun upgrade secondario o di nodi	Sono esclusi tutti gli upgrade secondari e gli upgrade dei nodi. Evita interruzioni delle VM per i nodi del cluster a causa degli upgrade. Tuttavia, possono verificarsi interruzioni del piano di controllo.	Non può terminare più di 180 giorni dopo la data di creazione dell'esclusione o estendersi oltre la data di fine del ciclo di vita della versione secondaria.

Per le definizioni delle versioni secondarie e patch, consulta Schema di controllo delle versioni.

Crea un cluster con un'esclusione di manutenzione

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

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

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Fai clic su Crea.
Configura il cluster.
Nel riquadro di navigazione, in Cluster, fai clic su Automazione.
In Esclusioni dalla manutenzione, fai clic su Aggiungi esclusione dalla manutenzione.
Seleziona un'Ambito, un'Ora di inizio e un'Ora di fine.
Fai clic su Crea.

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

Configura un'esclusione dalla manutenzione per un cluster esistente

Puoi configurare un'esclusione della manutenzione su un cluster esistente utilizzando la console Google Cloud o gcloud CLI.

gcloud

Configura un'esclusione dalla manutenzione per un cluster esistente:

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 di manutenzione.
START_DATE_TIME: data e ora di inizio dell'esclusione.
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.

Console

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

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.
In Automazione, accanto al campo Esclusioni dalla manutenzione, fai clic su Modifica esclusioni dalla manutenzione.
In Esclusioni dalla manutenzione, fai clic su Aggiungi esclusione dalla manutenzione.
Seleziona un'Ambito, un'Ora di inizio e un'Ora di fine.
Fai clic su Salva modifiche.

Rimuovere un'esclusione dalla manutenzione

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

gcloud

Rimuovi un'esclusione di 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 di manutenzione da rimuovere.

Console

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

Vai alla pagina Google Kubernetes Engine nella console Google Cloud.

Vai a Google Kubernetes Engine
Nell'elenco dei cluster, fai clic sul nome del cluster da modificare.
In Automazione, accanto al campo Esclusioni dalla manutenzione, fai clic su Modifica esclusioni dalla manutenzione.
In Esclusioni dalla manutenzione, fai clic su Elimina elemento accanto al campo Ora di fine per l'esclusione che vuoi rimuovere.
Fai clic su Salva modifiche.

Per vedere tutte le esclusioni di manutenzione su un cluster, puoi visualizzare il criterio di manutenzione del cluster.

Esempio di esclusione della manutenzione

L'esempio seguente impedisce la manutenzione nei quattro giorni del Black Friday e del Cyber Monday, il periodo delle vendite con il volume più elevato dell'anno per molte attività di vendita al dettaglio. Questo esempio mostra come evitare che si verifichi un periodo di manutenzione dal Black Friday 2021 (26 novembre 2021) al Cyber Monday 2021 (29 novembre 2021), dalla mezzanotte del fuso orario orientale (UTC-5) alle 23:59:59 del Pacifico (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

Visualizza il criterio di manutenzione di un cluster

Per visualizzare il criterio di manutenzione di un cluster, incluso se ha un periodo di manutenzione e tutte le esclusioni di manutenzione, usa il seguente comando:

gcloud container clusters describe CLUSTER_NAME

Risoluzione dei problemi

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 solo un massimo di 3 esclusioni di manutenzione che escludono tutti gli upgrade (ossia l'ambito di "nessun upgrade"), altrimenti ricevi il seguente errore:

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

Puoi specificare solo un massimo di 20 esclusioni di 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

Scopri di più sugli upgrade di cluster e nodi.
Scopri come abilitare l'upgrade automatico dei nodi.
Scopri come ricevere notifiche relative al cluster.