Add details of MQTT broker upgrades

Author: dominicbetts

articles/iot-operations/deploy-iot-ops/howto-upgrade.md

@@ -1,18 +1,18 @@
 ---
 title: Upgrade versions
 description: Upgrade an Azure IoT Operations instance using the Azure portal or CLI.
-author: kgremban
-ms.author: kgremban
+author: dominicbetts
+ms.author: dobett
 ms.topic: how-to
 ms.custom: devx-track-azurecli
-ms.date: 02/14/2025
+ms.date: 02/28/2025
 
 #CustomerIntent: As an OT professional, I want to manage Azure IoT Operations instances.
 ---
 
 # Upgrade versions
 
-Upgrade an Azure IoT Operations deployment to a newer version. Azure IoT Operations supports upgrade from version 1.0.x onwards. There is no support for upgrading from any preview version of Azure IoT Operations to any generally available (GA) version.
+Upgrade an Azure IoT Operations deployment to a newer version. Azure IoT Operations supports upgrade from version 1.0.x onwards. There's no support for upgrading from any preview version of Azure IoT Operations to any generally available (GA) version.
 
 ## Prerequisites
 
@@ -28,7 +28,7 @@ Upgrade an Azure IoT Operations deployment to a newer version. Azure IoT Operati
 
 You can upgrade an existing Azure IoT Operations instance to any patch of the same minor version, or to the next minor version.
 
-Azure IoT Operations doesn't support downgrading between versions. To move to an older version, uninstall Azure IoT Operations and reinstall the desired version. 
+Azure IoT Operations doesn't support downgrading between versions. To move to an older version, uninstall Azure IoT Operations and reinstall the desired version.
 
 ## Upgrade
 
@@ -64,13 +64,13 @@ If your Azure IoT Operations deployment is eligible for an upgrade, the Azure po
 
 1. After the upgrade command completes successfully, refresh your instance to see the changes.
 
-The **Version** value displayed on your instance's overview page reflects the version of the Azure IoT Operations instance. However, you may be prompted to upgrade if a required Arc extension has an available upgrade. You can tell that an upgrade was successful if the **Upgrade** option disappears from the instance overview page, even if it doesn't look like anything changed. You can check the versions of the Arc extensions for your Azure IoT Operation deployment on the **Extensions** page of your Arc-enabled cluster in the Azure portal.
+The **Version** value displayed on your instance's overview page reflects the version of the Azure IoT Operations instance. However, you might be prompted to upgrade if a required Arc extension has an available upgrade. You can tell that an upgrade was successful if the **Upgrade** option disappears from the instance overview page, even if it doesn't look like anything changed. You can check the versions of the Arc extensions for your Azure IoT Operation deployment on the **Extensions** page of your Arc-enabled cluster in the Azure portal.
 
 ### [Azure CLI](#tab/cli)
 
 Use the [az iot ops upgrade](/cli/azure/iot/ops#az-iot-ops-upgrade) command to upgrade an existing Azure IoT Operations deployment to a newer version.
 
-The upgrade command evaluates the entire Azure IoT Operations deployment for available updates, including the arc extensions that are installed in the `az iot ops init` command as well as the Azure IoT Operations instance.
+The upgrade command evaluates the entire Azure IoT Operations deployment for available updates, including the arc extensions that are installed in the `az iot ops init` command and the Azure IoT Operations instance.
 
 Use the following steps to upgrade your deployment to the latest version:
 
@@ -98,3 +98,16 @@ Refer to [IoT Operations versions](https://aka.ms/aio-versions) to find the CLI
 
 ---
 
+## MQTT broker upgrade considerations
+
+To ensure zero data loss and high availability during deployment upgrades, the MQTT broker implements rolling updates across the MQTT broker pods. The health manager pod coordinates an incremental upgrade process for the MQTT broker pods to ensure that:
+
+* Active client connections remain uninterrupted.
+* Any in-flight messages are preserved.
+* Data stored on disk is properly migrated between versions.
+
+If a failure occurs during the upgrade process, the health manager pod automatically restarts the upgrade process while ensuring no loss of data or connectivity.
+
+Rolling updates can only occur if the MQTT broker is deployed with two or more backend replicas. MQTT broker upgrades aren't supported for single-replica deployments. When you deploy Azure IoT Operations, you specify the number of backend replicas to create in the [az iot ops create](/cli/azure/iot/ops#az-iot-ops-create) command with the `--broker-backend-rf` parameter.
+
+Azure IoT Operations doesn't support downgrading between versions. To move to an older version, uninstall Azure IoT Operations and reinstall the desired version.