Como diagnosticar problemas no cluster

Neste documento, mostramos como usar o gkectl diagnose para diagnosticar problemas nos clusters.

Visão geral

A ferramenta gkectl tem dois comandos para solucionar problemas com clusters: gkectl diagnose cluster e gkectl diagnose snapshot. Os comandos funcionam com clusters de administrador e usuário.

gkectl diagnose cluster

Executar verificações de integridade no cluster e relatar os erros. Executa verificações de integridade nos componentes a seguir:

• VCenter
  • Credencial
  • DRS
  • Grupos antiafinidade
  • Rede
  • Versão
  • Data center
  • Datastore
  • ResourcePool
  • Pasta
  • Rede
• Balanceador de carga (F5, Seesaw, Manual)
• Cluster de usuários e pools de nós
• Objetos de cluster
• Objetos de máquina e os nós de cluster correspondentes
• Pods nos namespaces kube-system e gke-system
• Plano de controle do usuário se o cluster de destino for um usuário de usuário
• Volumes permanentes do vSphere no cluster
• Sinais de contenção de memória e vCPU do usuário e administrador (CPU virtual)
• O cluster de usuários e administradores ESXi configurou os alarmes de uso da CPU e da memória.
• Hora do dia (TOD)
• Política de rede de nós para um cluster com o Dataplane V2 ativado

gkectl diagnose snapshot

Compacta o status, as configurações e os registros de um cluster em um arquivo tarball. 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, Services, Endpoints, ConfigMaps, replicaSets, CronJobs, Pods e os proprietários desses pods, incluindo implantações, DaemonSets e StatefulSets

• Status do plano de controle do usuário se o cluster de destino for um usuário (o plano de controle do cluster de usuário for executado no cluster de administrador)

• 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

• Registros do contêiner no nó do plano de controle do cluster de administrador quando o servidor da API Kubernetes não está disponível.

• Informações do vSphere, incluindo objetos de VM e seus eventos, com base no pool de recursos. Inclui ainda objetos Datacenter, Cluster, Rede e Datastore associados às VMs.

• Informações do balanceador de carga F5 BIG-IP, incluindo servidor virtual, endereço virtual, pool, nó e monitor

• Registros do comando gkectl diagnose snapshot

• Um arquivo de índice HTML para todos os arquivos no snapshot

• Opcionalmente, o arquivo de configuração do cluster usado para instalar e fazer upgrade do cluster

As credenciais, incluindo as credenciais vSphere e F5, são removidas antes da criação do tarball.

Como diagnosticar clusters

Execute gke diagnose cluster para procurar problemas comuns no cluster.

Observação: a sinalização --kubeconfig sempre precisa apontar para o arquivo kubeconfig do cluster de administrador. gkectl diagnose retorna um erro se você fornecer o kubeconfig do cluster de usuário.

Observação: quando houver problemas de VIP com o cluster de segmentação, use o --config para fornecer o arquivo de configuração do cluster de administrador. Isso fornece mais informações de depuração.

gkectl diagnose cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config ADMIN_CLUSTER_CONFIG

Exemplo de saída:

Failed to access the api server via LB VIP "...": ...
Try to use the admin master IP instead of problematic VIP...
Reading config with version "[CONFIG_VERSION]"
Finding the admin master VM...
Fetching the VMs in the resource pool "[RESOURCE_POOL_NAME]"...
Found the "[ADMIN_MASTER_VM_NAME]" is the admin master VM.
Diagnosing admin|user cluster "[TARGET_CLUSTER_NAME]"...
...

Como diagnosticar um cluster de administrador

É possível diagnosticar um cluster de administrador passando o nome dele ou apenas passando o kubeconfig.

Como usar o kubeconfig do cluster de administrador

Passar no kubeconfig do cluster de administrador faz com que gkectl escolha automaticamente o cluster de administrador:

gkectl diagnose cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG]

Como usar o nome do cluster de administrador

Para saber o nome do cluster de administração, execute o seguinte comando:

kubectl get cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG]

Em seguida, transmita o nome do cluster de administrador para gkectl diagnose cluster:

gkectl diagnose cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[ADMIN_CLUSTER_NAME]

Se o cluster de administrador estiver funcionando corretamente, gkectl diagnose cluster retornará uma saída semelhante a esta:

Preparing for the diagnose tool...
Diagnosing the cluster......DONE

- Validation Category: Admin Cluster Connectivity
Checking VMs TOD (availability)...SUCCESS

