AKSのノードには余裕があるのに、kubectlの応答が遅い、Podの配置が進まない。そのような問題を調べる際に役立つのが、AKSコントロールプレーンメトリクスです。Azure Monitor Managed Service for Prometheusによる収集機能が2026年8月にGA（一般提供）となり、API Server、etcd、Schedulerなど6種類の管理コンポーネントを監視できます。
ただし、Managed Prometheusを有効にするだけで、すべてのコントロールプレーンメトリクスが収集されるわけではありません。専用の有効化オプションが必要で、標準の収集対象はAPI Serverとetcdです。その他のコンポーネントは、ConfigMapで追加設定します。(Microsoft Learn)
ここでは、有効化コマンド、収集対象の設定、確認に使えるPromQL、運用時の注意点まで解説します。
AKSコントロールプレーンメトリクスGAで監視できるもの
コントロールプレーンは、Kubernetes APIの受付、クラスタ情報の保存、Podの配置判断などを担当します。アプリケーションを実行するノードの監視とは、確認する対象が異なります。(Kubernetes)
今回のGAの対象は、こうしたAKSの管理コンポーネントから、Managed Prometheusでメトリクスを収集する機能です。ワークロードの変更や自動化処理、スケーリングが、コントロールプレーンにどのような影響を与えているかを時系列で調べられます。
代表的な指標と初期設定は次のとおりです。表の「初期設定」は、コントロールプレーンメトリクス機能を有効化した後の収集設定を示します。(Microsoft Learn)
| 監視対象 | 確認できる内容の例 | 代表的なメトリクス | 初期設定 |
|---|---|---|---|
| API Server | API要求数やエラーの傾向 | apiserver_request_total | 有効 |
| etcd | リーダーの有無 | etcd_server_has_leader | 有効 |
| Scheduler | 配置待ちPodの状況 | scheduler_pending_pods | 無効 |
| Controller Manager | 内部処理の待ち行列 | workqueue_depth | 無効 |
| Cluster Autoscaler | スケーリング判断に関係する配置不能Pod | cluster_autoscaler_unschedulable_pods_count | 無効 |
| Node Auto-Provisioning | ノード作成の推移 | karpenter_nodes_created_total | 無効 |
Cluster AutoscalerとNode Auto-Provisioning（NAP）は、監視する場面も異なります。Cluster Autoscalerは既存のノードプールの増減、NAPはワークロードに応じたVM構成の選択やノードのプロビジョニングを扱います。利用中のスケーリング方式に合わせて、監視対象を選びましょう。(Microsoft Learn)
無料のプラットフォームメトリクスやログとの違い
今回のGAは、「AKSのAPI Serverを初めて監視できるようになった」という意味ではありません。AKSには従来から、自動収集されるプラットフォームメトリクスがあり、コントロールプレーンのログを取得する仕組みもあります。(Microsoft Learn)
| 監視の仕組み | 主な用途 | 収集・確認方法 |
|---|---|---|
| プラットフォームメトリクス | API ServerのCPU・メモリ使用率など、提供されている基本指標の確認 | 自動収集。Azureのメトリックスエクスプローラーで確認 |
| Managed Prometheusのメトリクス | API要求、etcdの状態、スケジューリングなどの時系列分析 | 収集を有効化し、Azure Monitor workspaceに保存。PromQLで分析 |
| コントロールプレーンログ | 個々の処理や監査イベントの詳細調査 | 診断設定で収集。Log Analytics workspaceに送る場合はKQLで分析 |
Azure Monitor workspaceとLog Analytics workspaceは別のリソースです。 前者はPrometheusメトリクス、後者はログの保存・分析に使います。既にContainer insightsでログを収集していても、それだけで今回のメトリクス収集を設定したことにはなりません。(Microsoft Learn)
実務では、メトリクスで「いつ、どの処理に異常が出たか」を絞り込み、その時間帯のログで詳細を調べる使い分けが有効です。
導入前に確認する条件と制限
AKSクラスタはマネージドID認証を使用している必要があります。監視の有効化にはクラスタへのContributor権限などが必要で、収集後のデータ閲覧にはMonitoring Readerなどの権限を確認します。Grafanaとの連携では、ロール割り当てに関する追加権限も必要になる場合があります。(Microsoft Learn)
また、2026年9月3日時点の機能ドキュメントでは、このコントロールプレーンメトリクス収集はAzure Private Linkに対応していません。 閉域での監視通信が必須の環境では、GAという提供状態だけで導入可能と判断しないでください。セルフホストのPrometheusによる代替スクレイプも、この機能のサポート対象ではありません。(Microsoft Learn)
CLIで設定する場合、後述する--enable-control-plane-metricsはAzure CLI 2.88.0で追加されています。古い環境ではaz versionでバージョンを確認し、az aks update --helpにオプションが表示されることを確かめてください。(Microsoft Learn)
Azure CLIでコントロールプレーンメトリクスを有効にする
以下は、対象のAzureサブスクリプションにサインイン済みのBash環境を想定した例です。リソースグループ名、クラスタ名、ワークスペースIDは実際の値に置き換えてください。
Managed Prometheusが既に有効なクラスタ
既存のManaged Prometheus環境に、コントロールプレーンの収集を追加します。(Microsoft Learn)
RESOURCE_GROUP="rg-aks-prod"
CLUSTER_NAME="aksprod"
az aks update \
--resource-group "$RESOURCE_GROUP" \
--name "$CLUSTER_NAME" \
--enable-control-plane-metricsこの操作で、標準の対象であるAPI Serverとetcdのメトリクス収集を有効化します。SchedulerやController Managerなどの追加は、後述するConfigMapで設定します。(Microsoft Learn)
Managed Prometheusも同時に有効化するクラスタ
Managed Prometheusが未設定の場合は、--enable-azure-monitor-metricsも指定します。既存のAzure Monitor workspaceに集約する例は次のとおりです。(Microsoft Learn)
AMW_RESOURCE_ID="/subscriptions/<subscription-id>/resourceGroups/<workspace-rg>/providers/Microsoft.Monitor/accounts/<workspace-name>"
az aks update \
--resource-group "$RESOURCE_GROUP" \
--name "$CLUSTER_NAME" \
--enable-azure-monitor-metrics \
--enable-control-plane-metrics \
--azure-monitor-workspace-resource-id "$AMW_RESOURCE_ID"ワークスペースを指定しない場合は、既定のワークスペースが使用されるか、新しく作成されます。監視データの保存先を統一したい環境では、事前に集約先を決めて明示的に指定するほうが管理しやすくなります。(Microsoft Learn)
新規クラスタでは、通常のaz aks createコマンドに--enable-azure-monitor-metricsと--enable-control-plane-metricsを追加します。既にプレビュー期間中にコントロールプレーンメトリクスを有効化していたクラスタは、収集を継続する扱いです。(Microsoft Learn)
SchedulerやAutoscalerをConfigMapで追加する
API Serverとetcd以外も監視する場合は、kube-system名前空間のama-metrics-settings-configmapを設定します。
まず、対象クラスタに接続したkubectlで既存設定を確認します。Managed Prometheusを有効化した直後の標準状態では、ConfigMap自体が存在しない場合があります。NotFoundだけで監視の故障とは判断しません。(Microsoft Learn)
kubectl -n kube-system get configmap ama-metrics-settings-configmap最小取り込みを維持して監視対象を増やす設定例
次は、Cluster Autoscalerを利用しているクラスタで、SchedulerとController Managerの監視も追加する例です。configmap-controlplane.yamlとして保存します。
既存のConfigMapがある場合は、先にバックアップを取得し、ほかの設定を残したうえで差分を反映してください。特に、既存のcluster-metricsやメトリクスのkeep-listを、サンプルで丸ごと置き換えないようにします。
apiVersion: v1
kind: ConfigMap
metadata:
name: ama-metrics-settings-configmap
namespace: kube-system
data:
schema-version: "v2"
config-version: "cpmetrics1"
controlplane-metrics: |-
default-targets-scrape-enabled: |-
apiserver = true
etcd = true
kube-scheduler = true
kube-controller-manager = true
cluster-autoscaler = true
node-auto-provisioning = false
minimal-ingestion-profile: |-
enabled = trueこの設定は、公式サンプルのスキーマv2に沿った構成です。NAPを監視する環境ではnode-auto-provisioningをtrueにし、Cluster Autoscaler側も実際の利用状況に合わせて設定します。
なお、ここでのtrueはメトリクスの収集設定です。NAPやCluster Autoscalerそのものを導入・有効化する操作とは別です。(Microsoft Learn)
設定を適用します。
kubectl apply -f configmap-controlplane.yaml古いスキーマの設定をそのまま混ぜない
スキーマv2では、ノードなどの設定をcluster-metrics、コントロールプレーンの設定をcontrolplane-metricsに分けます。収集対象のキーも、旧形式のcontrolplane-apiserverではなく、該当セクション内のapiserverを使います。(Microsoft Learn)
既存設定がv1の場合、schema-versionだけをv2へ変更するのでは不十分です。収集対象、keep-list、最小取り込みの設定を、v2の構造に合わせて移してください。(Microsoft Learn)
PromQLでAPI Serverとetcdの収集を確認する
収集したメトリクスはAzure Monitor workspaceで照会できます。AzureポータルのPrometheusクエリ画面で確認できるため、最初の動作確認にGrafanaの構築は必須ではありません。(Microsoft Learn)
以下の例は、clusterラベルがaksprodの場合です。クラスタの別名を設定している環境では、そのラベル値に置き換えます。(Microsoft Learn)
また、ConfigMapの収集対象名と、クエリで使うjobラベルは区別してください。API Serverとetcdのコントロールプレーン収集には、それぞれcontrolplane-apiserver、controlplane-etcdのジョブ名が使われます。(Microsoft Learn)
API Serverのリクエスト数を確認する
HTTPステータスコード別に、直近5分間から計算した1秒あたりのAPI要求数を表示する例です。
sum by (code) (
rate(apiserver_request_total{
cluster="aksprod",
job="controlplane-apiserver"
}[5m])
)apiserver_request_totalは累積値なので、そのままの値だけで現在の負荷を判断せず、rate()で増加速度を確認します。カウンターに対して先にrate()を計算し、その後で集計する形にします。(Prometheus)
要求数の増加だけで障害とは限りません。デプロイや定期処理の時間と照らし合わせ、エラーや処理時間の悪化を伴っているかを確認するためのグラフとして使います。
API Serverの平均処理時間を確認する
API操作の種類を示すverb別に、平均処理時間を計算する例です。
sum by (verb) (
rate(apiserver_request_duration_seconds_sum{
cluster="aksprod",
job="controlplane-apiserver"
}[5m])
)
/
sum by (verb) (
rate(apiserver_request_duration_seconds_count{
cluster="aksprod",
job="controlplane-apiserver"
}[5m])
)処理時間の合計を要求数で割る方法です。複数インスタンスを集計する場合も、インスタンスごとの平均値を単純平均するのではなく、合計と件数をそれぞれ集計してから割ります。(Prometheus)
このクエリの単位は秒です。要求がない区間など、分母がゼロになる場合の値を「処理時間ゼロ」と読み替えないようにしてください。
p95・p99は最小取り込みのままでは計算できない
API要求時間のp95・p99を見たい場合は、ヒストグラムの収集設定に注意が必要です。
標準の最小取り込みでは、apiserver_request_duration_secondsの全バケットを収集していません。主に合計値、件数、+Infバケットが対象で、平均時間を確認する構成です。したがって、一般的なhistogram_quantile()の式を貼るだけでは、適切なパーセンタイルを得られません。(Microsoft Learn)
p95・p99が必要なら、API Serverのkeep-listにapiserver_request_duration_seconds_bucket、apiserver_request_duration_seconds_sum、apiserver_request_duration_seconds_countを含め、必要なバケット系列を取り込みます。クラシックヒストグラムを集計するときは、leラベルを保持する必要があります。(Microsoft Learn)
まず平均時間で監視を始め、遅い要求の分布まで必要になった段階で収集量を増やすと、費用と分析目的を合わせやすくなります。
etcdのリーダー状態を確認する
etcd_server_has_leader{
cluster="aksprod",
job="controlplane-etcd"
}1はそのメンバーにリーダーが存在する状態、0は存在しない状態を示します。「そのメンバー自身がリーダーかどうか」を示す指標ではありません。(etcd)
インスタンスごとの値と継続時間を確認してください。また、メトリクスが返らない状態は0とは別です。データ欠落を正常値や異常値へ自動的に読み替えると、誤判定につながります。
Grafanaとアラートに展開する
API Server・etcdのダッシュボードを利用する
Grafanaで可視化する場合は、API Server用の「Kubernetes / API Server」（ID：20331）と、etcd用の「Kubernetes / ETCD」（ID：20330）のテンプレートを利用できます。インポート後は、Prometheusデータソースと対象クラスタの選択を確認します。(Grafana Labs)
運用では、通常時だけでなく、定期バッチや大規模デプロイの時間帯も確認しておくと比較しやすくなります。障害時に初めてグラフを見るのではなく、「通常の変更作業でどこまで増えるか」を把握しておくことが重要です。
アラートはPrometheusルールグループで設定する
Managed Prometheusのアラートは、Azure Monitor workspaceのルールグループで管理できます。Azureポータルでルールグループを作成し、対象ワークスペース・クラスタ、PromQL、評価間隔、通知先のアクショングループなどを設定します。(Microsoft Learn)
最初から大量の通知を作るより、APIエラーの継続、API処理時間の悪化、etcdのリーダー不在など、通知後の対応を決められるものから始めましょう。閾値だけでなく、「何分続いたら通知するか」「誰がどの画面を確認するか」もセットで決めます。
Podの配置待ちを「ノード不足」と即断しない
例えば、Schedulerの配置待ちが増えていても、ノード追加だけで解消するとは限りません。PodのCPU要求、ノードのtaint、ボリュームの配置制約などが原因になる場合があります。(Microsoft Learn)
メトリクスで対象時間帯を特定したら、kubectl describe pod -n <namespace> <pod-name>でEventsを確認します。そのうえでAutoscalerやNAPの動きと照合すると、「配置条件が合わない」のか「必要な容量が用意されない」のかを分けて調べられます。
コントロールプレーンメトリクスの価値は、単にグラフを増やすことではありません。API処理、Podの配置判断、ノードの確保を分けて調べ、誤った対処を減らすことにあります。
費用とメトリクス欠落で失敗しないための注意点
GAになっても、Prometheusの収集・クエリは無料とは限らない
Managed Prometheusの料金は、取り込んだデータサンプル数と、クエリで処理したサンプル数に基づきます。Azureの標準プラットフォームメトリクスが無料で収集されることとは、分けて考えてください。(Microsoft Learn)
コストを抑える基本は、最小取り込みを有効にしたまま、必要な収集対象と指標を追加することです。最小取り込みを無効化すると、収集量が大きく増える可能性があります。(Microsoft Learn)
Azure Managed Grafanaを追加する場合は、そのサービス料金も見積もりに含めます。メトリクス収集だけを試す段階では、まずワークスペース上のクエリで確認する進め方が適しています。(マイクロソフト アジュール)
CPU・メモリを含む全指標が取得できるわけではない
コントロールプレーンのPrometheusメトリクスでは、取り込みプロファイルにかかわらず、各対象のCPU・メモリ使用量メトリクスは公開されないと案内されています。一方、API ServerのCPU・メモリ使用率はプラットフォームメトリクス側に用意されています。(Microsoft Learn)
「欲しい指標がないから最小取り込みを無効にする」と決める前に、その指標がどの監視経路で提供されるのかを確認しましょう。
データが表示されないときの確認順
次の順で確認すると、設定不足と収集障害を切り分けやすくなります。(Microsoft Learn)
| 症状 | 最初に確認すること |
|---|---|
| コントロールプレーンの指標が一つもない | Managed Prometheusとコントロールプレーン収集の両方が有効か |
| 設定した直後にデータがない | 反映まで数分待ち、適用後を含む時間範囲で再確認する |
| SchedulerやAutoscalerだけ表示されない | 対象の収集設定がtrueか。実際の利用状況に合っているか |
| ConfigMapを変更しても変わらない | 名前空間、ConfigMap名、スキーマ、設定の階層を確認する |
| ワークスペースで確認できない | 正しい保存先を開いているか。閲覧権限があるか |
| 特定のメトリクスだけ存在しない | 対象がその指標を公開しているか。keep-listで除外していないか |
なお、コントロールプレーンを収集するコンポーネントは、ノード側のama-metricsアドオンとは別です。ノードのメトリクスが届いていることだけで、コントロールプレーンの収集も正常と判断しないでください。(Microsoft Learn)
コントロールプレーンの収集だけを停止する
検証を終える場合など、コントロールプレーンメトリクスだけを止めるには、専用オプションを使います。(Microsoft Learn)
az aks update \
--resource-group "$RESOURCE_GROUP" \
--name "$CLUSTER_NAME" \
--disable-control-plane-metrics--disable-azure-monitor-metricsはManaged Prometheus全体の無効化です。他の対象のメトリクス収集も止まるため、停止範囲を取り違えないようにしてください。(Microsoft Learn)
まずはAPI Serverとetcdの最小収集から始める
AKSコントロールプレーンメトリクスを導入するなら、最初に既存のManaged Prometheus設定と、接続先のAzure Monitor workspaceを確認しましょう。
その後、API Serverとetcdの収集を有効にし、API要求数、平均処理時間、etcdのリーダー状態がクエリで返ることを確認します。Scheduler、Controller Manager、Autoscaler、NAPは、実際に切り分けたい問題に合わせて追加する進め方が適しています。
最初の到達点は「全メトリクスの収集」ではなく、異常を見つけたときに、次に確認するコンポーネントとログが分かる状態です。収集、可視化、通知、調査手順までをつなげて設定しましょう。
コメント