创建快照以诊断集群问题

gkectl 工具有两个用于排查集群问题的命令:gkectl diagnose snapshotgkectl diagnose cluster。这两个命令适用于管理员集群和用户集群。 本文档介绍如何使用 gkectl diagnose 命令创建诊断快照,以排查集群中的问题。

如需详细了解如何使用 gkectl diagnose cluster 命令诊断集群问题,请参阅诊断集群问题

如果您需要其他帮助,请与 Cloud Customer Care 联系。

gkectl diagnose snapshot

此命令会将集群的状态、配置和日志压缩到一个 tar 文件中。当您运行 gkectl diagnose snapshot 时,该命令会在过程中自动运行 gkectl diagnose cluster,并将输出文件放在快照中名为 /diagnose-report 的新文件夹中。

默认快照

gkectl diagnose snapshot 命令的默认配置会捕获有关集群的以下信息:

  • Kubernetes 版本。

  • kubenetes 资源在 kube-system 和 gke-system 命名空间中的状态:集群、机器、节点、服务、端点、ConfigMap、ReplicaSet、CronJob、Pod 以及这些 Pod 的所有者,包括 Deployment、DaemonSet 和 StatefulSet。

  • 控制平面的状态。

  • 有关每个节点配置的详细信息,包括 IP 地址、iptables 规则、装载点、文件系统、网络连接,以及正在运行的进程。

  • 当 Kubernetes API 服务器不可用时,来自管理员集群的控制平面节点的容器日志。

  • vSphere 信息,包括虚拟机对象及其基于资源池的事件。此外,还会收集与虚拟机关联的数据中心、集群、网络和 Datastore 对象的相关信息。

  • F5 BIG-IP 负载均衡器信息,包括虚拟服务器、虚拟地址、池、节点和监控器。

  • 来自 gkectl diagnose snapshot 命令的日志。

  • 预检作业的日志。

  • 基于场景的命名空间中容器的日志。

  • 快照文件 /nodes/<admin_master_node_name>/sudo_kubeadm_certs_check-expiration 中有关管理员集群 Kubernetes 证书到期时间的信息。

  • 快照中所有文件的 HTML 索引文件。

  • (可选)用于安装和升级具有 --config 标志的集群的管理员集群配置文件。

在创建 tar 文件之前,系统会移除凭据(包括 vSphere 和 F5 的凭据)。

轻量级快照

在 Google Distributed Cloud 1.29 及更高版本中,为管理员集群和用户集群提供了轻量级 gkectl diagnose snapshot 版本。轻量级快照可加快快照的创建过程,因为它捕获的集群相关信息较少。将 --scenario=lite 添加到命令时,快照中仅包含以下信息:

  • kubenetes 资源在 kube-system 和 gke-system 命名空间中的状态:集群、机器、节点、服务、端点、ConfigMap、ReplicaSet、CronJob、Pod 以及这些 Pod 的所有者,包括 Deployment、DaemonSet 和 StatefulSet

  • 来自 gkectl diagnose snapshot 命令的日志

捕获集群状态

如果 gkectl diagnose cluster 命令发现错误,您应捕获集群的状态并将信息提供给 Cloud Customer Care 团队。您可以使用 gkectl diagnose snapshot 命令捕获此信息。

gkectl diagnose snapshot 有一个用于 --config 的可选标志。除了收集有关集群的信息之外,此标志还会收集用于创建或升级集群的 GKE on VMware 配置文件。

捕获管理员集群状态

要捕获管理员集群的状态,请运行以下命令:

gkectl diagnose snapshot --kubeconfig=ADMIN_CLUSTER_KUBECONFIG --config

--config 参数是可选的:

如果目标集群中的虚拟 IP 地址 (VIP) 存在问题,请使用 --config 标志提供管理员集群配置文件,以提供更多调试信息。

在 1.29 及更高版本中,如果您不需要默认快照中的所有信息,则可以添加 --scenario=lite

输出包括文件列表和 tar 文件的名称,如以下示例输出所示:

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.

如需将 tar 文件解压缩到某个目录,请运行以下命令:

tar -zxf TAR_FILE_NAME --directory EXTRACTION_DIRECTORY_NAME

请替换以下内容:

  • TAR_FILE_NAME:tar 文件的名称。

  • EXTRACTION_DIRECTORY_NAME:您要将 tar 文件归档解压缩到的目录。

要查看快照生成的文件列表,请运行以下命令:

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

NODE_NAME 替换为您要查看其文件的节点的名称。

要查看特定操作的详细信息,请打开其中一个文件。

指定管理员集群的 SSH 密钥

获取管理员集群的快照时,gkectl 会自动查找管理员集群的私有 SSH 密钥。您还可以使用 --admin-ssh-key-path 参数显式指定密钥。

按照使用 SSH 连接到集群节点中的说明下载 SSH 密钥。

gkectl diagnose snapshot 命令中,将 --admin-ssh-key-path 设置为解码后的密钥路径:

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

捕获用户集群状态

要捕获用户集群的状态,请运行以下命令:

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

以下示例输出包含文件列表和 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.

快照场景