- Validation Category: Admin Cluster F5 BIG-IP
Checking f5 (credentials, partition)...SUCCESS

- Validation Category: Admin Cluster VCenter
Checking Credentials...SUCCESS
Checking DRS enabled...SUCCESS
Checking Hosts for AntiAffinityGroups...SUCCESS
Checking Version...SUCCESS
Checking Datacenter...SUCCESS
Checking Datastore...SUCCESS
Checking Resource pool...SUCCESS
Checking Folder...SUCCESS
Checking Network...SUCCESS

- Validation Category: Admin Cluster
Checking cluster object...SUCCESS
Checking machine deployment...SUCCESS
Checking machineset...SUCCESS
Checking machine objects...SUCCESS
Checking kube-system pods...SUCCESS
Checking anthos-identity-service pods...SUCCESS
Checking storage...SUCCESS
Checking resource...SUCCESS
Checking virtual machine resource contention...SUCCESS
Checking host resource contention...SUCCESS
All validation results were SUCCESS.
Cluster is healthy!

Como diagnosticar um cluster de usuário

Para diagnosticar um cluster, primeiro consiga o nome dele:

kubectl get cluster --kubeconfig=[USER_CLUSTER_KUBECONFIG]

Em seguida, passe o kubeconfig do cluster de administrador e o nome do cluster do usuário:

gkectl diagnose cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
  --cluster-name=[USER_CLUSTER_NAME]

Observação: gkectl diagnose retornará um erro se você fornecer o kubeconfig do cluster de usuários.

Se o cluster de usuários estiver funcionando corretamente, gkectl diagnose cluster retornará uma saída semelhante a esta:

Preparing for the diagnose tool...
Diagnosing the cluster......DONE

Diagnose result is saved successfully in 

- Validation Category: User Cluster Connectivity
Checking Node Network Policy...SUCCESS
Checking VMs TOD (availability)...SUCCESS

- Validation Category: User Cluster F5 BIG-IP
Checking f5 (credentials, partition)...SUCCESS

- Validation Category: User Cluster VCenter
Checking Credentials...SUCCESS
Checking DRS enabled...SUCCESS
Checking Hosts for AntiAffinityGroups...SUCCESS
Checking VSphere CSI Driver...SUCCESS
Checking Version...SUCCESS
Checking Datacenter...SUCCESS
Checking Datastore...SUCCESS
Checking Resource pool...SUCCESS
Checking Folder...SUCCESS
Checking Network...SUCCESS

- Validation Category: User Cluster
Checking user cluster and node pools...SUCCESS
Checking cluster object...SUCCESS
Checking machine deployment...SUCCESS
Checking machineset...SUCCESS
Checking machine objects...SUCCESS
Checking control plane pods...SUCCESS
Checking kube-system pods...SUCCESS
Checking gke-system pods...SUCCESS
Checking gke-connect pods...SUCCESS
Checking anthos-identity-service pods...SUCCESS
Checking storage...SUCCESS
Checking resource...SUCCESS
Checking virtual machine resource contention...SUCCESS
Checking host resource contention...SUCCESS
All validation results were SUCCESS.
Cluster is healthy!

Solução de problemas de cluster diagnosticado

Se você tiver os seguintes problemas ao executar o comando gke diagnose cluster, veja algumas soluções possíveis.

.

Problema	Causas possíveis	Resolução
O servidor da API Kubernetes não está acessível, seja para o cluster de administração ou para clusters de usuários.	Verifique os gráficos de latência de memória (OBB, na sigla em inglês) de integridade da máquina virtual, que preferencialmente têm uma latência de memória por volta de zero. A contenção de memória também pode aumentar a contenção da CPU e os gráficos de prontidão da CPU podem ter um pico, porque haverá interação.	Aumente a memória física. Para ver outras opções, consulte Sugestões de solução de problemas do VMware.
A criação do pool de nós expira.	Alta latência de leitura/gravação do VMDK. Verifique a integridade da integridade da VM para a latência de leitura e gravação do disco virtual. De acordo com o VMware, uma latência total maior que 20 ms indica um problema.	Consulte Soluções de VMware para problemas de desempenho do disco.

Como capturar o estado do cluster

Se gkectl diagnose cluster encontrar erros, será necessário capturar o estado do cluster e fornecer as informações ao Google. É possível fazer isso usando o comando gkectl diagnose snapshot.

gkectl diagnose snapshot tem uma sinalização opcional, --config. Além de coletar informações sobre o cluster, essa sinalização coleta os clusters do Anthos no arquivo de configuração da VMware que foi usado para criar ou fazer upgrade do cluster.

Observação: a sinalização --kubeconfig sempre precisa apontar para o arquivo kubeconfig do cluster de administrador. gkectl diagnose retornará um erro se você fornecer o kubeconfig do cluster de usuário.

Como capturar o estado do cluster de administrador

Para capturar o estado de um cluster de administrador, execute o seguinte comando, em que --config é opcional:

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] [--config]

Observação: quando houver um problema VIP com o cluster de destino, use --config para fornecer o arquivo de configuração do cluster de administrador. Isso fornece mais informações de depuração.

A saída inclui uma lista de arquivos e o nome de um arquivo tarball:

Taking snapshot of admin cluster "[ADMIN_CLUSTER_NAME]"...
   Using default snapshot configuration...
   Setting up "[ADMIN_CLUSTER_NAME]" ssh key file...DONE
   Taking snapshots...
       commands/kubectl_get_pods_-o_yaml_--kubeconfig_...env.default.kubeconfig_--namespace_kube-system
       commands/kubectl_get_deployments_-o_yaml_--kubeconfig_...env.default.kubeconfig_--namespace_kube-system
       commands/kubectl_get_daemonsets_-o_yaml_--kubeconfig_...env.default.kubeconfig_--namespace_kube-system
       ...
       nodes/[ADMIN_CLUSTER_NODE]/commands/journalctl_-u_kubelet
       nodes/[ADMIN_CLUSTER_NODE]/files/var/log/startup.log
       ...
   Snapshot succeeded. Output saved in [TARBALL_FILE_NAME].tar.gz.

Para extrair o arquivo tarball para um diretório, execute o seguinte comando:

tar -zxf [TARBALL_FILE_NAME] --directory [EXTRACTION_DIRECTORY_NAME]

Para ver a lista de arquivos produzidos pelo snapshot, execute os seguintes comandos:

cd [EXTRACTION_DIRECTORY_NAME]/[EXTRACTED_SNAPSHOT_DIRECTORY]
ls kubectlCommands
ls nodes/[NODE_NAME]/commands
ls nodes/[NODE_NAME]/files

Para ver os detalhes de uma operação específica, abra um dos arquivos.

Como especificar a chave SSH para o cluster de administrador

Quando você recebe um snapshot do cluster de administrador, o gkectl encontra a chave SSH privada do cluster de administrador automaticamente. Também é possível especificar a chave explicitamente usando o parâmetro --admin-ssh-key-path.

Siga as instruções sobre Como usar o SSH para se conectar a um nó de cluster para fazer o download das chaves SSH.

Em seguida, no comando gkectl diagnose snapshot, defina --admin-ssh-key-path como o caminho do arquivo de chave decodificado:

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--admin-ssh-key-path=[PATH_TO_DECODED_KEY]

Como capturar o estado do cluster de usuário

Para capturar o estado de um cluster de usuário, execute o seguinte comando:

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME]

A saída inclui uma lista de arquivos e o nome de um arquivo tarball:

Taking snapshot of user cluster "[USER_CLUSTER_NAME]"...
Using default snapshot configuration...
Setting up "[USER_CLUSTER_NAME]" ssh key file...DONE
    commands/kubectl_get_pods_-o_yaml_--kubeconfig_...env.default.kubeconfig_--namespace_user
    commands/kubectl_get_deployments_-o_yaml_--kubeconfig_...env.default.kubeconfig_--namespace_user
    commands/kubectl_get_daemonsets_-o_yaml_--kubeconfig_...env.default.kubeconfig_--namespace_user
    ...
    commands/kubectl_get_pods_-o_yaml_--kubeconfig_.tmp.user-kubeconfig-851213064_--namespace_kube-system
    commands/kubectl_get_deployments_-o_yaml_--kubeconfig_.tmp.user-kubeconfig-851213064_--namespace_kube-system
    commands/kubectl_get_daemonsets_-o_yaml_--kubeconfig_.tmp.user-kubeconfig-851213064_--namespace_kube-system
    ...
    nodes/[USER_CLUSTER_NODE]/commands/journalctl_-u_kubelet
    nodes/[USER_CLUSTER_NODE]/files/var/log/startup.log
    ...
Snapshot succeeded. Output saved in [FILENAME].tar.gz.

Cenários de snapshots

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

• system: (padrão) coleta um snapshot para os namespaces do sistema: kube-system e gke-system.

