Merge branch 'main' of https://github.com/MicrosoftDocs/azure-docs-pr into erfreshness3

Author: duongau

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

@@ -5,29 +5,92 @@ author: kgremban
 ms.author: kgremban
 ms.topic: how-to
 ms.custom: devx-track-azurecli
-ms.date: 11/11/2024
+ms.date: 01/31/2025
 
 #CustomerIntent: As an OT professional, I want to manage Azure IoT Operations instances.
 ---
 
-# Upgrade or rollback between versions
+# Upgrade or downgrade 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.
+Upgrade an Azure IoT Operations deployment 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.
+## Prerequisites
+
+* Azure CLI. This scenario requires Azure CLI version 2.64.0 or higher. Use `az --version` to check your version and `az upgrade` to update if necessary. For more information, see [Get started with Azure CLI](/cli/azure/get-started-with-azure-cli).
+
+* The Azure IoT Operations extension for Azure CLI. Use the following command to add the extension or update it to the latest version:
+
+  ```azurecli
+  az extension add --upgrade --name azure-iot-ops
+  ```
 
 ## 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:
+Upgrade and rollback are supported between N+3 or N-3 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    |
+| Version | Upgrade range | Downgrade range |
+| ------- | ------------- | --------------- |
+| 1.0.0   | 1.0.1 through 1.3.x | None      |
+| 1.1.0   | 1.1.1 through 1.4.x | 1.0.x     |
+| 1.4.4   | 1.4.5 through 1.7.x | 1.1.x through 1.4.3 |
 
 ## 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.
