kubectl を使用してクラスタの状態を調査する

Google Kubernetes Engine（GKE）の問題の根本原因を診断するには、Kubernetes リソースのライブ状態、構成、イベントを詳細に検査する必要があります。表面的な症状を超えて問題を解決するには、クラスタのコントロール プレーンを直接クエリして操作するツールが必要です。

このページでは、クラスタのライブ状態を調査するための基本的な kubectl コマンドについて説明します。これらのコマンドを学習すると、Kubernetes コントロール プレーンから詳細情報を直接収集できるため、問題が発生した理由を理解するのに役立ちます。

この情報は、クラスタの健全性チェックを詳細に実行し、リソースを管理し、インフラストラクチャの問題をきめ細かいレベルでトラブルシューティングする必要があるプラットフォーム管理者とオペレーターにとって重要です。また、アプリケーション デベロッパーがアプリケーションの動作をデバッグし、Pod のログとイベントを検査し、Kubernetes 環境内のデプロイの正確な状態を確認するうえでも不可欠です。 Google Cloud のコンテンツで使用されている一般的なロールとタスクの例の詳細については、一般的な GKE ユーザーのロールとタスクをご覧ください。

始める前に

開始する前に、次のタスクを実行します。

  • kubectl をインストールします。

  • クラスタと通信するように kubectl コマンドライン ツールを構成します。

    gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION

    次のように置き換えます。

    • CLUSTER_NAME: クラスタの名前。
    • LOCATION: クラスタのコントロール プレーンの Compute Engine のロケーション。リージョン クラスタの場合はリージョン、ゾーンクラスタの場合はゾーンを指定します。

  • 権限を確認します。kubectl コマンドを実行するために必要な権限があるかどうかを確認するには、kubectl auth can-i コマンドを使用します。たとえば、kubectl get nodes を実行する権限があるかどうかを確認するには、kubectl auth can-i get nodes コマンドを実行します。

    必要な権限がある場合、コマンドは yes を返します。それ以外の場合、コマンドは no を返します。

    kubectl コマンドを実行する権限がない場合は、次のようなエラー メッセージが表示されることがあります。

    Error from server (Forbidden): pods "POD_NAME" is forbidden: User
"USERNAME@DOMAIN.com" cannot list resource "pods" in API group "" in the
namespace "default"

    必要な権限がない場合は、クラスタ管理者に必要なロールの割り当てを依頼してください。

実行中の概要を確認する

kubectl get コマンドを使用すると、クラスタで発生していることの全体像を把握できます。次のコマンドを使用して、最も重要なクラスタ コンポーネントであるノードと Pod のステータスを確認します。

  1. ノードが正常かどうかを確認するには、すべてのノードとそのステータスの詳細を表示します。

    kubectl get nodes

    出力は次のようになります。

    NAME                                        STATUS   ROLES    AGE     VERSION

gke-cs-cluster-default-pool-8b8a777f-224a   Ready    <none>   4d23h   v1.32.3-gke.1785003
gke-cs-cluster-default-pool-8b8a777f-egb2   Ready    <none>   4d22h   v1.32.3-gke.1785003
gke-cs-cluster-default-pool-8b8a777f-p5bn   Ready    <none>   4d22h   v1.32.3-gke.1785003

    Ready 以外のステータスは、追加の調査が必要です。

  2. Pod が正常かどうかを確認するには、すべての Pod とそのステータスの詳細を表示します。

    kubectl get pods --all-namespaces

    出力は次のようになります。

    NAMESPACE   NAME       READY   STATUS      RESTARTS   AGE
kube-system netd-6nbsq 3/3     Running     0          4d23h
kube-system netd-g7tpl 3/3     Running     0          4d23h

    Running 以外のステータスは、追加の調査が必要です。一般的なステータスは次のとおりです。

    • Running: 正常に実行されている状態。
    • Pending: Pod はノードでスケジュールされるのを待機している状態です。
    • CrashLoopBackOff: アプリが起動してエラーで終了し、Kubernetes によって再起動されるため、Pod 内のコンテナがループ内で繰り返しクラッシュしています。
    • ImagePullBackOff: Pod がコンテナ イメージを pull できません。

上記のコマンドは、kubectl get コマンドの使用方法の 2 つの例にすぎません。このコマンドを使用して、さまざまなタイプの Kubernetes リソースの詳細を確認することもできます。確認できるリソースの完全なリストについては、Kubernetes ドキュメントの kubectl get をご覧ください。

特定のリソースの詳細

問題を特定したら、詳細情報を取得する必要があります。問題の例としては、ステータスが Running ではない Pod があります。詳細を取得するには、kubectl describe コマンドを使用します。

たとえば、特定の Pod の説明を取得するには、次のコマンドを実行します。

kubectl describe pod POD_NAME -n NAMESPACE_NAME

次のように置き換えます。

  • POD_NAME: 問題が発生している Pod の名前。
  • NAMESPACE_NAME: Pod が存在する Namespace。Namespace がわからない場合は、kubectl get pods コマンドの出力から Namespace 列を確認します。

kubectl describe コマンドの出力には、リソースに関する詳細情報が含まれます。Pod のトラブルシューティングを行う際に確認すると役立つセクションを以下に示します。

  • Status: Pod の現在のステータス。
  • Conditions: Pod の全体的な健全性と readiness。
  • Restart Count: Pod 内のコンテナが再起動した回数。数値が高い場合は注意が必要です。
  • Events: この Pod に発生した重要なことのログ（ノードへのスケジュール、コンテナ イメージの pull、エラーの発生など）。Events セクションには、Pod が失敗した理由を直接示す情報が記載されていることがよくあります。

kubectl get コマンドと同様に、kubectl describe コマンドを使用して、複数のタイプのリソースの詳細を確認できます。確認できるリソースの完全なリストについては、Kubernetes ドキュメントの kubectl describe をご覧ください。

次のステップ