Criar snapshots para diagnosticar problemas de cluster

A ferramenta gkectl tem dois comandos para solucionar problemas com clusters: gkectl diagnose snapshot e gkectl diagnose cluster. Os comandos funcionam com clusters de administrador e usuário. Neste documento, mostramos como usar o comando gkectl diagnose para criar snapshots de diagnóstico para solucionar problemas nos clusters.

Para mais informações sobre como usar o comando gkectl diagnose cluster para diagnosticar problemas de cluster, consulte Diagnosticar problemas de cluster.

Se precisar de mais ajuda, entre em contato com o Cloud Customer Care.

gkectl diagnose snapshot

Esse comando compacta o status, as configurações e os registros de um cluster em um arquivo .tar. Quando você executa gkectl diagnose snapshot, o comando executa automaticamente gkectl diagnose cluster como parte do processo, e os arquivos de saída são colocados em uma nova pasta no snapshot chamada /diagnose-report.

Snapshot padrão

A configuração padrão do comando gkectl diagnose snapshot 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

  • Status do plano de controle.

  • 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 de contêiner do 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. Também coleta informações sobre os objetos Datacenter, Cluster, Network e Datastore associados às VMs.

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

  • Registros do comando gkectl diagnose snapshot

  • Registros de jobs de simulação.

  • Registros de contêineres em namespaces com base nos cenários.

  • Informações sobre a expiração do certificado do Kubernetes do cluster de administrador no arquivo de snapshot /nodes/<admin_master_node_name>/sudo_kubeadm_certs_check-expiration.

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

  • Opcionalmente, o arquivo de configuração do cluster de administrador usado para instalar e fazer upgrade do cluster com a sinalização--config.

As credenciais, incluindo para o vSphere e F5, são removidas antes da criação do arquivo .tar.

Instantâneo leve

Na versão 1.29 e mais recentes do Google Distributed Cloud, uma versão leve de gkectl diagnose snapshot está disponível para os clusters de administrador e de usuário. O snapshot leve acelera o processo porque captura menos informações sobre o cluster. Quando você adiciona --scenario=lite ao comando, apenas as seguintes informações são incluídas no snapshot:

  • 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

  • Registros do comando gkectl diagnose snapshot

Capturar o estado do cluster

Se os comandos gkectl diagnose cluster encontrarem erros, capture o estado do cluster e forneça as informações ao Cloud Customer Care. É possível capturar essas informações usando o comando gkectl diagnose snapshot.

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

Capturar o estado do cluster de administrador

Para capturar o estado de um cluster de administrador, execute o seguinte comando:

gkectl diagnose snapshot --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config

O parâmetro --config é opcional:

Se houver um problema com um endereço IP virtual (VIP, na sigla em inglês) no cluster de destino, use a sinalização --config para fornecer o arquivo de configuração do cluster de administrador e fornecer mais informações de depuração.

Na versão 1.29 e mais recentes, é possível incluir --scenario=lite se você não precisar de todas as informações no snapshot padrão.

A saída inclui uma lista de arquivos e o nome de um arquivo .tar, conforme mostrado no exemplo de saída a seguir:

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 [TAR_FILE_NAME].tar.gz.

Para extrair o arquivo .tar em um diretório, execute o seguinte comando:

tar -zxf TAR_FILE_NAME --directory EXTRACTION_DIRECTORY_NAME

Substitua:

  • TAR_FILE_NAME: o nome do arquivo .tar.

  • EXTRACTION_DIRECTORY_NAME: o diretório em que você quer extrair o arquivo .tar.

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

Substitua NODE_NAME pelo nome do nó em que você quer visualizar os arquivos.

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

Especifique a chave SSH do 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.

No comando gkectl diagnose snapshot, defina --admin-ssh-key-path como o caminho de chave decodificado:

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

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

O exemplo de saída a seguir inclui uma lista de arquivos e o nome de um arquivo tar:

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

