Merge pull request #287790 from kgremban/m2-final

Jill Grant · web-flow · commit 2f4ef21b6d70 · 2024-10-02T21:21:46.000-06:00
Final M2 review of deployment docs
diff --git a/articles/iot-operations/deploy-iot-ops/howto-deploy-iot-operations.md b/articles/iot-operations/deploy-iot-ops/howto-deploy-iot-operations.md
@@ -5,7 +5,7 @@ author: kgremban
 ms.author: kgremban
 ms.topic: how-to
 ms.custom: ignite-2023, devx-track-azurecli
-ms.date: 09/26/2024
+ms.date: 10/02/2024
 
 #CustomerIntent: As an OT professional, I want to deploy Azure IoT Operations to a Kubernetes cluster.
 ---
@@ -112,7 +112,9 @@ The Azure portal deployment experience is a helper tool that generates a deploym
 
    1. Select **Select Azure Storage container**.
 
-   1. Schema registry requires an Azure Storage account with hierarchical namespace and public network access enabled. Choose a storage account from the list of hierarchical namespace-enabled accounts, or select **Create** to create one.
+   1. Choose a storage account from the list of hierarchical namespace-enabled accounts, or select **Create** to create one.
+
+      Schema registry requires an Azure Storage account with hierarchical namespace and public network access enabled. When creating a new storage account, choose a **General purpose v2** storage account type and set **Hierarchical namespace** to **Enabled**.
 
    1. Select a container in your storage account or select **Container** to create one.
 
@@ -152,13 +154,26 @@ The Azure portal deployment experience is a helper tool that generates a deploym
 
    1. If you chose to create a new schema registry on the previous tab, copy and run the `az iot ops schema registry create` command.
 
-   1. Copy and run the `az iot ops init` command.
+   1. Prepare your cluster for Azure IoT Operations deployment by deploying dependencies and foundational services, including schema registry. Copy and run the `az iot ops init` command.
+
+      >[!TIP]
+      >The `init` command only needs to be run once per cluster. If you're reusing a cluster that already had Azure IoT Operations version 0.7.0 deployed on it, you can skip this step.
+
+      This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
+
+   1. Deploy Azure IoT Operations to your cluster. Copy and run the `az iot ops create` command.
+
+      This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
 
-   1. Copy and run the `az iot ops create` command.
+   1. Enable secret sync on your Azure IoT Operations instance. Copy and run the `az iot ops secretsync enable` command. This command:
 
-   1. Copy and run the `az iot ops secretsync enable` command.
+      * Creates a federated identity credential using the user-assigned managed identity.
+      * Adds a role assignment to the user-assigned managed identity for access to the Azure Key Vault.
+      * Adds a minimum secret provider class associated with the Azure IoT Operations instance.
 
-   1. Copy and run the `az iot ops identity assign` command.
+   1. Assign a user-assigned managed identity to your Azure IoT Operations instance. Copy and run the `az iot ops identity assign` command.
+   
+      This command also creates a federated identity credential using the OIDC issuer of the indicated connected cluster and the Azure IoT Operations service account.
 
 1. Once all of the Azure CLI commands complete successfully, you can close the **Install Azure IoT Operations** wizard.
 
@@ -204,16 +219,21 @@ Azure IoT Operations requires a schema registry on your cluster. Schema registry
 
 1. Prepare your cluster with the dependencies that Azure IoT Operations requires by running [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init).
 
+   >[!TIP]
+   >The `init` command only needs to be run once per cluster. If you're reusing a cluster that already had Azure IoT Operations version 0.7.0 deployed on it, you can skip this step.
+
    ```azurecli
    az iot ops init --cluster <CLUSTER_NAME> --resource-group <RESOURCE_GROUP> --sr-resource-id <SCHEMA_REGISTRY_RESOURCE_ID>
    ```
 