• system-with-logs: colete um snapshot system com registros.

• all: colete um snapshot para todos os namespaces.

• all-with-logs: colete um snapshot all com registros.

É possível usar cada um dos quatro cenários com um cluster de administrador ou um de usuário. Portanto, há oito permutações possíveis. Os exemplos a seguir mostram algumas das possibilidades.

Para criar um snapshot do cluster de administrador usando o cenário system:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--scenario=system

Para criar um snapshot de um cluster de usuários usando o cenário system-with-logs:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--scenario=system-with-logs

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

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--scenario=all

Para criar um snapshot do cluster de administrador usando o cenário all-with-logs:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--scenario=all-with-logs

Como usar --log-since para limitar um snapshot

Nos cenários system-with-logs e all-with-logs, use a sinalização --log-since para limitar a coleta de registros a um período recente. Por exemplo, é possível coletar apenas os registros dos últimos dois dias ou das últimas três horas. Por padrão, diagnose snapshot coleta todos os registros.

Para limitar o período da coleta de registros:

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[CLUSTER_NAME] \
--scenario=system-with-logs \
--log-since=[DURATION]

Substitua [DURATION] por um valor de tempo como 120m ou 48h.

Observações:

• A sinalização --log-since é compatível apenas com os registros kubectl e journalctl.
• Sinalizações de comando como --log-since não são permitidas na configuração do snapshot personalizado.

Como executar uma simulação para um snapshot

É possível usar a sinalização --dry-run para mostrar as ações a serem realizadas e a configuração do snapshot.

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

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[ADMIN_CLUSTER_NAME] \
--dry-run

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

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--dry-run

Como usar uma configuração de snapshot

Se os quatro cenários não atenderem às suas necessidades, crie um snapshot personalizado transmitindo um arquivo de configuração de snapshot usando a sinalização --snapshot-config:

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--snapshot-config=[SNAPSHOT_CONFIG_FILE]

Como gerar uma configuração de snapshot

É possível gerar uma configuração de snapshot para um determinado cenário transmitindo as sinalizações --scenario e --dry-run. Por exemplo, para ver a configuração de snapshot do cenário padrão (system) de um cluster de usuário, digite o seguinte comando:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--scenario=system
--dry-run

A resposta será semelhante a:

numOfParallelThreads: 10
excludeWords:
- password
kubectlCommands:
- commands:
  - kubectl get clusters -o wide
  - kubectl get machines -o wide
  - kubectl get clusters -o yaml
  - kubectl get machines -o yaml
  - kubectl describe clusters
  - kubectl describe machines
  namespaces:
  - default
- commands:
  - kubectl version
  - kubectl cluster-info
  - kubectl get nodes -o wide
  - kubectl get nodes -o yaml
  - kubectl describe nodes
  namespaces: []
- commands:
  - kubectl get pods -o wide
  - kubectl get deployments -o wide
  - kubectl get daemonsets -o wide
  - kubectl get statefulsets -o wide
  - kubectl get replicasets -o wide
  - kubectl get services -o wide
  - kubectl get jobs -o wide
  - kubectl get cronjobs -o wide
  - kubectl get endpoints -o wide
  - kubectl get configmaps -o wide
  - kubectl get pods -o yaml
  - kubectl get deployments -o yaml
  - kubectl get daemonsets -o yaml
  - kubectl get statefulsets -o yaml
  - kubectl get replicasets -o yaml
  - kubectl get services -o yaml
  - kubectl get jobs -o yaml
  - kubectl get cronjobs -o yaml
  - kubectl get endpoints -o yaml
  - kubectl get configmaps -o yaml
  - kubectl describe pods
  - kubectl describe deployments
  - kubectl describe daemonsets
  - kubectl describe statefulsets
  - kubectl describe replicasets
  - kubectl describe services
  - kubectl describe jobs
  - kubectl describe cronjobs
  - kubectl describe endpoints
  - kubectl describe configmaps
  namespaces:
  - kube-system
  - gke-system
  - gke-connect.*
prometheusRequests: []
nodeCommands:
- nodes: []
  commands:
  - uptime
  - df --all --inodes
  - ip addr
  - sudo iptables-save --counters
  - mount
  - ip route list table all
  - top -bn1
  - sudo docker ps -a
  - ps -edF
  - ps -eo pid,tid,ppid,class,rtprio,ni,pri,psr,pcpu,stat,wchan:14,comm,args,cgroup
  - sudo conntrack --count