Os cenários de snapshot permitem controlar as informações incluídas em um snapshot. Para especificar um cenário, use a sinalização --scenario. A lista a seguir mostra os valores possíveis:

  • system (padrão): colete snapshots com registros em namespaces do sistema compatíveis.

  • all: colete snapshots com registros em todos os namespaces, incluindo namespaces definidos pelo usuário.

  • lite (1.29 e mais recentes): colete snapshots apenas com recursos do Kubernetes e registros gkectl. Todos os outros registros, como registros de contêiner e de kernel de nó, são excluídos.

Os cenários de snapshot disponíveis variam de acordo com a versão do Google Distributed Cloud.

  • Versões anteriores à 1.13: system, system-with-logs, all e all-with-logs.

  • Versões 1.13 - 1.28: system e all. O cenário system é o mesmo que o antigo system-with-logs. O cenário all é o mesmo que o antigo all-with-logs.

  • Versões 1.29 e mais recentes: system, all e lite.

Para criar um snapshot do cluster de administrador, não é necessário especificar um cenário:

gkectl diagnose snapshot \
    --kubeconfig=ADMIN_CLUSTER_KUBECONFIG

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

gkectl diagnose snapshot \
    --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
    --cluster-name=USER_CLUSTER_NAME \
    --scenario=system

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 de um cluster de usuário usando o cenário lite:

gkectl diagnose snapshot \
    --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
    --cluster-name=USER_CLUSTER_NAME \
    --scenario=lite

Usar --log-since para limitar um snapshot

É possível usar 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.

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

Substitua <var>DURATION</var> por um valor de tempo como 120m ou 48h.

As seguintes considerações se aplicam:

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

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

Usar uma configuração de snapshot

Se esses dois cenários (--scenario system ou all) não atenderem às suas necessidades, crie um snapshot personalizado transmitindo um arquivo de configuração usando a sinalização --snapshot-config:

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

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

As informações a seguir são exibidas na saída:

  • 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 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 em um bucket do Cloud Storage. Isso é muito útil se você precisar de ajuda do Cloud Customer Care.

Antes de fazer upload de snapshots para um bucket do Cloud Storage, revise e atenda aos seguintes requisitos iniciais:

  • Ative storage.googleapis.com no projeto host da frota. Embora seja possível usar um projeto diferente, o projeto host da frota é 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"

    Substitua CONNECT_REGISTER_SERVICE_ACCOUNT pela conta de serviço do registro de conexão.

Com esses requisitos atendidos, agora é possível fazer upload do snapshot para o bucket do Cloud Storage:

gkectl diagnose snapshot --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
    --cluster-name CLUSTER_NAME \
    --upload \
    --share-with GOOGLE_SUPPORT_SERVICE_ACCOUNT

A sinalização --share-with pode aceitar uma lista de nomes de contas de serviço. Substitua GOOGLE_SUPPORT_SERVICE_ACCOUNT pela conta de serviço do Cloud Customer Care fornecida pelo Cloud Customer Care, além de outras contas de serviço fornecidas pelo Cloud Customer Care.

Quando você usa a sinalização --upload, o comando procura no projeto um bucket de armazenamento que tenha um nome que comece com "anthos-snapshot-". Se esse bucket existir, 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 universal exclusivo de 32 dígitos.

Ao usar a sinalização --share-with, você não precisa compartilhar manualmente o acesso ao bucket com o Cloud Customer Care.

O exemplo de saída a seguir é exibido quando você faz upload de um snapshot para um bucket do Cloud Storage:

Using "system" snapshot configuration...
Taking snapshot of user cluster <var>CLUSTER_NAME</var>...
Setting up <var>CLUSTER_NAME</var> 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 "<var>SNAPSHOT_FILE_PATH</var>".
Uploading snapshot to Google Cloud Storage......  DONE
Uploaded the snapshot successfully to gs://anthos-snapshot-a4b17874-7979-4b6a-a76d-e49446290282/<var>xSNAPSHOT_FILE_NAME</var>.
Shared successfully with service accounts:
<var>GOOGLE_SUPPORT_SERVICE_ACCOUNT</var>

A seguir

Se precisar de mais ajuda, entre em contato com o Cloud Customer Care.