コントロール プレーンの指標を収集して表示する

このページでは、Google Cloud Managed Service for Prometheus を使用して、Kubernetes API サーバー、スケジューラ、Controller Manager によって出力された指標を Cloud Monitoring に送信するように Google Kubernetes Engine（GKE）クラスタを構成する方法について説明します。このページでは、これらの指標が Monitoring に書き込まれる際の形式と、指標のクエリ方法についても説明します。

始める前に

始める前に、次の作業が完了していることを確認してください。

• Google Kubernetes Engine API を有効にする。
Google Kubernetes Engine API の有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。

要件

Kubernetes コントロール プレーン コンポーネントによって出力された指標を Cloud Monitoring に送信するには、次の要件があります。

• クラスタでシステム指標が有効になっている。

コントロール プレーン指標の収集を構成する

コントロール プレーンの指標は、Google Cloud コンソール、gcloud CLI、または Terraform を使用して、既存の GKE クラスタで有効にできます。

gcloud container clusters update CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --monitoring=SYSTEM,API_SERVER,SCHEDULER,CONTROLLER_MANAGER

割り当て

コントロール プレーンの指標は、Cloud Monitoring API の「1 分あたりの時系列取り込みリクエスト」の割り当てを消費します。指標パッケージを有効にする前に、その割り当ての直近のピーク使用量を確認してください。同じプロジェクトに多くのクラスタがある場合や、すでに割り当ての上限に近づいている場合は、いずれかのオブザーバビリティ パッケージを有効にする前に割り当ての上限の引き上げをリクエストできます。

料金

GKE コントロール プレーンの指標では、Google Cloud Managed Service for Prometheus を使用して、Cloud Monitoring に指標を読み込みます。Cloud Monitoring では、取り込まれたサンプルの数に基づいて、これらの指標の取り込みに対して課金されます。ただし、GKE Enterprise エディションが有効になっているプロジェクトに属する登録済みクラスタでは、これらの指標は無料です。

詳細については、Cloud Monitoring の料金をご覧ください。

指標の形式

Cloud Monitoring に書き込まれる Kubernetes コントロール プレーンの指標はすべて、リソースタイプ prometheus_target を使用します。各指標名には接頭辞 prometheus.googleapis.com/ が使用され、Prometheus 指標タイプ（/gauge、/histogram、/counter など）を示す接尾辞が付いています。それ以外の場合、各指標名はオープンソースの Kubernetes によって公開される指標名と同一です。

Cloud Monitoring からのエクスポート

Kubernetes コントロール プレーンの指標は、Cloud Monitoring API を使用して Cloud Monitoring からエクスポートできます。Kubernetes コントロール プレーンのすべての指標が Google Cloud Managed Service for Prometheus を使用して取り込まれるため、Prometheus Query Language（PromQL）を使用して Kubernetes コントロール プレーンの指標をクエリできます。Monitoring Query Language（MQL）を使用してクエリすることもできます。

指標のクエリ

Kubernetes コントロール プレーンの指標をクエリするときに使用する名前は、PromQL と Cloud Monitoring ベースの機能（MQL、Metrics Explorer のメニュー形式のインターフェースなど）のどちらを使用するかによって異なります。

次の Kubernetes コントロール プレーンの指標の表では、指標名ごとに 2 つのバージョンを示します。

• PromQL の指標名: Google Cloud コンソールの Cloud Monitoring ページまたは Cloud Monitoring API の PromQL フィールドで PromQL を使用する場合は、PromQL の指標名を使用します。
• Cloud Monitoring の指標名: 他の Monitoring 機能を使用する場合は、以下の表の Cloud Monitoring の指標名を使用します。この名前には prometheus.googleapis.com/ を付ける必要があります（表中の項目では省略されています）。

API サーバーの指標

このセクションでは、API サーバーの指標の一覧と、指標の解釈と使用に関する追加情報について説明します。

API サーバー指標のリスト

API サーバーの指標を有効にすると、次の表に示されているすべての指標が、GKE クラスタと同じプロジェクトの Cloud Monitoring にエクスポートされます。

この表の Cloud Monitoring の指標名には、prometheus.googleapis.com/ という接頭辞を付ける必要があります。この接頭辞は、表中の項目では省略されています。

以下のセクションでは、API サーバーの指標について説明します。

apiserver_request_duration_seconds

この指標は、API サーバーのレイテンシをモニタリングするために使用します。この指標で記録されたリクエスト期間には、リクエストを受け取ってからサーバーがクライアントへのレスポンスを完了するまでのすべてのリクエスト処理フェーズが含まれます。具体的には、次の処理にかかった時間が含まれています。

• リクエストの認証と認可。
• リクエストに関連するサードパーティ Webhook とシステム Webhook の呼び出し。
• リクエストされたオブジェクトのメモリ内キャッシュ（resourceVersion URL パラメータを指定するリクエストの場合）または etcd（他のすべてのリクエストの場合）からの取得。
• group、version、resource、subresource ラベルを使用すると、低速なリクエストを一意に識別し、さらに詳しく調査できます。
• クライアントへのレスポンスの書き込みとクライアントのレスポンスの受信

この指標の使用の詳細については、レイテンシをご覧ください。

この指標はカーディナリティが非常に高いため、この指標を使用する場合は、フィルタまたはグループ化を使用して特定のレイテンシの原因を確認する必要があります。

apiserver_admission_controller_admission_duration_seconds

この指標は、サードパーティの Webhook ではなく、組み込みアドミッション Webhook のレイテンシを測定します。サードパーティの Webook でレイテンシの問題を診断するには、apiserver_admission_webhook_admission_duration_seconds 指標を使用します。

apiserver_admission_webhook_admission_duration_seconds と
apiserver_admission_step_admission_duration_seconds

これらの指標は、外部のサードパーティ アドミッション Webhook のレイテンシを測定します。一般に、apiserver_admission_webhook_admission_duration_seconds 指標はより有用な指標です。この指標の使用の詳細については、レイテンシをご覧ください。

apiserver_request_total

この指標を使用して、API サーバーでリクエスト トラフィックをモニタリングします。リクエストの成功率と失敗率を判断する際にも使用できます。この指標の使用の詳細については、トラフィックとエラー率をご覧ください。

この指標はカーディナリティが非常に高いため、この指標を使用する場合は、フィルタまたはグループ化を使用してエラーの原因を特定する必要があります。

apiserver_storage_objects

この指標を使用して、システムの飽和度を検出し、考えられるリソース漏洩を特定します。詳しくは、飽和度をご覧ください。

apiserver_current_inflight_requests

この指標は、最後の 1 秒間にアクティブに配信されたリクエストの最大数を記録します。詳しくは、飽和度をご覧ください。

指標に「watch」などの長時間実行リクエストは含まれません。

API サーバーのモニタリング

API サーバーの指標から、システムの健全性に関する主なシグナルについて分析情報を得ることができます。

• レイテンシ: リクエストの処理にはどれくらいの時間がかかるのか。
• トラフィック: システムにどのくらいの需要があるのか。
• エラー率: リクエストが失敗した頻度。
• 飽和度: システムの完全性はどの程度か。

このセクションでは、API サーバーの指標を使用して API サーバーの状態をモニタリングする方法について説明します。

レイテンシ

API サーバーが過負荷になると、リクエストのレイテンシが増加します。API サーバーに対するリクエストのレイテンシを測定するには、apiserver_request_duration_seconds 指標を使用します。レイテンシの原因をより具体的に特定するには、verb ラベルまたは resource ラベルで指標をグループ化します。

GET、POST、PATCH などの単一リソース呼び出しで推奨される上限は 1 秒です。Namespace スコープとクラスタ スコープの両方の LIST 呼び出しで推奨される上限は 30 秒です。上限の期待値は、オープンソースの Kubernetes コミュニティで定義された SLO によって設定されます。詳細については、API 呼び出しレイテンシの SLI / SLO の詳細をご覧ください。

apiserver_request_duration_seconds 指標の値が想定以上の時間で増加している場合は、次の考えられる原因を調査してください。

• Kubernetes コントロール プレーンが過負荷状態になっている可能性があります。これを確認するには、apiserver_request_total と apiserver_storage_objects の指標を確認します。
  • code ラベルを使用して、リクエストが正常に処理されているかどうかを確認します。設定可能な値については、HTTP ステータス コードをご覧ください。
  • リクエストを一意に識別するには、group、version、resource、subresource ラベルを使用します。

• サードパーティのアドミッション Webhook が遅いか、応答していません。apiserver_admission_webhook_admission_duration_seconds 指標の値が増えている場合、サードパーティまたはユーザー定義のアドミッション Webhook の一部は速度が遅くなっているか、応答していないことを意味します。アドミッション Webhook のレイテンシにより、ジョブ スケジューリングに遅延が生じることがあります。

  • Kubernetes コントロール プレーンのインスタンスごとに 99 パーセンタイルの Webhook レイテンシをクエリするには、次の PromQL クエリを使用します。

    sum by (instance) (histogram_quantile(0.99, rate(apiserver_admission_webhook_admission_duration_seconds_bucket{cluster="CLUSTER_NAME"}[1m])))
    

    50、90、95、99.9 パーセンタイルも確認することをおすすめします。このクエリを調整するには 0.99 値を変更します。

  • 外部 Webhook のタイムアウトは約 10 秒に設定されています。apiserver_admission_webhook_admission_duration_seconds 指標にアラート ポリシーを設定すると、Webhook タイムアウトに近づいたときにアラートを受け取ることができます。

  • また、name ラベルの apiserver_admission_webhook_admission_duration_seconds 指標をグループ化して、特定の Webhook で発生している問題を診断することもできます。

• 多くのオブジェクトを一覧表示しています。特定のタイプのオブジェクトの数（レスポンス サイズ）が増加すると、LIST 呼び出しのレイテンシが増加します。

• クライアント側の問題:

  • クライアントに、レスポンスをタイムリーに受信するための十分なリソースがない可能性があります。確認するには、クライアント Pod の CPU 使用率の指標を確認します。
  • クライアントのネットワーク接続が遅くなっています。これは、クライアントがスマートフォンなどのデバイスで実行しているときに発生する可能性がありますが、Compute Engine ネットワークで実行されているクライアントでは可能性がほとんどありません。
  • クライアントが予期せず終了しましたが、TCP 接続のタイムアウト時間が数十秒に設定されています。接続がタイムアウトする前にサーバーのリソースがブロックされるため、レイテンシが増加する可能性があります。

詳細については、Kubernetes ドキュメントで API の優先度と公平性を使用する際のベスト プラクティスをご覧ください。

トラフィックとエラー率

API サーバーのトラフィックと、成功または失敗したリクエストの数を測定するには、apiserver_request_total 指標を使用します。たとえば、Kubernetes コントロール プレーンのインスタンスごとの API サーバー トラフィックを測定するには、次の PromQL クエリを使用します。

sum by (instance) (increase(apiserver_request_total{cluster="CLUSTER_NAME"}[1m]))

• 失敗したリクエストをクエリするには、次の PromQL クエリを使用して、code ラベルで 4xx 値と 5xx 値をフィルタします。

  sum(rate(apiserver_request_total{code=~"[45].."}[5m]))
  

• 成功したリクエストをクエリするには、次の PromQL クエリを使用して、2xx 値の code ラベルをフィルタリングします。

  sum(rate(apiserver_request_total{code=~"2.."}[5m]))
  

• API サーバーにより Kubernetes コントロール プレーンのインスタンスごとに拒否されたリクエストをクエリするには、次の PromQL クエリを使用して、値 429（http.StatusTooManyRequests）の code ラベルをフィルタリングします。

  sum by (instance) (increase(apiserver_request_total{cluster="CLUSTER_NAME", code="429"}[1m]))
  

飽和度

システムの飽和度は、apiserver_current_inflight_requests と apiserver_storage_objects 指標を使用して測定できます。

apiserver_storage_objects 指標の値が増加している場合、オブジェクトは作成しても削除しないカスタム コントローラで問題が発生している可能性があります。resource ラベルで指標をフィルタリングまたはグループ化して、増加しているリソースや増加を特定できます。

API の優先度と公平性の設定に沿って apiserver_current_inflight_requests 指標を評価します。これらの設定はリクエストの優先順位付けに影響するため、指標の値だけで結論を導き出すことはできません。詳細については、API の優先度と公平性をご覧ください。

スケジューラの指標

このセクションでは、スケジューラの指標のリストと、指標の解釈と使用に関する追加情報について説明します。

スケジューラ指標のリスト

スケジューラの指標を有効にすると、次の表に示されているすべての指標が、GKE クラスタと同じプロジェクトの Cloud Monitoring にエクスポートされます。

この表の Cloud Monitoring の指標名には、prometheus.googleapis.com/ という接頭辞を付ける必要があります。この接頭辞は、表中の項目では省略されています。

以下のセクションでは、API サーバーの指標について説明します。

scheduler_pending_pods

scheduler_pending_pods 指標を使用して、スケジューラの負荷をモニタリングできます。この指標の値が増加している場合、リソースに問題がある可能性があります。スケジューラには 3 つのキューがあり、この指標はキューごとに保留中のリクエストの数を報告します。次のキューがサポートされています。

• active キュー
  • スケジューラがスケジューリングしようとしている Pod のセット。優先度が最も高い Pod がキューの先頭になります。
• backoff キュー
  • 一連の Pod は、最後にスケジューラが試したときにスケジューリングできませんでしたが、次回はスケジューリング可能である可能性があります。
  • このキューの Pod はバックオフ期間（最大 10 秒）待機する必要があります。その後、別のスケジューリング試行のために active キューに戻ります。backoff キューの管理の詳細については、実装リクエスト（Kubernetes の問題 75417）をご覧ください。

• unschedulable セット

  • スケジューラがスケジューリングを試みたが、スケジュール不可と判断された Pod のセット。このキューにある場合は、ノードの準備状況の問題やノードセレクタの構成に互換性の問題がある可能性があります。

    リソースの制約により Pod がスケジューリングされない場合、Pod はバックオフ処理の対象になりません。クラスタがいっぱいの場合、新しい Pod はスケジューリングされず、unscheduled キューに配置されます。

  • スケジューリングされていない Pod が存在する場合は、リソースが不足しているか、ノード構成に問題がある可能性があります。クラスタの状態を変更するイベントの後に、Pod は backoff キューまたは active キューに移動します。このキューの Pod は、クラスタ内で Pod をスケジューリング可能にする変更がなかったことを示します。

  • アフィニティでは、ノードを Pod に割り当てる方法を定義します。アフィニティ ルールまたは反アフィニティ ルールを使用すると、スケジューリングされていない Pod が増加する可能性があります。

  • PVC / Service の追加 / 更新、Pod の終了、新しいノードの登録などのイベントによって、スケジューリングされていない一部またはすべての Pod が backoff キューまたは active キューに移動します。詳細については、Kubernetes の問題 81214 をご覧ください。

詳細については、スケジューラのレイテンシとリソースの問題をご覧ください。

scheduler_scheduling_attempt_duration_seconds

この指標は、スケジューラ内での 1 回のスケジューリングの所要時間を測定し、結果（スケジュール済み、スケジュール不可、エラー）で分類されます。この期間は、スケジューラが Pod を選択してから、Pod がノードに配置されてスケジュール不可と判断されるか、エラーが発生するまで続きます。スケジューリング時間には、スケジューリング プロセス内の時間とバインディング時間が含まれます。バインディングとは、スケジューラがノードの割り当てを API サーバーに伝えるプロセスです。詳細については、スケジューラのレイテンシをご覧ください。

この指標では、Pod がアドミッション コントロールまたは検証に費やした時間は取得されません。

スケジューリングの詳細については、Pod のスケジューリングをご覧ください。

scheduler_schedule_attempts_total

この指標は、スケジューリングの試行回数を測定します。Pod をスケジュールするたびに、値が増加します。この指標を使用して、スケジューラが使用可能かどうかを判断できます。値が増加している場合、スケジューラは動作可能です。result ラベルを使用して成功を判断できます。Pod は scheduled か unschedulable のどちらかです。

この指標は、scheduler_pending_pods 指標と強い相関関係があります。保留中の Pod が多数ある場合、Pod のスケジューリング回数が過剰になることがあります。詳細については、リソースの問題をご覧ください。

このスケジューラは、スケジュールする Pod がない場合に増加します（カスタム セカンダリ スケジューラを使用している場合など）。

scheduler_preemption_attempts_total と scheduler_preemptions_victims

プリエンプション指標を使用すると、リソースを追加する必要があるかどうかを判断できます。

優先度の高い Pod があり、Pod 用のスペースがないためにスケジューリングできない可能性があります。この場合、スケジューラはノード上で実行中の 1 つ以上の Pod をプリエンプトしてリソースを解放します。scheduler_preemption_attempts_total 指標は、スケジューラが Pod をプリエンプトしようとした回数を追跡します。

scheduler_preemptions_victims 指標は、プリエンプション用に選択された Pod をカウントします。

プリエンプションの試行回数は、result ラベルの値が unschedulable のときに scheduler_schedule_attempts_total 指標の値と強い相関関係があります。2 つの値は同じではありません。たとえば、クラスタのノードが 0 の場合、プリエンプションは試行されませんが、スケジューリングの失敗が発生する可能性があります。

詳細については、リソースの問題をご覧ください。

スケジューラのモニタリング

