クラスタの問題の診断に活用できるスナップショットを作成する

いずれかのクラスタで問題が発生した場合は、Cloud カスタマーケアのヘルプを利用できます。カスタマーケアは、問題を診断するために使用できるクラスタのスナップショットをとるよう依頼することがありますスナップショットでは、クラスタとノードの構成ファイルがキャプチャされ、その情報が 1 つの tar ファイルにパッケージ化されます。

このドキュメントでは、クラスタのデフォルトのスナップショットか、よりカスタマイズされたスナップショットの作成方法について説明します。また、クラスタで特定のエラーが発生した場合に、スナップショットを作成する方法についても説明します。

デフォルトのスナップショット

この後のセクションでは、標準スナップショットの内容とその作成方法について説明します。カスタマイズしたスナップショットの詳細については、カスタマイズしたスナップショットのセクションをご覧ください。

デフォルトのスナップショットに含まれる情報

クラスタのスナップショットとは、クラスタに関する構成ファイルとログから成る tar ファイルのことです。具体的には、このコマンドのデフォルト構成で、クラスタに関する次の情報が取得されます。

Kubernetes のバージョン
kube-system と gke-system Namespace 内の Kubernetes リソースのステータス: クラスタ、マシン、ノード、Service、Endpoint、ConfigMap、ReplicaSet、CronJob、Pod とそのオーナー（Deployment、DaemonSet、StatefulSet を含む）
各ノードの構成の詳細（IP アドレス、iptables ルール、マウントポイント、ファイルシステム、ネットワーク接続、実行中のプロセスなど）
GDC 上の VM ランタイムと、クラスタで実行されている VM と VM 関連のリソースに関する情報。デフォルトで収集される情報の詳細と、VM 固有のスナップショットの作成方法については、このドキュメントのスナップショット内の VM 情報をご覧ください。
bmctl check cluster --snapshot コマンドから出力されたログ。

デフォルトのスナップショットには、クラスタの認証情報は含まれません。Cloud カスタマーケアによりその情報がリクエストされた場合は、クラスタ情報の取得をご覧ください。

スナップショットコマンドを実行したときに収集される情報の包括的なリストについては、構成ファイルの詳細に示されている構成ファイルをご覧ください。この構成ファイルには、デフォルトのスナップショットを作成するときに実行されるコマンドが示されています。

デフォルトのスナップショットの作成方法

クラスタのスナップショットは、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 カスタマーケアとアクセス権を共有します。

方法 #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 ファイルには、クラスタのシステムコンポーネントとマシンに関連するデバッグ情報が含まれています。

このコマンドを実行すると、次の名前空間からポッドに関する情報が収集されます。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 コマンドは、2 つのシナリオに対応します。シナリオを指定するには、--scenario フラグを使用します。使用できる値は、次のリストのとおりです。

system: ログを含む、システムコンポーネントのスナップショットを収集します。
all: ログを含む、すべての Pod のスナップショットを収集します。

管理クラスタまたはユーザークラスタでこの 2 つのシナリオのそれぞれを使用できます。たとえば、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 コマンドは、直近の 3 時間に発生したロギングのスナップショットを作成します。

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 アドレスを少なくとも 1 つ指定します。
- commands: 各ノードで実行するコマンド（と引数）のリスト。各コマンドの出力は、スナップショットに含まれます。
nodeFiles: このセクションでは、次の情報を指定します。
- nodes: ファイルの収集元となるクラスタノードの IP アドレスのリスト。管理クラスタに到達できない場合にスナップショットを作成するには、ノード IP アドレスを少なくとも 1 つ指定します。
- 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
  ...

スナップショット内の VM 情報

GDC 上の VM ランタイムを使用して GKE on Bare Metal 上で仮想マシン（VM）を作成および管理する場合は、スナップショットから関連する診断情報を収集できます。スナップショットは、VM の問題を診断してトラブルシューティングするための重要なリソースです。

デフォルトで収集される情報

デフォルトのスナップショットを作成すると、スナップショットには GDC の VM ランタイムと関連リソースに関する情報が含まれます。GDC 上の VM ランタイムは、GKE on Bare Metal にバンドルされています。VMRuntime カスタムリソースは、ワークロードを実行するクラスタで使用できます。GDC で VM ランタイムを有効にしていない場合でも、スナップショットには VMRuntime カスタムリソース YAML の記述が含まれます。

GDC の VM ランタイムを有効にしている場合、スナップショットには、クラスタ内の VM 関連リソース（オブジェクトが存在する場合）のステータスと構成情報が含まれます。VM 関連リソースには、Pod、Deployment、DaemonSet、ConfigMap などの Kubernetes オブジェクトが含まれます。

`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

スナップショット構成ファイルの使用方法について詳しくは、このドキュメントのカスタマイズしたスナップショットをご覧ください。