クラスタの問題の診断

このドキュメントでは、gkectl diagnose を使用してクラスタの問題を診断する方法について説明します。

概要

gkectl ツールには、クラスタの問題を解決するために 2 つのコマンド(gkectl diagnose clustergkectl diagnose snapshot)が用意されています。これらのコマンドは、管理者クラスタとユーザー クラスタの両方で機能します。

gkectl diagnose cluster

クラスタでヘルスチェックを実行し、エラーを報告します。次のコンポーネントでヘルスチェックを実行します。

  • VCenter
    • 認証情報
    • DRS
    • アンチ アフィニティ グループ
    • ネットワーク
    • バージョン
    • データセンター
    • データストア
    • リソースプール
    • フォルダ
    • ネットワーク
  • ロードバランサ(F5、Seesaw、手動)
  • ユーザー クラスタとノードプール
  • クラスタ オブジェクト
  • マシン オブジェクトと対応するクラスタノード
  • kube-system と gke-system の Namespace にある Pod
  • ターゲット クラスタがユーザー クラスタの場合のユーザー コントロール プレーン
  • クラスタ内の vSphere 永続ボリューム
  • ユーザーおよび管理クラスタの vCPU(仮想 CPU)とメモリの競合シグナル
  • ユーザーおよび管理クラスタの ESXi のホスト CPU 使用率とメモリ使用量の事前構成アラーム
  • 1 日のうちの時間(TOD)
  • Dataplane V2 が有効になっているクラスタのノード ネットワーク ポリシー

gkectl diagnose snapshot

クラスタのステータス、構成、ログを tarball ファイルに圧縮します。具体的には、このコマンドのデフォルト構成で、クラスタに関する次の情報が取得されます。

  • Kubernetes のバージョン

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

  • ターゲット クラスタがユーザー クラスタである場合のユーザー コントロール プレーンのステータス(ユーザー クラスタのコントロール プレーンは管理クラスタで実行されます)

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

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

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

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

  • gkectl diagnose snapshot コマンドのログ

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

  • 必要に応じて、クラスタのインストールとアップグレードに使用されるクラスタ構成ファイル

認証情報(vSphere と F5 の認証情報など)は、tarball が作成される前に削除されます。

クラスタの診断

gke diagnose cluster を実行すると、クラスタに関する一般的な問題を確認できます。

gkectl diagnose cluster --kubeconfig ADMIN_CLUSTER_KUBECONFIG --config ADMIN_CLUSTER_CONFIG

出力例:

Failed to access the api server via LB VIP "...": ...
Try to use the admin master IP instead of problematic VIP...
Reading config with version "[CONFIG_VERSION]"
Finding the admin master VM...
Fetching the VMs in the resource pool "[RESOURCE_POOL_NAME]"...
Found the "[ADMIN_MASTER_VM_NAME]" is the admin master VM.
Diagnosing admin|user cluster "[TARGET_CLUSTER_NAME]"...
...

管理クラスタの診断

管理クラスタは、その名前か kubeconfig を渡すだけで診断できます。

管理クラスタの kubeconfig の使用

管理クラスタの kubeconfig を渡すと、gkectl は自動的に管理クラスタを選択します。

gkectl diagnose cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG]

管理クラスタ名の使用

管理クラスタ名を取得するには、次のコマンドを実行します。

kubectl get cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG]

次に、管理クラスタ名を gkectl diagnose cluster に渡します。

gkectl diagnose cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[ADMIN_CLUSTER_NAME]

管理クラスタが正常に機能している場合は、gkectl diagnose cluster で次のような出力が返されます。

Preparing for the diagnose tool...
Diagnosing the cluster......DONE

- Validation Category: Admin Cluster Connectivity
Checking VMs TOD (availability)...SUCCESS

- Validation Category: Admin Cluster F5 BIG-IP
Checking f5 (credentials, partition)...SUCCESS

- Validation Category: Admin Cluster VCenter
Checking Credentials...SUCCESS
Checking DRS enabled...SUCCESS
Checking Hosts for AntiAffinityGroups...SUCCESS
Checking Version...SUCCESS
Checking Datacenter...SUCCESS
Checking Datastore...SUCCESS
Checking Resource pool...SUCCESS
Checking Folder...SUCCESS
Checking Network...SUCCESS

- Validation Category: Admin Cluster
Checking cluster object...SUCCESS
Checking machine deployment...SUCCESS
Checking machineset...SUCCESS
Checking machine objects...SUCCESS
Checking kube-system pods...SUCCESS
Checking anthos-identity-service pods...SUCCESS
Checking storage...SUCCESS
Checking resource...SUCCESS
Checking virtual machine resource contention...SUCCESS
Checking host resource contention...SUCCESS
All validation results were SUCCESS.
Cluster is healthy!

