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 l'advanced cluster abilitato. La funzionalità di backup e ripristino è in anteprima nella versione 1.32 e in GA 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 il ripristino da un file di backup a meno che il cluster non abbia subito un errore catastrofico. Contatta l'assistenza clienti Google Cloud per ricevere aiuto nella scelta della soluzione migliore.

La procedura di backup e ripristino di gkectl non include i volumi persistenti. I volumi creati dal provisioner del volume locale (LVP) rimangono invariati.

Eseguire il backup di un cluster

Il comando gkectl backup cluster aggiunge le informazioni del 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). Questi dati vengono sottoposti a backup dal control plane del cluster o da uno dei control plane per un deployment ad alta disponibilità (HA).

Il file tar di backup contiene credenziali sensibili, tra cui le chiavi dell'account di servizio e la chiave SSH. Archivia i file di backup in una posizione sicura. Per evitare l'esposizione involontaria dei file, la procedura di backup utilizza solo file in memoria.

Esegui regolarmente il backup dei cluster per assicurarti che i dati degli snapshot siano relativamente aggiornati. Modifica 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 della procedura di backup è acquisire il cluster in uno stato buono noto in modo da poter ripristinare l'operazione in caso di errore catastrofico.

Per eseguire il backup di un cluster:

1. Esegui il comando seguente 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 prevedi di 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 come testuser_backup_2025-08-23T150405Z0700.tar.gz.

Se vuoi, 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 amministratore e utente venga caricato su vSphere oltre a essere salvato sulla workstation di amministrazione, procedi nel seguente modo:

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 precedenti. Se vuoi conservare i file di backup meno recenti, aggiungi il flag --keep-all-backups, disponibile nella versione 1.32.100 e successive.

Ripristinare 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 catastrofico e non può essere ripristinato in altro modo. Ad esempio, i dati etcd sono danneggiati o il pod etcd si trova in un ciclo di arresti anomali.

Utilizza il comando gkectl restore solo se tutti e tre i nodi del control plane non sono riusciti.

• Se si è verificato un errore in un solo nodo e autoRepair.enabled è impostato su true nel file di configurazione del cluster di amministrazione, il nodo in cui si è verificato l'errore 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 piano di controllo hanno generato errori, consulta la sezione Ripristinare 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 perdi gli oggetti Event esistenti. Tuttavia, la perdita di oggetti Event non ha alcun impatto sul funzionamento del cluster. Gli eventi devono essere trattati come dati informativi, supplementari e basati sul miglior tentativo.

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, la procedura 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 del 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 dello spazio 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 il quorum

Quando due nodi del control plane non funzionano 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, specifica l'indirizzo IP del nodo control plane funzionante.

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

• È presente un solo nodo del control plane funzionante.
• Il nodo del control plane funzionante è accessibile con la chiave SSH. Per ulteriori informazioni, vedi Utilizzo di SSH per la connessione a un nodo del cluster.

Per ripristinare il quorum, esegui il comando applicabile per il 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 seguenti sezioni potrebbero aiutarti a risolvere il problema.

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 in 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 di scratch 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 correlate 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 è valida per il processo di ripristino. Per risolvere il problema, puoi aggiungere temporaneamente di nuovo la chiave SSH originale, quindi eseguire il ripristino. Al termine del processo di ripristino, puoi ruotare la chiave SSH.