{AKS} Add support for customer control plane scaling profile

src/aks-preview/HISTORY.rst

@@ -12,6 +12,10 @@ To release a new version, please select a new version number (usually plus 1 to
 Pending
 +++++++
 
+19.0.0b25
++++++++
+* `az aks create/update`: Add `--control-plane-scaling-size` parameter to configure control plane scaling profile with available sizes 'H2', 'H4', and 'H8'.
+
 19.0.0b24
 +++++++
 * Vendor new SDK and bump API version to 2026-01-02-preview.

src/aks-preview/azext_aks_preview/_help.py

@@ -702,6 +702,14 @@
         - name: --enable-hosted-system
           type: bool
           short-summary: Create a cluster with fully hosted system components. This applies only when creating a new automatic cluster.
+        - name: --control-plane-scaling-size --cp-scaling-size
+          type: string
+          short-summary: (PREVIEW) The control plane scaling size for the cluster.
+          long-summary: |
+              Provides scaled and performance-guaranteed control plane capacity for AKS clusters.
+              Enables customers to select a control plane scaling size that delivers higher API server throughput,
+              increased etcd capacity, and faster pod scheduling rates. Available values are 'H2', 'H4', and 'H8'.
+              Requires Kubernetes version >= 1.33.0 and Azure CNI Overlay networking.
     examples:
         - name: Create a Kubernetes cluster with an existing SSH public key.
           text: az aks create -g MyResourceGroup -n MyManagedCluster --ssh-key-value /path/to/publickey
@@ -793,6 +801,8 @@
           text: az aks create -g MyResourceGroup -n MyManagedCluster --enable-managed-system-pool
         - name: Create a kubernetes cluster with a managed installation of Gateway API CRDs from the standard release channel.
           text: az aks create -g MyResourceGroup -n MyManagedCluster --enable-gateway-api
+        - name: Create a kubernetes cluster with control plane scaling size H4.
+          text: az aks create -g MyResourceGroup -n MyManagedCluster --network-plugin azure --network-plugin-mode overlay --pod-cidr 10.244.0.0/16 --control-plane-scaling-size H4
         - name: Create an automatic cluster with hosted system components enabled.
           text: az aks create -g MyResourceGroup -n MyManagedCluster --sku automatic --enable-hosted-system
 
@@ -1430,6 +1440,14 @@
         - name: --disable-application-load-balancer
           type: bool
           short-summary: Disable Application Load Balancer (Application Gateway for Containers) addon.
+        - name: --control-plane-scaling-size --cp-scaling-size
+          type: string
+          short-summary: (PREVIEW) The control plane scaling size for the cluster.
+          long-summary: |
+              Provides scaled and performance-guaranteed control plane capacity for AKS clusters.
+              Enables customers to select a control plane scaling size that delivers higher API server throughput,
+              increased etcd capacity, and faster pod scheduling rates. Available values are 'H2', 'H4', and 'H8'.
+              Requires Kubernetes version >= 1.33.0 and Azure CNI Overlay networking.
     examples:
       - name: Reconcile the cluster back to its current state.
         text: az aks update -g MyResourceGroup -n MyManagedCluster
@@ -1513,6 +1531,8 @@
         text: az aks update -g MyResourceGroup -n MyManagedCluster --enable-opentelemetry-logs --opentelemetry-logs-port 4317
       - name: Disable OpenTelemetry metrics collection on an existing cluster
         text: az aks update -g MyResourceGroup -n MyManagedCluster --disable-opentelemetry-metrics
+      - name: Update a kubernetes cluster's control plane scaling size.
+        text: az aks update -g MyResourceGroup -n MyManagedCluster --control-plane-scaling-size H8
       - name: Disable OpenTelemetry logs collection on an existing cluster
         text: az aks update -g MyResourceGroup -n MyManagedCluster --disable-opentelemetry-logs
 """

src/aks-preview/azext_aks_preview/_params.py

@@ -1201,6 +1201,14 @@ def load_arguments(self, _):
             help="Enable managed installation of Gateway API CRDs from the standard release channel."
         )
         c.argument("enable_hosted_system", action="store_true", is_preview=True)
+        c.argument(
+            "control_plane_scaling_size",
+            options_list=["--control-plane-scaling-size", "--cp-scaling-size"],
+            arg_type=get_enum_type(["H2", "H4", "H8"]),
+            is_preview=True,
+            help="The control plane scaling size. Provides scaled and performance-guaranteed control plane capacity. "
+                 "Available values are 'H2', 'H4', and 'H8'.",
+        )
 
     with self.argument_context("aks update") as c:
         # managed cluster paramerters
@@ -1779,6 +1787,14 @@ def load_arguments(self, _):
             is_preview=True,
             help="Disable Application Load Balancer (Application Gateway for Containers)."
         )
+        c.argument(
+            "control_plane_scaling_size",
+            options_list=["--control-plane-scaling-size", "--cp-scaling-size"],
+            arg_type=get_enum_type(["H2", "H4", "H8"]),
+            is_preview=True,
+            help="The control plane scaling size. Provides scaled and performance-guaranteed control plane capacity. "
+                 "Available values are 'H2', 'H4', and 'H8'.",
+        )
 
     with self.argument_context("aks upgrade") as c:
         c.argument("kubernetes_version", completer=get_k8s_upgrades_completion_list)

src/aks-preview/azext_aks_preview/custom.py

@@ -1160,7 +1160,8 @@ def aks_create(
     enable_upstream_kubescheduler_user_configuration=False,
     # managed gateway installation
     enable_gateway_api=False,
-    enable_hosted_system=False
+    enable_hosted_system=False,
+    control_plane_scaling_size=None,
 ):
     # DO NOT MOVE: get all the original parameters and save them as a dictionary
     raw_parameters = locals()
@@ -1404,6 +1405,7 @@ def aks_update(
     # application load balancer
     enable_application_load_balancer=False,
     disable_application_load_balancer=False,
+    control_plane_scaling_size=None,
 ):
     # DO NOT MOVE: get all the original parameters and save them as a dictionary
     raw_parameters = locals()

src/aks-preview/azext_aks_preview/managed_cluster_decorator.py

@@ -3767,6 +3767,28 @@ def get_enable_hosted_system(self) -> bool:
             raise RequiredArgumentMissingError('"--enable-hosted-system" requires "--sku automatic".')
         return enable_hosted_system
 
+    def get_control_plane_scaling_size(self) -> Union[str, None]:
+        """Obtain the value of control_plane_scaling_size.
+
+        :return: str or None
+        """
+        # try to read from raw parameters first
+        control_plane_scaling_size = self.raw_param.get("control_plane_scaling_size")
+
+        # for update scenarios, read from existing mc if raw parameter not set
+        if (
+            control_plane_scaling_size is None and
+            self.decorator_mode == DecoratorMode.UPDATE
+        ):
+            if (
+                self.mc and
+                self.mc.control_plane_scaling_profile is not None and
+                self.mc.control_plane_scaling_profile.scaling_size is not None
+            ):
+                control_plane_scaling_size = self.mc.control_plane_scaling_profile.scaling_size
+
+        return control_plane_scaling_size
+
 
 # pylint: disable=too-many-public-methods
 class AKSPreviewManagedClusterCreateDecorator(AKSManagedClusterCreateDecorator):
@@ -4796,6 +4818,23 @@ def set_up_bootstrap_profile(self, mc: ManagedCluster) -> ManagedCluster:
 
         return mc
 
+    def set_up_control_plane_scaling_profile(self, mc: ManagedCluster) -> ManagedCluster:
+        """Set up the control plane scaling profile for the ManagedCluster object.
+
+        :return: the ManagedCluster object
+        """
+        self._ensure_mc(mc)
+
+        control_plane_scaling_size = self.context.get_control_plane_scaling_size()
+        if control_plane_scaling_size is not None:
+            mc.control_plane_scaling_profile = (
+                self.models.ManagedClusterControlPlaneScalingProfile(  # pylint: disable=no-member
+                    scaling_size=control_plane_scaling_size,
+                )
+            )
+
+        return mc
+
     def set_up_static_egress_gateway(self, mc: ManagedCluster) -> ManagedCluster:
         self._ensure_mc(mc)
 
@@ -4918,6 +4957,8 @@ def construct_mc_profile_preview(self, bypass_restore_defaults: bool = False) ->
         mc = self.set_up_agentpool_profile_ssh_access(mc)
         # set up bootstrap profile
         mc = self.set_up_bootstrap_profile(mc)
+        # set up control plane scaling profile
+        mc = self.set_up_control_plane_scaling_profile(mc)
         # set up static egress gateway profile
         mc = self.set_up_static_egress_gateway(mc)
         # set up imds restriction(a property in network profile)
@@ -7102,6 +7143,23 @@ def update_bootstrap_profile(self, mc: ManagedCluster) -> ManagedCluster:
 
         return mc
 
+    def update_control_plane_scaling_profile(self, mc: ManagedCluster) -> ManagedCluster:
+        """Update the control plane scaling profile for the ManagedCluster object.
+
+        :return: the ManagedCluster object
+        """
+        self._ensure_mc(mc)
+
+        control_plane_scaling_size = self.context.get_control_plane_scaling_size()
+        if control_plane_scaling_size is not None:
+            if mc.control_plane_scaling_profile is None:
+                mc.control_plane_scaling_profile = (
+                    self.models.ManagedClusterControlPlaneScalingProfile()  # pylint: disable=no-member
+                )
+            mc.control_plane_scaling_profile.scaling_size = control_plane_scaling_size
+
+        return mc
+
     def update_static_egress_gateway(self, mc: ManagedCluster) -> ManagedCluster:
         """Update static egress gateway addon for the ManagedCluster object.
 
@@ -7550,6 +7608,8 @@ def update_mc_profile_preview(self) -> ManagedCluster:
         mc = self.update_node_provisioning_profile(mc)
         # update bootstrap profile
         mc = self.update_bootstrap_profile(mc)
+        # update control plane scaling profile
+        mc = self.update_control_plane_scaling_profile(mc)
         # update static egress gateway
         mc = self.update_static_egress_gateway(mc)
         # update imds restriction

src/aks-preview/azext_aks_preview/tests/latest/test_aks_commands.py

@@ -9685,6 +9685,53 @@ def test_aks_create_with_windows_gmsa(
             checks=[self.is_empty()],
         )
 
+    @AllowLargeResponse()
+    @AKSCustomResourceGroupPreparer(
+        random_name_length=17,
+        name_prefix="clitest",
+        location="centraluseuap",
+    )
+    def test_aks_create_with_control_plane_scaling_profile(
+        self, resource_group, resource_group_location
+    ):
+        # reset the count so in replay mode the random names will start with 0
+        self.test_resources_count = 0
+        # kwargs for string formatting
+        aks_name = self.create_random_name("cliakstest", 16)
+        self.kwargs.update(
+            {
+                "resource_group": resource_group,
+                "name": aks_name,
+                "location": resource_group_location,
+                "resource_type": "Microsoft.ContainerService/ManagedClusters",
+                "ssh_key_value": self.generate_ssh_keys(),
+            }
+        )
+
+        # create with control plane scaling size H4
+        create_cmd = (
+            "aks create --resource-group={resource_group} --name={name} --location={location} "
+            "--network-plugin azure --network-plugin-mode overlay --pod-cidr 10.244.0.0/16 "
+            "--ssh-key-value={ssh_key_value} --node-count 1 "
+            "--control-plane-scaling-size H4 "
+            "--aks-custom-headers AKSHTTPCustomFeatures=Microsoft.ContainerService/ControlPlaneScalingProfilePreview"
+        )
+        self.cmd(
+            create_cmd,
+            checks=[
+                self.check("provisioningState", "Succeeded"),
+                self.check("networkProfile.networkPlugin", "azure"),
+                self.check("networkProfile.networkPluginMode", "overlay"),
+                self.check("controlPlaneScalingProfile.scalingSize", "H4"),
+            ],
+        )
+
+        # delete
+        self.cmd(
+            "aks delete -g {resource_group} -n {name} --yes --no-wait",
+            checks=[self.is_empty()],
+        )
+
     @AllowLargeResponse()
     @AKSCustomResourceGroupPreparer(
         random_name_length=17,