スナップショットを作成してクラスタの問題を診断する

このドキュメントでは、gkectl diagnose コマンドを使用して、VMware 用 Google Distributed Cloud（ソフトウェアのみ）で作成されたクラスタの問題をトラブルシューティングするための診断スナップショットを作成する方法について説明します。gkectl ツールには、クラスタの問題を解決するために 2 つのコマンド（gkectl diagnose snapshot と gkectl diagnose cluster）が用意されています。これらのコマンドは、管理者クラスタとユーザー クラスタの両方で機能します。

gkectl diagnose cluster コマンドを使用してクラスタの問題を診断する方法については、クラスタの問題を診断するをご覧ください。

さらにサポートが必要な場合は、Cloud カスタマーケアにお問い合わせください。

gkectl diagnose snapshot

このコマンドは、クラスタのステータス、構成、ログを tar ファイルに圧縮します。gkectl diagnose snapshot を実行すると、そのコマンドはプロセスの一環として gkectl diagnose cluster を自動的に実行し、/diagnose-report というスナップショット内の新しいフォルダに出力ファイルが配置されます。

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

この gkectl diagnose snapshot コマンドのデフォルト構成では、クラスタに関する次の情報が取得されます。

• Kubernetes のバージョン。

• kube-system と gke-system Namespace 内の Kubernetes リソースのステータス: クラスタ、マシン、ノード、Service、Endpoint、ConfigMap、ReplicaSet、CronJob、Pod とそのオーナー（Deployment、DaemonSet、StatefulSet を含む）。

• コントロール プレーンのステータス。

• 各ノードの構成の詳細（IP アドレス、iptables ルール、マウント ポイント、ファイル システム、ネットワーク接続、実行中のプロセスなど）。

• 管理クラスタのコントロール プレーン ノードからのコンテナログ（Kubernetes API サーバーが使用できない場合）。

• リソースプールに基づいた vSphere 情報（VM オブジェクトとそれらのイベントなど）。また、VM に関連付けられたデータセンター、クラスタ、ネットワーク、データストアのオブジェクトに関する情報も収集されます。

• 仮想サーバー、仮想アドレス、プール、ノード、モニターなどの F5 BIG-IP ロードバランサ情報。

• gkectl diagnose snapshot コマンドのログ。

• プリフライト ジョブのログ。

• シナリオに基づく名前空間内のコンテナのログ。

• スナップショット ファイル /nodes/<admin_master_node_name>/sudo_kubeadm_certs_check-expiration にある管理クラスタの Kubernetes 証明書の有効期限に関する情報。

• スナップショット内のすべてのファイルの HTML インデックス ファイル。

• 必要に応じて、--config フラグを指定してクラスタのインストールとアップグレードに使用する管理クラスタ構成ファイル。

認証情報（vSphere や F5 の認証情報など）は、tar ファイルが作成される前に削除されます。

軽量のスナップショット

Google Distributed Cloud バージョン 1.29 以降では、管理クラスタとユーザー クラスタの両方で簡易版の gkectl diagnose snapshot を使用できます。軽量のスナップショットは、クラスタに関する情報をキャプチャする量が少ないため、スナップショット プロセスを高速化します。コマンドに --scenario=lite を追加すると、スナップショットには次の情報がのみ含まれます。

• kube-system と gke-system Namespace 内の Kubernetes リソースのステータス: クラスタ、マシン、ノード、Service、Endpoint、ConfigMap、ReplicaSet、CronJob、Pod とそのオーナー（Deployment、DaemonSet、StatefulSet を含む）

• gkectl diagnose snapshot コマンドのログ

クラスタの状態をキャプチャする

gkectl diagnose cluster コマンドでエラーが検出された場合は、クラスタの状態をキャプチャして Cloud カスタマーケアに情報を提供する必要があります。この情報は、gkectl diagnose snapshot コマンドを使用して取得できます。

gkectl diagnose snapshot には、--config のオプション フラグがあります。このフラグは、クラスタに関する情報の収集に加えて、クラスタの作成またはアップグレードに使用された構成ファイルを収集します。

注: --kubeconfig フラグは必ず管理クラスタの kubeconfig ファイルを指す必要があります。ユーザー クラスタの kubeconfig を指定すると、gkectl diagnose はエラーを返します。

管理クラスタの状態をキャプチャする

管理クラスタの状態をキャプチャするには、次のコマンドを実行します。

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 フラグを使用してログ収集を最近の期間に制限できます。たとえば、過去 2 日間または過去 3 時間のログのみを収集できます。デフォルトでは、diagnose snapshot はすべてのログを収集します。

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

