Merge pull request #287516 from kgremban/aio-bugs

Reviews, bugs, and acrolinx

Author: prmerger-automator[bot]

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

@@ -27,7 +27,7 @@ In this article, we discuss Azure IoT Operations *deployments* and *instances*,
 
 * An Azure IoT Operations *instance* is the parent resource that bundles the suite of services that are defined in [What is Azure IoT Operations Preview?](../overview-iot-operations.md) like MQTT broker, dataflows, and OPC UA connector.
 
-When we talk about deploying Azure IoT Operations we mean the full set of components that make up a *deployment*. Once the deployment exists, you can view, manage, and update the *instance*.
+When we talk about deploying Azure IoT Operations, we mean the full set of components that make up a *deployment*. Once the deployment exists, you can view, manage, and update the *instance*.
 
 ## Prerequisites
 
@@ -107,7 +107,7 @@ Azure IoT Operations requires a schema registry on your cluster. Schema registry
    | Optional parameter | Value | Description |
    | --------- | ----- | ----------- |
    | `--custom-role-id` | Role definition ID | Provide a custom role ID to assign to the schema registry instead of the default **Storage Blob Data Contributor** role. Format: `/subscriptions/<SUBSCRIPTION_ID>/providers/Microsoft.Authorization/roleDefinitions/<ROLE_ID>`. |
-   | `--sa-container` | string | Storage account container where schemas will be stored. If this container doesn't exist, it will be created. The default container name is **schemas**. |
+   | `--sa-container` | string | Storage account container to store schemas. If this container doesn't exist, this command creates it. The default container name is **schemas**. |
 
 ### Deploy Azure IoT Operations
 
@@ -122,8 +122,8 @@ Azure IoT Operations requires a schema registry on your cluster. Schema registry
    | Optional parameter | Value | Description |
    | --------- | ----- | ----------- |
    | `--no-progress` |  | Disables the deployment progress display in the terminal. |
-   | `--enable-fault-tolerance` | `false`, `true` | Enables fault tolerance for Azure Arc Container Storage. At least 3 cluster nodes are required. |
-   | `--ops-config` | `observability.metrics.openTelemetryCollectorAddress="<FULLNAMEOVERRIDE>.azure-iot-operations.svc.cluster.local:<GRPC_ENDPOINT>` | If you followed the optional prerequisites to prepare your cluster for observability, provide the otel collector address you configured in the otel-collector-values.yaml file.<br><br>The sample values used in [Configure observability](../configure-observability-monitoring/howto-configure-observability.md) are **fullnameOverride=aio-otel-collector** and **grpc.enpoint=4317**. |
+   | `--enable-fault-tolerance` | `false`, `true` | Enables fault tolerance for Azure Arc Container Storage. At least three cluster nodes are required. |
+   | `--ops-config` | `observability.metrics.openTelemetryCollectorAddress="<FULLNAMEOVERRIDE>.azure-iot-operations.svc.cluster.local:<GRPC_ENDPOINT>` | If you followed the optional prerequisites to prepare your cluster for observability, provide the OpenTelemetry (OTel) collector address you configured in the otel-collector-values.yaml file.<br><br>The sample values used in [Configure observability](../configure-observability-monitoring/howto-configure-observability.md) are **fullnameOverride=aio-otel-collector** and **grpc.enpoint=4317**. |
    | `--ops-config` | `observability.metrics.exportInternalSeconds=<CHECK_INTERVAL>` | If you followed the optional prerequisites to prepare your cluster for observability, provide the **check_interval** value you configured in the otel-collector-values.yaml file.<br><br>The sample value used in [Configure observability](../configure-observability-monitoring/howto-configure-observability.md) is **check_interval=60**. |
 
 1. Deploy Azure IoT Operations. This command takes several minutes to complete:
@@ -149,8 +149,7 @@ Secret management for Azure IoT Operations uses Azure Secret Store to sync the s
 
 Azure secret requires a user-assigned managed identity with access to the Azure Key Vault where secrets are stored. Dataflows also requires a user-assigned managed identity to authenticate cloud connections.
 
