[AKS] Add --enable-control-plane-metrics and --disable-control-plane-metrics for Managed Prometheus

[bragi92]

Description

Add CLI support for the new Control Plane Metrics feature in the Azure Managed Prometheus addon. This enables collection of operational runtime metrics from managed control plane components (kube-apiserver, etcd, etc.) via the ManagedClusterAzureMonitorProfileMetricsControlPlane model.

Background

• API Spec PR: Dakydd/cpmetrics 2026 02 02 preview Azure/azure-rest-api-specs#41280 (merged March 12, 2026)
• API Version: 2026-02-02-preview
• Feature Docs: https://aka.ms/aks/controlplane-metrics

This is part of the CCP Metrics GA plan. The feature transitions from a preview feature-flag-based enablement to an explicit opt-in via a new controlPlane property on the ManagedClusterAzureMonitorProfileMetrics model.

New CLI Parameters

Parameter	Command	Type	Description
--enable-control-plane-metrics	az aks create	bool	Enable control plane metrics when creating a cluster with --enable-azure-monitor-metrics
--disable-control-plane-metrics	az aks create	bool	Explicitly disable control plane metrics at create time
--enable-control-plane-metrics	az aks update	bool	Enable control plane metrics on an existing cluster (requires Azure Monitor Metrics to be enabled)
--disable-control-plane-metrics	az aks update	bool	Disable control plane metrics on an existing cluster

CLI Usage Examples

Enable on new cluster:

az aks create --enable-azure-monitor-metrics \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-control-plane-metrics

Enable on existing cluster (metrics already enabled):

az aks update --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-control-plane-metrics

Enable both monitor metrics and control plane on existing cluster:

az aks update --enable-azure-monitor-metrics \
  --name <cluster-name> \
  --resource-group <resource-group> \
  --enable-control-plane-metrics

Disable control plane metrics:

az aks update --name <cluster-name> \
  --resource-group <resource-group> \
  --disable-control-plane-metrics

Validation Rules

1. Cannot use standalone: --enable-control-plane-metrics cannot be used without --enable-azure-monitor-metrics on create, or without Azure Monitor Metrics already being enabled on the cluster for update. Error:

   --enable-control-plane-metrics cannot be used as a standalone flag. This flag must be used in conjunction with --enable-azure-monitor-metrics to enable control plane metrics collection.

2. Mutual exclusivity: --enable-control-plane-metrics and --disable-control-plane-metrics cannot be specified together.

3. Disable requires metrics: --disable-control-plane-metrics requires Azure Monitor Metrics to be enabled on the cluster.

ARM Model Shape

{
  "azureMonitorProfile": {
    "metrics": {
      "enabled": true,
      "controlPlane": {
        "enabled": true
      },
      "kubeStateMetrics": { }
    }
  }
}

Files Changed

File	Changes
_params.py	Added enable_control_plane_metrics and disable_control_plane_metrics to both create and update command groups
custom.py	Added new parameters to aks_create() and aks_update() function signatures
managed_cluster_decorator.py	Added getter/validator methods with validation (mutual exclusivity, requires monitor metrics). Updated set_up_azure_monitor_profile (create) and update_azure_monitor_profile (update) to set control_plane on the metrics object
_help.py	Added help text for all new parameters in both create and update commands

Customer Scenarios Covered

#	Scenario	Behavior
1	New cluster with control plane metrics	az aks create --enable-azure-monitor-metrics --enable-control-plane-metrics enables API Server and ETCD metrics
2	Existing cluster, add control plane metrics	az aks update --enable-control-plane-metrics (if monitor metrics already enabled)
3	Preview to GA transition	Existing preview customers backfilled via regional looper; controlPlane.enabled=true set automatically
4	Without monitor metrics addon	az aks create --enable-control-plane-metrics alone gives error with guidance to enable monitor metrics first
5	Disable control plane metrics	az aks update --disable-control-plane-metrics stops collection while keeping monitor metrics enabled

Known Blockers

SDK dependency: ManagedClusterAzureMonitorProfileMetricsControlPlane does not yet exist in azure-mgmt-containerservice. Current pin is 41.0.0 and latest beta 41.1.0b1 also does not include it. This PR is ready for review but cannot be merged or tested end-to-end until the SDK is updated.

TODO (post SDK availability)

• Bump azure-mgmt-containerservice version in setup.py
• Add unit tests in test_managed_cluster_decorator.py
• Add integration test recordings
• Verify end-to-end with a live cluster

Related

• API Spec PR: Dakydd/cpmetrics 2026 02 02 preview Azure/azure-rest-api-specs#41280
• Last SDK bump PR: {AKS} Vendor new SDK and bump API version to 2026-01-01 Azure/azure-cli#32955

[github-actions]

The git hooks are available for azure-cli and azure-cli-extensions repos. They could help you run required checks before creating the PR.

Please sync the latest code with latest dev branch (for azure-cli) or main branch (for azure-cli-extensions).
After that please run the following commands to enable git hooks:

pip install azdev --upgrade
azdev setup -c <your azure-cli repo path> -r <your azure-cli-extensions repo path>