Criar snapshots para ajudar a diagnosticar problemas de cluster

Se você tiver um problema com um dos clusters, poderá receber ajuda do Cloud Customer Care O Customer Care pode solicitar que você faça um "snapshot" do cluster, que poderá ser usado pela equipe para diagnosticar o problema. Um snapshot captura arquivos de configuração de cluster e de nó, além de empacotar essas informações em um único arquivo .tar.

Neste documento, você verá como criar snapshots padrão ou mais personalizados de um cluster. Você também saberá como criar snapshots quando um cluster está passando por erros específicos.

Instantâneos padrão

As seções a seguir descrevem o que está em um snapshot padrão e como criar um. Para informações sobre snapshots personalizados, consulte a seção Snapshots personalizados.

Quais informações contêm um snapshot padrão?

O snapshot de um cluster é um arquivo .tar de arquivos de configuração e registros sobre o cluster. Especificamente, a configuração padrão do comando captura as seguintes informações sobre o cluster:

Versão do Kubernetes
Status dos recursos do Kubernetes nos namespaces kube-system e gke-system: cluster, machine, nós, Serviços, Endpoints, ConfigMaps, ReplicaSets, CronJobs, Pods e os proprietários desses pods, incluindo implantações, DaemonSets e StatefulSets
Detalhes sobre cada configuração de nó, incluindo endereços IP, regras de iptables, pontos de montagem, sistemas de arquivos, conexões de rede e processos em execução.
Informações sobre o ambiente de execução da VM na GDC e todas as VMs e recursos relacionados à VM em execução no cluster. Para mais informações sobre o que é coletado por padrão e como criar snapshots específicos da VM, consulte Informações da VM em snapshots neste documento.
Registros do comando bmctl check cluster --snapshot

As informações de credencial de um cluster não estão incluídas no snapshot padrão. Se o Cloud Customer Care solicitar essas informações, consulte Como recuperar informações de cluster.

Para uma lista abrangente de informações coletadas ao executar o comando de snapshot, consulte o arquivo de configuração mostrado na seção Detalhes do arquivo de configuração. Este arquivo de configuração mostra quais comandos são executados ao capturar um snapshot padrão.

Como criar um snapshot padrão

O comando bmctl check cluster tira um snapshot de um cluster. É possível usar esse comando para executar uma das seguintes ações:

Criar um snapshot e fazer o upload automático para um bucket do Cloud Storage
crie um snapshot de um cluster e salve o arquivo de snapshot na máquina local em que você está executando o comando.

Método 1: crie um snapshot padrão e faça o upload automático para o bucket do Cloud Storage

Para criar e fazer upload de um snapshot em um bucket do Cloud Storage, faça o seguinte:

Configure a API e a conta de serviço conforme descrito em Configurar uma conta de serviço que possa acessar um bucket do Cloud Storage.

Esta é uma etapa única.
Execute o comando bmctl a seguir para criar e fazer o upload automático de um snapshot para um bucket do Cloud Storage:
```
bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --admin-kubeconfig=ADMIN_KUBECONFIG \
    --service-account-key-file SA_KEY_FILE
```
No comando, substitua as seguintes entradas por informações específicas ao ambiente do cluster:
- CLUSTER_NAME: o nome do cluster do qual você quer gerar um snapshot.
- ADMIN_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.
- SA_KEY_FILE: o caminho para o arquivo de chave JSON baixado para a conta de serviço criada na etapa anterior. Se você não usar a flag --service-account-key-file, o comando usará as credenciais associadas à variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. A especificação explícita das credenciais da conta de serviço com a flag tem precedência.
Esse comando gera um arquivo tar do instantâneo e o salva localmente. Quando a conta de serviço está configurada corretamente, o comando também faz upload do arquivo .tar do snapshot em um bucket do Cloud Storage. O comando pesquisa o projeto em busca de um bucket de armazenamento que tenha um nome que comece com "anthos-snapshot-". Se esse bucket for encerrado, o comando fará upload do snapshot para esse bucket. Se o comando não encontrar um bucket com um nome correspondente, ele criará um novo bucket com o nome anthos-snapshot-UUID, em que UUID é um identificador exclusivo universal de 32 dígitos.

Observação: é possível usar a flag --upload-to para fornecer um nome de bucket específico para o upload do snapshot.
Compartilhe o acesso com o Cloud Customer Care, conforme descrito em Permitir que o suporte do Google Cloud visualize o instantâneo do cluster enviado.