nodeFiles:
- nodes: []
  files:
  - /proc/sys/fs/file-nr
  - /proc/sys/net/nf_conntrack_max
seesawCommands: []
seesawFiles: []
nodeCollectors:
- nodes: []
f5:
  enabled: true
vCenter:
  enabled: true

• numOfParallelThreads: número de linhas de execução paralelas usadas para tirar snapshots.

• excludeWords: lista de palavras a serem excluídas do snapshot (não diferencia maiúsculas de minúsculas). As linhas que contêm essas palavras são removidas dos resultados do snapshot. A "senha" é sempre excluída, independentemente de você especificá-la ou não.

• kubectlCommands: lista de comandos kubectl a serem executados. Os resultados são salvos. Os comandos são executados nos namespaces correspondentes. Para comandos kubectl logs, todos os pods e contêineres nos namespaces correspondentes são adicionados automaticamente. As expressões regulares são compatíveis com a especificação de namespaces. Se você não especificar um namespace, o namespace default será usado.

• nodeCommands: lista de comandos a serem executados nos nós correspondentes. Os resultados são salvos. Quando os nós não são especificados, todos os nós no cluster de destino são considerados.

• nodeFiles: lista de arquivos a serem coletados dos nós correspondentes. Os arquivos são salvos. Quando os nós não são especificados, todos os nós no cluster de destino são considerados.

• seesawCommands: lista de comandos a serem executados para coletar informações do balanceador de carga da Seesaw. Os resultados serão salvos se o cluster estiver usando o balanceador de carga Seesaw.

• seesawFiles: lista de arquivos a serem coletados para o balanceador de carga da Seesaw.

• nodeCollectors: um coletor em execução para nós Cilium que reúne informações de eBPF.

• f5: uma sinalização para ativar a coleta de informações relacionadas com o balanceador de carga F5 BIG-IP.

• vCenter: uma sinalização para ativar a coleta de informações relacionadas com o vCenter.

• prometheusRequests: lista de solicitações do Prometheus. Os resultados são salvos.

Fazer upload de snapshots para um bucket do Google Cloud Storage

Para facilitar a manutenção de registros, a análise e o armazenamento, faça upload de todos os snapshots de um cluster de usuário específico para um bucket do Google Cloud Storage. Isso é útil principalmente se você precisar de ajuda do Suporte do Google Cloud.

Antes de executar esse comando, verifique se você cumpriu esses requisitos de configuração.

• Ative storage.googleapis.com no projeto de conexão. Embora seja possível usar um projeto diferente, o projeto de conexão é recomendado.

gcloud services enable --project=FLEET_HOST_PROJECT_ID \
storage.googleapis.com

• Conceda o roles/storage.admin à conta de serviço no projeto pai e transmita o arquivo de chave json da conta de serviço usando o parâmetro --service-account-key-file. É possível usar qualquer conta de serviço, mas recomendamos o uso da conta de serviço do registro de conexão. Consulte Contas de serviço para mais informações.

gcloud projects add-iam-policy-binding FLEET_HOST_PROJECT_ID \
    --member "serviceAccount:CONNECT_REGISTER_SERVICE_ACCOUNT" \
    --role "roles/storage.admin"

Com esses requisitos atendidos, agora é possível fazer o upload do snapshot com este comando:

gkectl diagnose snapshot --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
--cluster-name CLUSTER_NAME \
--upload-to BUCKET_NAME  \
--service-account-key-file SERVICE_ACCOUNT_KEY_FILE

Substitua SERVICE_ACCOUNT_KEY_FILE pelo nome do arquivo de chave da conta de serviço.

Exemplo de saída:

Using "system" snapshot configuration...
Taking snapshot of user cluster CLUSTER_NAME...
Setting up CLUSTER_NAME ssh key...DONE
Using the gke-connect register service account key...
Setting up Google Cloud Storage bucket for uploading the snapshot...DONE
Taking snapshots in 10 thread(s)...
   ...
Snapshot succeeded.
Snapshots saved in "SNAPSHOT_FILE_PATH".
Uploading snapshot to Google Cloud Storage......  DONE
Uploaded the snapshot successfully to gs://BUCKET_NAME/CLUSTER_NAME/SNAPSHOT_FILE_NAME.

Problemas conhecidos

Versão 1.1.2-gke.0: caminho resolvido para vários data centers

Consulte os clusters do Anthos nas notas da versão do VMware.

Versões 1.1.x: volume não anexado à máquina

Consulte os clusters do Anthos nas notas da versão do VMware.