创建快照以帮助诊断集群问题

如果某个集群存在问题，您可以从 Cloud Customer Care 获取帮助。Customer Care 可能会要求您截取集群的“快照”，可用于诊断问题。快照会捕获集群和节点配置文件，并将该信息打包为一个 tar 文件。

本文档介绍如何创建集群的默认快照或更多自定义快照，还介绍了在集群出现特定错误时如何创建快照。

默认快照

以下部分介绍了标准快照中的内容以及如何创建标准快照。如需了解自定义快照，请参阅自定义快照部分。

默认快照包含哪些信息？

集群的快照是一个有关该集群的配置文件和日志的 tar 文件。具体而言，该命令的默认配置会捕获有关集群的以下信息：

Kubernetes 版本。
kubenetes 资源在 kube-system 和 gke-system 命名空间中的状态：集群、机器、节点、服务、端点、ConfigMap、ReplicaSet、CronJob、Pod 以及这些 Pod 的所有者，包括 Deployment、DaemonSet 和 StatefulSet。
有关每个节点配置的详细信息，包括 IP 地址、iptables 规则、装载点、文件系统、网络连接，以及正在运行的进程。
有关 GDC 上的虚拟机运行时以及集群中运行的任何虚拟机和虚拟机相关资源的信息。如需详细了解默认收集的内容以及如何创建特定于虚拟机的快照，请参阅本文档中的快照中的虚拟机信息。
来自 bmctl check cluster --snapshot 命令的日志。

集群的凭据信息不包含在默认快照中。如果 Cloud Customer Care 请求该信息，请参阅检索集群信息。

如需查看运行快照命令时收集的信息的完整列表，请参阅详细的配置文件部分中显示的配置文件。此配置文件展示了截取默认快照时运行的命令。

如何创建默认快照

bmctl check cluster 命令用于截取集群的快照。您可以使用此命令执行以下任一操作：

创建快照并将其自动上传到 Cloud Storage 存储桶。
创建集群快照并将快照文件保存在运行该命令的本地机器上。

方法 #1：创建默认快照并自动上传到 Cloud Storage 存储桶

如需创建快照并将其上传到 Cloud Storage 存储桶，请执行以下操作：

按照配置可访问 Cloud Storage 存储桶的服务账号中的说明设置 API 和服务账号。

此步骤只需执行一次。
运行以下 bmctl 命令以创建快照并将快照自动上传到 Cloud Storage 存储桶：
```
bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --admin-kubeconfig=ADMIN_KUBECONFIG \
    --service-account-key-file SA_KEY_FILE
```
在该命令中，将以下条目替换为特定于您的集群环境的信息：
- CLUSTER_NAME：您要截取其快照的集群的名称。
- ADMIN_KUBECONFIG：管理员集群 kubeconfig 文件的路径。
- SA_KEY_FILE：在上一步中创建的服务账号的已下载 JSON 密钥文件的路径。如果您不使用 --service-account-key-file 标志，该命令会使用与 GOOGLE_APPLICATION_CREDENTIALS 环境变量关联的凭据。使用此标志明确指定服务账号凭据优先。
此命令会生成快照 tar 文件并将其保存在本地。正确设置服务账号后，该命令还会将快照 tar 文件上传到 Cloud Storage 中的存储桶。该命令会在您的项目中搜索名称以“anthos-snapshot-”开头的存储桶。如果此存储桶存在，该命令会将快照上传到该存储桶。如果该命令找不到名称匹配的存储桶，则会使用名称 anthos-snapshot-UUID 创建一个新存储桶，其中 UUID 是通用的 32 位数字唯一标识符。

注意：您可以使用 --upload-to 标志来提供快照将要上传到的特定存储桶名称。
按照允许 Google Cloud 支持团队查看您上传的集群快照中的说明，与 Cloud Customer Care 共享访问权限。

方法 #2：仅在本地机器上创建默认快照

使用 --local 标志可确保您的集群快照仅保存在本地。您可以使用以下命令捕获已创建的集群的状态：

bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --admin-kubeconfig=ADMIN_KUBECONFIG --local

替换以下内容：

CLUSTER_NAME：目标集群的名称。
ADMIN_KUBECONFIG：管理员集群 kubeconfig 文件的路径。

此命令会将一个 tar 文件输出到本地机器。此 tar 文件的名称采用 snapshot-CLUSTER_NAME-TIMESTAMP.tar.gz 格式，其中 TIMESTAMP 表示该文件的创建日期和时间。此 tar 文件包含集群的系统组件和机器的相关调试信息。

执行此命令时，系统会从以下命名空间收集有关 Pod 的信息：gke-system、gke-connect、capi-system、capi-webhook-system、cert-manager 和 capi-kubeadm-bootstrap-system

但是，您可以使用 --snapshot-scenario all 标志扩大收集的诊断信息的范围。此标志会将诊断快照的范围扩大为包含集群中的所有 Pod：

bmctl check cluster --snapshot --snapshot-scenario all \
    --cluster=CLUSTER_NAME \
    --kubeconfig=KUBECONFIG_PATH \
    --local