ユーザー クラスタの診断

クラスタを診断するには、まずユーザー クラスタの名前を取得します。

kubectl get cluster --kubeconfig=[USER_CLUSTER_KUBECONFIG]

次に、管理クラスタの kubeconfig とユーザー クラスタの名前を渡します。

gkectl diagnose cluster --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
  --cluster-name=[USER_CLUSTER_NAME]

ユーザー クラスタが正常に機能している場合は、gkectl diagnose cluster で次のような出力が返されます。

Preparing for the diagnose tool...
Diagnosing the cluster......DONE

Diagnose result is saved successfully in 

- Validation Category: User Cluster Connectivity
Checking Node Network Policy...SUCCESS
Checking VMs TOD (availability)...SUCCESS

- Validation Category: User Cluster F5 BIG-IP
Checking f5 (credentials, partition)...SUCCESS

- Validation Category: User Cluster VCenter
Checking Credentials...SUCCESS
Checking DRS enabled...SUCCESS
Checking Hosts for AntiAffinityGroups...SUCCESS
Checking VSphere CSI Driver...SUCCESS
Checking Version...SUCCESS
Checking Datacenter...SUCCESS
Checking Datastore...SUCCESS
Checking Resource pool...SUCCESS
Checking Folder...SUCCESS
Checking Network...SUCCESS

- Validation Category: User Cluster
Checking user cluster and node pools...SUCCESS
Checking cluster object...SUCCESS
Checking machine deployment...SUCCESS
Checking machineset...SUCCESS
Checking machine objects...SUCCESS
Checking control plane pods...SUCCESS
Checking kube-system pods...SUCCESS
Checking gke-system pods...SUCCESS
Checking gke-connect pods...SUCCESS
Checking anthos-identity-service pods...SUCCESS
Checking storage...SUCCESS
Checking resource...SUCCESS
Checking virtual machine resource contention...SUCCESS
Checking host resource contention...SUCCESS
All validation results were SUCCESS.
Cluster is healthy!

原因が判明しているクラスタの問題のトラブルシューティング

gke diagnose cluster コマンドの実行時に次のような問題が発生した場合の解決策を次に示します。

.
事象考えられる原因解決策
管理クラスタおよびユーザー クラスタのどちらからも Kubernetes API サーバーにアクセスできない。 仮想マシンの OOB(すぐに使用できる)メモリ レイテンシ グラフを確認します。理想的なメモリ レイテンシはゼロに近いことです。また、メモリの競合により、CPU の競合が発生する可能性もあります。さらに、CPU readiness グラフは、スワップの増加に伴って急増する場合があります。 物理メモリを増やします。その他のオプションについては、VMware のトラブルシューティング ヒントをご覧ください。
ノードプールの作成でタイムアウトが発生する。 VMDK の読み取りと書き込みのレイテンシが高くなっています。仮想ディスクの読み取りと書き込みレイテンシの VM ヘルス OOB を確認します。VMware によると、レイテンシの合計が 20 ミリ秒を上回ると、問題が発生していることを意味します。 ディスク パフォーマンスの問題が発生した場合の VMware の解決策をご覧ください。

クラスタの状態のキャプチャ

gkectl diagnose cluster がエラーを見つけた場合、クラスタの状態をキャプチャし、Google に情報を提供する必要があります。そのためには、gkectl diagnose snapshot コマンドを使用します。

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

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

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

gkectl diagnose snapshot --kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] --config

出力には、ファイルの一覧と tarball ファイルの名前が含まれます。

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 [TARBALL_FILE_NAME].tar.gz.

tarball ファイルをディレクトリに抽出するには、次のコマンドを実行します。

tar -zxf [TARBALL_FILE_NAME] --directory [EXTRACTION_DIRECTORY_NAME]

スナップショットにより生成されたファイルのリストを表示するには、次のコマンドを実行します。

cd [EXTRACTION_DIRECTORY_NAME]/[EXTRACTED_SNAPSHOT_DIRECTORY]
ls kubectlCommands
ls nodes/[NODE_NAME]/commands
ls nodes/[NODE_NAME]/files

特定の操作の詳細を確認するには、表示されたファイルのいずれかを開きます。

管理クラスタの 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]

出力には、ファイルの一覧と tarball ファイルの名前が含まれます。

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.

スナップショットのシナリオ