<var>DURATION</var> は、120m や 48h などの値に置き換えます。

次のことに注意してください。

• --log-since フラグは、kubectl ログと journalctl ログでのみサポートされます。
• カスタマイズされたスナップショット構成では、--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

スナップショット構成を使用する

これら 2 つのシナリオ（--scenario system または all）がニーズに合わない場合は、--snapshot-config フラグを使用してスナップショット構成ファイルを渡すことで、カスタマイズされたスナップショットを作成できます。

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

注: バージョン 1.13 以降、スナップショット シナリオの意味が変わりました。system-with-logs と all-with-logs のシナリオ オプションがなくなりました。バージョン 1.13 以降では、system と all のシナリオ オプションを使用してログが収集されます。

スナップショット構成を生成する

特定のシナリオのスナップショット構成を生成するには、--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: スナップショットから除外する単語のリスト（大文字と小文字は区別されません）。これらの単語を含む行はスナップショットの結果から削除されます。指定したかどうかにかかわらず、「パスワード」は常に除外されます。

• kubectlCommands: 実行する kubectl コマンドのリスト。結果は保存されます。コマンドは、対応する Namespace に対して実行されます。kubectl logs コマンドの場合、対応する Namespace 内のすべての Pod とコンテナが自動的に追加されます。正規表現が、Namespace の指定に使用されます。名前空間を指定しない場合は、default 名前空間が使用されます。

• nodeCommands: 対応するノードで実行するコマンドのリスト。結果は保存されます。ノードが指定されていない場合、ターゲット クラスタ内のすべてのノードが考慮されます。

• nodeFiles: 対応するノードから収集されるファイルのリスト。ファイルは保存されます。ノードが指定されていない場合、ターゲット クラスタ内のすべてのノードが考慮されます。

• seesawCommands: Seesaw ロードバランサの情報を収集するために実行するコマンドのリスト。クラスタで Seesaw ロードバランサが使用されている場合は、結果が保存されます。

• seesawFiles: Seesaw ロードバランサに関して収集されるファイルのリスト。

• nodeCollectors: Cilium ノードで eBPF 情報を収集するために実行されるコレクタ。

• f5: F5 BIG-IP ロードバランサに関する情報の収集を有効にするフラグ。

• vCenter: vCenter に関する情報の収集を有効にするフラグ。

• prometheusRequests: Prometheus リクエストのリスト。結果は保存されます。

スナップショットを Cloud Storage バケットにアップロードする

特定のクラスタのすべてのスナップショットを Cloud Storage バケットにアップロードすると、レコードの保持、分析、保存が容易になります。これは、Cloud カスタマーケアのサポートが必要な場合に特に役立ちます。

スナップショットを Cloud Storage バケットにアップロードする前に、次の初期要件を確認して完了してください。

• フリートホスト プロジェクトで storage.googleapis.com を有効にします。別のプロジェクトを使用することもできますが、フリートホスト プロジェクトをおすすめします。

  gcloud services enable --project=FLEET_HOST_PROJECT_ID storage.googleapis.com
  

• 親プロジェクトのサービス アカウントに roles/storage.admin を付与し、--service-account-key-file パラメータを使用してサービス アカウントの JSON キーファイルを渡します。任意のサービス アカウントを使用できますが、connect register サービス アカウントをおすすめします。詳細については、サービス アカウントをご覧ください。

  注: gkectl diagnose snapshot コマンドで --share-with フラグを使用する場合、この設定要件は必要ありません。スナップショットへのアクセスを手動で Cloud カスタマーケアと共有する場合は、次のコマンドを使用します。スナップショットを作成するときに、--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 は、connect register サービス アカウントに置き換えます。

これらの要件を満たしたら、スナップショットを 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 カスタマーケアが提供する Cloud カスタマーケア サービス アカウントと Cloud カスタマーケアが提供するその他のサービス アカウントに置き換えます。

--upload フラグを使用すると、コマンドによって「anthos-snapshot-」で始まる名前のストレージ バケットのプロジェクトを検索します。このようなバケットが存在すると、コマンドによって、そのバケットにスナップショットがアップロードされます。名前が一致するバケットが見つからない場合、このコマンドによって anthos-snapshot-UUID という名前の新しいバケットが作成されます。ここで、UUID は 32 桁の汎用の固有識別子です。

--share-with フラグを使用する場合、手動で Cloud カスタマーケアとバケットへのアクセスを共有する必要はありません。

注: --upload-to フラグを使用すると、スナップショットをアップロードする特定のバケット名を指定できます。

スナップショットを 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 カスタマーケアにお問い合わせください。