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 de VMs no Google Distributed Cloud 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:

  1. Configure a API e a conta de serviço:

    1. Ative a API Cloud Storage no projeto do Google Cloud.
    2. Conceda um papel storage.admin à conta de serviço para que ela possa fazer upload de dados no Cloud Storage.
    3. Faça o download da chave JSON da conta de serviço.

    Consulte os detalhes em Como ativar contas de serviço e serviços do Google.

  2. 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 \
    --kubeconfig=KUBECONFIG_PATH \
    --upload-to BUCKET_NAME \
    [--service-account-key-file SERVICE_ACCOUNT_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.
    • KUBECONFIG_PATH: o caminho até o arquivo kubeconfig do cluster de administrador. (O caminho para o arquivo kubeconfig é bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME-kubeconfig por padrão. No entanto, se você tiver especificado seu espaço de trabalho com a sinalização WORKSPACE_DIR, o caminho será WORKSPACE_DIR/CLUSTER_NAME/CLUSTER_NAME-kubeconfig).
    • BUCKET_NAME: o nome de um bucket do Cloud Storage que é seu.
    • SERVICE_ACCOUNT_KEY_FILE: se você não fornecer a sinalização --service-account-key-file, bmctl tentará buscar o caminho para o arquivo de chave da conta de serviço da variável de ambiente GOOGLE_APPLICATION_CREDENTIALS.

  3. Crie uma conta de serviço e compartilhe o acesso com o Cloud Customer Care, conforme descrito em Permitir que o suporte do Google Cloud visualize seu snapshot do cluster enviado.

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

É possível capturar o estado dos clusters criados com o comando:

bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --kubeconfig=KUBECONFIG_PATH

Substitua:

  • CLUSTER_NAME: o nome do cluster de destino.

  • KUBECONFIG_PATH: o caminho até o arquivo kubeconfig do cluster de administrador. (O caminho para o arquivo kubeconfig é bmctl-workspace/CLUSTER_NAME/CLUSTER_NAME-kubeconfig por padrão. No entanto, se você tiver especificado seu espaço de trabalho com a sinalização WORKSPACE_DIR, o caminho será WORKSPACE_DIR/CLUSTER_NAME/CLUSTER_NAME-kubeconfig).

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

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=ADMIN_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=ADMIN_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:

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

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

  3. 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:

  1. Recupere um arquivo de configuração de snapshot do cluster dos seus arquivos.

  2. Modifique o arquivo de configuração de snapshot para que ele contenha as informações que você quer.

  3. 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 da VM no Google Distributed Cloud 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 de VMs no Google Distributed Cloud e os recursos relacionados. O ambiente de execução de VMs no Google Distributed Cloud é fornecido com o GKE em Bare Metal, e o recurso personalizado VMRuntime está disponível nos clusters que executam cargas de trabalho. Mesmo que não tenha ativado o ambiente de execução de VMs no Google Distributed Cloud, o snapshot ainda vai conter a descrição YAML do recurso personalizado VMRuntime.

Se você tiver ativado o ambiente de execução da VM no Google Distributed Cloud, os snapshots vão conter informações de status e configuração dos recursos relacionados à VM (quando os objetos estão 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.