Kube 状態指標を収集して表示する

このページでは、Google Cloud Managed Service for Prometheus を使用して、厳選された一連の Kube の状態（Deployment と Pod の指標を含む）を 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 を実行して最新のバージョンを取得する。

要件

Kube 状態指標を収集するには、GKE クラスタが次の要件を満たしている必要があります。

• クラスタで GKE 1.27.2-gke.1200 以降を実行している必要があります。バージョン 1.29.2-gke.2000 以降の GKE Standard クラスタとバージョン 1.27.4-gke.900 以降の GKE Autopilot クラスタでは、Kube 状態指標パッケージがデフォルトで有効になっています。
• クラスタでシステム指標が有効になっている。
• クラスタで Google Cloud Managed Service for Prometheus マネージド コレクションが有効になっている。新しいクラスタでは、Google Cloud Managed Service for Prometheus マネージド コレクションがデフォルトで有効になっています。

Kube 状態指標の収集を構成する

kube 状態指標は、Google Cloud コンソール、gcloud CLI、または Terraform を使用して有効にできます。

gcloud container clusters update CLUSTER_NAME \
    --location=COMPUTE_LOCATION \
    --enable-managed-prometheus \
    --monitoring=SYSTEM,DAEMONSET,DEPLOYMENT,HPA,POD,STATEFULSET,STORAGE

割り当て

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

料金

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

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

指標の形式

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

Cloud Monitoring からのエクスポート

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

指標のクエリ

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

次の kube 状態指標の表では、指標名ごとに 2 つのバージョンを示します。

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

ストレージ指標

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

詳細については、PersistentVolume 指標と PersistentVolumeClaim 指標をご覧ください。

Pod の指標

Pod とは、ストレージとネットワーク リソースを共有するコンテナの実行方法の仕様を備えた 1 つ以上のコンテナのグループです。

Pod の指標の表

Pod の指標を使用すると、Pod の動作のモニタリングとアラートの作成を行うことができます。次の表に、Kube 状態指標パッケージで使用可能な指標を示します。

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

詳細については、Pod の指標をご覧ください。

Pod の指標のサンプルクエリ

スケジュール不可の Pod があるかどうかを確認するには、次の PromQL 式を使用します。

sum(kube_pod_status_unschedulable{cluster="CLUSTER", namespace="NAMESPACE"})

名前空間内のスケジュール不可の Pod の数に対してアラートを出すには、次の PromQL 式を使用します。

sum(kube_pod_status_unschedulable{cluster="CLUSTER", namespace="NAMESPACE"}) > LIMIT

kube_pod_container_status_waiting_reason 指標で、次のような PromQL 式を使用して、特定の待機状態で停止しているコンテナのアラートを作成できます。

max_over_time(kube_pod_container_status_waiting_reason{reason="REASON", cluster="CLUSTER", namespace="NAMESPACE"}[5m]) >= 1

REASON の値は、コンテナの待機状態を指定します。次に例を示します。

• CrashLoopBackOff
• ImagePullBackOff
• ContainerCreating

いずれかの待機状態で停止したコンテナのアラートを作成するには、次の PromQL 式を使用します。

max_over_time(kube_pod_container_status_waiting_reason{cluster="CLUSTER", namespace="NAMESPACE"}[5m]) >= 1

readiness チェックに失敗したコンテナの数を確認するには、次の PromQL 式を使用します。

sum(kube_pod_container_status_ready) by (pod, container) == 0

このセクションのクエリとアラートの式の一部は、GitHub の Prometheus コミュニティ Kubernetes Helm チャート リポジトリの kubernetes-apps.yaml ファイルから適用されています。

インタラクティブ ハンドブック

Kube 状態指標は、スケジュール不可の Pod またはクラッシュ ループの Pod のトラブルシューティングに、GKE インタラクティブ ハンドブックでも使用されます。これらの障害モードの詳細については、次のトラブルシューティングのドキュメントをご覧ください。

• クラッシュ ループしている Pod
• スケジュール不可の Pod

Kube 状態指標パッケージが有効になっていない場合、Pod のスケジューリングの問題を検出する主な方法は、「Failed Scheduling」ログイベントのクエリを行うことです。Kube 状態指標パッケージを有効にすると、kube_pod_status_unschedulable 指標を使用できます。これは同じ目的を果たしますが、集計とグラフ化が簡単になります。この指標を使用すると、スケジュールできない Pod の数と、問題が発生した日時を確認できます。

同様に、GKE システム指標 kubernetes.io/container/restart_count を使用して、クラッシュ ループの Pod を検出できます。kube_pod_container_status_waiting_reason 指標でもクラッシュループの Pod を列挙して、Pod が CrashLookBackOff 以外の待機状態（ImagePullBackOff や ContainerCreating など）で停止しているかどうかを判断することもできます。

