kube-controller-manager は、コントロールプレーンのコンポーネントであり、ノードコントローラー、StatefulSet コントローラー、Deployment コントローラーなど、Kubernetes のコアコントローラーを実行します。本トピックでは、kube-controller-manager が公開する監視メトリクスと、その健全性をモニターするための組み込みダッシュボードの使用方法について説明します。
基本概念
監視メトリクス
監視メトリクスは、kube-controller-manager の内部状態を反映します。以下の表に、利用可能なメトリクスを示します。
| メトリクス | タイプ | 説明 | 監視タイミング |
|---|---|---|---|
workqueue_adds_total | Counter | ワークキューによって処理された Add イベントの合計数。 | 異常な急増は、リソース変更のバーストを示唆します。クラスターの活動状況と相関付けて確認してください。 |
workqueue_depth | Gauge | ワークキューの現在の長さ（深さ）。 | 長期間にわたって高値が継続する場合は、コントローラーが流入するイベントに追いついていません。コントローラーの goroutine 状態およびリソース圧力について調査してください。 |
workqueue_queue_duration_seconds_bucket | Histogram | タスクがワークキュー内で処理されるまで待機する時間。バケットしきい値：{10⁻⁸、10⁻⁷、10⁻⁶、10⁻⁵、10⁻⁴、10⁻³、10⁻²、10⁻¹、1、10} 秒。 | p95/p99 分位数における高遅延は、キューのバックログを示します。histogram_quantile を使用して、SLO に基づくアラートを設定してください。 |
memory_utilization_byte | Gauge | kube-controller-manager が使用するメモリ量。単位：バイト。 | OOM 再起動を防止するため、コンテナのメモリ制限に近づいた場合にはアラートを発行してください。 |
cpu_utilization_core | Gauge | kube-controller-manager が使用する CPU 容量。単位：コア。 | 長期間にわたって高い CPU 使用率が継続する場合、コントローラーによる過剰な再同期が発生している可能性があります。 |
rest_client_requests_total | Counter | kube-apiserver に対する HTTP リクエスト数。ステータスコード、メソッド、ホストごとにグループ化されます。 | 4xx や 5xx 応答の増加は、コントローラーの操作に影響を与える kube-apiserver のサーバーエラーを示します。 |
rest_client_request_duration_seconds_bucket | Histogram | kube-controller-manager から kube-apiserver への HTTP リクエストの遅延。動詞および URL ごとに分類されます。 | p99 分位数における遅延の増加は、kube-apiserver の低速化を示しており、これによりコントローラーの再同期が遅延します。 |
非推奨のメトリクス
以下のメトリクスは非推奨となっており、今後のバージョンで削除されます。これらのメトリクスに依存するアラートやダッシュボードは、すべて削除してください。
| 非推奨のメトリクス | 置換 |
|---|---|
cpu_utilization_ratio | cpu_utilization_core |
memory_utilization_ratio | memory_utilization_byte |
ダッシュボードへのアクセス
kube-controller-manager ダッシュボードを開く手順については、「ACK Pro マネージドクラスターでのコントロールプレーンコンポーネントのダッシュボードの表示」をご参照ください。
ダッシュボードのリファレンス
ダッシュボードは、上記のメトリクスを Prometheus クエリ言語 (PromQL) を用いて構築されています。すべてのダッシュボードに共通して適用される 2 つのパラメーターがあります：
quantile：表示するリクエストの分位数（例：p99 の場合は 0.99）。
interval：
rate()計算で使用される PromQL のサンプリング間隔。
以下では、各ダッシュボードパネルとその PromQL を説明します。
ワークキューダッシュボード
| パネル | PromQL | 表示内容 |
|---|---|---|
| ワークキュー エントリーレート | sum(rate(workqueue_adds_total{job="ack-kube-controller-manager"}[$interval])) by (name) | 選択した間隔における、コントローラーごとのワークキューへの Add イベント登録レート。 |
| ワークキューの深さ | sum(rate(workqueue_depth{job="ack-kube-controller-manager"}[$interval])) by (name) | 選択した間隔における、コントローラーごとのワークキューの深さの変化。上昇傾向はキューのバックログを示します。 |
| ワークキューの処理遅延 | histogram_quantile($quantile, sum(rate(workqueue_queue_duration_seconds_bucket{job="ack-kube-controller-manager"}[5m])) by (name, le)) | 選択した分位数における、イベントがワークキュー内で待機する時間。 |
リソースダッシュボード
| パネル | PromQL | 表示内容 |
|---|---|---|
| メモリ使用量 | memory_utilization_byte{container="kube-controller-manager"} | kube-controller-manager が使用するメモリ量。単位：バイト。 |
| CPU 使用量 | cpu_utilization_core{container="kube-controller-manager"}*1000 | kube-controller-manager が使用する CPU 量。単位：ミリコア。 |
Kube API ダッシュボード
| パネル | PromQL | 表示内容 |
|---|---|---|
| Kube API リクエスト QPS | 下記を参照 | kube-controller-manager から kube-apiserver へのクエリ毎秒 (QPS)。HTTP メソッドおよびステータスコードごとに分類されます。 |
| Kube API リクエスト遅延 | histogram_quantile($quantile, sum(rate(rest_client_request_duration_seconds_bucket{job="ack-kube-controller-manager"}[$interval])) by (verb,url,le)) | 選択した分位数における、kube-controller-manager と kube-apiserver 間の往復遅延。動詞および URL ごとに分類されます。 |
Kube API リクエスト QPS パネルでは、ステータスコードのクラスごとに応答を分離するために、4 つのクエリを使用します：
sum(rate(rest_client_requests_total{job="ack-kube-controller-manager",code=~"2.."}[$interval])) by (method,code)
sum(rate(rest_client_requests_total{job="ack-cloud-controller-manager",code=~"3.."}[$interval])) by (method,code)
sum(rate(rest_client_requests_total{job="ack-cloud-controller-manager",code=~"4.."}[$interval])) by (method,code)
sum(rate(rest_client_requests_total{job="ack-cloud-controller-manager",code=~"5.."}[$interval])) by (method,code)トラブルシューティング
ダッシュボードパネルにデータが表示されない
メトリクス収集ジョブが有効であるか確認してください。ワークキューおよび Kube API パネルでは、job="ack-kube-controller-manager" を使用しています。データが表示されない場合は、Prometheus のスクレイプジョブが正常に実行されていること、および kube-controller-manager が想定されるポートでメトリクスを公開していることを確認してください。
ヒストグラムメトリクスに不完全なデータが表示される
workqueue_queue_duration_seconds_bucket のようなヒストグラムメトリクスは、ファミリー内の 3 つの系列（_bucket、_sum、_count）すべてを収集する必要があります。いずれかの系列が欠落している場合、histogram_quantile は結果を返しません。スクレイプ構成がすべての系列を収集しているか確認してください。
workqueue_depth が継続的に高止まりする
workqueue_depth が継続的にゼロでない値を示す場合、コントローラーがイベントを十分な速度で処理できていないことを意味します。コントローラーの goroutine 数および API サーバーの遅延を確認してください。同一時点での rest_client_request_duration_seconds_bucket の高値は、API サーバーのボトルネックを根本原因としていることを示唆します。
次のステップ
その他のコントロールプレーンコンポーネントのメトリクス、ダッシュボードの使用方法、およびトラブルシューティングに関するガイダンスについては、以下をご参照ください。