本頁面由 Cloud Translation API 翻譯而成。

建立快照，協助診斷叢集問題

如果叢集發生問題，可以向 Cloud Customer Care 尋求協助。客戶服務人員可能會要求你「擷取」叢集快照，以診斷問題。快照會擷取叢集和節點的設定檔，並將這些資訊封裝成單一 tar 檔案。

本文說明如何建立叢集的預設快照，或更自訂的快照。本文也會說明叢集發生特定錯誤時，如何建立快照。

如需其他協助，請與 Cloud Customer Care 團隊聯絡。如要進一步瞭解支援資源，包括下列項目，請參閱「取得支援」：

提出支援案件的規定。
工具：協助您排解問題，例如環境設定、記錄和指標。
支援的元件。

預設快照

以下各節說明標準快照的內容，以及如何建立快照。如要瞭解自訂快照，請參閱「自訂快照」一節。

預設快照包含哪些資訊？

叢集快照是叢集設定檔和記錄的 tar 檔案。具體來說，指令的預設設定會擷取叢集的下列資訊：

Kubernetes 版本。
kube-system 和 gke-system 命名空間中的 Kubernetes 資源狀態：叢集、機器、節點、服務、端點、ConfigMap、ReplicaSet、CronJob、Pod，以及這些 Pod 的擁有者，包括 Deployment、DaemonSet 和 StatefulSet。
每個節點設定的詳細資料，包括 IP 位址、iptables 規則、掛接點、檔案系統、網路連線和執行中的程序。
GDC 上的 VM Runtime 資訊，以及叢集中執行的任何 VM 和 VM 相關資源。如要進一步瞭解預設收集的資訊，以及如何建立 VM 專屬快照，請參閱本文的「快照中的 VM 資訊」一節。
bmctl check cluster --snapshot 指令的記錄。

預設快照不包含叢集的憑證資訊。如果 Cloud 客戶服務要求提供這項資訊，請參閱「擷取叢集資訊」。

如需執行快照指令時收集的資訊完整清單，請參閱下節的詳細設定檔。這個設定檔會顯示擷取預設快照時執行的指令。

建立預設快照

bmctl check cluster 指令會建立叢集快照。您可以使用這項指令執行下列任一動作：

建立快照，並自動將快照上傳至 Cloud Storage bucket。
建立叢集快照，並將快照檔案儲存在執行指令的本機電腦上。

方法 1：建立預設快照，並自動上傳至 Cloud Storage bucket

如要建立快照並上傳至 Cloud Storage bucket，請按照下列步驟操作：

按照「設定可存取 Cloud Storage bucket 的服務帳戶」一文所述，設定 API 和服務帳戶。

這個步驟只需執行一次。
執行下列 bmctl 指令，建立快照並自動上傳至 Cloud Storage bucket：
```
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-」的儲存空間值區。如果找到這類值區，指令就會將快照上傳至該值區。如果指令找不到名稱相符的 bucket，就會建立名為 anthos-snapshot-UUID 的新 bucket，其中 UUID 是 32 位數的通用唯一 ID。

注意： 您可以使用 --upload-to 標記，提供要上傳快照的特定值區名稱。
按照「允許 Cloud Customer Care 查看您上傳的叢集快照」一文的說明，與 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

在指令列調整平行執行緒

快照常式通常會執行許多指令。多個平行執行緒可讓您同時執行指令，有助於加快日常安排的執行速度。

在 1.31 以上版本中，bmctl check cluster 指令支援 --num-of-parallel-threads 標記。您可以使用這個旗標設定用於拍攝快照的平行執行緒數量。

根據預設，快照常式會使用 10 個執行緒。如果快照時間過長，請調高這個值。

下列指令範例會將平行執行緒數量設為 30。

bmctl check cluster --snapshot --cluster=cluster1 \
    --admin-kubeconfig=bmctl-workspace/admin-cluster/admin-cluster-kubeconfig \
    --num-of-parallel-threads=30

建立自訂快照時，這項功能與快照設定檔中的 numOfParallelThreads 欄位類似。

自訂快照

您可能基於下列原因，需要建立叢集的自訂快照：

如要加入叢集的更多資訊，而非預設快照提供的資訊。
排除預設快照中的部分資訊。

建立自訂快照

如要建立自訂快照，必須使用快照設定檔。下列步驟說明如何建立及修改設定檔，並使用該檔案建立叢集的自訂快照：

在叢集上執行下列指令，並將輸出內容寫入檔案，即可建立快照設定檔：

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：安全殼層金鑰檔案的路徑。如果無法連線至管理員叢集，則必須填寫這個欄位。

發生特定錯誤時建立快照

發生特定事件 (例如升級停滯) 時，可能需要額外步驟或指令參數，才能順利建立快照。

在安裝或升級作業停滯時建立預設快照

安裝或升級管理、混合或獨立叢集時，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：節點安全殼層金鑰檔案的路徑。
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
  ...

快照中的 VM 資訊

如果您使用 GDC 的 VM Runtime 在 Google Distributed Cloud 上建立及管理虛擬機器 (VM)，可以透過快照收集相關診斷資訊。快照是診斷及排解 VM 問題的重要資源。

系統預設會收集哪些資料

建立預設快照時，快照會包含 GDC 上的 VM Runtime 和相關資源資訊。GDC 的 VM Runtime 會與 Google Distributed Cloud 綁定，且VMRuntime自訂資源會提供給執行工作負載的叢集。即使您尚未在 GDC 上啟用 VM Runtime，快照仍會包含 VMRuntime 自訂資源 YAML 說明。

如果您已在 GDC 上啟用 VM Runtime，快照會包含叢集中 VM 相關資源的狀態和設定資訊 (物件存在時)。與 VM 相關的資源包括 Kubernetes 物件，例如 Pod、Deployment、DaemonSet 和 ConfigMap。

`vm-system` 命名空間中的物件

下列物件的狀態和設定資訊位於所產生快照的 kubectlCommands/vm-system 中：

KubeVirt
VirtualMachineType
VMHighAvailabilityPolicy

其他命名空間中的物件

建立 VM (VirtualMachine) 時，您可以指定命名空間。如果未指定命名空間，VM 會取得 default 命名空間。本節中的其他物件 (例如 VirtualMachineInstance) 全都繫結至對應 VM 的命名空間。

下列物件的狀態和設定資訊位於產生的快照中。kubectlCommands/VM_NAMESPACE如果沒有為 VM 設定特定命名空間，資訊會位於 kubectlCommands/default：

VirtualMachine
VirtualMachineInstance
VirtualMachineDisk
GuestEnvironmentData
VirtualMachineAccessRequest
VirtualMachinePasswordResetRequest

未命名空間的物件

下列物件未納入命名空間，因此對應資訊會直接位於所產生快照的 kubectlCommands 中：

VMRuntime
DataVolume
CDI
GPUAllocation

使用快照設定檔，只擷取 VM 詳細資料

如果專門要診斷 VM 的問題，可以使用快照設定檔，將收集的資訊限制為僅與 VM 相關的詳細資料，並調整收集的 VM 資訊。

下列快照設定檔說明如何建構 VM 專屬快照。您可以加入其他指令，收集快照的更多資訊。

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

如要進一步瞭解如何使用快照設定檔，請參閱本文的「自訂快照」一節。

後續步驟