インタラクティブ ハンドブックを探すには、次の操作を行います。

1. Google Cloud コンソールで [ダッシュボード] ページに移動します。

   [ダッシュボード] に移動

   検索バーを使用してこのページを検索する場合は、小見出しが「Monitoring」の結果を選択します。

2. [GCP] カテゴリをクリックして、ダッシュボード リストをフィルタリングします。
3. リスト内の「GKE Interactive Playbook」ダッシュボードの名前をクリックします。

デプロイ指標

Deployment は、Pod などのリソースの状態を更新して、ロールアウトや停止といったイベントを管理するコントローラです。

Deployment の指標の表

Deployment の指標を使用すると、コントローラの動作のモニタリングとアラートの作成を行うことができます。次の表に、Kube 状態指標パッケージで使用可能な指標を示します。

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

詳細については、Deployment の指標をご覧ください。

Deployment の指標のサンプルクエリ

Deployment の指標をクラスタ、名前空間、Deployment の名前でフィルタすることで、個々の Deployment のグラフとアラート ポリシーを作成できます。

たとえば、使用可能なレプリカの数と 1 つの Deployment で想定されるレプリカの数を比較する場合は、次の PromQL クエリを使用すると両方の指標を 1 つのグラフにプロットできます。

kube_deployment_spec_replicas{cluster="CLUSTER", namespace="NAMESPACE", deployment=DEPLOYMENT"}

kube_deployment_status_replicas_available{cluster="CLUSTER", namespace="NAMESPACE", deployment=DEPLOYMENT"}

失敗した Deployment または停滞している Deployment に対してアラートを出すには、次の PromQL 式を使用します。

(
  kube_deployment_spec_replicas{cluster="CLUSTER", namespace="NAMESPACE", deployment="DEPLOYMENT"}
    >
  kube_deployment_status_replicas_available{cluster="CLUSTER", namespace="NAMESPACE", deployment="DEPLOYMENT"}
) and (
  changes(kube_deployment_status_replicas_updated{cluster="CLUSTER", namespace="NAMESPACE", deployment="DEPLOYMENT"}[10m])
    ==
  0
)

このセクションのクエリとアラートの式の一部は、GitHub の Prometheus コミュニティ Kubernetes Helm チャート リポジトリの kubernetes-apps.yaml ファイルから適用されています。

StatefulSet の指標

StatefulSet は、ステートフル アプリケーションで一連の Pod のデプロイとスケーリングを管理するコントローラです。このコントローラは、Pod の順序と一意性を管理します。

StatefulSet の指標の表

StatefulSet の指標を使用すると、コントローラの動作のモニタリングとアラートの作成を行うことができます。次の表に、Kube 状態指標パッケージで使用可能な指標を示します。

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

詳細については、StatefulSet の指標をご覧ください。

StatefulSet の指標のサンプルクエリ

StatefulSet の指標をクラスタ、Namespace、StatefulSet の名前でフィルタリングすることで、個々の StatefulSet のグラフとアラート ポリシーを作成できます。

たとえば、使用可能なレプリカの数と 1 つの StatefulSet で想定されるレプリカの数を比較する場合は、次の PromQL クエリを使用すると両方の指標を 1 つのグラフにプロットできます。

kube_statefulset_replicas{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}

kube_statefulset_status_replicas_ready{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}

失敗した StatefulSet または停滞している StatefulSet に対してアラートを出すには、次の PromQL 式を使用します。

(
  kube_statefulset_replicas{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}
    >
  kube_statefulset_status_replicas_ready{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}
) and (
  changes(kube_statefulset_status_replicas_updated{cluster="CLUSTER", namespace="NAMESPACE", statefulset="STATEFULSET"}[10m])
    ==
  0
)

このセクションのクエリとアラートの式の一部は、GitHub の Prometheus コミュニティ Kubernetes Helm チャート リポジトリの kubernetes-apps.yaml ファイルから適用されています。

DaemonSet の指標

DaemonSet は、いくつかのノードのセットが Pod のコピーを実行するようにするコントローラです。たとえば、ノードがクラスタに追加されると、DaemonSet はそのノードに Pod を追加します。このコントローラは、特定のプロセスがすべてのノードで実行されるようにする場合に便利です。

DaemonSet の指標の表

DaemonSet の指標を使用すると、コントローラの動作のモニタリングとアラートの作成を行うことができます。次の表に、Kube 状態指標パッケージで使用可能な指標を示します。

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

詳細については、DaemonSet の指標をご覧ください。

DaemonSet の指標のサンプルクエリ

DaemonSet の指標を、クラスタ、名前空間、DaemonSet の名前でフィルタすることで、個々の DaemonSet のグラフとアラート ポリシーを作成できます。

たとえば、使用可能なレプリカの数と 1 つの DaemonSet で想定されるレプリカの数を比較する場合は、次の PromQL クエリを使用すると両方の指標を 1 つのグラフにプロットできます。

kube_daemonset_status_updated_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonsetset=DAEMONSET"}

kube_daemonset_status_desired_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset=DAEMONSET"}

失敗した DaemonSet または停滞している DaemonSet に対してアラートを出すには、次の PromQL 式を使用します。

(
  (
    kube_daemonset_status_number_misscheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}
      !=
    0
  ) or (
    kube_daemonset_status_updated_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}
      !=
    kube_daemonset_status_desired_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}
  )
) and (
  changes(kube_daemonset_status_updated_number_scheduled{cluster="CLUSTER", namespace="NAMESPACE", daemonset="DAEMONSET"}[5m])
    ==
  0
)

