Fazer backup e restaurar clusters com bmctl

Este documento descreve como usar o bmctl para fazer backup e restaurar clusters criados com o software do Distributed Cloud somente para bare metal. Estas instruções se aplicam a todos os tipos de cluster.

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 Cloud Customer Care para receber ajuda e decidir a melhor solução.

O que é e o que não é incluído no backup

O processo de backup e restauração do bmctl opera na camada do plano de controle do Kubernetes e é diferente de outras soluções de backup. As soluções de backup que não são do Kubernetes capturam dados de carga de trabalho, armazenamento permanente e os sistemas operacionais host das máquinas físicas. O processo de backup e restauração do bmctl restaura seus clusters do Kubernetes sem fazer backup de nenhum desses outros componentes.

Estado do plano de controle (com backup pelo processo bmctl)

O bmctl faz backup dos seguintes objetos:

• repositório etcd. Todos os recursos do Kubernetes e objetos personalizados que definem a configuração e o estado escolhido do cluster (por exemplo, especificações de pod, implantações, ConfigMaps e secrets).
• Certificados da ICP. Certificados usados para comunicação segura no cluster.
• Arquivos de configuração e manifestos de nós. Configurações relacionadas aos nós do cluster.

Armazenamento de carga de trabalho e do ambiente de execução de VM (não tem backup pelo processo bmctl)

O bmctl não faz backup dos seguintes dados:

• Estado do pod e do ambiente de execução do contêiner ativos. O bmctl não salva processos ativos e dados de aplicativos na memória. Após uma restauração, o Kubernetes reinicia os pods das especificações do etcd. Todo estado não salvo na memória é perdido.
• Armazenamento de volume permanente. O bmctl não faz backup de dados armazenados em volumes permanentes, volumes criados pelo provisionador de volume local (LVP) ou drivers de armazenamento externo.
• Discos de máquina virtual. O bmctl não faz backup do conteúdo do disco rígido virtual da VM, como bancos de dados, arquivos ou estado do sistema operacional dentro da VM.

Você precisa usar mecanismos de backup nativos do Kubernetes ou no convidado para proteger os dados do aplicativo e o estado da máquina virtual. Se o driver de armazenamento subjacente for compatível com snapshots de volume CSI, use snapshots de volume padrão do Kubernetes para criar cópias pontuais de volumes permanentes. Para mais informações sobre como configurar o armazenamento, consulte Visão geral do armazenamento.

Execute agentes de backup no sistema operacional convidado das máquinas virtuais do VM Runtime ou implante ferramentas de backup nativas do aplicativo em cargas de trabalho do Kubernetes.

Sistemas operacionais de host físico (sem suporte)

Trate os sistemas operacionais Linux físicos nos nós do Google Distributed Cloud como infraestrutura descartável. A arquitetura de rede do Kubernetes não é compatível com a restauração de imagens do SO no nível do host. Portanto, o Google não oferece suporte à instalação de agentes de backup de terceiros no nível do host diretamente no SO do host nem à restauração de nós físicos de backups de imagens no nível do SO ou snapshots de disco.

Se você instalar agentes de backup físico de terceiros diretamente no SO Linux host, poderá causar riscos graves.

Muitos agentes de backup instalam módulos de kernel proprietários ou drivers de filtro no nível do bloco para rastrear mudanças e bloquear blocos de disco local durante operações de snapshot, o que pode causar os seguintes problemas:

• O banco de dados etcd não pode adicionar aos registros de gravação antecipada, os heartbeats do nó atingem o tempo limite, o consenso do Raft falha e os clusters ficam instáveis.
• Drivers de kernel de terceiros não compatíveis entram em conflito com rotinas de kernel de baixo nível e o ambiente de execução de contêineres, causando falhas nas atualizações do cluster.
• Restaurar um nó físico de um backup de imagem ou snapshot de disco viola o protocolo de consenso do Raft. O banco de dados etcd fica dessincronizado com registros em nós do plano de controle e ocorre uma corrupção grave do estado do cluster.
• Os nós de trabalho ficam dessincronizados com a fonte da verdade do servidor da API, os endereços IP do Dataplane V2 (Cilium) entram em conflito, e o tráfego é descartado.

Para recuperar um nó físico que apresentou falha no sistema operacional ou no hardware, não restaure uma imagem do SO. Em vez disso, remova o nó do cluster, reinstale um sistema operacional de base limpo e adicione o nó novamente ao pool de nós. Para instruções detalhadas de recuperação, consulte Redefinir um nó com falha.