-
-1. If you don't have an Azure Key Vault, create one by using the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
+1. Create an Azure Key Vault if you don't have one available. Use the [az keyvault create](/cli/azure/keyvault#az-keyvault-create) command.
 
    ```azurecli
    az keyvault create --resource-group "<RESOURCE_GROUP>" --location "<LOCATION>" --name "<KEYVAULT_NAME>" --enable-rbac-authorization 
@@ -272,7 +271,7 @@ Azure secret requires a user-assigned managed identity with access to the Azure
 
    1. Copy and run the `az iot ops identity assign` command.
 
-1. Once all of the Azure CLI commands have completed successfully, you can close the **Install Azure IoT Operations** wizard.
+1. Once all of the Azure CLI commands complete successfully, you can close the **Install Azure IoT Operations** wizard.
 
 ---
 

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

@@ -14,7 +14,7 @@ ms.date: 09/26/2024
 
 [!INCLUDE [public-preview-note](../includes/public-preview-note.md)]
 
-An Azure Arc-enabled Kubernetes cluster is a prerequisite for deploying Azure IoT Operations Preview. This article describes how to prepare a cluster before you [Deploy Azure IoT Operations Preview to an Arc-enabled Kubernetes cluster](howto-deploy-iot-operations.md). This article includes guidance for both Ubuntu, Windows, and cloud environments.
+An Azure Arc-enabled Kubernetes cluster is a prerequisite for deploying Azure IoT Operations Preview. This article describes how to prepare a cluster before you [Deploy Azure IoT Operations Preview to an Arc-enabled Kubernetes cluster](howto-deploy-iot-operations.md). This article includes guidance for both Ubuntu and Windows.
 
 > [!TIP]
 > The steps in this article prepare your cluster for a secure settings deployment, which is a longer but production-ready process. If you want to deploy Azure IoT Operations quickly and run a sample workload with only test settings, see the [Quickstart: Run Azure IoT Operations Preview in Github Codespaces with K3s](../get-started-end-to-end-sample/quickstart-deploy.md) instead.
@@ -23,9 +23,11 @@ An Azure Arc-enabled Kubernetes cluster is a prerequisite for deploying Azure Io
 
 ## Prerequisites
 
-Azure IoT Operations should work on any Arc-enabled Kubernetes cluster that meets the [Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements). Currently Azure IoT Operations doesn't support ARM64 architectures.
+Azure IoT Operations should work on any Arc-enabled Kubernetes cluster that meets the [Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements). Currently Azure IoT Operations doesn't support Arm64 architectures.
 
-Microsoft supports AKS Edge Essentials for deployments on Windows and K3s for deployments on Ubuntu. For a list of specific hardware and software combinations that are tested and validated, see [Validated environments](../overview-iot-operations.md#validated-environments).
+Microsoft supports Azure Kubernetes Service (AKS) Edge Essentials for deployments on Windows and K3s for deployments on Ubuntu. For a list of specific hardware and software combinations that are tested and validated, see [Validated environments](../overview-iot-operations.md#validated-environments).
+
+If you want to deploy Azure IoT Operations to a multi-node solution, we recommend K3s on Ubuntu.
 
 To prepare your Azure Arc-enabled Kubernetes cluster, you need:
 
@@ -40,7 +42,7 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
   > [!NOTE]
   > **Special instructions for AIO Internal Bugbash**:
   >
-  > Official IoT Ops CLI releases are installed via extension index like so az extension add --upgrade --name azure-iot-ops mentioned below. However for bug bashes, we will distribute one-off release candidates intended to expose functionality to exercise internally. Use this for Bug Bash 2 on 9/27 and skip the az extension command below
+  > Official IoT Ops CLI releases are installed via extension index with the *az extension add --upgrade --name azure-iot-ops* command mentioned below. However for bug bashes, we will distribute one-off release candidates intended to expose functionality to exercise internally. Use this for Bug Bash 2 on 9/27 and skip the az extension command below
   >
   >``` bash
   >az storage blob download --auth-mode login --blob-url https://azedgecli.blob.core.windows.net/drop/azure_iot_ops-0.7.0a11-py3-none-any.whl -f ./azure_iot_ops-0.7.0a11-py3-none-any.whl
