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

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

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 のオプションのフラグがあります。このフラグは、クラスタに関する情報の収集に加えて、クラスタの作成またはアップグレードに使用された GKE on VMware 構成ファイルを収集します。

注: --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 の指定に使用されます。Namespace を指定しない場合は、default Namespace が使用されます。

• 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 カスタマーケアにお問い合わせください。