Se precisar de mais ajuda, entre em contato com o Cloud Customer Care. Consulte também Receber suporte para mais informações sobre recursos de suporte, incluindo o seguinte:

• Requisitos para abrir um caso de suporte.
• Ferramentas para ajudar na solução de problemas, como configuração do ambiente, registros e métricas.
• Componentes compatíveis.

Fazer backup de um cluster

O comando bmctl backup cluster empacota os dados do etcd e os certificados de PKI do cluster em um arquivo tar. O banco de dados etcd é o repositório de dados central para todos os dados do cluster, contendo todos os objetos do Kubernetes e recursos personalizados necessários para gerenciar o estado do cluster. Os certificados PKI fazem a autenticação por TLS. Esses dados são armazenados em backup 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 do Google Distributed Cloud usa somente 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.

A versão de bmctl que você usa para fazer backup de um cluster precisa corresponder à versão do cluster de gerenciamento.

Se você instalou o Node Agent nos clusters, o diretório /tmp no nó de administrador e em todos os nós de destino precisa ter 12 GB de espaço livre. Se não for possível mudar o tamanho do diretório /tmp para os nós de destino, consulte Mudar a capacidade de armazenamento local para nós de destino. Se não for possível mudar o tamanho do diretório /tmp para o nó de administrador, consulte Mudar a capacidade de armazenamento local de um nó de administrador.

Para fazer backup de um cluster:

1. 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.

   Use o seguinte comando para verificar o cluster:

   bmctl check cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster que você planeja armazenar em backup.
   • ADMIN_KUBECONFIG: o caminho do arquivo kubeconfig do cluster de administrador.

2. Execute o seguinte comando para garantir que o cluster de destino não esteja em um estado de reconciliação:

   kubectl describe cluster CLUSTER_NAME -n CLUSTER_NAMESPACE --kubeconfig ADMIN_KUBECONFIG
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster para backup.
   • CLUSTER_NAMESPACE: o namespace do cluster. Por padrão, os namespaces do cluster do Google Distributed Cloud são o nome do cluster que inclui cluster-. Por exemplo, se você nomear o cluster test, o namespace terá um nome como cluster-test.
   • ADMIN_KUBECONFIG: o caminho do arquivo kubeconfig do cluster de administrador.

3. Verifique a seção Status na resposta ao comando para Conditions do tipo Reconciling.

   Conforme mostrado no exemplo a seguir, um status False para essas Conditions significa que o cluster está estável e pronto para ser salvo em backup.

   ...
   Status:
     ...
     Cluster State:  Running
     ...
     Control Plane Node Pool Status:
       ...
       Conditions:
         Last Transition Time:  2023-11-03T16:37:15Z
         Observed Generation:   1
         Reason:                ReconciliationCompleted
         Status:                False
         Type:                  Reconciling
     ...
   

4. Execute o seguinte comando para fazer backup do cluster:

   bmctl backup cluster -c CLUSTER_NAME --kubeconfig ADMIN_KUBECONFIG
   

   Substitua:

   • CLUSTER_NAME: o nome do cluster para backup.
   • ADMIN_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.

   Por padrão, o arquivo tar de backup foi salvo no diretório do espaço de trabalho (bmctl-workspace, por padrão) 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_2006-01-02T150405Z0700.tar.gz.

   Para especificar um nome e local diferentes para o arquivo de backup, use a sinalização --backup-file.

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.

Restaurar um cluster

A restauração de um cluster a partir de um backup é um último recurso e precisa ser usado quando um cluster falhar de forma catastrófica e não puder ser retornado de forma alguma. Por exemplo, se os dados do etcd estiverem corrompidos ou o pod do etcd estiver em um loop de falhas.

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, de melhor esforço e complementares.

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.

A versão de bmctl que você usa para fazer backup de um cluster precisa corresponder à versão do cluster de gerenciamento.

Para restaurar um cluster:

1. Garanta que todas as máquinas de nó que estavam disponíveis para o cluster no momento do backup estejam funcionando corretamente e acessíveis.

2. Garanta que a conectividade SSH entre os nós funcione com as chaves SSH usadas no momento do backup.

   Essas chaves SSH são restabelecidas como parte do processo de restauração.

3. Verifique se as chaves da conta de serviço que foram usadas no momento do backup ainda estão ativas.

   Essas chaves de conta de serviço são restabelecidas para o cluster restaurado.

