Merge pull request #287459 from kgremban/m2-bbscrub

pre-bugbash docs review

Author: JamesJBarnett

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/23/2024
+ms.date: 09/26/2024
 
 #CustomerIntent: As an OT professional, I want to deploy Azure IoT Operations to a Kubernetes cluster.
 ---
@@ -83,12 +83,6 @@ The Azure portal deployment experience is a helper tool that generates a deploym
 
    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.
 
-   > [!NOTE]
-   > If you're using GitHub Codespaces in a browser, `az login` returns a localhost error in the browser window after logging in. To fix, either:
-   >
-   > * Open the codespace in VS Code desktop, and then run `az login` in the terminal. This opens a browser window where you can log in to Azure.
-   > * Or, after you get the localhost error on the browser, copy the URL from the browser and use `curl <URL>` in a new terminal tab. You should see a JSON response with the message "You have logged into Microsoft Azure!".
-
 ### Create a storage account and schema registry
 
 Azure IoT Operations requires a schema registry on your cluster. Schema registry requires an Azure storage account so that it can synchronize schema information between cloud and edge.
@@ -105,11 +99,14 @@ Azure IoT Operations requires a schema registry on your cluster. Schema registry
    az iot ops schema registry create --name <NEW_SCHEMA_REGISTRY_NAME> --resource-group <RESOURCE_GROUP> --registry-namespace <NEW_SCHEMA_REGISTRY_NAMESPACE> --sa-resource-id $(az storage account show --name <STORAGE_ACCOUNT_NAME> --resource-group <RESOURCE_GROUP> -o tsv --query id)
    ```
 
+   >[!NOTE]
+   >This command requires that you have role assignment write permissions because it assigns a role to give schema registry access to the storage account. By default, the role is the built-in **Storage Blob Data Contributor** role, or you can create a custom role with restricted permissions to assign instead.
+
    Use the optional parameters to customize your schema registry, including:
 
    | Optional parameter | Value | Description |
    | --------- | ----- | ----------- |
-   | `--custom-role-id` | Role definition, ID | The schema registry needs read/write access to the storage account. Provide a custom role ID to use instead of the default **Storage Blob Data Contributor**. Format: `/subscriptions/<SUBSCRIPTION_ID>/providers/Microsoft.Authorization/roleDefinitions/<ROLE_ID>`. |
+   | `--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**. |
 
 ### Deploy Azure IoT Operations
@@ -152,19 +149,14 @@ 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.
 
    ```azurecli
    az keyvault create --resource-group "<RESOURCE_GROUP>" --location "<LOCATION>" --name "<KEYVAULT_NAME>" --enable-rbac-authorization 
    ```
 