Método 2: criar um snapshot padrão apenas na máquina local

Use a flag --local para garantir que o snapshot do cluster seja salvo apenas localmente. É possível capturar o estado dos clusters criados com o comando:

bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --admin-kubeconfig=ADMIN_KUBECONFIG --local

Substitua:

CLUSTER_NAME: o nome do cluster de destino.
ADMIN_KUBECONFIG: o caminho até o arquivo kubeconfig do cluster de administrador.

Esse comando gera um arquivo .tar na máquina local. O nome desse arquivo .tar está no formato snapshot-CLUSTER_NAME-TIMESTAMP.tar.gz, em que TIMESTAMP indica a data e a hora em que o arquivo foi criado. Esse arquivo .tar inclui informações de depuração relevantes sobre os componentes e máquinas do sistema de um cluster.

Quando você executa esse comando, as informações são coletadas sobre pods dos seguintes namespaces: gke-system ,gke-connect ,capi-system ,capi-webhook-system ,cert-manager ecapi-kubeadm-bootstrap-system

No entanto, é possível ampliar o escopo das informações de diagnóstico coletadas usando a sinalização --snapshot-scenario all. Essa sinalização aumenta o escopo do snapshot de diagnóstico para incluir todos os pods em um cluster:

bmctl check cluster --snapshot --snapshot-scenario all \
    --cluster=CLUSTER_NAME \
    --kubeconfig=KUBECONFIG_PATH \
    --local

Cenários de snapshots

O comando bmctl check cluster --snapshot é compatível com dois cenários. Para especificar um cenário, use a sinalização --scenario. A lista a seguir mostra os valores possíveis:

system: colete um snapshot de componentes do sistema, incluindo os registros deles.
all: colete um snapshot de todos os pods, incluindo os registros deles.

É possível usar cada um dos dois cenários com um cluster de administrador ou um cluster de usuário. Por exemplo, para criar um snapshot do cluster de administrador usando o cenário system:

bmctl check cluster --snapshot --snapshot-scenario system \
    --cluster=ADMIN_CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

Para criar um snapshot de um cluster de usuário usando o cenário all:

bmctl check cluster --snapshot --snapshot-scenario all \
    --cluster=USER_CLUSTER_NAME \
    --kubeconfig=USER_KUBECONFIG_PATH

Executar uma simulação para um snapshot

Quando você usa a sinalização --snapshot-dry-run, o comando não cria um snapshot. Em vez disso, ele mostra quais ações o comando de snapshot executaria e gera um arquivo de configuração de snapshots. Para informações sobre o arquivo de configuração do snapshot, consulte Como criar um snapshot personalizado.

Para executar um snapshot de simulação no cluster de administrador, insira o seguinte comando:

bmctl check cluster --snapshot --snapshot-dry-run \
    --cluster=ADMIN_CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

Para executar um snapshot de simulação em um cluster de usuário, insira o seguinte comando:

bmctl check cluster --snapshot --snapshot-dry-run \
    --cluster=USER_CLUSTER_NAME \
    --kubeconfig=USER_KUBECONFIG_PATH

Receber registros de um período específico

É possível usar a flag --since para recuperar registros de um período de interesse específico. Dessa forma, é possível criar snapshots menores e mais focados da geração de registros que ocorreram nos últimos segundos, minutos ou horas.

Por exemplo, o comando bmctl a seguir cria um snapshot da geração de registros das últimas três horas:

bmctl check cluster --snapshot --since=3h \
    --cluster=CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

Especificar um diretório em que o snapshot seja salvo temporariamente

É possível usar a flag --snapshot-temp-output-dir para especificar um diretório em que o snapshot é salvo temporariamente:

bmctl check cluster --snapshot --snapshot-temp-output-dir=TEMP_OUTPUT_DIR \
    --cluster=CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

Se você não especificar um diretório, o snapshot será salvo temporariamente no diretório /tmp. Use a opção --snapshot-temp-output-dir quando o espaço for limitado no diretório /tmp padrão, por exemplo.

Suprimir geração de registros do console

É possível usar a flag --quiet para suprimir a exibição de mensagens de registro no console durante a execução de um snapshot. Em vez disso, os registros do console são salvos no arquivo "bmctl_diagnose_snapshot.log" como parte do snapshot.

Execute o seguinte comando para suprimir a exibição de mensagens de registro no console:

bmctl check cluster --snapshot --quiet \
    --cluster=CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

Instantâneos personalizados

É possível criar um snapshot personalizado de um cluster pelos seguintes motivos:

Para incluir mais informações sobre o cluster do que o fornecido no snapshot padrão.
Para excluir algumas informações que estão no snapshot padrão.

Como criar um snapshot personalizado

A criação de um instantâneo personalizado exige o uso de um arquivo de configuração de instantâneo. As etapas a seguir explicam como criar o arquivo de configuração, modificá-lo e usá-lo para criar um snapshot personalizado de um cluster:

Crie um arquivo de configuração de snapshot executando o seguinte comando no cluster e gravando a saída em um arquivo:

bmctl check cluster \
    --snapshot --snapshot-dry-run --cluster CLUSTER_NAME \
    --kubeconfig KUBECONFIG_PATH

Defina o tipo de informação que você quer que apareça no snapshot personalizado. Para fazer isso, modifique o arquivo de configuração de snapshot que você criou na etapa 1. Por exemplo, se você quiser que o snapshot contenha informações adicionais, como o tempo de execução de um nó específico, adicione o comando Linux uptime à seção relevante do arquivo de configuração. O trecho a seguir de um arquivo de configuração mostra como fazer o comando do snapshot fornecer informações uptime sobre o nó 10.200.0.3. Essas informações não aparecem em um snapshot padrão.
```
...
nodeCommands:
- nodes:
  - 10.200.0.3
  commands:
  - uptime
...
```
Depois de modificar o arquivo de configuração para definir que tipo de snapshot você quer, crie o snapshot personalizado executando o seguinte comando:
```
bmctl check cluster --snapshot --snapshot-config SNAPSHOT_CONFIG_FILE \
    --cluster CLUSTER_NAME--kubeconfig KUBECONFIG_PATH
```
A sinalização --snapshot-config direciona o comando bmctl para usar o conteúdo do arquivo de configuração de snapshot para definir quais informações aparecem no snapshot.

O arquivo de configuração em detalhes

O exemplo de arquivo de configuração de snapshot a seguir mostra os comandos e arquivos padrão usados para criar um snapshot, mas é possível adicionar mais comandos e arquivos quando mais informações de diagnóstico forem necessárias:

numOfParallelThreads: 10
excludeWords:
- password
nodeCommands:
- nodes:
  - 10.200.0.3
  - 10.200.0.4
  commands:
  - uptime
  - df --all --inodes
  - ip addr
  - ip neigh
  - iptables-save --counters
  - mount
  - ip route list table all
  - top -bn1 || true
  - docker info || true
  - docker ps -a || true
  - crictl ps -a || true
  - docker ps -a | grep anthos-baremetal-haproxy | cut -d ' ' -f1 | head -n 1 | xargs
    sudo docker logs || true
  - docker ps -a | grep anthos-baremetal-keepalived | cut -d ' ' -f1 | head -n 1 |
    xargs sudo docker logs || true
  - crictl ps -a | grep anthos-baremetal-haproxy | cut -d ' ' -f1 | head -n 1 | xargs
    sudo crictl logs || true
  - crictl ps -a | grep anthos-baremetal-keepalived | cut -d ' ' -f1 | head -n 1 |
    xargs sudo crictl logs || true
  - ps -edF
  - ps -eo pid,tid,ppid,class,rtprio,ni,pri,psr,pcpu,stat,wchan:14,comm,args,cgroup
  - conntrack --count
  - dmesg
  - systemctl status -l docker || true
  - journalctl --utc -u docker
  - journalctl --utc -u docker-monitor.service
  - systemctl status -l kubelet
  - journalctl --utc -u kubelet
  - journalctl --utc -u kubelet-monitor.service
  - journalctl --utc --boot --dmesg
  - journalctl --utc -u node-problem-detector
  - systemctl status -l containerd || true
  - journalctl --utc -u containerd
  - systemctl status -l docker.haproxy || true
  - journalctl --utc -u docker.haproxy
  - systemctl status -l docker.keepalived || true
  - journalctl --utc -u docker.keepalived
  - systemctl status -l container.haproxy || true
  - journalctl --utc -u container.haproxy
  - systemctl status -l container.keepalived || true
  - journalctl --utc -u container.keepalived