gkectl diagnose snapshot コマンドは、4 つのシナリオをサポートしています。シナリオを指定するには、--scenario フラグを使用します。使用できる値は、次のリストのとおりです。

  • system: (デフォルト)システム Namespace(kube-systemgke-system)のスナップショットを収集します。

  • system-with-logs: ログを含む system スナップショットを収集します。

  • all: すべての Namespace のスナップショットを収集します。

  • all-with-logs: ログを含む all スナップショットを収集します。

4 つのシナリオはそれぞれ管理クラスタまたはユーザー クラスタで使用できるため、考えられる置換は 8 つあります。いくつかの方法を、次に例として示します。

system シナリオを使用して、管理クラスタのスナップショットを作成する場合:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--scenario=system

system-with-logs シナリオを使用して、ユーザー クラスタのスナップショットを作成する場合:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--scenario=system-with-logs

all シナリオを使用して、ユーザー クラスタのスナップショットを作成する場合:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--cluster-name=[USER_CLUSTER_NAME] \
--scenario=all

all-with-logs シナリオを使用して、管理クラスタのスナップショットを作成する場合:

gkectl diagnose snapshot \
--kubeconfig=[ADMIN_CLUSTER_KUBECONFIG] \
--scenario=all-with-logs

--log-since を使用してスナップショットを制限する

system-with-logsall-with-logs のシナリオでは、--log-since フラグを使用してログ収集を最近の期間に制限できます。たとえば、過去 2 日間または過去 3 時間のログのみを収集できます。デフォルトでは、diagnose snapshot はすべてのログを収集します。

ログの収集期間を制限するには:

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

[DURATION] は、120m48h などの値に置き換えます。

注:

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

スナップショット構成の使用

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

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

スナップショット構成の生成

特定のシナリオのスナップショット構成を生成するには、--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 リクエストのリスト。結果は保存されます。

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

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

コマンドを実行する前に、これらの設定要件を満たしていることを確認してください。

  • フリートホスト プロジェクトstorage-api.googleapis.com を有効にします。別のプロジェクトを使用することもできますが、フリートホスト プロジェクトをおすすめします。
gcloud services enable --project=PROJECT_ID \
storage-api.googleapis.com
  • 親プロジェクトのサービス アカウントに roles/storage.admin を付与し、--service-account-key-file パラメータを使用してサービス アカウントの json キーファイルを渡します。任意のサービス アカウントを使用できますが、connect 登録サービス アカウントをおすすめします。詳細については、サービス アカウントをご覧ください。
gcloud projects add-iam-policy-binding PROJECT_ID \
    --member "serviceAccount:CONNECT_REGISTER_SERVICE_ACCOUNT" \
    --role "roles/storage.admin"

CONNECT_REGISTER_SERVICE_ACCOUNT は、connect register サービス アカウントに置き換えます。

これらの要件を満たしたら、次のコマンドでスナップショットをアップロードできます。

gkectl diagnose snapshot --kubeconfig=ADMIN_CLUSTER_KUBECONFIG \
--cluster-name CLUSTER_NAME \
--upload-to BUCKET_NAME  \
--service-account-key-file SERVICE_ACCOUNT_KEY_FILE \
--share-with GOOGLE_SUPPORT_SERVICE_ACCOUNT

SERVICE_ACCOUNT_KEY_FILE は、サービス アカウント キーのファイル名に置き換えます。

--share-with フラグには、サービス アカウント名のリストを指定できます。GOOGLE_SUPPORT_SERVICE_ACCOUNT を、Google サポートが提供する他のサービス アカウントとともに、Google サポートが提供する Google サポート サービス アカウントに置き換えます。

使用する場合は、オプションの share-with フラグを --upload-to--service-account-file と併用する必要があります。これにより、スナップショットを最初に Google Cloud Storage にアップロードし、読み取り権限を共有することが可能です。

出力例:

Using "system" snapshot configuration...
Taking snapshot of user cluster CLUSTER_NAME...
Setting up CLUSTER_NAME 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 "SNAPSHOT_FILE_PATH".
Uploading snapshot to Google Cloud Storage......  DONE
Uploaded the snapshot successfully to gs://BUCKET_NAME/CLUSTER_NAME/xSNAPSHOT_FILE_NAME.
Shared successfully with service accounts:
GOOGLE_SUPPORT_SERVICE_ACCOUNT

既知の問題

バージョン 1.1.2-gke.0: パスが複数のデータセンターに解決される

Anthos clusters on VMware のリリースノートをご覧ください。

バージョン 1.1.x: Volume がマシンに接続されていない

Anthos clusters on VMware のリリースノートをご覧ください。