Fazer backup e restaurar clusters avançados com gkectl

Este documento descreve como fazer backup e restaurar clusters de administrador e de usuário do Google Distributed Cloud versão 1.32 e mais recentes com o cluster avançado ativado. O recurso de backup e restauração está em pré-lançamento na versão 1.32 e em disponibilidade geral na versão 1.33 e mais recentes.

Aviso: usar um arquivo de backup para restaurar o cluster é o último recurso. O processo de restauração redefine o cluster atual e substitui as informações dele. Não recomendamos a restauração de um arquivo de backup, a menos que o cluster tenha falhado catastroficamente. Entre em contato com o atendimento ao cliente do Cloud para receber ajuda para decidir o melhor curso de ação.

O processo de backup e restauração gkectl não inclui volumes permanentes. Todos os volumes criados pelo provisionador de volume local (LVP) não são alterados.

Fazer backup de um cluster

O comando gkectl backup cluster adiciona as informações de cluster do armazenamento etcd e os certificados de PKI do cluster especificado a um arquivo tar. O armazenamento etcd é o armazenamento secundário do Kubernetes para todos os dados de cluster e contém todos os objetos do Kubernetes e objetos personalizados necessários para gerenciar o estado do cluster. Os certificados de ICP são usados para autenticação por Transport Layer Security (TLS). Esses dados são armazenados em backup a partir do plano de controle do cluster ou de um dos planos de controle para uma implantação de alta disponibilidade (HA).

O arquivo tar de backup contém credenciais confidenciais, incluindo as chaves da conta de serviço e a chave SSH. Armazene os arquivos de backup em um local seguro. Para evitar a exposição não intencional de arquivos, o processo de backup usa apenas arquivos na memória.

Faça backup dos clusters regularmente para garantir que os dados de snapshots sejam relativamente atuais. Ajuste a taxa de backups para refletir a frequência de alterações significativas nos clusters.

Antes de começar, verifique se o cluster está funcionando corretamente, com credenciais de trabalho e conectividade SSH para todos os nós. O objetivo do processo de backup é capturar o cluster em um estado válido conhecido para que você consiga restaurar a operação se ocorrer uma falha catastrófica.

Para fazer backup de um cluster:

1. Execute o seguinte comando para verificar seu cluster:

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

   Substitua:

   • CLUSTER_NAME: o nome do cluster que você planeja fazer backup.

   • ADMIN_KUBECONFIG: o caminho do arquivo kubeconfig do cluster de administrador.

2. Execute o comando aplicável para fazer backup do cluster:

   Cluster de administrador

   gkectl backup admin --kubeconfig ADMIN_KUBECONFIG
   

   Cluster de usuário

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

Por padrão, o arquivo tar de backup é salvo no diretório gkectl-workspace/backups na estação de trabalho do administrador. O arquivo .tar é chamado de CLUSTER_NAME_backup_TIMESTAMP.tar.gz, em que CLUSTER_NAME é o nome do cluster que está sendo armazenado em backup e TIMESTAMP é a data e a hora em que o backup foi feito. Por exemplo, se o nome do cluster for testuser, o arquivo de backup terá um nome como testuser_backup_2025-08-23T150405Z0700.tar.gz.

Se quiser, especifique um nome e local diferentes para o arquivo de backup com a flag --backup-file. Por exemplo:

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

O arquivo de backup expira após um ano e o processo de restauração do cluster não funciona com arquivos de backup expirados.

Fazer backup no vSphere

Para configurar backups de modo que o arquivo de backup dos clusters de administrador e de usuário seja enviado ao vSphere, além de ser salvo na estação de trabalho de administrador, faça o seguinte:

1. Adicione o campo clusterBackup.datastore ao arquivo de configuração do cluster de administrador:

   clusterBackup:
       datastore: DATASTORE
   

   Substitua DATASTORE pelo armazenamento de dados em que você quer armazenar o backup. O armazenamento de dados precisa estar no mesmo data center que o cluster de administrador. Os backups estão localizados no diretório anthos/CLUSTER_NAME/backup do repositório de dados especificado.

2. Atualize o cluster de administrador:

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

   Substitua:

   • ADMIN_KUBECONFIG: o caminho do arquivo kubeconfig do cluster de administrador.

   • ADMIN_CONFIG: é o caminho do arquivo de configuração do cluster de administrador

Por padrão, o comando gkectl backup salva os três arquivos de backup mais recentes no vSphere e exclui os mais antigos. Se você quiser manter os arquivos de backup mais antigos, adicione a flag --keep-all-backups, que está disponível na versão 1.32.100 e mais recentes.

Restaurar um cluster

A restauração de um cluster de um backup é um último recurso e só deve ser usada quando um cluster falhar de forma catastrófica e não puder ser retornado ao serviço de outra maneira. Por exemplo, se os dados do etcd estiverem corrompidos ou o pod do etcd estiver em um loop de falhas.

Use o comando gkectl restore somente se os três nós do plano de controle falharem.