快照场景

bmctl check cluster --snapshot 命令支持两种场景。要指定场景，请使用 --scenario 标志。以下列表显示了可能的值：

system：收集系统组件的快照，包括其日志。
all：收集所有 Pod 的快照，包括其日志。

您可以为管理员集群或用户集群使用每一种场景。例如，要使用 system 场景创建管理员集群的快照，请使用以下命令：

bmctl check cluster --snapshot --snapshot-scenario system \
    --cluster=ADMIN_CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

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

bmctl check cluster --snapshot --snapshot-scenario all \
    --cluster=USER_CLUSTER_NAME \
    --kubeconfig=USER_KUBECONFIG_PATH

对快照执行试运行

使用 --snapshot-dry-run 标志时，该命令不会创建快照，而是会显示快照命令将执行的操作，并输出快照配置文件。如需了解快照配置文件，请参阅如何创建自定义快照。

要在管理员集群上执行试运行快照，请输入以下命令：

bmctl check cluster --snapshot --snapshot-dry-run \
    --cluster=ADMIN_CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

要在用户集群上执行试运行快照，请输入以下命令：

bmctl check cluster --snapshot --snapshot-dry-run \
    --cluster=USER_CLUSTER_NAME \
    --kubeconfig=USER_KUBECONFIG_PATH

获取特定时间段内的日志

您可以使用 --since 标志检索您特别关注的时间段内的日志。通过这种方式，您可以创建过去几秒、几分钟或几小时内发生的较小、更有针对性的日志记录快照。

例如，以下 bmctl 命令会创建过去三个小时内发生的日志记录快照：

bmctl check cluster --snapshot --since=3h \
    --cluster=CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

指定临时保存快照的目录

您可以使用 --snapshot-temp-output-dir 标志指定临时保存快照的目录：

bmctl check cluster --snapshot --snapshot-temp-output-dir=TEMP_OUTPUT_DIR \
    --cluster=CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

如果未指定目录，快照会临时保存在 /tmp 目录中。例如，当默认 /tmp 目录中的空间有限时，最好使用 --snapshot-temp-output-dir 选项。

禁止控制台日志记录

您可以使用 --quiet 标志在快照运行期间禁止日志消息显示在控制台中。相反，控制台日志会作为快照的一部分保存在“bmctl_diagnose_snapshot.log”文件中。

运行以下命令以禁止日志消息显示在控制台中：

bmctl check cluster --snapshot --quiet \
    --cluster=CLUSTER_NAME \
    --kubeconfig=ADMIN_KUBECONFIG_PATH

自定义快照

出于以下原因，您可能需要创建集群的自定义快照：

包含的集群相关信息超过默认快照中提供的信息。
排除默认快照中的某些信息。

如何创建自定义快照

创建自定义快照需要使用快照配置文件。以下步骤介绍了如何创建和修改配置文件，并使用配置文件创建集群的自定义快照：

通过在集群上运行以下命令并将输出写入文件来创建快照配置文件：

bmctl check cluster \
    --snapshot --snapshot-dry-run --cluster CLUSTER_NAME \
    --kubeconfig KUBECONFIG_PATH

定义您要在自定义快照中显示的信息类型。为此，请修改您在第 1 步中创建的快照配置文件。例如，如果您希望快照包含其他信息（例如特定节点的运行时长），请将 Linux 命令 uptime 添加到配置文件的相关部分。配置文件的以下代码段展示了如何让快照命令提供关于节点 10.200.0.3 的 uptime 信息。此信息不会出现在标准快照中。
```
...
nodeCommands:
- nodes:
  - 10.200.0.3
  commands:
  - uptime
...
```
修改配置文件以定义所需的快照类型后，通过运行以下命令创建自定义快照：
```
bmctl check cluster --snapshot --snapshot-config SNAPSHOT_CONFIG_FILE \
    --cluster CLUSTER_NAME--kubeconfig KUBECONFIG_PATH
```
--snapshot-config 标志指示 bmctl 命令使用快照配置文件的内容来定义快照中显示的信息。

详细的配置文件

以下示例快照配置文件展示了用于创建快照的标准命令和文件，但当需要其他诊断信息时，您可以添加更多命令和文件：

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

配置文件中的以下条目可能与上述示例配置文件中显示的条目不同：

nodeCommands 和 nodeFiles 部分中节点的 IP 地址
集群的 nodeSSHKey 的路径

配置文件中的字段

快照配置文件采用 YAML 格式。配置文件包含以下字段：

numOfParallelThreads：快照例程通常运行大量命令。多个并行线程可帮助例程更快地执行。按照前面的示例配置文件所示，我们建议您将 numOfParallelThreads 设置为 10。如果快照截取时间过长，请提高此值。
excludeWords：快照包含大量用于集群节点的数据。使用 excludeWords 时，您可以在共享快照时降低安全风险。例如，排除 password 以便无法识别相应的密码字符串。
nodeCommands：本部分指定了以下信息：
- nodes：您要从中收集信息的集群节点的 IP 地址列表。如需在管理员集群无法访问时创建快照，请指定至少一个节点 IP 地址。
- commands：要在每个节点上运行的命令（和参数）的列表。每个命令的输出都包含在快照中。
nodeFiles：本部分指定了以下信息：
- nodes：要从中收集文件的集群节点的 IP 地址列表。要在管理员集群无法访问时创建快照，请至少指定一个节点 IP 地址。
- files：要从每个节点检索的文件列表。在节点上发现指定文件时，文件将包含在快照中。
nodeSSHKey：您的 SSH 密钥文件的路径。如果管理员集群无法访问，则此字段为必填字段。

在遇到特定错误时创建快照

如何在安装或升级停滞期间创建默认快照

安装或升级管理员集群、混合集群或独立集群时，bmctl 有时可能会停滞，此时可以看到以下输出：

等待集群 kubeconfig 准备就绪。
等待集群准备就绪。
等待节点池准备就绪。
等待升级完成。

尽管如此，如果您遇到安装或升级停滞的情况，可以通过运行以下命令使用引导集群截取集群的快照：

bmctl check cluster --snapshot --cluster=CLUSTER_NAME \
    --kubeconfig=WORKSPACE_DIR/.kindkubeconfig

如何在安装或升级停滞期间创建自定义快照

以下步骤展示了如何在安装或升级停滞时创建集群的自定义快照：

从归档中检索集群的快照配置文件。
修改快照配置文件，使快照包含您需要的信息。

通过运行以下命令创建自定义快照：

bmctl check cluster --snapshot
    --snapshot-config=SNAPSHOT_CONFIG_FILE \
    --cluster=CLUSTER_NAME
    --kubeconfig=WORKSPACE_DIR/.kindkubeconfig

如何在管理员集群无法访问时创建自定义快照

如果管理员集群无法访问，您可以运行以下命令来截取集群的自定义快照：

bmctl check cluster --snapshot --cluster CLUSTER_NAME
    --node-ssh-key SSH_KEY_FILE
    --nodes NODE_1_IP_ADDRESS, NODE_2_IP_ADDRESS, ...

在该命令中，将以下条目替换为特定于您的集群环境的信息：

CLUSTER_NAME：您要截取其快照的集群的名称。
SSH_KEY_FILE：节点 SSH 密钥文件的路径。
NODE_x_IP_ADDRESS：您想要了解的集群节点的 IP 地址。

或者，您可以在单独的行中列出节点 IP 地址：

bmctl check cluster
    --snapshot --cluster CLUSTER_NAME \
    --node-ssh-key SSH_KEY_FILE \
    --nodes NODE_1_IP_ADDRESS \
    --nodes NODE_2_IP_ADDRESS
  ...

快照中的虚拟机信息

如果您使用 GDC 上的虚拟机运行时在 GKE on Bare Metal 上创建和管理虚拟机，则可以在快照中收集相关诊断信息。快照是诊断和排查虚拟机问题的关键资源。

默认收集的信息

创建默认快照时，它包含有关 GDC 上的虚拟机运行时和相关资源的信息。GDC 上的虚拟机运行时与 GKE on Bare Metal 捆绑在一起，并且 VMRuntime 自定义资源可在运行工作负载的集群上使用。即使您尚未在 GDC 上启用虚拟机运行时，快照仍会包含 VMRuntime 自定义资源 YAML 说明。

如果您已在 GDC 上启用了虚拟机运行时，则快照包含集群中虚拟机相关资源（如果存在对象）的状态和配置信息。虚拟机相关资源包括 Kubernetes 对象，例如 Pod、Deployment、DaemonSet 和 ConfigMap。

`vm-system` 命名空间中的对象

以下对象的状态和配置信息位于生成的快照中的 kubectlCommands/vm-system 中：

KubeVirt
VirtualMachineType
VMHighAvailabilityPolicy

其他命名空间中的对象

创建虚拟机 (VirtualMachine) 时，您可以指定命名空间。如果未指定命名空间，则虚拟机将获取 default 命名空间。本部分中的其他对象（例如 VirtualMachineInstance）均绑定到相应虚拟机的命名空间。

以下对象的状态和配置信息位于生成的快照中的 kubectlCommands/VM_NAMESPACE 中。如果您没有为虚拟机设置特定命名空间，则该信息位于 kubectlCommands/default 中：

VirtualMachine
VirtualMachineInstance
VirtualMachineDisk
GuestEnvironmentData
VirtualMachineAccessRequest
VirtualMachinePasswordResetRequest

不受命名空间限制的对象

以下对象不受命名空间限制，因此它们的对应信息直接位于生成的快照的 kubectlCommands 中：

VMRuntime
DataVolume
CDI
GPUAllocation

使用快照配置文件仅捕获虚拟机详细信息

如果您要诊断虚拟机的问题，则可以使用快照配置文件将收集的信息限制为仅与虚拟机相关的详细信息并定制收集的虚拟机信息。

以下快照配置文件展示了如何构建特定于虚拟机的快照。您可以添加其他命令来为快照收集更多信息。

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

如需详细了解如何使用快照配置文件，请参阅本文档中的自定义快照。