4. Para restaurar um cluster de administrador, híbrido ou autônomo, execute o seguinte comando:

   bmctl restore cluster -c CLUSTER_NAME --backup-file BACKUP_FILE
   

   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.

5. Para restaurar um cluster de usuário, execute o seguinte comando:

   bmctl restore cluster -c 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.

Quando a restauração terminar, siga estas etapas para verificar se ela foi concluída:

1. Execute os comandos a seguir para verificar a prontidão do nó e os pods do sistema em execução com o arquivo kubeconfig gerado:

   Há dois tipos de pods do etcd:

   • etcd-HOST_NAME, que corresponde ao pod etcd principal
   • etcd-events-HOST_NAME, que corresponde ao pod etcd-events

   kubectl get pods -n kube-system --kubeconfig GENERATED_KUBECONFIG
   kubectl get nodes --kubeconfig GENERATED_KUBECONFIG
   

2. Para cada pod do etcd, execute o seguinte comando para verificar a integridade do etcd:

   kubectl exec ETCD_POD_NAME -n kube-system \
       --kubeconfig GENERATED_KUBECONFIG \
       -- /bin/sh -c 'ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2379 \
       --cacert=/etc/kubernetes/pki/etcd/ca.crt --key=/etc/kubernetes/pki/etcd/peer.key \
       --cert=/etc/kubernetes/pki/etcd/peer.crt endpoint health'
   

   Para um membro do etcd íntegro, a resposta será semelhante a esta:

   https://127.0.0.1:2379 is healthy: successfully committed proposal: took = 11.514177ms
   

3. Para cada pod etcd-events, execute o comando a seguir para verificar a integridade de etcd-events:

   kubectl exec ETCD_EVENTS_POD_NAME -n kube-system \
       --kubeconfig GENERATED_KUBECONFIG \
       -- /bin/sh -c 'ETCDCTL_API=3 etcdctl --endpoints=https://127.0.0.1:2382 \
       --cacert=/etc/kubernetes/pki/etcd/ca.crt --key=/etc/kubernetes/pki/etcd/peer.key \
       --cert=/etc/kubernetes/pki/etcd/peer.crt endpoint health'
   

   Para um membro etcd-events íntegro, a resposta será semelhante a esta:

   https://127.0.0.1:2382 is healthy: successfully committed proposal: took = 14.308148ms
   

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 o Suporte do Google.

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

Você pode receber mensagens de erro durante o processo de backup ou restauração que não sejam muito autoexplicativas ou claras nas próximas etapas. Se a estação de trabalho em que você executa o comando bmctl não tem muita RAM, você pode ter memória insuficiente para executar o processo de backup ou restauração.

O Google Distributed Cloud versão 1.13 e mais recentes pode usar 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 o usuário que executa o comando seja um usuário raiz (ou use sudo).

Permissões ausentes para arquivos durante a restauração

Após uma tarefa de restauração bem-sucedida, a exclusão do bootstrap pode falhar com uma mensagem de erro semelhante ao exemplo a seguir:

  Error: failed to restore node config files: sftp: "Failure" (SSH_FX_FAILURE)

Esse erro pode significar que alguns diretórios exigidos pela restauração não são graváveis.

O Google Distributed Cloud versão 1.14 e mais recentes têm mensagens de erro mais claras sobre quais diretórios precisam ser graváveis. Verifique se os diretórios informados são graváveis e atualize as permissões neles conforme necessário.

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 do 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.

Não é possível criar um backup para um nó do agente do nó

Se você usa o Node Agent e recebe um erro informando que a criação do backup não gerou um arquivo de arquivamento, semelhante a este:

  I0508 15:29:36.831790  657351 backup_cluster.go:255] Retrying backup node: 128.187.102.133, due to error: failed receive chunk data: rpc error: code = Unknown desc = archiver.CreateArchiveWithList
  failed: failed to create archive file: failed to copy data from file: var/lib/etcd-events/member/snap/db, file size: 26136576, copy bytes: 12478464,
  error: write /tmp/uploadFileTemp1561164777: no space left on device

Verifique se há 12 GB de espaço livre no diretório /tmp no nó de administrador e em todos os nós de destino. Se não for possível mudar o tamanho do diretório /tmp para os nós de destino, consulte Aumentar a capacidade de armazenamento local para backups do agente de nó.

Depois de confirmar que há 12 GB de espaço livre no diretório /tmp para o nó de administrador e todos os nós de destino, tente fazer o backup novamente.