-1. Give yourself **Secrets officer** permissions on the vault, so that you can create secrets:
-
-   ```azurecli
-   az role assignment create --role "Key Vault Secrets Officer" --assignee <CURRENT_USER> --scope /subscriptions/<SUBSCRIPTION>/resourcegroups/<RESOURCE_GROUP>/providers/Microsoft.KeyVault/vaults/<KEYVAULT_NAME> 
-   ```
-
-1. Create a user-assigned managed identity that has access to the Azure Key Vault.
+1. Create a user-assigned managed identity that will be assigned access to the Azure Key Vault.
 
    ```azurecli
    az identity create --name "<USER_ASSIGNED_IDENTITY_NAME>" --resource-group "<RESOURCE_GROUP>" --location "<LOCATION>" --subscription "<SUBSCRIPTION>" 

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

@@ -15,10 +15,17 @@ ms.date: 09/24/2024
 
 Azure IoT Operations uses Azure Key Vault as the managed vault solution on the cloud, and uses [Azure Secret Store](#manage-secrets-for-your-azure-iot-operations-preview-deployment) to sync the secrets down from the cloud and store them on the edge as Kubernetes secrets.
 
+>[!NOTE]
+>**Special instructions for AIO Internal Bugbash**:
+>
+>Refer to [Test secrets and user-assigned managed identity](https://msazure.visualstudio.com/One/_wiki/wikis/AIO.wiki/710296/Test-Secrets-and-User-Assigned-Managed-Identity) for instructions on how to test secrets with the PLC simulator.
+
 ## Prerequisites
 
 * An Azure IoT Operations instance deployed with secure settings. If you deployed Azure IoT Operations with test settings and now want to use secrets, you need to first [enable secure settings](./howto-enable-secure-settings.md).
 
+* Creating secrets in the key vault requires **Secrets officer** permissions at the resource level. For information about assigning roles to users, see [Steps to assign an Azure role](../../role-based-access-control/role-assignments-steps.md).
+
 ## Add and use secrets
 
 Secrets management for Azure IoT Operations uses Azure Secret Store to sync the secrets from an Azure Key Vault and store them on the edge as Kubernetes secrets. When you enabled secure settings during deployment, you selected an Azure Key Vault for secret management. It is in this Key Vault where all secrets to be used within Azure IoT Operations are stored. 
@@ -34,8 +41,6 @@ Secrets are used in asset endpoints and dataflow endpoints for authentication. I
 
 - **Add from Azure Key Vault**: synchronizes an existing secret in key vault down to the edge if it wasn't synchronized before. Selecting this option shows you the list of secret references in the selected key vault. Use this option if you created the secret in the key vault beforehand.  
 
-- **Add synced secret**: uses an existing and synchronized to the edge secret for the component. Selecting this option shows you the list of already synchronized secrets. Use this option if you previously created and synchronized the secret but didn't use it in an Azure IoT Operations component.
-
 ## Manage Synced Secrets
 
 You can use **Manage Secrets** for asset endpoints and dataflow endpoints to view or delete synced secrets. 

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: 08/26/2024
+ms.date: 09/26/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.
 ---
@@ -43,8 +43,8 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
   > 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.0a10-py3-none-any.whl -f ./azure_iot_ops-0.7.0a10-py3-none-any.whl
-  >az extension add --upgrade --source ./azure_iot_ops-0.7.0a10-py3-none-any.whl
+  >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
   >```
 
   ```bash
@@ -69,8 +69,8 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
    >
    > 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.0a10-py3-none-any.whl -f ./azure_iot_ops-0.7.0a10-py3-none-any.whl
-   >    az extension add --upgrade --source ./azure_iot_ops-0.7.0a10-py3-none-any.whl
+   >    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:
@@ -84,19 +84,11 @@ To prepare your Azure Arc-enabled Kubernetes cluster, you need:
   * [Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements).
   * [K3s requirements](https://docs.k3s.io/installation/requirements).
 
-### [Codespaces](#tab/codespaces)
-
-* 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.
-
-* A [GitHub](https://github.com) account.
-
-* Visual Studio Code installed on your development machine. For more information, see [Download Visual Studio Code](https://code.visualstudio.com/download).
-
 ---
 
 ## Create a cluster
 
-This section provides steps to create clusters in validated environments on Linux and Windows as well as GitHub Codespaces in the cloud.
+This section provides steps to create clusters in validated environments on Linux and Windows.
 
 ### [AKS Edge Essentials](#tab/aks-edge-essentials)
 
@@ -164,38 +156,17 @@ By default, Azure Kubernetes Service Edge Essentials clusters support Azure Cont
 
 ### [Ubuntu](#tab/ubuntu)
 
-Install dependencies on Ubuntu:
-
-1. Run the helm installation script:
-
-  ```bash
-  curl -fsSL -o get_helm.sh https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 
-  chmod 700 get_helm.sh 
-  ./get_helm.sh 
-  helm version 
-   ```
-
-Install dependencies on Ubuntu:
-
-1. Run the kubectl installation script:
-
-  ```bash
-  curl -LO “https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl” 
-  curl -LO “https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl.sha256” 
-  echo “$(cat kubectl.sha256) kubectl” | sha256sum --check 
-  sudo install -o root -g root -m 0755 kubectl /usr/local/bin/kubectl 
-  kubectl version --client 
-   ```
-
 To prepare a K3s Kubernetes cluster on Ubuntu:
 
-1. Run the K3s installation script:
+1. Install K3s following the instructions in the [K3s quick-start guide](https://docs.k3s.io/quick-start).
+
+1. Check to see that kubectl was installed as part of K3s. If not, follow the instructions to [Install kubectl on Linux](https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/).
 
    ```bash