スケジューラの指標を使用すると、スケジューラのパフォーマンスに関する分析情報を取得できます。

• スケジューラ レイテンシ: スケジューラが実行されているか。Pod のスケジュールにはどのくらいの時間がかかるのか。
• リソースの問題: Pod のスケジューリングでリソースの制約が発生しているか。

このセクションでは、スケジューラ指標を使用してスケジューラをモニタリングする方法について説明します。

スケジューラのレイテンシ

スケジューラのタスクは、Pod が実行されるようにすることです。そのため、スケジューラの停止や実行速度の低下を確認する必要があります。

• スケジューラが実行され、Pod がスケジューリングされていることを確認するには、scheduler_schedule_attempts_total 指標を使用します。

• スケジューラの実行速度が遅い場合は、次の考えられる原因を調査します。

  • 保留中の Pod の数が増加している。scheduler_pending_pods 指標を使用して、保留中の Pod の数をモニタリングします。次の PromQL クエリは、クラスタ内のキューごとに保留中の Pod の数を返します。

    sum by (queue)
    (delta(scheduler_pending_pods{cluster="CLUSTER_NAME"}[2m]))
    

  • Pod を個々にスケジューリングしようとすると、速度が遅くなる。scheduler_scheduling_attempt_duration_seconds 指標を使用して、スケジューリングのレイテンシをモニタリングします。

    この指標は、少なくとも 50 パーセンタイルと 95 パーセンタイルで確認することをおすすめします。次の PromQL クエリは、95 パーセンタイル値を取得しますが、調整可能です。

    sum by (instance) (histogram_quantile(0.95, rate(
    scheduler_scheduling_attempt_duration_seconds_bucket{cluster="CLUSTER_NAME"}[5m])))
    

リソースに関する問題

スケジューラの指標は、十分なリソースがあるかどうかの評価にも役立ちます。scheduler_preemption_attempts_total 指標の値が増加している場合は、次の PromQL クエリを使用して scheduler_preemption_victims の値を確認します。

scheduler_preemption_victims_sum{cluster="CLUSTER_NAME"}

スケジューリングする優先度の高い Pod が多いと、プリエンプトの試行回数とプリエンプション障害の回数の両方が増えます。プリエンプション指標は、プリエンプションをトリガーした優先度の高い Pod がスケジューリングされたかどうかを示すものではありません。そのため、プリエンプション指標の値が増えた場合は、scheduler_pending_pods 指標の値もモニタリングします。保留中の Pod の数も増加している場合、優先度の高い Pod の処理に十分なリソースがない可能性があります。使用可能なリソースのスケールアップ、リソース クレームを削減した新しい Pod の作成、ノードセレクタの変更が必要になることがあります。

• プリエンプション障害の回数が増えていない場合は、削除可能な優先度の低い Pod はありません。この場合は、新しい Pod が割り当てられるようにノードを追加することを検討してください。

• プリエンプション障害が増加している場合は、優先度の高い Pod のスケジューリングを待機しているため、スケジューラは実行中の Pod をプリエンプトします。プリエンプション指標は、優先度の高い Pod が正常にスケジュールされたかどうかを示すものではありません。

  優先度の高い Pod がスケジュールされているかどうかを判断するには、scheduler_pending_pods 指標の値を減らします。この指標の値が増加している場合は、ノードの追加が必要になることがあります。

更新やスケーリングなどのイベント中にクラスタ内でワークロードがスケジューリングされる予定の場合、scheduler_pending_pods 指標の値が一時的に急増することがあります。クラスタに十分なリソースがある場合、この急増は一時的なものになります。保留中の Pod の数が減少しない場合は、次の操作を行います。

• ノードが閉鎖されていないことを確認します。閉鎖されたノードは新しい Pod を受け入れません。
• 次のスケジューリング ディレクティブを確認します。これらが正しく構成されていないために、Pod をスケジューリングできない可能性があります。
  • ノードのアフィニティとセレクタ。
  • taint と toleration
  • Pod トポロジの分散の制約。

リソース不足で Pod をスケジューリングできない場合は、既存のノードを解放するか、ノード数を増やすことを検討してください。

コントローラ マネージャーの指標

コントローラ マネージャーの指標を有効にすると、次の表に示されているすべての指標が、GKE クラスタと同じプロジェクトの Cloud Monitoring にエクスポートされます。

この表の Cloud Monitoring の指標名には、prometheus.googleapis.com/ という接頭辞を付ける必要があります。この接頭辞は、表中の項目では省略されています。