• Se apenas um nó falhar e autoRepair.enabled estiver definido como true no arquivo de configuração do cluster de administrador, o nó com falha será reparado automaticamente. Se autoRepair.enabled não estiver configurado, adicione-o ao arquivo de configuração do cluster de administrador e execute gkectl update admin. Depois da atualização, o nó é recriado automaticamente.

• Se dois nós do plano de controle falharem, consulte a seção Restaurar quorum nesta página.

Observação: para melhorar o desempenho do cluster, o Google Distributed Cloud usa uma instância etcd separada para armazenar objetos de eventos. Esses objetos de evento têm um time to live (TTL) de uma hora. A operação de restauração do cluster cria uma instância nova e vazia de eventos etcd. Portanto, você perde os objetos de evento atuais. No entanto, a perda de objetos de evento não afeta a operação do cluster. Os eventos precisam ser tratados como apenas dados informativos, complementares e de melhor esforço.

O arquivo tar de backup contém credenciais confidenciais, incluindo as chaves da conta de serviço e a chave SSH. Para evitar a exposição não intencional de arquivos, o processo de restauração do Google Distributed Cloud usa somente arquivos na memória.

Antes de restaurar um cluster, verifique se as seguintes condições foram atendidas:

• Todas as máquinas de nó do plano de controle que estavam disponíveis para o cluster no momento do backup estejam funcionando corretamente e acessíveis.
• A conectividade SSH entre os nós funciona com as chaves SSH usadas no momento do backup. Essas chaves SSH são restabelecidas como parte do processo de restauração.
• As chaves da conta de serviço usadas no momento do backup ainda estão ativas. Essas chaves de conta de serviço são restabelecidas para o cluster restaurado.

Para restaurar um cluster:

1. Execute o comando aplicável para restaurar o cluster:

   Cluster de administrador

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

   Substitua:

   • BACKUP_FILE: o caminho e o nome do arquivo de backup que você está usando.

   • ADMIN_CONFIG: o caminho até o arquivo de configuração do cluster de administrador.

   Cluster de usuário

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

   Substitua:

   • CLUSTER_NAME: o nome do cluster que você está restaurando.

   • BACKUP_FILE: o caminho e o nome do arquivo de backup que você está usando.

   • ADMIN_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.

   No final do processo de restauração, um novo arquivo kubeconfig é gerado para o cluster restaurado no diretório do espaço de trabalho gkectl-workspace.

2. Quando a restauração terminar, execute o comando a seguir para verificar se ela foi bem-sucedida:

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

   Substitua GENERATED_KUBECONFIG pelo arquivo kubeconfig gerado.

Quórum de restauração

Quando dois nós do plano de controle falham em um cluster, é possível usar o comando gkectl restore para restaurar o quorum. Ao restaurar o quorum, em vez de especificar o arquivo de backup para o comando gkectl restore, especifique o endereço IP do nó do plano de controle em funcionamento.

Antes de executar o comando, verifique se as seguintes condições foram atendidas:

• Há um (e apenas um) nó do plano de controle em funcionamento.
• O nó do plano de controle em funcionamento pode ser acessado com a chave SSH. Para mais informações, consulte Como usar o SSH para se conectar a um nó de cluster.

Para restaurar o quórum, execute o comando aplicável ao tipo de cluster:

Cluster de administrador

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

Substitua:

• ADMIN_KUBECONFIG: o caminho do arquivo kubeconfig do cluster de administrador.

• ADMIN_CONFIG: é o caminho do arquivo de configuração do cluster de administrador

• WORKING_NODE_IP: o endereço IP do nó do plano de controle em funcionamento.

• ADMIN_SSH_KEY_PATH: o caminho da chave SSH do cluster de administrador.

Cluster de usuário

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

Substitua:

• CLUSTER_NAME: o nome do cluster que você está restaurando.

• ADMIN_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.

• WORKING_NODE_IP: o endereço IP do nó do plano de controle em funcionamento.

• USER_SSH_KEY_PATH: o caminho da chave SSH do cluster de usuário.

Resolver problemas

Se você tiver problemas com o processo de backup ou restauração, as seções a seguir poderão ajudar a resolver o problema.

Se precisar de mais ajuda, entre em contato com a equipe do Cloud Customer Care.

Memória insuficiente durante um backup ou restauração

Se a estação de trabalho em que você executa o comando gkectl não tem muita RAM, você pode ter memória insuficiente para executar o processo de backup ou restauração. Se necessário, crie e use um disco de trabalho temporário para processar as operações de backup ou restauração usando o parâmetro --use-disk no comando de backup. Para preservar as permissões do arquivo, esse parâmetro modifica as permissões dos arquivos. Portanto, exige que você execute o comando como um usuário raiz (ou use sudo).

Atualização da chave SSH após um backup interromper o processo de restauração

As operações relacionadas ao SSH durante o processo de restauração podem falhar se a chave SSH for atualizada após a realização de um backup. Nesse caso, a nova chave SSH se torna inválida para o processo de restauração. Para resolver esse problema, adicione temporariamente a chave SSH original de volta e execute a restauração. Após a conclusão do processo de restauração, é possível girar a chave SSH.