-   curl -sfL https://get.k3s.io | sh -
+   kubectl version --client
    ```
 
-   For full installation information, see the [K3s quick-start guide](https://docs.k3s.io/quick-start).
+1. Follow the instructions to [Install Helm](https://helm.sh/docs/intro/install/).
 
 1. Create a K3s configuration yaml file in `.kube/config`:
 
@@ -231,36 +202,6 @@ To prepare a K3s Kubernetes cluster on Ubuntu:
 
 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. If you want to enable that option, prepare your multi-node cluster with the following steps:
 
-1. Install the required NVME over TCP module for your kernel using the following command:
-
-   ```bash
-   sudo apt install linux-modules-extra-`uname -r`
-   ```
-
-   > [!NOTE]
-   > The minimum supported Linux kernel version is 5.1. At this time, there are known issues with 6.4 and 6.2. For the latest information, refer to [Azure Container Storage release notes](/azure/azure-arc/edge-storage-accelerator/release-notes)
-
-1. On each node in your cluster, set the number of **HugePages** to 512 using the following command:
-
-   ```bash
-   HUGEPAGES_NR=512
-   echo $HUGEPAGES_NR | sudo tee /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
-   echo "vm.nr_hugepages=$HUGEPAGES_NR" | sudo tee /etc/sysctl.d/99-hugepages.conf
-   ```
-
-### [Codespaces](#tab/codespaces)
-
-> [!IMPORTANT]
-> Codespaces are easy to set up quickly and tear down later, but they're not suitable for performance evaluation or scale testing. Use GitHub Codespaces for exploration only.
-
-[!INCLUDE [prepare-codespaces](../includes/prepare-codespaces.md)]
-
-### Configure multi-node clusters for Azure Container Storage
-
-On multi-node clusters with at least three nodes, you have the option of enabling fault tolerance for storage with [Azure Container Storage (preview)](/azure/azure-arc/edge-storage-accelerator/overview) when you deploy Azure IoT Operations.
-
-*This feature isn't recommended for Codespaces because Codespaces aren't persistent.* If you want to enable fault tolerance anyways, prepare your multi-node cluster with the following steps:
-
 1. Install the required NVME over TCP module for your kernel using the following command:
 
    ```bash
@@ -320,37 +261,6 @@ To connect your cluster to Azure Arc:
 
 [!INCLUDE [connect-cluster-k3s](../includes/connect-cluster-k3s.md)]
 
-### [Codespaces](#tab/codespaces)
-
-To connect your cluster to Azure Arc:
-
-   > [!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:
-   >
-   > ``` bash
-   >    az storage blob download --auth-mode login --blob-url https://azedgecli.blob.core.windows.net/drop/azure_iot_ops-0.7.0a10-py3-none-any.whl -f ./azure_iot_ops-0.7.0a10-py3-none-any.whl
-   >    az extension add --upgrade --source ./azure_iot_ops-0.7.0a10-py3-none-any.whl
-   > ```
-
-1. In your codespace terminal, sign in to Azure CLI:
-
-   ```azurecli
-   az login
-   ```
-
-   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.
-
-   > [!TIP]
-   > If you're using the GitHub codespace environment in a browser rather than VS Code desktop, running `az login` returns a localhost error. To fix the error, either:
-   >
-   > * Open the codespace in VS Code desktop, and then return to the browser terminal and rerun `az login`.
-   > * Or, after you get the localhost error on the browser, copy the URL from the browser and run `curl "<URL>"` in a new terminal tab. You should see a JSON response with the message "You have logged into Microsoft Azure!."
-
-[!INCLUDE [connect-cluster-k3s](../includes/connect-cluster-k3s.md)]
-
 ---
 
 ## Verify your cluster

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

@@ -16,13 +16,6 @@ ms.date: 05/02/2024
 
 In this quickstart, you deploy a suite of IoT services to an Azure Arc-enabled Kubernetes cluster so that you can remotely manage your devices and workloads. Azure IoT Operations is a digital operations suite of services. This quickstart guides you through using Orchestrator to deploy these services to a Kubernetes cluster. At the end of the quickstart, you have a cluster that you can manage from the cloud that generates sample data to use in the following quickstarts.
 
-The services deployed in this quickstart include:
-
-* [MQTT broker](../manage-mqtt-broker/overview-iot-mq.md)
-* [Connector for OPC UA](../discover-manage-assets/overview-opcua-broker.md)
-* [Azure Device Registry Preview](../discover-manage-assets/overview-manage-assets.md#store-assets-as-azure-resources-in-a-centralized-registry) including a schema registry
-* [Observability](../configure-observability-monitoring/howto-configure-observability.md)
-
 The rest of the quickstarts in this end-to-end series build on this one to define sample assets, data processing pipelines, and visualizations. If you want to deploy Azure IoT Operations to a cluster such as AKS Edge Essentials in order to run your own workloads, see [Prepare your Azure Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-prepare-cluster.md?tabs=aks-edge-essentials) and [Deploy Azure IoT Operations Preview to an Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-deploy-iot-operations.md).
 
 ## Before you begin
@@ -88,8 +81,8 @@ To connect your cluster to Azure Arc:
    > 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:
    >
    > ``` bash
-   >    az storage blob download --auth-mode login --blob-url https://azedgecli.blob.core.windows.net/drop/azure_iot_ops-0.7.0a10-py3-none-any.whl -f ./azure_iot_ops-0.7.0a10-py3-none-any.whl
-   >    az extension add --upgrade --source ./azure_iot_ops-0.7.0a10-py3-none-any.whl
+   >    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
    > ```
 
 1. Register the required resource providers in your subscription: