adding arc-enable steps

asergaz · asergaz · commit 272c7ce405b9 · 2025-05-30T12:50:21.000+01:00
diff --git a/articles/iot-operations/develop-edge-apps/quickstart-get-started-sdks.md b/articles/iot-operations/develop-edge-apps/quickstart-get-started-sdks.md
@@ -25,7 +25,10 @@ Before you begin, prepare the following prerequisites:
 
 ## Setting up
 
-Developing with the Azure IoT Operations SDKs requires a Kubernetes cluster with Azure IoT Operations deployed. Additional configuration will allow MQTT broker to be accessed directly from the developer environment. The following development environment setup options use [k3d](https://k3d.io/#what-is-k3d) to simplify Kubernetes cluster creation. GitHub Codespaces provides the most streamlined experience and can get the development environment up and running in a couple of minutes.
+Developing with the Azure IoT Operations SDKs requires a Kubernetes cluster with Azure IoT Operations deployed. Additional configuration will allow MQTT broker to be accessed directly from the developer environment. The following development environment setup options use [K3s](https://k3s.io/) running in [K3d](https://k3d.io/) for a lightweight Kubernetes cluster. GitHub Codespaces provides the most streamlined experience and can get the development environment up and running in a couple of minutes.
+
+> [!IMPORTANT]
+> The following development environment setup options, use [K3s](https://k3s.io/) running in [K3d](https://k3d.io/) for a lightweight Kubernetes cluster, and deploys Azure IoT Operations with [test settings](../deploy-iot-ops/overview-deploy.md#test-settings-deployment). If you want to use [secure settings](../deploy-iot-ops/overview-deploy.md#secure-settings-deployment), we recommend you follow the instructions in [Prepare your Azure Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-prepare-cluster.md) to create a K3s cluster on Ubuntu and [Deploy Azure IoT Operations to an Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-deploy-iot-operations.md) to deploy with secure settings. Then proceed to [configure Azure IoT Operations for deployment](#configure-azure-iot-operations-for-deployment).
 
 ### [Codespaces](#tab/codespaces)
 
@@ -36,7 +39,8 @@ Developing with the Azure IoT Operations SDKs requires a Kubernetes cluster with
 
     [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure/iot-operations-sdks?quickstart=1&editor=vscode)
 
-1. Once the codespace is created, you will have a container with the developer tools and a local k3s cluster pre-installed.
+1. Once the codespace is created, you will have a container with the developer tools and a local k3s cluster running in k3d pre-installed.
+
 
 ### [Ubuntu](#tab/ubuntu)
 
@@ -62,6 +66,19 @@ Developing with the Azure IoT Operations SDKs requires a Kubernetes cluster with
     sudo ./tools/deployment/initialize-cluster.sh
     ```
 
+    This script does the following:
+
+    1. Installs prerequisites including:
+        1. Install k3d
+        1. Install Step CLI
+        1. Helm
+        1. AZ CLI
+        1. Step
+    1. **DELETE** the existing default k3d cluster
+    1. Deploy a new k3d cluster
+    1. Set up port forwarding for ports `1883`, `8883`, and `8884` to enable TLS
+    1. Create a local registry
+
 ### [Visual Studio Code Dev Containers](#tab/vscode-dev-containers)
 
 > [!WARNING]
@@ -133,11 +150,24 @@ Developing with the Azure IoT Operations SDKs requires a Kubernetes cluster with
     sudo ./tools/deployment/initialize-cluster.sh
     ```
 
+    This script does the following:
+
+    1. Installs prerequisites including:
+        1. Install k3d
+        1. Install Step CLI
+        1. Helm
+        1. AZ CLI
+        1. Step
+    1. **DELETE** the existing default k3d cluster
+    1. Deploy a new k3d cluster
+    1. Set up port forwarding for ports `1883`, `8883`, and `8884` to enable TLS
+    1. Create a local registry
+
 ---
 
 ## Deploy Azure IoT Operations
 
-Azure IoT Operations will be deployed on the development cluster that you created in the previous step, and then the configuration will be altered with the `configure-aio.sh` script to provide additional off-cluster access methods to streamline development:
+Azure IoT Operations will be deployed on the development cluster that you created in the previous step.
 
 ### [Codespaces](#tab/codespaces)
 
@@ -152,6 +182,8 @@ Follow the instructions in [Quickstart: Run Azure IoT Operations in GitHub Codes
 
 ### [Visual Studio Code Dev Containers](#tab/vscode-dev-containers)
 
+Open a new bash terminal in the VS Code Dev Container and do the following steps:
+
 [!INCLUDE [deploy-aio-sdks-linux](../includes/deploy-aio-sdks-linux.md)]
 
 ### [Windows Subsystem for Linux (WSL)](#tab/wsl)
@@ -160,6 +192,10 @@ Follow the instructions in [Quickstart: Run Azure IoT Operations in GitHub Codes
 
 ---
 
+## Configure Azure IoT Operations for development
+
+After Azure IoT Operations is deployed, you need to configure it for development. This includes setting up the MQTT broker and authentication methods, as well as ensuring that the necessary environment variables are set for your development environment:
+
 1. Check that Azure IoT Operations is successfully installed and **resolve any errors before continuing**:
 
     ```azurecli
@@ -189,6 +225,13 @@ Follow the instructions in [Quickstart: Run Azure IoT Operations in GitHub Codes
     ./tools/deployment/configure-aio.sh
     ```
 
+    This script does the following:
+
+    1. Setup certificate services, if missing
+    1. Create root and intermediate CAs for x509 authentication
+    1. Create the trust bundle ConfigMap for the Broker to authentication x509 clients
+    1. Configure a `BrokerListener` and `BrokerAuthentication` resources for SAT and x509 auth
+
 ## Shell configuration
 
 The samples within [Azure IoT Operations SDKs github repository](https://github.com/Azure/iot-operations-sdks) read configuration from environment variables. We have provided an `.env` file in the repository root that exports the variables used by the samples to connect to the MQTT Broker. Edit the `.env` file to set the values for your environment, or use the default values provided in the file.
diff --git a/articles/iot-operations/includes/deploy-aio-sdks-linux.md b/articles/iot-operations/includes/deploy-aio-sdks-linux.md
@@ -13,9 +13,41 @@ ms.author: sergaz
    az group create --location <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID>
    ```
 
-1. Follow the instructions in [Prepare your Azure Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-prepare-cluster.md#arc-enable-your-cluster) to arc-enable your cluster in Ubuntu. 
+1. Register the required resource providers in your subscription:
 
-1. Follow the instructions in [Deploy Azure IoT Operations to an Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-deploy-iot-operations.md) to deploy Azure IoT Operations to your cluster.
+   >[!NOTE]
+   >This step only needs to be run once per subscription. To register resource providers, you need permission to do the `/register/action` operation, which is included in subscription Contributor and Owner roles. For more information, see [Azure resource providers and types](../../azure-resource-manager/management/resource-providers-and-types.md).
 
-    > [!NOTE]
-    > You can start with test settings, and then [enable secure settings](../deploy-iot-ops/howto-enable-secure-settings.md) later.
+   ```azurecli
+   az provider register -n "Microsoft.ExtendedLocation"
+   az provider register -n "Microsoft.Kubernetes"
+   az provider register -n "Microsoft.KubernetesConfiguration"
+   az provider register -n "Microsoft.IoTOperations"
+   az provider register -n "Microsoft.DeviceRegistry"
+   az provider register -n "Microsoft.SecretSyncController"
+   ```
+
+1. Use the [az connectedk8s connect](/cli/azure/connectedk8s#az-connectedk8s-connect) command to Arc-enable your Kubernetes cluster and manage it as part of your Azure resource group.
+
+   ```azurecli
+   az connectedk8s connect --name <CLUSTER_NAME> -l <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID> --disable-auto-upgrade
+   ```
+
+   To prevent unplanned updates to Azure Arc and the system Arc extensions that Azure IoT Operations uses as dependencies, this command disables autoupgrade. Instead, [manually upgrade agents](/azure/azure-arc/kubernetes/agent-upgrade#manually-upgrade-agents) as needed.
+
+1. Prepare for enabling the Azure Arc service, custom location, on your Arc cluster by getting the custom location object ID and saving it as the environment variable, OBJECT_ID. You must be logged into Azure CLI with a Microsoft Entra user account to successfully run the command, not a service principal. Run the following command **exactly as written**, without changing the GUID value. 
+
+   ```azurecli
+   export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
+   ```
+
+   > [!NOTE]
+   >If you receive the error: "Unable to fetch oid of 'custom-locations' app. Proceeding without enabling the feature. Insufficient privileges to complete the operation," then your service principal might lack the necessary permissions to retrieve the object ID of the custom location. Log into Azure CLI with a Microsoft Entra user account that meets the prerequisites. For more information, see [Create and manage custom locations](https://aka.ms/enable-cl-sp).
+
+1. Use the [az connectedk8s enable-features](/cli/azure/connectedk8s#az-connectedk8s-enable-features) command to enable the custom location feature on your Arc cluster. This command uses the OBJECT_ID environment variable saved from the previous step to set the value for the custom-locations-oid parameter: 
+
+   ```azurecli
+   az connectedk8s enable-features -n <CLUSTER_NAME> -g <RESOURCE_GROUP> --custom-locations-oid $OBJECT_ID --features cluster-connect custom-locations
+   ```
+
+1. Follow the instructions in [Deploy Azure IoT Operations to an Arc-enabled Kubernetes cluster](../deploy-iot-ops/howto-deploy-iot-operations.md) to deploy Azure IoT Operations to your cluster with **Test settings**.
