Backup e ripristino di cluster avanzati con gkectl

Questo documento descrive come eseguire il backup e il ripristino dei cluster di amministrazione e utente di Google Distributed Cloud versione 1.32 e successive con il cluster avanzato abilitato. La funzionalità di backup e ripristino è in anteprima nella versione 1.32 e in disponibilità generale nella versione 1.33 e successive.

Avviso: l'utilizzo di un file di backup per ripristinare il cluster è l'ultima risorsa. Il processo di ripristino reimposta il cluster esistente e sovrascrive le informazioni del cluster. Sconsigliamo di eseguire il ripristino da un file di backup, a meno che il cluster non abbia subito un errore irreversibile. Contatta l'assistenza clienti Google Cloud per ricevere aiuto nel decidere la migliore linea d'azione.

Il processo di backup e ripristino di gkectl non include i volumi permanenti. Tutti i volumi creati dal provisioner di volumi locali (LVP) rimangono invariati.

Esegui il backup di un cluster

Il comando gkectl backup cluster aggiunge le informazioni sul cluster dall'archivio etcd e i certificati PKI per il cluster specificato a un file tar. L'archivio etcd è l'archivio di backup di Kubernetes per tutti i dati del cluster e contiene tutti gli oggetti Kubernetes e gli oggetti personalizzati necessari per gestire lo stato del cluster. I certificati PKI vengono utilizzati per l'autenticazione tramite Transport Layer Security (TLS). Il backup di questi dati viene eseguito dal control plane del cluster o da uno dei control plane per un deployment ad alta affidabilità (HA).

Il file tar di backup contiene credenziali sensibili, tra cui le chiavi dell'account di servizio e la chiave SSH. Conserva i file di backup in un luogo sicuro. Per evitare l'esposizione involontaria dei file, il processo di backup utilizza solo file in memoria.

Esegui regolarmente il backup dei cluster per assicurarti che i dati degli snapshot siano relativamente aggiornati. Regola la frequenza dei backup in modo che rifletta la frequenza delle modifiche significative ai tuoi cluster.

Prima di iniziare, assicurati che il cluster funzioni correttamente, con credenziali funzionanti e connettività SSH a tutti i nodi. Lo scopo del processo di backup è acquisire il cluster in uno stato valido noto in modo da poter ripristinare il funzionamento in caso di errore irreversibile.

Per eseguire il backup di un cluster:

1. Esegui questo comando per controllare il cluster:

   gkectl diagnose cluster --cluster-name CLUSTER_NAME \
       --kubeconfig ADMIN_KUBECONFIG
   

   Sostituisci quanto segue:

   • CLUSTER_NAME: il nome del cluster di cui vuoi eseguire il backup.

   • ADMIN_KUBECONFIG: il percorso del file kubeconfig per il cluster di amministrazione.

2. Esegui il comando applicabile per eseguire il backup del cluster:

   Cluster di amministrazione

   gkectl backup admin --kubeconfig ADMIN_KUBECONFIG
   

   Cluster utente

   gkectl backup cluster --cluster-name CLUSTER_NAME \
       --kubeconfig ADMIN_KUBECONFIG
   

Per impostazione predefinita, il file tar di backup viene salvato nella directory gkectl-workspace/backups sulla workstation di amministrazione. Il file tar è denominato CLUSTER_NAME_backup_TIMESTAMP.tar.gz, dove CLUSTER_NAME è il nome del cluster di cui viene eseguito il backup e TIMESTAMP è la data e l'ora in cui è stato eseguito il backup. Ad esempio, se il nome del cluster è testuser, il file di backup ha un nome simile a testuser_backup_2025-08-23T150405Z0700.tar.gz.

Facoltativamente, puoi specificare un nome e una posizione diversi per il file di backup con il flag --backup-file, ad esempio:

gkectl backup cluster testuser \
    --kubeconfig admin-cluster/kubeconfig \
    --backup-file cluster-backups/testuser-backup-aug-23-2025.tar.gz

Il file di backup scade dopo un anno e il processo di ripristino del cluster non funziona con i file di backup scaduti.

Backup su vSphere

Per configurare i backup in modo che il file di backup per i cluster di amministrazione e utente venga caricato su vSphere oltre a essere salvato sulla workstation di amministrazione, segui questi passaggi:

1. Aggiungi il campo clusterBackup.datastore al file di configurazione del cluster di amministrazione:

   clusterBackup:
       datastore: DATASTORE
   

   Sostituisci DATASTORE con il datastore in cui vuoi archiviare il backup. Il datastore deve trovarsi nello stesso data center del cluster di amministrazione. I backup si trovano nella directory anthos/CLUSTER_NAME/backup del datastore specificato.

2. Aggiorna il cluster di amministrazione:

   gkectl update admin --kubeconfig ADMIN_KUBECONFIG \
       --config ADMIN_CONFIG
   

   Sostituisci quanto segue:

   • ADMIN_KUBECONFIG: il percorso del file kubeconfig per il cluster di amministrazione.

   • ADMIN_CONFIG: il percorso del file di configurazione del cluster di amministrazione.

Per impostazione predefinita, il comando gkectl backup salva i tre file di backup più recenti in vSphere ed elimina i file di backup meno recenti. Se vuoi conservare i file di backup precedenti, aggiungi il flag --keep-all-backups, disponibile nella versione 1.32.100 e successive.

Ripristina un cluster

Il ripristino di un cluster da un backup è l'ultima risorsa e deve essere utilizzato solo quando un cluster ha subito un errore irreversibile e non può essere rimesso in servizio in nessun altro modo. Ad esempio, i dati etcd sono danneggiati o il pod etcd è in un loop di arresto anomalo.

Utilizza il comando gkectl restore solo se tutti e tre i nodi del control plane hanno avuto un errore.

• Se un solo nodo non funziona e autoRepair.enabled è impostato su true nel file di configurazione del cluster di amministrazione, il nodo con errori viene riparato automaticamente. Se autoRepair.enabled non è configurato, aggiungilo al file di configurazione del cluster di amministrazione ed esegui gkectl update admin. Dopo l'aggiornamento, il nodo viene ricreato automaticamente.

• Se due nodi del control plane hanno avuto un errore, consulta la sezione Ripristina il quorum in questa pagina.

Nota: per migliorare le prestazioni del cluster, Google Distributed Cloud utilizza un'istanza etcd separata per archiviare gli oggetti Event. Questi oggetti Event hanno una durata (TTL) di un'ora. L'operazione di ripristino del cluster crea una nuova istanza etcd-events vuota, quindi gli oggetti Event esistenti vengono persi. Tuttavia, la perdita di oggetti Event non ha alcun impatto sul funzionamento del cluster. Gli eventi devono essere considerati solo come dati supplementari, informativi e best-effort.

Il file tar di backup contiene credenziali sensibili, tra cui le chiavi dell'account di servizio e la chiave SSH. Per evitare l'esposizione involontaria dei file, il processo di ripristino di Google Distributed Cloud utilizza solo file in memoria.

Prima di ripristinare un cluster, assicurati che siano soddisfatte le seguenti condizioni:

• Tutte le macchine dei nodi del control plane disponibili per il cluster al momento del backup funzionano correttamente e sono raggiungibili.
• La connettività SSH tra i nodi funziona con le chiavi SSH utilizzate al momento del backup. Queste chiavi SSH vengono reintegrate nell'ambito del processo di ripristino.
• Le chiavi del service account utilizzate al momento del backup sono ancora attive. Queste chiavi dei service account vengono reintegrate per il cluster ripristinato.

Per ripristinare un cluster:

1. Esegui il comando applicabile per ripristinare il cluster:

   Cluster di amministrazione

   gkectl restore admin --backup-file BACKUP_FILE \
       --config ADMIN_CONFIG
   

   Sostituisci quanto segue:

   • BACKUP_FILE: il percorso e il nome del file di backup che stai utilizzando.

   • ADMIN_CONFIG: il percorso del file di configurazione del cluster di amministrazione.

   Cluster utente

   gkectl restore cluster --cluster-name CLUSTER_NAME \
       --backup-file BACKUP_FILE \
       --kubeconfig ADMIN_KUBECONFIG
   

   Sostituisci quanto segue:

   • CLUSTER_NAME: il nome del cluster che stai ripristinando.

   • BACKUP_FILE: il percorso e il nome del file di backup che stai utilizzando.

   • ADMIN_KUBECONFIG: il percorso del file kubeconfig del cluster di amministrazione.

   Al termine del processo di ripristino, viene generato un nuovo file kubeconfig per il cluster ripristinato nella directory dell'area di lavoro gkectl-workspace.

2. Al termine del ripristino, esegui questo comando per verificare che sia andato a buon fine:

   gkectl diagnose cluster --cluster-name CLUSTER_NAME \
       --kubeconfig GENERATED_KUBECONFIG
   

   Sostituisci GENERATED_KUBECONFIG con il file kubeconfig generato.

Ripristina quorum

Quando due nodi del control plane hanno avuto un errore in un cluster, puoi utilizzare il comando gkectl restore per ripristinare il quorum. Quando ripristini il quorum, anziché specificare il file di backup nel comando gkectl restore, specifichi l'indirizzo IP del nodo del control plane funzionante.

Prima di eseguire il comando, assicurati che siano soddisfatte le seguenti condizioni:

• È in funzione un solo nodo del control plane.
• Il nodo del control plane funzionante è accessibile con la chiave SSH. Per saperne di più, consulta Utilizzo di SSH per connettersi a un nodo del cluster.

Per ripristinare il quorum, esegui il comando applicabile al tuo tipo di cluster:

Cluster di amministrazione

gkectl restore admin --kubeconfig ADMIN_KUBECONFIG \
    --config ADMIN_CONFIG \
    --control-plane-node WORKING_NODE_IP \
    --ssh-key ADMIN_SSH_KEY_PATH

Sostituisci quanto segue:

• ADMIN_KUBECONFIG: il percorso del file kubeconfig per il cluster di amministrazione.

• ADMIN_CONFIG: il percorso del file di configurazione del cluster di amministrazione.

• WORKING_NODE_IP: l'indirizzo IP del nodo del control plane funzionante.

• ADMIN_SSH_KEY_PATH: il percorso della chiave SSH del cluster di amministrazione.

Cluster utente

gkectl restore cluster --cluster-name CLUSTER_NAME \
    --kubeconfig ADMIN_KUBECONFIG \
    --control-plane-node WORKING_NODE_IP \
    --ssh-key USER_SSH_KEY_PATH

Sostituisci quanto segue:

• CLUSTER_NAME: il nome del cluster che stai ripristinando.

• ADMIN_KUBECONFIG: il percorso del file kubeconfig del cluster di amministrazione.

• WORKING_NODE_IP: l'indirizzo IP del nodo del control plane funzionante.

• USER_SSH_KEY_PATH: il percorso della chiave SSH del cluster utente.

Risoluzione dei problemi

Se riscontri problemi con la procedura di backup o ripristino, le sezioni seguenti potrebbero aiutarti a risolverli.

Se hai bisogno di ulteriore assistenza, contatta il team di assistenza clienti Google Cloud.

Esaurimento della memoria durante un backup o un ripristino

Se la workstation su cui esegui il comando gkectl non dispone di molta RAM, potresti non avere memoria sufficiente per eseguire il processo di backup o ripristino. Se necessario, crea e utilizza un disco temporaneo per elaborare le operazioni di backup o ripristino utilizzando il parametro --use-disk nel comando di backup. Per preservare le autorizzazioni dei file, questo parametro modifica le autorizzazioni dei file, quindi richiede l'esecuzione del comando come utente root (o l'utilizzo di sudo).

L'aggiornamento della chiave SSH dopo un backup interrompe il processo di ripristino

Le operazioni relative a SSH durante il processo di ripristino potrebbero non riuscire se la chiave SSH viene aggiornata dopo l'esecuzione di un backup. In questo caso, la nuova chiave SSH non è più valida per il processo di ripristino. Per risolvere il problema, puoi aggiungere temporaneamente la chiave SSH originale, quindi eseguire il ripristino. Al termine del processo di ripristino, puoi ruotare la chiave SSH.