通过快照场景,您可以控制快照中包含的信息。如需指定场景,请使用 --scenario 标志。以下列表显示了可能的值:

  • system(默认):在受支持的系统命名空间中收集包含日志的快照。

  • all:收集所有命名空间(包括用户定义的命名空间)中的日志快照。

  • lite(1.29 及更高版本):仅使用 Kubernetes 资源和 gkectl 日志收集快照。所有其他日志(例如容器日志和节点内核日志)均被排除在外。

可用的快照场景因 Google Distributed Cloud 版本而异。

  • 低于 1.13 的版本:systemsystem-with-logsallall-with-logs

  • 版本 1.13 - 1.28:systemallsystem 场景与旧 system-with-logs 场景相同。all 场景与旧的 all-with-logs 场景相同。

  • 版本 1.29 及更高版本:systemalllite

如需创建管理员集群的快照,您无需指定场景:

gkectl diagnose snapshot \
    --kubeconfig=ADMIN_CLUSTER_KUBECONFIG

要使用 system 场景创建用户集群的快照,请执行以下操作:

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

要使用 all 场景创建用户集群的快照,请执行以下操作:

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

要使用 lite 场景创建用户集群的快照,请执行以下操作:

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

使用 --log-since 限制快照

您可以使用 --log-since 标志将日志收集限制为最近的时间段。例如,您可以仅收集过去两天或过去三小时的日志。默认情况下,diagnose snapshot 会收集所有日志。

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

<var>DURATION</var> 替换为时间值,如 120m48h

需要注意以下几点:

  • kubectljournalctl 日志支持 --log-since 标志。
  • 自定义快照配置中不允许使用 --log-since 等命令标志。

对快照执行试运行

您可以使用 --dry-run 标志来显示要执行的操作和快照配置。

要在管理员集群上执行试运行,请输入以下命令:

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

要在用户集群上执行试运行,请输入以下命令:

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

使用快照配置

如果这两种场景(--scenario systemall)不能满足您的需求,您可以通过使用 --snapshot-config 标志传入快照配置文件来创建自定义快照:

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

生成快照配置

您可以通过传入 --scenario--dry-run 标志为给定场景生成快照配置。例如,要查看用户集群的默认场景 (system) 的快照配置,请输入以下命令:

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

输出类似于以下示例:

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:用于截取快照的并行线程数。

  • excludeWords:要从快照中排除的字词列表(不区分大小写)。系统会从快照结果中移除包含这些字词的行。无论您是否指定“password”,都始终会将其排除。

  • kubectlCommands:要运行的 kubectl 命令列表。系统会保存结果。这些命令将针对相应的命名空间运行。对于 kubectl logs 命令,系统会自动添加相应命名空间中的所有 Pod 和容器。支持使用正则表达式指定命名空间。如果您未指定命名空间,则假定为 default 命名空间。

  • nodeCommands:要在相应节点上运行的命令列表。系统会保存结果。未指定节点时,将考虑目标集群中的所有节点。

  • nodeFiles:要从相应节点收集的文件列表。系统会保存这些文件。未指定节点时,将考虑目标集群中的所有节点。

  • seesawCommands:要运行以收集 Seesaw 负载均衡器信息的命令列表。如果集群使用 Seesaw 负载平衡器,则会保存结果。

  • seesawFiles:要为 Seesaw 负载均衡器收集的文件列表。

  • nodeCollectors:为 Cilium 节点运行以收集 eBPF 信息的收集器。

  • f5:此标志用于启用收集与 F5 BIG-IP 负载均衡器相关的信息。

  • vCenter:此标志用于启用收集与 vCenter 相关的信息。

  • prometheusRequests:Prometheus 请求列表。系统会保存结果。

将快照上传到 Cloud Storage 存储桶

为了更轻松地保存、分析和存储,您可以将特定集群的所有快照上传到 Cloud Storage 存储桶。如果您需要 Cloud Customer Care 的帮助,则此操作特别有用。

在将快照上传到 Cloud Storage 存储桶之前,请查看并完成以下初始要求:

  • 舰队宿主项目中启用 storage.googleapis.com。虽然您可以使用其他项目,但建议使用舰队宿主项目。

    gcloud services enable --project=FLEET_HOST_PROJECT_ID storage.googleapis.com
    
  • roles/storage.admin 授予其父项目的服务账号,并使用 --service-account-key-file 参数传入服务账号 JSON 密钥文件。您可以使用任何服务账号,但建议使用连接注册服务账号。如需了解详情,请参阅服务账号

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

    CONNECT_REGISTER_SERVICE_ACCOUNT 替换为连接注册服务帐号。

满足这些要求后,您就可以将快照上传到 Cloud Storage 存储桶了:

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

--share-with 标志可以接受服务账号名称列表。将 GOOGLE_SUPPORT_SERVICE_ACCOUNT 替换为 Cloud Customer Care 提供的 Cloud Customer Care 服务帐号,以及 Cloud Customer Care 提供的任何其他服务帐号。

使用 --upload 标志时,该命令会在项目中搜索名称以“anthos-snapshot-”开头的存储桶。如果存在此类存储桶,该命令会将快照上传到该存储桶。如果该命令未找到具有匹配名称的存储桶,它会创建一个名为 anthos-snapshot-UUID 的新存储桶,其中 UUID 是 32 位的通用唯一标识符。

使用 --share-with 标志时,您无需手动与 Cloud Customer Care 共享存储桶的访问权限

将快照上传到 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>

后续步骤

如果您需要其他帮助,请与 Cloud Customer Care 联系。