nodeFiles:
- nodes:
  - 10.200.0.3
  - 10.200.0.4
  files:
  - /proc/sys/fs/file-nr
  - /proc/sys/net/netfilter/nf_conntrack_max
  - /proc/sys/net/ipv4/conf/all/rp_filter
  - /lib/systemd/system/kubelet.service
  - /etc/systemd/system/kubelet.service.d/10-kubeadm.conf
  - /lib/systemd/system/docker.service || true
  - /etc/systemd/system/containerd.service || true
  - /etc/docker/daemon.json || true
  - /etc/containerd/config.toml || true
  - /etc/systemd/system/container.keepalived.service || true
  - /etc/systemd/system/container.haproxy.service || true
  - /etc/systemd/system/docker.keepalived.service || true
  - /etc/systemd/system/docker.haproxy.service || true
nodeSSHKey: ~/.ssh/id_rsa # path to your ssh key file

As seguintes entradas no arquivo de configuração provavelmente são diferentes das que aparecem no arquivo de configuração de amostra acima:

Os endereços IP dos nós nas seções nodeCommands e nodeFiles
O caminho para o nodeSSHKey do cluster

Campos no arquivo de configuração

Um arquivo de configuração de snapshot está no formato YAML. O arquivo de configuração inclui os seguintes campos:

numOfParallelThreads: a rotina de snapshot geralmente executa vários comandos. Várias linhas de execução paralelas ajudam a executar a rotina mais rapidamente. Recomendamos que você defina numOfParallelThreads como 10, conforme mostrado no arquivo de configuração de amostra anterior. Se os snapshots levarem muito tempo, aumente esse valor.
excludeWords: o snapshot contém uma grande quantidade de dados para os nós do cluster. Use excludeWords para reduzir os riscos de segurança ao compartilhar seu snapshot. Por exemplo, exclua password para que as strings de senha correspondentes não possam ser identificadas.
nodeCommands: esta seção especifica as seguintes informações:
- nodes: uma lista de endereços IP para os nós do cluster de onde você quer coletar informações. Para criar um snapshot quando o cluster de administrador não estiver acessível, especifique pelo menos um endereço IP do nó.
- commands: uma lista de comandos e argumentos a serem executados em cada nó. A saída de cada comando é incluída no snapshot.
nodeFiles: esta seção especifica as seguintes informações:
- nodes: uma lista de endereços IP dos nós de cluster em que você quer coletar arquivos. Para criar um snapshot quando o cluster de administrador não estiver acessível, especifique pelo menos um endereço IP do nó .
- files: uma lista de arquivos a serem recuperados de cada nó. Quando os arquivos especificados são encontrados em um nó, eles são incluídos no snapshot.
nodeSSHKey: caminho para o arquivo de chave SSH. Quando o cluster de administrador está inacessível, esse campo é obrigatório.

Como criar snapshots ao enfrentar erros específicos

Como criar um snapshot padrão durante instalações ou upgrades interrompidos

Ao instalar ou fazer upgrade de clusters de administrador, híbridos ou independentes, o bmctl às vezes pode ser interrompido em pontos em que os seguintes resultados podem ser vistos:

Aguardando a preparação do cluster kubeconfig.
Aguardando a preparação do cluster.
Aguardando a preparação dos pools de nós.
Aguardando a conclusão do upgrade.

Se você tiver uma instalação ou um upgrade interrompido, ainda assim poderá tirar um snapshot de um cluster usando o cluster de inicialização. Para isso, execute o seguinte comando:

bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --kubeconfig=WORKSPACE_DIR/.kindkubeconfig

Como criar um snapshot personalizado durante instalações ou upgrades interrompidos

As etapas a seguir mostram como criar um snapshot personalizado de um cluster quando uma instalação ou upgrade é interrompido:

Recupere um arquivo de configuração de snapshot do cluster dos seus arquivos.
Modifique o arquivo de configuração de snapshot para que ele contenha as informações que você quer.

Crie o snapshot personalizado executando o seguinte comando:

bmctl check cluster --snapshot
    --snapshot-config=SNAPSHOT_CONFIG_FILE \
    --cluster=CLUSTER_NAME
    --kubeconfig=WORKSPACE_DIR/.kindkubeconfig

Como criar um snapshot personalizado quando o cluster de administrador está inacessível

Quando o cluster de administrador estiver inacessível, execute o seguinte comando para capturar um snapshot personalizado do cluster:

