@@ -11,6 +11,9 @@ To release a new version, please select a new version number (usually plus 1 to
 
 Pending
 +++++++
+* `az aks create`: Add `--enable-upgrade-gate` to enable health-aware upgrade gating for the cluster.
+* `az aks update`: Add `--enable-upgrade-gate` and `--disable-upgrade-gate` to enable or disable health-aware upgrade gating for the cluster.
+* `az aks nodepool add/update`: Add `--enable-upgrade-gate` and `--disable-upgrade-gate` to enable or disable health-aware upgrade gating for the node pool.
 
 22.0.0b13
 +++++++++
 
@@ -794,7 +794,13 @@
               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'.
+        - name: --enable-upgrade-gate
+          type: bool
+          short-summary: Enable upgrade gate for the cluster. Agent pool upgrades wait for health signal validation and abort if unhealthy signals are observed.
+          long-summary: This is a cluster-wide opt-in that applies to all agent pools in the cluster; an agent pool cannot opt out of it. Health signals are HealthSignal custom resources published by monitoring components running in the cluster. Force upgrade (--enable-force-upgrade) overrides the gate. For more information, see https://aka.ms/aks/upgrade-gate.
     examples:
+        - name: Create a kubernetes cluster with upgrade gate enabled.
+          text: az aks create -g MyResourceGroup -n MyManagedCluster --enable-upgrade-gate
         - 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
         - name: Create a Kubernetes cluster with a specific version.
@@ -1120,6 +1126,14 @@
         - name: --upgrade-override-until
           type: string
           short-summary: Until when the cluster upgradeSettings overrides are effective. It needs to be in a valid date-time format that's within the next 30 days. For example, 2023-04-01T13:00:00Z. Note that if --force-upgrade is set to true and --upgrade-override-until is not set, by default it will be set to 3 days from now.
+        - name: --enable-upgrade-gate
+          type: bool
+          short-summary: Enable upgrade gate for the cluster. Agent pool upgrades wait for health signal validation and abort if unhealthy signals are observed.
+          long-summary: This is a cluster-wide opt-in that applies to all agent pools in the cluster; an agent pool cannot opt out of it. Health signals are HealthSignal custom resources published by monitoring components running in the cluster. Force upgrade (--enable-force-upgrade) overrides the gate. For more information, see https://aka.ms/aks/upgrade-gate.
+        - name: --disable-upgrade-gate
+          type: bool
+          short-summary: Disable upgrade gate for the cluster.
+          long-summary: Agent pools that explicitly enabled upgrade gate keep their own setting and remain gated.
         - name: --enable-managed-identity
           type: bool
           short-summary: Update current cluster to managed identity to manage cluster resource group.
@@ -1655,6 +1669,8 @@
     examples:
       - name: Reconcile the cluster back to its current state.
         text: az aks update -g MyResourceGroup -n MyManagedCluster
+      - name: Enable upgrade gate for a kubernetes cluster.
+        text: az aks update -g MyResourceGroup -n MyManagedCluster --enable-upgrade-gate
       - name: Enable cluster-autoscaler within node count range [1,5]
         text: az aks update --enable-cluster-autoscaler --min-count 1 --max-count 5 -g MyResourceGroup -n MyManagedCluster
       - name: Disable cluster-autoscaler for an existing cluster
@@ -2701,6 +2717,14 @@
         - name: --final-soak-duration
           type: int
           short-summary: Wait time (in minutes) after all old nodes are drained before removing them. Default is 60 minutes. Only for blue-green upgrades.
+        - name: --enable-upgrade-gate
+          type: bool
+          short-summary: Enable upgrade gate for the node pool. Upgrades of this node pool wait for health signal validation and abort if unhealthy signals are observed.
+          long-summary: When the cluster-level upgrade gate is enabled, a new node pool inherits it by default. Health signals are HealthSignal custom resources published by monitoring components running in the cluster. Force upgrade (--enable-force-upgrade) overrides the gate. For more information, see https://aka.ms/aks/upgrade-gate.
+        - name: --disable-upgrade-gate
+          type: bool
+          short-summary: Disable upgrade gate for the node pool.
+          long-summary: Rejected by the service when the cluster-level upgrade gate is enabled, since a node pool cannot opt out of a cluster-wide opt-in.
     examples:
         - name: Create a nodepool in an existing AKS cluster with ephemeral os enabled.
           text: az aks nodepool add -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster --node-osdisk-type Ephemeral --node-osdisk-size 48
@@ -2728,6 +2752,8 @@
           text: az aks nodepool add -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster --upgrade-strategy BlueGreen
         - name: Create a node pool with an ordered mixed MIG profile layout
           text: az aks nodepool add -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster --enable-managed-gpu --gpu-mig-strategy Mixed --gpu-mig-profiles MIG1g MIG2g MIG2g MIG2g
+        - name: Create a node pool with upgrade gate enabled
+          text: az aks nodepool add -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster --enable-upgrade-gate
 """
 
 helps['aks nodepool scale'] = """
@@ -2943,13 +2969,23 @@
         - name: --crg-id
           type: string
           short-summary: The Capacity Reservation Group (CRG) ID used to associate the existing nodepool with the existing Capacity Reservation Group resource.
+        - name: --enable-upgrade-gate
+          type: bool
+          short-summary: Enable upgrade gate for the node pool. Upgrades of this node pool wait for health signal validation and abort if unhealthy signals are observed.
+          long-summary: Health signals are HealthSignal custom resources published by monitoring components running in the cluster. Force upgrade (--enable-force-upgrade) overrides the gate. For more information, see https://aka.ms/aks/upgrade-gate.
+        - name: --disable-upgrade-gate
+          type: bool
+          short-summary: Disable upgrade gate for the node pool.
+          long-summary: Rejected by the service when the cluster-level upgrade gate is enabled, since a node pool cannot opt out of a cluster-wide opt-in. Use 'az aks update --disable-upgrade-gate' instead.
         - name: --node-public-ip-prefix-ids
           type: string
           short-summary: Comma-separated list of public IP prefix resource IDs for dual-stack node public IPs (IPv4 and/or IPv6).
           long-summary: At most one IPv4 and one IPv6 prefix may be specified. On an existing node pool this adds or replaces the assigned prefixes; an accepted change rolls the pool so existing nodes are recreated with the new public IPs. Requires the NodePublicIPv6PrefixPreview feature flag.
     examples:
       - name: Reconcile the nodepool back to its current state.
         text: az aks nodepool update -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster
+      - name: Enable upgrade gate for a node pool.
+        text: az aks nodepool update -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster --enable-upgrade-gate
       - name: Enable cluster-autoscaler within node count range [1,5]
         text: az aks nodepool update --enable-cluster-autoscaler --min-count 1 --max-count 5 -g MyResourceGroup -n nodepool1 --cluster-name MyManagedCluster
       - name: Disable cluster-autoscaler for an existing cluster
 
@@ -257,6 +257,7 @@
     validate_system_node_subnet_id,
     validate_node_subnet_id,
     validate_force_upgrade_disable_and_enable_parameters,
+    validate_upgrade_gate_disable_and_enable_parameters,
     validate_azure_service_mesh_revision,
     validate_artifact_streaming,
     validate_os_disk_full_caching,
@@ -1478,6 +1479,8 @@ def load_arguments(self, _):
             help='The resource ID of the prepared image specification to use for provisioning nodes in the default '
                  'node pool.'
         )