+   This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
+
    Use the [optional parameters](/cli/azure/iot/ops#az-iot-ops-init-optional-parameters) to customize your cluster, including:
 
    | 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 three cluster nodes are required. |
+   | `--no-progress` |  | Disable the deployment progress display in the terminal. |
+   | `--enable-fault-tolerance` | `false`, `true` | Enable 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**. |
 
@@ -223,13 +243,16 @@ Azure IoT Operations requires a schema registry on your cluster. Schema registry
    az iot ops create --name <NEW_INSTANCE_NAME> --cluster <CLUSTER_NAME> --resource-group <RESOURCE_GROUP>
    ```
 
+   This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
+
    Use the optional parameters to customize your instance, including:
 
    | Optional parameter | Value | Description |
    | --------- | ----- | ----------- |
-   | `--no-progress` |  | Disables the deployment progress display in the terminal. |
+   | `--no-progress` |  | Disable the deployment progress display in the terminal. |
    | `--enable-rsync-rules` |  | Enable the resource sync rules on the instance to project resources from the edge to the cloud. |
    | `--add-insecure-listener` |  | Add an insecure 1883 port config to the default listener. *Not for production use*. |
+   | `--custom-location` | String | Provide a name for the custom location created for your cluster. The default value is **location-{hash(5)}**. |
    | `--broker-config-file` | Path to JSON file | Provide a configuration file for the MQTT broker. For more information, see [Advanced MQTT broker config](https://github.com/Azure/azure-iot-ops-cli-extension/wiki/Advanced-Mqtt-Broker-Config) and [Configure core MQTT broker settings](../manage-mqtt-broker/howto-configure-availability-scale.md). |
 
 Once the `create` command completes successfully, you have a working Azure IoT Operations instance running on your cluster. At this point, your instance is configured for most testing and evaluation scenarios. If you want to prepare your instance for production scenarios, continue to the next section to enable secure settings.
@@ -269,23 +292,21 @@ Azure secret requires a user-assigned managed identity with access to the Azure
 
    You will need to grant the identity permission to whichever cloud resource this will be used for. 
 
-1. Run the following command to assign the identity to the Azure IoT Operations instance. This command also created a federated identity credential using the OIDC issuer of the indicated connected cluster and the Azure IoT Operations service account.
+1. Run the following command to assign the identity to the Azure IoT Operations instance. This command also creates a federated identity credential using the OIDC issuer of the indicated connected cluster and the Azure IoT Operations service account.
 
    ```azurecli
    az iot ops identity assign --name <INSTANCE_NAME> --resource-group <RESOURCE_GROUP> --mi-user-assigned <USER_ASSIGNED_MI_RESOURCE_ID>
    ```
 
 ---
 
-While the deployment is in progress, you can watch the resources being applied to your cluster.
-
-If your terminal supports it, the `init` and `create` commands display the deployment progress.
-
+While the deployment is in progress, you can watch the resources being applied to your cluster. If your terminal supports it, the `init` and `create` commands display the deployment progress.
+<!-- 
   :::image type="content" source="./media/howto-deploy-iot-operations/view-deployment-terminal.png" alt-text="A screenshot that shows the progress of an Azure IoT Operations deployment in a terminal.":::
 
   Once the **Deploy IoT Operations** phase begins, the text in the terminal becomes a link to view the deployment progress in the Azure portal.
 
-  :::image type="content" source="./media/howto-deploy-iot-operations/view-deployment-portal.png" alt-text="A screenshot that shows the progress of an Azure IoT Operations deployment in the Azure portal." lightbox="./media/howto-deploy-iot-operations/view-deployment-portal.png":::
+  :::image type="content" source="./media/howto-deploy-iot-operations/view-deployment-portal.png" alt-text="A screenshot that shows the progress of an Azure IoT Operations deployment in the Azure portal." lightbox="./media/howto-deploy-iot-operations/view-deployment-portal.png"::: -->
 
 Otherwise, or if you choose to disable the progress interface with `--no-progress` added to the commands, you can use kubectl commands to view the pods on your cluster:
 
diff --git a/articles/iot-operations/deploy-iot-ops/howto-prepare-cluster.md b/articles/iot-operations/deploy-iot-ops/howto-prepare-cluster.md
@@ -5,7 +5,7 @@ author: kgremban
 ms.author: kgremban
 ms.topic: how-to
 ms.custom: ignite-2023, devx-track-azurecli
-ms.date: 09/26/2024
+ms.date: 10/02/2024
 
 #CustomerIntent: As an IT professional, I want prepare an Azure-Arc enabled Kubernetes cluster so that I can deploy Azure IoT Operations to it.
 ---
@@ -45,11 +45,13 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
 
 * Hardware that meets the system requirements:
 
-  * Ensure that your machine has a minimum of 10-GB available RAM, 4 available vCPUs, and 52-GB free disk space reserved for Azure IoT Operations.
+  * Ensure that your machine has a minimum of 16-GB available RAM, 8 available vCPUs, and 52-GB free disk space reserved for Azure IoT Operations.
   * [Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements).
   * [AKS Edge Essentials requirements and support matrix](/azure/aks/hybrid/aks-edge-system-requirements).
   * [AKS Edge Essentials networking guidance](/azure/aks/hybrid/aks-edge-concept-networking).
 
+* If you're going to deploy Azure IoT Operations to a multi-node cluster with fault tolerance enabled, review the hardware and storage requirements in [Prepare Linux for Edge Volumes](/azure/azure-arc/container-storage/prepare-linux-edge-volumes).
+
 ### [Ubuntu](#tab/ubuntu)
 
 * An Azure subscription. If you don't have an Azure subscription, [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
@@ -64,6 +66,7 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
 
 * Hardware that meets the system requirements:
 
+  * Ensure that your machine has a minimum of 16-GB available RAM and 8 available vCPUs reserved for Azure IoT Operations.
   * [Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements).
   * [K3s requirements](https://docs.k3s.io/installation/requirements).
 
diff --git a/articles/iot-operations/deploy-iot-ops/overview-deploy.md b/articles/iot-operations/deploy-iot-ops/overview-deploy.md
@@ -5,7 +5,7 @@ author: kgremban
 ms.author: kgremban
 ms.topic: conceptual
 ms.custom:
-ms.date: 09/10/2024
+ms.date: 10/02/2024
 
 #CustomerIntent: As an IT professional, I want to understand the components and deployment details before I start using Azure IoT Operations.
 ---
@@ -16,7 +16,7 @@ ms.date: 09/10/2024
 
 ## 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.
+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).
 
@@ -28,7 +28,7 @@ Azure IoT Operations offers two deployment modes. You can choose to deploy with
 
 A deployment with only test settings enabled:
 
-* Does not configure secrets or user-assigned managed identity capabilities.
+* Doesn't configure secrets or user-assigned managed identity capabilities.
 * 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.
 
@@ -86,6 +86,56 @@ Azure IoT Operations supports Azure Arc sites for organizing instances. A _site_
 
 For more information, see [What is Azure Arc site manager (preview)?](/azure/azure-arc/site-manager/overview)
 
+## Domain allowlist for Azure IoT Operations
+
+If you use enterprise firewalls or proxies to manage outbound traffic, add the following endpoints to your domain allowlist before deploying Azure IoT Operations Preview.
+
+Additionally, allow the Arc-enabled Kubernetes endpoints in [Azure Arc network requirements](/azure/azure-arc/network-requirements-consolidated).
+
+```text
+nw-umwatson.events.data.microsoft.com 
+dc.services.visualstudio.com 
+github.com 
+self.events.data.microsoft.com 
+mirror.enzu.com 
+ppa.launchpadcontent.net 
+msit-onelake.pbidedicated.windows.net 
+gcr.io 
+adhs.events.data.microsoft.com 
+gbl.his.arc.azure.cn 
+onegetcdn.azureedge.net 
+graph.windows.net 
+pas.windows.net 
+agentserviceapi.guestconfiguration.azure.com 
+aka.ms 
+api.segment.io 
+download.microsoft.com 
+raw.githubusercontent.com 
+go.microsoft.com 
+global.metrics.azure.eaglex.ic.gov 
+gbl.his.arc.azure.us 
+packages.microsoft.com 
+global.metrics.azure.microsoft.scloud 
+www.powershellgallery.com
+k8s.io 
+guestconfiguration.azure.com 
+ods.opinsights.azure.com 
+vault.azure.net 
+googleapis.com 
+quay.io 
+handler.control.monitor.azure.com 
+pkg.dev 
+docker.io 
+prod.hot.ingestion.msftcloudes.com 
+docker.com 
+prod.microsoftmetrics.com 
+oms.opinsights.azure.com 
+azureedge.net 
+monitoring.azure.com
+blob.core.windows.net 
+azurecr.io
+```
+
 ## Next steps
 
 [Prepare your Azure Arc-enabled Kubernetes cluster](./howto-prepare-cluster.md) to configure and Arc-enable a cluster for Azure IoT Operations.
diff --git a/articles/iot-operations/get-started-end-to-end-sample/quickstart-deploy.md b/articles/iot-operations/get-started-end-to-end-sample/quickstart-deploy.md
@@ -5,7 +5,7 @@ author: kgremban
 ms.author: kgremban
 ms.topic: quickstart
 ms.custom: ignite-2023, devx-track-azurecli
-ms.date: 05/02/2024
+ms.date: 10/02/2024
 
 #CustomerIntent: As a < type of user >, I want < what? > so that < why? >.
 ---
@@ -170,18 +170,22 @@ Run the following CLI commands in your Codespaces terminal.
 1. Initialize your cluster for Azure IoT Operations.
 
    >[!TIP]
-   >This command only needs to be run once per cluster. If you're reusing a cluster that already had Azure IoT Operations version 0.7.0 deployed on it, you can skip this step.
+   >The `init` command only needs to be run once per cluster. If you're reusing a cluster that already had Azure IoT Operations version 0.7.0 deployed on it, you can skip this step.
 
    ```azurecli
    az iot ops init --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP --sr-resource-id $(az iot ops schema registry show --name $SCHEMA_REGISTRY --resource-group $RESOURCE_GROUP -o tsv --query id)
    ```
 
+   This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
+
 1. Deploy Azure IoT Operations. This command takes several minutes to complete:
 
    ```azurecli
    az iot ops create --cluster $CLUSTER_NAME --resource-group $RESOURCE_GROUP --name ${CLUSTER_NAME}-instance
    ```
 
+   This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
+
    If 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.
 
 ## View resources in your cluster