bmctl check cluster --snapshot --cluster CLUSTER_NAME
    --node-ssh-key SSH_KEY_FILE
    --nodes NODE_1_IP_ADDRESS, NODE_2_IP_ADDRESS, ...

No comando, substitua as seguintes entradas por informações específicas ao ambiente do cluster:

CLUSTER_NAME: o nome do cluster de que você quer gerar um snapshot.
SSH_KEY_FILE: o caminho para o arquivo de chave SSH.
NODE_x_IP_ADDRESS: o endereço IP do nó do cluster sobre o qual você quer informações.

Como alternativa, é possível listar os endereços IP de nós em linhas separadas:

bmctl check cluster
    --snapshot --cluster CLUSTER_NAME \
    --node-ssh-key SSH_KEY_FILE \
    --nodes NODE_1_IP_ADDRESS \
    --nodes NODE_2_IP_ADDRESS
  ...

Informações de VM em snapshots

Se você usar o ambiente de execução de VMs no GDC para criar e gerenciar máquinas virtuais (VMs) no GKE em Bare Metal, será possível coletar informações de diagnóstico relevantes em snapshots. Os snapshots são um recurso essencial para diagnosticar e resolver problemas com as VMs.

O que é coletado por padrão

Quando você cria um snapshot padrão, ele contém as informações sobre o ambiente de execução da VM na GDC e os recursos relacionados. O ambiente de execução de VMs no GDC é empacotado com o GKE em Bare Metal e o recurso personalizado VMRuntime está disponível nos clusters que executam cargas de trabalho. Mesmo que você não ative o ambiente de execução da VM na GDC, o snapshot ainda vai conter a descrição do YAML de recurso personalizado VMRuntime.

Se você tiver ativado o ambiente de execução da VM no GDC, os snapshots vão conter informações de status e configuração para os recursos relacionados à VM (quando os objetos estiverem presentes) no cluster. Os recursos relacionados à VM incluem objetos do Kubernetes, como pods, implantações, DaemonSets e ConfigMaps.

Objetos no namespace `vm-system`

As informações de status e configuração dos objetos a seguir estão localizadas em kubectlCommands/vm-system no snapshot gerado:

KubeVirt
VirtualMachineType
VMHighAvailabilityPolicy

Objetos em outros namespaces

Ao criar uma VM (VirtualMachine), é possível especificar o namespace. Se você não especificar um namespace, a VM receberá o namespace default. Os outros objetos nesta seção, como VirtualMachineInstance, estão vinculados ao namespace da VM correspondente.

As informações de status e configuração dos objetos a seguir estão localizadas em kubectlCommands/VM_NAMESPACE no snapshot gerado. Se você não definiu um namespace específico para sua VM, as informações estarão localizadas em kubectlCommands/default:

VirtualMachine
VirtualMachineInstance
VirtualMachineDisk
GuestEnvironmentData
VirtualMachineAccessRequest
VirtualMachinePasswordResetRequest

Objetos que não têm namespace

Os objetos a seguir não têm namespace, então as informações correspondentes ficam localizadas diretamente em kubectlCommands no snapshot gerado:

VMRuntime
DataVolume
CDI
GPUAllocation

Usar um arquivo de configuração de snapshot para capturar apenas os detalhes da VM

Se você estiver diagnosticando problemas específicos para VMs, será possível usar um arquivo de configuração de snapshot para restringir as informações coletadas apenas aos detalhes relacionados à VM e adaptar as informações coletadas.

O arquivo de configuração de snapshot a seguir ilustra como criar um snapshot específico da VM. É possível incluir comandos adicionais para coletar mais informações para seu snapshot.

---
kubectlCommands:
- commands:
    - kubectl get vm -o wide
    - kubectl get vmi -o wide
    - kubectl get gvm -o wide
    - kubectl get vm -o yaml
    - kubectl get vmi -o yaml
    - kubectl get gvm -o yaml
    - kubectl describe vm
    - kubectl describe vmi
    - kubectl describe gvm
  namespaces:
    - .*
- commands:
    - kubectl get virtualmachinetype -o wide
    - kubectl get virtualmachinedisk -o wide
    - kubectl get virtualmachinetype -o yaml
    - kubectl get virtualmachinedisk -o yaml
    - kubectl describe virtualmachinetype
    - kubectl describe virtualmachinedisk
  namespaces:
    - vm-system

Para mais informações sobre como usar arquivos de configuração de snapshot, consulte Snapshots personalizados neste documento.