+        # upgrade gate
+        c.argument("enable_upgrade_gate", action="store_true", is_preview=True)
 
     with self.argument_context("aks update") as c:
         # managed cluster paramerters
@@ -1584,6 +1587,19 @@ def load_arguments(self, _):
             validator=validate_force_upgrade_disable_and_enable_parameters,
         )
         c.argument("upgrade_override_until", is_preview=True)
+        # upgrade gate
+        c.argument(
+            "enable_upgrade_gate",
+            action="store_true",
+            is_preview=True,
+            validator=validate_upgrade_gate_disable_and_enable_parameters,
+        )
+        c.argument(
+            "disable_upgrade_gate",
+            action="store_true",
+            is_preview=True,
+            validator=validate_upgrade_gate_disable_and_enable_parameters,
+        )
         c.argument(
             "cluster_autoscaler_profile",
             nargs="+",
@@ -2578,6 +2594,19 @@ def load_arguments(self, _):
             validator=validate_prepared_image_specification_id,
             help='The resource ID of the prepared image specification to use for provisioning nodes in the node pool.'
         )
+        # upgrade gate
+        c.argument(
+            "enable_upgrade_gate",
+            action="store_true",
+            is_preview=True,
+            validator=validate_upgrade_gate_disable_and_enable_parameters,
+        )
+        c.argument(
+            "disable_upgrade_gate",
+            action="store_true",
+            is_preview=True,
+            validator=validate_upgrade_gate_disable_and_enable_parameters,
+        )
 
     with self.argument_context("aks nodepool update") as c:
         c.argument(
@@ -2746,6 +2775,19 @@ def load_arguments(self, _):
             validator=validate_prepared_image_specification_id,
             help='The resource ID of the prepared image specification to use for provisioning nodes in the node pool.'
         )
+        # upgrade gate
+        c.argument(
+            "enable_upgrade_gate",
+            action="store_true",
+            is_preview=True,
+            validator=validate_upgrade_gate_disable_and_enable_parameters,
+        )
+        c.argument(
+            "disable_upgrade_gate",
+            action="store_true",
+            is_preview=True,
+            validator=validate_upgrade_gate_disable_and_enable_parameters,
+        )
 
     with self.argument_context("aks nodepool upgrade") as c:
         # upgrade strategy
 
@@ -859,6 +859,13 @@ def validate_force_upgrade_disable_and_enable_parameters(namespace):
         )
 
 
+def validate_upgrade_gate_disable_and_enable_parameters(namespace):
+    if namespace.disable_upgrade_gate and namespace.enable_upgrade_gate:
+        raise MutuallyExclusiveArgumentError(
+            'Providing both --disable-upgrade-gate and --enable-upgrade-gate flags is invalid'
+        )
+
+
 def sanitize_resource_id(resource_id):
     resource_id = resource_id.strip()
     if not resource_id.startswith("/"):
 
@@ -620,6 +620,30 @@ def get_max_blocked_nodes(self) -> str:
         # this parameter does not need validation
         return max_blocked_nodes
 
+    def get_upgrade_gate_enabled(self) -> Union[bool, None]:
+        """Obtain the agent pool upgrade gate setting from --enable-upgrade-gate / --disable-upgrade-gate.
+
+        Only applies to standalone agent pool commands; in managed cluster mode (e.g. `az aks create`), the flags
+        target the cluster-level setting and the server defaults new pools accordingly.
+
+        :return: True if enabling, False if disabling, None if neither flag is specified
+        """
+        if self.agentpool_decorator_mode != AgentPoolDecoratorMode.STANDALONE:
+            return None
+
+        enable_upgrade_gate = self.raw_param.get("enable_upgrade_gate")
+        disable_upgrade_gate = self.raw_param.get("disable_upgrade_gate")
+
+        if enable_upgrade_gate and disable_upgrade_gate:
+            raise MutuallyExclusiveArgumentError(
+                "Cannot specify --enable-upgrade-gate and --disable-upgrade-gate at the same time."
+            )
+        if enable_upgrade_gate:
+            return True
+        if disable_upgrade_gate:
+            return False
+        return None
+
     def get_enable_artifact_streaming(self) -> bool:
         """Obtain the value of enable_artifact_streaming.
         :return: bool
@@ -1847,6 +1871,8 @@ def construct_agentpool_profile_preview(self) -> AgentPool:
         agentpool = self.set_up_upgrade_strategy(agentpool)
         # set up blue green upgrade settings
         agentpool = self.set_up_blue_green_upgrade_settings(agentpool)
+        # set up upgrade gate settings
+        agentpool = self.set_up_upgrade_gate_settings(agentpool)
         # set up prepared image specification
         agentpool = self.set_up_prepared_image_specification(agentpool)
         # DO NOT MOVE: keep this at the bottom, restore defaults
@@ -1905,6 +1931,22 @@ def set_up_upgrade_settings(self, agentpool: AgentPool) -> AgentPool:
         agentpool.upgrade_settings = upgrade_settings
         return agentpool
 
+    def set_up_upgrade_gate_settings(self, agentpool: AgentPool) -> AgentPool:
+        """Set up upgrade gate settings for the AgentPool object.
+
+        :return: the AgentPool object
+        """
+        self._ensure_agentpool(agentpool)
+
+        upgrade_gate_enabled = self.context.get_upgrade_gate_enabled()
+        if upgrade_gate_enabled is not None:
+            if agentpool.upgrade_settings is None:
+                agentpool.upgrade_settings = self.models.AgentPoolUpgradeSettings()  # pylint: disable=no-member
+            agentpool.upgrade_settings.upgrade_gate_settings = (
+                self.models.UpgradeGateSettings(enabled=upgrade_gate_enabled)  # pylint: disable=no-member
+            )
+        return agentpool
+
     def set_up_blue_green_upgrade_settings(self, agentpool: AgentPool) -> AgentPool:
         """Set up blue-green upgrade settings for the AgentPool object.
 
