Merge pull request #265514 from kgremban/feb6-aio

Clean cluster prereq; role permissions; list spcs

Author: prmerger-automator[bot]

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

@@ -17,8 +17,19 @@ Deploy Azure IoT Operations preview - enabled by Azure Arc to a Kubernetes clust
 
 ## Prerequisites
 
+Cloud resources: 
+
 * 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.
 
+* Azure access permissions. At a minimum, have **Contributor** permissions in your Azure subscription. Depending on the deployment method and feature flag status you select, you may also need **Microsoft/Authorization/roleAssignments/write** permissions. If you *don't* have role assignment write permissions, take the following additional steps when deploying:
+
+  * If deploying with an Azure Resource Manager template, set the `deployResourceSyncRules` parameter to `false`.
+  * If deploying with the Azure CLI, include the `--disable-rsync-rules`.
+
+* An [Azure Key Vault](../../key-vault/general/overview.md) that has the **Permission model** set to **Vault access policy**. You can check this setting in the **Access configuration** section of an existing key vault.
+
+Development resources:
+
 * Azure CLI installed on your development machine. For more information, see [How to install the Azure CLI](/cli/azure/install-azure-cli). This scenario requires Azure CLI version 2.46.0 or higher. Use `az --version` to check your version and `az upgrade` to update if necessary.
 
 * The Azure IoT Operations extension for Azure CLI. Use the following command to add the extension or update it to the latest version:
@@ -27,17 +38,20 @@ Deploy Azure IoT Operations preview - enabled by Azure Arc to a Kubernetes clust
   az extension add --upgrade --name azure-iot-ops
   ```
 
-* An Azure Arc-enabled Kubernetes cluster. If you don't have one, follow the steps in [Prepare your Azure Arc-enabled Kubernetes cluster](./howto-prepare-cluster.md?tabs=wsl-ubuntu). Using Ubuntu in Windows Subsystem for Linux (WSL) is the simplest way to get a Kubernetes cluster for testing.
+A cluster host:
+
+* An Azure Arc-enabled Kubernetes cluster. If you don't have one, follow the steps in [Prepare your Azure Arc-enabled Kubernetes cluster](./howto-prepare-cluster.md?tabs=wsl-ubuntu). 
 
-  Azure IoT Operations should work on any CNCF-conformant kubernetes cluster. Currently, Microsoft only supports K3s on Ubuntu Linux and WSL, or AKS Edge Essentials on Windows.
+  If you've already deployed Azure IoT Operations to your cluster, uninstall those resources before continuing. For more information, see [Update a deployment](#update-a-deployment).
+
+  Azure IoT Operations should work on any CNCF-conformant kubernetes cluster. Currently, Microsoft only supports K3s on Ubuntu Linux and WSL, or AKS Edge Essentials on Windows. Using Ubuntu in Windows Subsystem for Linux (WSL) is the simplest way to get a Kubernetes cluster for testing.
 
   Use the Azure IoT Operations extension for Azure CLI to verify that your cluster host is configured correctly for deployment by using the [verify-host](/cli/azure/iot/ops#az-iot-ops-verify-host) command on the cluster host:
 
   ```azurecli
   az iot ops verify-host
   ```
 
-* An [Azure Key Vault](../../key-vault/general/overview.md) that has the **Permission model** set to **Vault access policy**. You can check this setting in the **Access configuration** section of an existing key vault.
 
 ## Deploy extensions
 
@@ -128,6 +142,8 @@ az iot ops init --cluster <CLUSTER_NAME> -g <RESOURCE_GROUP> --kv-id $(az keyvau
 >[!TIP]
 >If you get an error that says *Your device is required to be managed to access your resource*, go back to the previous step and make sure that you signed in interactively.
 
+If you don't have **Microsoft.Authorization/roleAssignment/write** permissions in your Azure subscription, include the `--disable-rsync-rules` feature flag.
+
 Use optional flags to customize the `az iot ops init` command. To learn more, see [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init).
 
 #### [GitHub Actions](#tab/github)
@@ -208,6 +224,7 @@ Now, you can deploy Azure IoT Operations to your cluster.
    | `dataProcessorSecrets` | object | Pass a secret to an Azure IoT Data Processor resource. |
    | `mqSecrets` | object | Pass a secret to an Azure IoT MQ resource. |
    | `opcUaBrokerSecrets` | object | Pass a secret to an Azure OPC UA Broker resource. |
+   | `deployResourceSyncRules` | Set to `false` if you don't have **Microsoft.Authorization/roleAssignment/write** permissions in your Azure subscription. |
 
 1. Save your changes to the parameters file.
 
@@ -269,6 +286,12 @@ To view your cluster on the Azure portal, use the following steps:
 
    There's also an extension called **akvsecretsprovider**. This extension is the secrets provider that you configured and installed on your cluster with the `az iot ops init` command. You might delete and reinstall the Azure IoT Operations components during testing, but keep the secrets provider extension on your cluster.
 
+## Update a deployment
+
+Currently, there is no support for updating an existing Azure IoT Operations deployment. Instead, start with a clean cluster for a new deployment.
+
+If you want to delete the Azure IoT Operations deployment on your cluster so that you can redeploy to it, navigate to your cluster on the Azure portal. Select the extensions of the type **microsoft.iotoperations.x** and **microsoft.deviceregistry.assets**, then select **Uninstall**. Keep the secrets provider on your cluster, as that is a prerequisite for deployment and not included in a fresh deployment. 
+
 ## Next steps
 
 If your components need to connect to Azure endpoints like SQL or Fabric, learn how to [Manage secrets for your Azure IoT Operations deployment](./howto-manage-secrets.md).

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

@@ -132,7 +132,11 @@ Once you have the secret store set up on your cluster, you can create and add Az
 
 1. Create your secret in Key Vault with whatever name and value you need. You can create a secret by using the [Azure portal](https://portal.azure.com) or the [az keyvault secret set](/cli/azure/keyvault/secret#az-keyvault-secret-set) command.
 
-1. On your cluster, identify the secret provider class (SPC) for the component that you want to add the secret to. For example, `aio-default-spc`.
+1. On your cluster, identify the secret provider class (SPC) for the component that you want to add the secret to. For example, `aio-default-spc`. Use the following command to list all SPCs on your cluster:
+
+   ```bash
+   kubectl get secretproviderclasses -A
+   ```
 
 1. Open the file in your preferred text editor. If you use k9s, type `e` to edit.
 

articles/iot-operations/get-started/quickstart-deploy.md

@@ -36,6 +36,8 @@ Review the prerequisites based on the environment you use to host the Kubernetes
 
 For this quickstart, we recommend GitHub Codespaces as a quick way to get started in a virtual environment without installing new tools. Or, use Azure Kubernetes Service (AKS) Edge Essentials to create a cluster on Windows devices or K3s on Ubuntu Linux devices.
 
+As part of this quickstart, you create a cluster in either Codespaces, AKS Edge Essentias, or Linux. If you want to reuse a cluster that you've deployed Azure IoT Operations to before, refer to the steps in [Clean up resources](#clean-up-resources) to uninstall Azure IoT Operations before continuing.
+
 # [Virtual](#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.
@@ -87,6 +89,8 @@ Azure IoT Operations is a suite of data services that run on Kubernetes clusters
 
 Azure IoT Operations should work on any Kubernetes cluster that conforms to the Cloud Native Computing Foundation (CNCF) standards. For this quickstart, use GitHub Codespaces, AKS Edge Essentials on Windows, or K3s on Ubuntu Linux.
 
+In this section, you create a new cluster and connect it to Azure Arc. If you want to reuse a cluster that you've deployed Azure IoT Operations to before, refer to the steps in [Clean up resources](#clean-up-resources) to uninstall Azure IoT Operations before continuing.
+
 # [Virtual](#tab/codespaces)
 
 [!INCLUDE [prepare-codespaces](../includes/prepare-codespaces.md)]

articles/iot-operations/troubleshoot/troubleshoot.md

@@ -25,6 +25,15 @@ For general deployment and configuration troubleshooting, you can use the Azure
 
 - Use [az iot ops support create-bundle](/cli/azure/iot/ops/support#az-iot-ops-support-create-bundle) to collect logs and traces to help you diagnose problems. The *support create-bundle* command creates a standard support bundle zip archive you can review or provide to Microsoft Support.
 
+### Linked authorization failed error
+
+If your deployment fails with the `"code":"LinkedAuthorizationFailed"` error, it means that you don't have **Microsoft.Authorization/roleAssignments/write** permissions on the resource group that contains your cluster.
+
+To resolve this issue, either request the required permissions or make the following adjustments to your deployment steps:
+
+  * If deploying with an Azure Resource Manager template, set the `deployResourceSyncRules` parameter to `false`.
+  * If deploying with the Azure CLI, include the `--disable-rsync-rules` flag with the [az iot ops init](/cli/azure/iot/ops#az-iot-ops-init) command.
+
 ## Data Processor pipeline deployment status is failed
 
 Your Data Processor pipeline deployment status is showing as **Failed**.