Merge pull request #290387 from kgremban/ga-upgrade

New: upgrade/rollback

Author: v-dirichards

articles/iot-operations/deploy-iot-ops/concept-production-guidelines.md

@@ -31,7 +31,7 @@ Create an Arc-enabled K3s cluster that meets the system requirements.
 * [Configure the cluster](./howto-prepare-cluster.md) according to documentation.
 * If you expect intermittent connectivity for your cluster, ensure that you've allocated enough disk space to the cluster cache data and messages while the [cluster is offline](../overview-iot-operations.md#offline-support).
 * If possible, have a second cluster as a staging area for testing new changes before deploying to the primary production cluster.
-* [Turn off auto-upgrade for Azure Arc](/azure/azure-arc/kubernetes/agent-upgrade#toggle-automatic-upgrade-on-or-off-when-connecting-a-cluster-to-azure-arc) to have complete control over when new updates are applied to your cluster.
+* [Turn off auto-upgrade for Azure Arc](/azure/azure-arc/kubernetes/agent-upgrade#toggle-automatic-upgrade-on-or-off-when-connecting-a-cluster-to-azure-arc) to have complete control over when new updates are applied to your cluster. Instead, [manually upgrade agents](/azure/azure-arc/kubernetes/agent-upgrade#manually-upgrade-agents) as needed.
 * *For multi-node clusters*: [Configure clusters with Edge Volumes](./howto-prepare-cluster.md#configure-multi-node-clusters-for-azure-container-storage) to prepare for enabling fault tolerance during deployment.
 
 ### Security
@@ -64,7 +64,7 @@ In the Azure portal deployment wizard, the broker resource is set up in the **Co
 
   | Setting | Single node | Multi node |
   | ------- | ----------- | ---------- |
-  | **frontendReplicas** | 2 | 5 |
+  | **frontendReplicas** | 1 | 5 |
   | **frontendWorkers** | 4 | 8 |
   | **backendRedundancyFactor** | 2 | 2 |
   | **backendWorkers** | 1 | 4 |

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

@@ -48,7 +48,7 @@ A cluster host:
 
 * Have an Azure Arc-enabled Kubernetes cluster with the custom location and workload identity features enabled. If you don't have one, follow the steps in [Prepare your Azure Arc-enabled Kubernetes cluster](./howto-prepare-cluster.md).
 
-  If you deployed Azure IoT Operations to your cluster previously, uninstall those resources before continuing. For more information, see [Update Azure IoT Operations](./howto-manage-update-uninstall.md#upgrade).
+  If you deployed Azure IoT Operations to your cluster previously, uninstall those resources before continuing. For more information, see [Update Azure IoT Operations](./howto-manage-update-uninstall.md#uninstall).
 
 * (Optional) Prepare your cluster for observability before deploying Azure IoT Operations: [Configure observability](../configure-observability-monitoring/howto-configure-observability.md).
 

articles/iot-operations/deploy-iot-ops/howto-manage-update-uninstall.md

@@ -186,39 +186,3 @@ az iot ops delete --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --inc
 ```
 
 ---
-
-## Upgrade
-
-Azure IoT Operations supports upgrading instances to new versions as they're released.
-
-You can't upgrade from a preview installation to a GA version.
-
-> [!NOTE]
-> There's a known issue with upgrading Azure IoT Operations if the MQTT broker only has one backend replica. Only upgrade Azure IoT Operations if the Broker has more than one backend replica.
-
-### [Azure portal](#tab/portal)
-
-1. In the [Azure portal](https://portal.azure.com), go to the resource group that contains your Azure IoT Operations instance, or search for and select **Azure IoT Operations**.
-
-1. Select the name of your Azure IoT Operations instance.
-
-1. On the **Overview** page of your instance, select **Upgrade**.
-
-1. The **Upgrade Azure IoT Operations** wizard prompts you to make sure you have the latest version for the Azure IoT Operations CLI extension. Copy and run the provided `az extension add` command.
-
-1. Update to the latest version of Azure IoT Operations instance. Copy and run the provided `az iot ops upgrade` command.
-
-1. Once the upgrade command completes successfully, you can exit the wizard and refresh your instance page.
-
-### [Azure CLI](#tab/cli)
-
-Use the `az iot ops upgrade` command to upgrade an Azure IoT Operations deployment. This command:
-
-* Upgrades Azure Arc extensions on your cluster.
-* Upgrades the Azure IoT Operations instance.
-
-```azurecli
-az iot ops upgrade --resource-group <RESOURCE_GROUP> --name <INSTANCE_NAME>
-```
-
----

articles/iot-operations/deploy-iot-ops/howto-prepare-cluster.md

@@ -161,9 +161,11 @@ Connect your cluster to Azure Arc so that it can be managed remotely.
 1. Use the [az connectedk8s connect](/cli/azure/connectedk8s#az-connectedk8s-connect) command to Arc-enable your Kubernetes cluster and manage it as part of your Azure resource group.
 
    ```azurecli
-   az connectedk8s connect --name <CLUSTER_NAME> -l <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID> --enable-oidc-issuer --enable-workload-identity
+   az connectedk8s connect --name <CLUSTER_NAME> -l <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID> --enable-oidc-issuer --enable-workload-identity --disable-auto-upgrade
    ```
 
+   To prevent unplanned updates to Azure Arc and the system Arc extensions that Azure IoT Operations uses as dependencies, this command disables auto-upgrade. Instead, [manually upgrade agents](/azure/azure-arc/kubernetes/agent-upgrade#manually-upgrade-agents) as needed.
+
 1. Get the cluster's issuer URL.
 
    ```azurecli
@@ -216,7 +218,9 @@ For instructions on running the script, see [Configure an AKS Edge Essentials cl
 
 ### [AKS on Azure Local](#tab/azure-local)
 
-For instructions on creating and Arc-enabling a cluster on Azure Local, see [Create Kubernetes clusters using Azure CLI](/azure/aks/hybrid/aks-create-clusters-cli).
+For instructions on creating and Arc-enabling an AKS cluster on Azure Local, see [Create Kubernetes clusters using Azure CLI](/azure/aks/hybrid/aks-create-clusters-cli).
+
+Then, once you have an Azure Arc-enabled Kubernetes cluster, you can [deploy Azure IoT Operations](howto-deploy-iot-operations.md).
 
 ---
 

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

@@ -0,0 +1,33 @@
+---
+title: Upgrade or rollback
+description: Upgrade an Azure IoT Operations instance or rollback to a previous version.
+author: kgremban
+ms.author: kgremban
+ms.topic: how-to
+ms.custom: devx-track-azurecli
+ms.date: 11/11/2024
+
+#CustomerIntent: As an OT professional, I want to manage Azure IoT Operations instances.
+---
+
+# Upgrade or rollback between versions
+
+Upgrade an Azure IoT Operations instance to a newer version or rollback to a previous version. Azure IoT Operations supports upgrade and rollback 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.
+
+>[!NOTE]
+>Currently, Azure IoT Operations has only one generally available version. Upgrade and rollback will be available once there are additional versions to upgrade or rollback between.
+
+## Understand upgrade support
+
+Upgrade and rollback are supported between N+2 or N-2 minor versions of Azure IoT Operations, or between any patch versions of the same minor version. The following table provides examples:
+
+| Current version | Upgrade range | Rollback range |
+| --------------- | ------------- | -------------- |
+| 1.0.0           | 1.0.1 through 1.2.x | None     |
+| 1.1.0           | 1.1.1 through 1.3.x | 1.0.x    |
+
+## Upgrade
+
+Azure IoT Operations supports upgrading instances to new GA versions as they're released.
+
+You can't upgrade from a preview installation to a GA version. To move to version 1.0.x, [uninstall Azure IoT Operations](howto-manage-update-uninstall.md#uninstall) and reinstall the new version.

articles/iot-operations/toc.yml

@@ -23,6 +23,8 @@ items:
         href: deploy-iot-ops/howto-deploy-iot-operations.md
       - name: Manage, update, or uninstall
         href: deploy-iot-ops/howto-manage-update-uninstall.md
+      - name: Upgrade or rollback versions
+        href: deploy-iot-ops/howto-upgrade.md
       - name: Enable secure settings
         href: deploy-iot-ops/howto-enable-secure-settings.md
       - name: Production deployment guidelines