@@ -2337,6 +2379,9 @@ def update_agentpool_profile_preview(self, agentpools: List[AgentPool] = None) -
         # update blue-green upgrade settings
         agentpool = self.update_blue_green_upgrade_settings(agentpool)
 
+        # update upgrade gate settings
+        agentpool = self.update_upgrade_gate_settings(agentpool)
+
         # update gpu profile
         agentpool = self.update_gpu_profile(agentpool)
 
@@ -2515,6 +2560,24 @@ def update_upgrade_settings(self, agentpool: AgentPool) -> AgentPool:
 
         return agentpool
 
+    def update_upgrade_gate_settings(self, agentpool: AgentPool) -> AgentPool:
+        """Update upgrade gate settings for the AgentPool object.
+
+        :return: the AgentPool object
+        """
+        self._ensure_agentpool(agentpool)
+
+        upgrade_gate_enabled = self.context.get_upgrade_gate_enabled()
+        if upgrade_gate_enabled is not None:
+            if agentpool.upgrade_settings is None:
+                agentpool.upgrade_settings = self.models.AgentPoolUpgradeSettings()  # pylint: disable=no-member
+            if agentpool.upgrade_settings.upgrade_gate_settings is None:
+                agentpool.upgrade_settings.upgrade_gate_settings = (
+                    self.models.UpgradeGateSettings()  # pylint: disable=no-member
+                )
+            agentpool.upgrade_settings.upgrade_gate_settings.enabled = upgrade_gate_enabled
+        return agentpool
+
     def update_blue_green_upgrade_settings(self, agentpool: AgentPool) -> AgentPool:
         """Update blue-green upgrade settings for the AgentPool object.
 
 
@@ -1487,6 +1487,8 @@ def aks_create(
     enable_on_demand_monitor=False,
     # prepared image specification
     prepared_image_specification_id=None,
+    # upgrade gate
+    enable_upgrade_gate=False,
 ):
     # DO NOT MOVE: get all the original parameters and save them as a dictionary
     raw_parameters = locals()
@@ -1555,6 +1557,9 @@ def aks_update(
     enable_force_upgrade=False,
     disable_force_upgrade=False,
     upgrade_override_until=None,
+    # upgrade gate
+    enable_upgrade_gate=False,
+    disable_upgrade_gate=False,
     cluster_autoscaler_profile=None,
     sku=None,
     tier=None,
@@ -2344,6 +2349,9 @@ def aks_agentpool_add(
     secondary_network_interfaces=None,
     # prepared image specification
     prepared_image_specification_id=None,
+    # upgrade gate
+    enable_upgrade_gate=False,
+    disable_upgrade_gate=False,
 ):
     # DO NOT MOVE: get all the original parameters and save them as a dictionary
     raw_parameters = locals()
@@ -2434,6 +2442,9 @@ def aks_agentpool_update(
     crg_id=None,
     # prepared image specification
     prepared_image_specification_id=None,
+    # upgrade gate
+    enable_upgrade_gate=False,
+    disable_upgrade_gate=False,
 ):
     # DO NOT MOVE: get all the original parameters and save them as a dictionary
     raw_parameters = locals()