このセクションのクエリとアラートの式の一部は、GitHub の Prometheus コミュニティ Kubernetes Helm チャート リポジトリの kubernetes-apps.yaml ファイルから適用されています。

HorizontalPodAutoscaler の指標

HorizontalPodAutoscaler（HPA）は、CPU やメモリ使用率などの指標に応じて、ワークロード（Deployment や StatefulSet など）の Pod の数を定期的に変更するコントローラです。ワークロードで使用できる Pod の数を変更すると、ワークロードの応答性を維持しながら効率性を確保できます。

HPA の詳細については、HorizontalPodAutoscaler の詳細表示をご覧ください。

HPA の指標の表

HorizontalPodAutoscaler の指標を使用すると、コントローラの動作のモニタリングとアラートの作成を行うことができます。次の表に、Kube 状態指標パッケージで使用可能な指標を示します。

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

詳細については、HorizontalPodAutoscaler の指標をご覧ください。

HPA の指標のサンプルクエリ

たとえば、HPA がレプリカの最大数に近づいているかどうかを判断する場合は、次の比率をプロットします。

kube_horizontalpodautoscaler_status_current_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"} /
kube_horizontalpodautoscaler_spec_max_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"}

最大数のレプリカで HPA を実行している場合は、Pod の最大数の仕様を増やすことをおすすめします。次の PromQL 式を使用するとこのケースを通知するアラートを作成できます。

kube_horizontalpodautoscaler_status_current_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"}
  ==
kube_horizontalpodautoscaler_spec_max_replicas{cluster="CLUSTER", namespace="NAMESPACE", horizontalpodautoscaler="HPA"}

kube_horizontalpodautoscaler_status_current_replicas と kube_horizontalpodautoscaler_status_desired_replicas の指標の値を比較して、現在のレプリカ数と必要なレプリカ数の間に差異があるかどうかを判断することもできます。この差異は、クラスタ内のリソースの制約を示している可能性があります。次の PromQL 式は、現在のレプリカ数と必要なレプリカ数、最小レプリカ数、最大レプリカ数との差異、現在のレプリカ数の変化を調べます。

(kube_horizontalpodautoscaler_status_desired_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}
  !=
kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"})
  and
(kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}
  >
kube_horizontalpodautoscaler_spec_min_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"})
  and
(kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}
  <
kube_horizontalpodautoscaler_spec_max_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"})
  and
changes(kube_horizontalpodautoscaler_status_current_replicas{job="kube-state-metrics", namespace=~"NAMESPACE"}[15m]) == 0

kube_horizontalpodautoscaler_status_condition 指標の condition ラベルと status ラベルは、HPA がさまざまな障害モードに陥ったタイミングを検出する場合にも役立ちます。例:

• 条件 ScalingLimited とステータス true は、HPA がレプリカの最小数と最大数のいずれかでバインドされていることを示します。

  kube_horizontalpodautoscaler_status_condition{status="true", condition="ScalingLimited"} == 1

• 条件 AbleToScale とステータス false は、HPA でスケールの取得または更新に関する問題が発生していることを示します。

  kube_horizontalpodautoscaler_status_condition{status="false", condition="AbleToScale"} == 1

• 条件 ScalingActive とステータス false は、HPA が無効になっているか、新しいスケールを計算できないことを示しています。

  kube_horizontalpodautoscaler_status_condition{status="false", condition="ScalingActive"} == 1

このセクションのクエリとアラートの式の一部は、GitHub の Prometheus コミュニティ Kubernetes Helm チャート リポジトリの kubernetes-apps.yaml ファイルから適用されています。