创建快照以诊断集群问题

gkectl 工具有两个用于排查集群问题的命令：gkectl diagnose snapshot 和 gkectl 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 的可选标志。除了收集有关集群的信息之外，此标志还会收集用于创建或升级集群的 Google Distributed Cloud 配置文件。

捕获管理员集群状态

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

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 的版本：system、system-with-logs、all 和 all-with-logs。
1.13 版 - 1.28 版：system 和 all。system 场景与旧的 system-with-logs 场景相同。all 场景与旧的 all-with-logs 场景相同。
1.29 版及更高版本：system、all 和 lite。

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

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> 替换为时间值，如 120m 或 48h。

需要注意以下几点：

仅 kubectl 和 journalctl 日志支持 --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 system 或 all）都不能满足您的需求，您可以使用 --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 密钥文件。您可以使用任何服务账号，但建议使用连接注册服务账号。如需了解详情，请参阅服务账号。

注意：如果您在 gkectl diagnose snapshot 命令中使用 --share-with 标志，则无需进行此设置。如果您要手动与 Cloud Customer Care 共享快照的访问权限，请在创建快照时使用以下命令，并且不要使用 --share-with 标志。
```
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>

后续步骤