+
+### [Azure portal](#tab/portal)
+
+If your Azure IoT Operations deployment is eligible for an upgrade, the Azure portal displays an **Upgrade** option. If you don't see the option to upgrade, then your deployment is on the latest version.
+
+1. In the [Azure portal](https://portal.azure.com), navigate to your Azure IoT Operations instance.
+1. Select **Upgrade** on the **Overview** page of your instance.
+
+   :::image type="content" source="./media/howto-upgrade/instance-upgrade.png" alt-text="Screenshot that shows the upgrade button enabled in the Azure portal.":::
+
+1. The portal presents the Azure CLI command to upgrade your instance, prepopulated with your subscription, resource group, and instance details. Select the copy icon next to the CLI command.
+
+1. Run the copied `az iot ops upgrade` command in any environment where you have the Azure CLI installed.
+
+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.
+
+### [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.
+
+```azurecli
+az iot ops upgrade --resource-group <RESOURCE_GROUP_NAME> --name <INSTANCE_NAME>
+```
+
+The CLI outputs a table of the components, if any, that have available upgrades. Enter `Y` to continue with the upgrade.
+
+To upgrade to a specific version of a component, specify the version number in the parameters. For example:
+
+```azurecli
+az iot ops upgrade --resource-group <RESOURCE_GROUP_NAME> --name <INSTANCE_NAME> --acs-version 2.2.3
+```
+
+You can find the supported component versions and release train information in the **azure-iot-operations-enablement.json** file included in any given [Azure IoT Operations release](https://github.com/Azure/azure-iot-operations/releases).
+
+---
+
+## Downgrade
+
+### [Azure portal](#tab/portal)
+
+The Azure portal doesn't offer a version downgrade option. Instead, use the Azure CLI.
+
+### [Azure CLI](#tab/cli)
+
+Use the [az iot ops upgrade](/cli/azure/iot/ops#az-iot-ops-upgrade) command to roll back an existing Azure IoT Operations instance to a previous version.
+
+In the upgrade command, you can specify a component version up to three minor versions older that the latest.
+
+You can find the supported component versions and release train information in the **azure-iot-operations-enablement.json** file included in any given [Azure IoT Operations release](https://github.com/Azure/azure-iot-operations/releases).
+
+---

articles/iot-operations/deploy-iot-ops/media/howto-upgrade/instance-upgrade.png

@@ -5,7 +5,7 @@ author: kgremban
 ms.author: kgremban
 ms.topic: quickstart
 ms.custom: ignite-2023, devx-track-azurecli
-ms.date: 10/22/2024
+ms.date: 01/30/2025
 
 #CustomerIntent: As a < type of user >, I want < what? > so that < why? >.
 ---
@@ -166,8 +166,8 @@ Run the following CLI commands in your Codespaces terminal.
    | Placeholder | Value |
    | ----------- | ----- |
    | <STORAGE_ACCOUNT_NAME> | A name for your storage account. Storage account names must be between 3 and 24 characters in length and only contain numbers and lowercase letters. |
-   | <SCHEMA_REGISTRY_NAME> | A name for your schema registry. |
-   | <SCHEMA_REGISTRY_NAMESPACE> | A name for your schema registry namespace. The namespace uniquely identifies a schema registry within a tenant. |
+   | <SCHEMA_REGISTRY_NAME> | A name for your schema registry. Schema registry names can only contain numbers, lowercase letters, and hyphens. |
+   | <SCHEMA_REGISTRY_NAMESPACE> | A name for your schema registry namespace. The namespace uniquely identifies a schema registry within a tenant. Schema registry namespace names can only contain numbers, lowercase letters, and hyphens. |
 
    ```azurecli
    STORAGE_ACCOUNT=<STORAGE_ACCOUNT_NAME>

articles/iot-operations/get-started-end-to-end-sample/quickstart-deploy.md

@@ -23,7 +23,7 @@ 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
+      - name: Upgrade versions
         href: deploy-iot-ops/howto-upgrade.md
       - name: Enable secure settings
         href: deploy-iot-ops/howto-enable-secure-settings.md

articles/iot-operations/toc.yml

@@ -27,6 +27,8 @@ This article lists the known issues for Azure IoT Operations.
 
 - If you deploy Azure IoT Operations in GitHub Codespaces, shutting down and restarting the Codespace causes a `This codespace is currently running in recovery mode due to a configuration error.` issue. Currently, there's no workaround for the issue. If you need a cluster that supports shutting down and restarting, choose one of the options in [Prepare your Azure Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-prepare-cluster.md).
 
+- Downgrading the Azure Container Storage extension from 2.2.3 to 2.2.2 causes a logging loop that leads to high CPU usage warnings. To resolve, upgrade the extension back to 2.2.3. For more information, see [Upgrade or downgrade between versions](../deploy-iot-ops/howto-upgrade.md).
+
 ## MQTT broker
 
 - MQTT broker resources created in your cluster using Kubernetes aren't visible Azure portal. This is expected because [managing Azure IoT Operations components using Kubernetes is in preview](../deploy-iot-ops/howto-manage-update-uninstall.md#preview-manage-components-using-kubernetes-deployment-manifests), and synchronizing resources from the edge to the cloud isn't currently supported.

articles/iot-operations/troubleshoot/known-issues.md

@@ -41,7 +41,8 @@ You can select one of the three possible virtual hub routing preference configur
 
 * **AS Path**
 
-   1. Prefer routes with the shortest BGP AS-Path length irrespective of the source of the route advertisements. Note: In vWANs with multiple remote virtual hubs, if there's a tie between remote ExpressRoute routes and remote site-to-site VPN routes, remote site-to-site VPN routes will be preferred.
+   1. Prefer routes with the shortest BGP AS-Path length irrespective of the source of the route advertisements.
+      * Note: In vWANs with multiple remote virtual hubs, remote ExpressRoute routes will be selected last. This behavior is true regardless of AS-Path length.
 
    1. Prefer routes from local virtual hub connections over routes learned from remote virtual hub.
    1. If there are routes from both ExpressRoute and Site-to-site VPN connections:

articles/virtual-wan/about-virtual-hub-routing-preference.md

@@ -10,32 +10,23 @@
  ms.custom: include file
 ---
 
-The following tables provide an overview of the different types of gateways, their respective limitations, and their expected performance metrics. These numbers are derived from the following testing conditions and represent the maximum support limits. Actual performance might vary, depending on how closely traffic replicates these testing conditions.
+The following tables provide an overview of the different types of gateways, their respective limitations, and their expected performance metrics.
 
-#### Testing conditions
 
-| Gateway SKU | Traffic sent from on-premises | Number of routes advertised by gateway | Number of routes learned by gateway |
-|--|--|--|--|
-| **Standard/ERGw1Az** | 1 Gbps | 500 | 4,000 |
-| **High Performance/ERGw2Az** | 2 Gbps | 500 | 9,500 |
-| **Ultra Performance/ErGw3Az** | 10 Gbps | 500 | 9,500 |
-| **ErGwScale (per scale unit)** | 1 Gbps | 500 | 4,000 |
-
-> [!NOTE]
-> ExpressRoute can facilitate up to 11,000 routes that span virtual network address spaces, on-premises networks, and any relevant virtual network peering connections. To ensure stability of your ExpressRoute connection, refrain from advertising more than 11,000 routes to ExpressRoute.
-
-#### Performance results
+#### Maximum supported limits
 
 This table applies to both the Azure Resource Manager and classic deployment models.
 
-| Gateway SKU | Megabits per second | Packets per second | Supported number of VMs in the virtual network <sup>1</sup> | Flow count limit |
-|--|--|--|--|--|
-| **Standard/ERGw1Az** | 1,000 | 100,000 | 2,000 | 200,000 |
-| **High Performance/ERGw2Az** | 2,000 | 200,000 | 4,500 | 400,000 |
-| **Ultra Performance/ErGw3Az** | 10,000 | 1,000,000 | 11,000 | 1,000,000 |
-| **ErGwScale (per scale unit)** | 1,000 | 100,000 | 2,000 | 100,000 per scale unit |
+| Gateway SKU | Megabits per second | Packets per second | Supported number of VMs in the virtual network <sup>1</sup> | Flow count limit | Number of routes learned by gateway |
+|--|--|--|--|--|--|
+| **Standard/ERGw1Az** | 1,000 | 100,000 | 2,000 | 200,000 | 4,000 |
+| **High Performance/ERGw2Az** | 2,000 | 200,000 | 4,500 | 400,000 | 9,500 |
+| **Ultra Performance/ErGw3Az** | 10,000 | 1,000,000 | 11,000 | 1,000,000 | 9,500 |
+| **ErGwScale (per scale unit 1-40)** | 1,000 per scale unit | 100,000 per scale unit | 2,000 per scale unit | 100,000 per scale unit | 60,000 total per gateway
 
 <sup>1</sup> The values in the table are estimates and vary depending on the CPU utilization of the gateway. If the CPU utilization is high and the number of supported VMs is exceeded, the gateway will start to drop packets.
+> [!NOTE]
+> ExpressRoute can facilitate up to 11,000 routes that span virtual network address spaces, on-premises networks, and any relevant virtual network peering connections. To ensure stability of your ExpressRoute connection, refrain from advertising more than 11,000 routes to ExpressRoute. The maximum number of routes advertised by gateway is 1,000 routes.
 
 > [!IMPORTANT]
 > * Application performance depends on multiple factors, such as end-to-end latency and the number of traffic flows that the application opens. The numbers in the table represent the upper limit that the application can theoretically achieve in an ideal environment. Additionally, we perform routine host and OS maintenance on the ExpressRoute virtual network gateway, to maintain reliability of the service. During a maintenance period, the control plane and data path capacity of the gateway is reduced.