@@ -65,13 +67,14 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
 * Azure CLI version 2.64.0 or newer installed on your development machine. Use `az --version` to check your version and `az upgrade` to update if necessary. For more information, see [How to install the Azure CLI](/cli/azure/install-azure-cli).
 
 > [!NOTE]
-   > **Special instructions for AIO Internal Bugbash**: 
+   > **Special instructions for AIO Internal Bugbash**:
+   >
+   > Official IoT Ops CLI releases are installed via extension index with the *az extension add --upgrade --name azure-iot-ops* command mentioned below. However for bug bashes, we will distribute one-off release candidates intended to expose functionality to exercise internally. Use this for Bug Bash 2 on 9/27 and skip the az extension command below
    >
-   > Official IoT Ops CLI releases are installed via extension index like so az extension add --upgrade --name azure-iot-ops mentioned below. However for bug bashes, we will distribute one-off release candidates intended to expose functionality to exercise internally. Use this for Bug Bash 2 on 9/27 and skip the az extension command below
    > ``` bash
    >    az storage blob download --auth-mode login --blob-url https://azedgecli.blob.core.windows.net/drop/azure_iot_ops-0.7.0a11-py3-none-any.whl -f ./azure_iot_ops-0.7.0a11-py3-none-any.whl
    >    az extension add --upgrade --source ./azure_iot_ops-0.7.0a11-py3-none-any.whl
-   > ```    
+   > ```
 
 * The latest version of the Azure IoT Operations extension for Azure CLI. Use the following command to add the extension or update it to the latest version:
 
@@ -118,7 +121,8 @@ The [AksEdgeQuickStartForAio.ps1](https://github.com/Azure/AKS-Edge/blob/main/to
    > [!NOTE]
    > **Special instructions for AIO Internal Bugbash**:
    >
-   > The instructions below for AksEdgeQuickStartForAio.ps1 from AKS-Edge GitHub repo are  for external customer consumption and will only work after AIO 0.7 is released. 
+   > The instructions below for AksEdgeQuickStartForAio.ps1 from AKS-Edge GitHub repo are for external customer consumption and will only work after AIO 0.7 is released.
+   >
    > For internal bug bashes, use this powershell script below instead
    >
    >```powershell
@@ -152,7 +156,7 @@ The [AksEdgeQuickStartForAio.ps1](https://github.com/Azure/AKS-Edge/blob/main/to
 
 On multi-node clusters with at least three nodes, you have the option of enabling fault tolerance for storage with [Azure Container Storage enabled by Azure Arc](/azure/azure-arc/container-storage/overview) when you deploy Azure IoT Operations.
 
-By default, Azure Kubernetes Service Edge Essentials clusters support Azure Container Storage. There are no additional steps to configure AKS Edge Essential clusters for fault tolerance.
+By default, Azure Kubernetes Service Edge Essentials clusters support Azure Container Storage. There are no extra steps to configure AKS Edge Essential clusters for fault tolerance.
 
 ### [Ubuntu](#tab/ubuntu)
 
@@ -241,7 +245,7 @@ To connect your cluster to Azure Arc:
 
    If at any point you get an error that says *Your device is required to be managed to access your resource*, run `az login` again and make sure that you sign in interactively with a browser.
 
-1. Set environment variables for your Azure subscription, location, a new resource group, and the cluster name as it will show up in your resource group.
+1. Set environment variables for your Azure subscription, location, a new resource group, and the cluster name as you want it to show up in your resource group.
 
    For the list of currently supported Azure regions, see [Supported regions](../overview-iot-operations.md#supported-regions).
 

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

@@ -14,6 +14,14 @@ ms.date: 09/10/2024
 
 [!INCLUDE [public-preview-note](../includes/public-preview-note.md)]
 
+## Supported environments
+
+Azure IoT Operations should work on any Arc-enabled Kubernetes cluster that meets the [Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements). Currently Azure IoT Operations doesn't support ARM64 architectures.
+
+Microsoft supports Azure Kubernetes Service (AKS) Edge Essentials for deployments on Windows and K3s for deployments on Ubuntu. For a list of specific hardware and software combinations that are tested and validated, see [Validated environments](../overview-iot-operations.md#validated-environments).
+
+If you want to deploy Azure IoT Operations to a multi-node solution, we recommend K3s on Ubuntu.
+
 ## Choose your features
 
 Azure IoT Operations offers two deployment modes. You can choose to deploy with *test settings*, a basic subset of features that are simpler to get started with for evaluation scenarios. Or, you can choose to deploy with *secure settings*, the full feature set.
@@ -26,18 +34,17 @@ A deployment with only test settings enabled:
 * Is meant to enable the end-to-end quickstart sample for evaluation purposes, so does support the OPC PLC simulator and connect to cloud resources using system-assigned managed identity.
 * Can be upgraded to use secure settings.
 
-If you want to deploy Azure IoT Operations with test settings, follow these articles:
+To deploy Azure IoT Operations with test settings, you can use the steps in [Quickstart: Run Azure IoT Operations Preview in GitHub Codespaces](../get-started-end-to-end-sample/quickstart-deploy.md). Or, to deploy with test settings on AKS Edge Essentials or K3s on Ubuntu, follow the secure settings deployment articles and stop at the optional secure settings steps.
 
-1. Start with [Quickstart: Run Azure IoT Operations Preview in GitHub Codespaces with K3s](../get-started-end-to-end-sample/quickstart-deploy.md), then follow the rest of the articles in the end-to-end sample to test and evaluate Azure IoT Operations.
-1. If you want to upgrade your Azure IoT Operations instance to use secure settings, follow the steps in [Enable secure settings](./howto-enable-secure-settings.md).
+If you want to upgrade your Azure IoT Operations instance to use secure settings, follow the steps in [Enable secure settings](./howto-enable-secure-settings.md).
 
 ### Secure settings deployment
 
 A deployment with secure settings enabled:
 
 * Includes the steps to enable secrets and user-assignment managed identity, which are important capabilities for developing a production-ready scenario. Secrets are used whenever Azure IoT Operations components connect to a resource outside of the cluster; for example, an OPC UA server or a dataflow endpoint.
 
-If you want to deploy Azure IoT Operations with secure settings, follow these articles:
+To deploy Azure IoT Operations with secure settings, follow these articles:
 
 1. Start with [Prepare your Azure Arc-enabled Kubernetes cluster](./howto-prepare-cluster.md) to configure and Arc-enable your cluster.
 1. Then, [Deploy Azure IoT Operations Preview](./howto-deploy-iot-operations.md).

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

@@ -25,7 +25,7 @@ In this quickstart, you use the operations experience web UI to create your asse
 
 ## Prerequisites
 
-In instance of Azure IoT Operations Preview deployed in a Kubernetes cluster. The [Quickstart: Run Azure IoT Operations Preview in GitHub Codespaces with K3s](quickstart-deploy.md) provides simple instructions to deploy an Azure IoT Operations instance that you can use for the quickstarts.
+Have an instance of Azure IoT Operations Preview deployed in a Kubernetes cluster. The [Quickstart: Run Azure IoT Operations Preview in GitHub Codespaces with K3s](quickstart-deploy.md) provides simple instructions to deploy an Azure IoT Operations instance that you can use for the quickstarts.
 
 To sign in to the operations experience web UI, you need a Microsoft Entra ID account with at least contributor permissions for the resource group that contains your **Kubernetes - Azure Arc** instance. To learn more, see [Operations experience web UI](../discover-manage-assets/howto-manage-assets-remotely.md#prerequisites).