You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
# Prepare your Azure Arc-enabled Kubernetes cluster
14
14
15
-
An Azure Arc-enabled Kubernetes cluster is a prerequisite for deploying Azure IoT Operations. This article describes how to prepare a cluster before you deploy Azure IoT Operations. This article includes guidance for both Ubuntuand Windows.
15
+
An Azure Arc-enabled Kubernetes cluster is a prerequisite for deploying Azure IoT Operations. This article describes how to prepare a cluster before you deploy Azure IoT Operations. This article includes guidance for Ubuntu, Windows, Azure Local, and Tanzu Kubernetes Grid (TKG).
16
16
17
17
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 in GitHub Codespaces with K3s](../get-started-end-to-end-sample/quickstart-deploy.md) instead. For more information about test settings and secure settings, see [Deployment details > Choose your features](./overview-deploy.md#choose-your-features).
18
18
19
19
## Prerequisites
20
20
21
-
Microsoft supports Azure Kubernetes Service (AKS) Edge Essentials for deployments on Windows and K3s for deployments on Ubuntu. If you want to deploy Azure IoT Operations to a multi-node solution, use K3s on Ubuntu.
21
+
Microsoft supports Azure Kubernetes Service (AKS) Edge Essentials for deployments on Windows, K3s for deployments on Ubuntu, AKS deployments on Azure Local, and Tanzu Kubernetes release (TKr) on TKG. If you want to deploy Azure IoT Operations to a multi-node solution, use K3s on Ubuntu.
22
22
23
23
### [Ubuntu](#tab/ubuntu)
24
24
25
25
To prepare an Azure Arc-enabled Kubernetes cluster, you need:
26
26
27
-
* An Azure subscription with either the Owner role or a combination of Contributor and User Access Administrator roles. You can check your access level by navigating to your subscription, selecting Access control (IAM) on the left-hand side of the Azure portal, and then selecting View my access. If you don't have an Azure subscription, [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
28
-
29
-
* An Azure resource group. Only one Azure IoT Operations instance is supported per resource group. To create a new resource group, use the [az group create](/cli/azure/group#az-group-create) command. For the list of currently supported Azure regions, see [Supported regions](../overview-iot-operations.md#supported-regions).
30
-
31
-
```azurecli
32
-
az group create --location <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID>
33
-
```
34
-
35
-
* Azure CLI version 2.53.0 or newer installed on your cluster 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).
36
-
37
-
* The latest version of the **connectedk8s** extension for Azure CLI:
38
-
39
-
```bash
40
-
az extension add --upgrade --name connectedk8s
41
-
```
27
+
[!INCLUDE [Cluster prerequisites for Ubuntu and Tanzu](../includes/cluster-prerequisites.md)]
42
28
43
29
* Hardware that meets the system requirements:
44
30
@@ -73,7 +59,22 @@ To prepare an Azure Arc-enabled Kubernetes cluster, you need:
*[Azure Arc-enabled Kubernetes system requirements](/azure/azure-arc/kubernetes/system-requirements).
62
+
63
+
### [TKG with a management cluster](#tab/tkgm)
64
+
65
+
To prepare a TKG workload cluster, you need:
66
+
67
+
[!INCLUDE [Cluster prerequisites for Ubuntu and Tanzu](../includes/cluster-prerequisites.md)]
68
+
69
+
-[TKG with a standalone management cluster.](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-kubernetes-grid/2-5/tkg/mgmt-index.html)
@@ -128,13 +129,13 @@ To prepare a K3s Kubernetes cluster on Ubuntu:
128
129
129
130
Connect your cluster to Azure Arc so that it can be managed remotely.
130
131
131
-
1.On the machine where you deployed the Kubernetes cluster, sign into Azure CLI with your Microsoft Entra user account that has the required role(s) for the Azure subscription:
132
+
1.From a machine that has `kubectl` access to your cluster, sign into Azure CLI with your Microsoft Entra user account that has the required role(s) for the Azure subscription:
132
133
133
-
```azurecli
134
+
```azurecli
134
135
az login
135
136
```
136
137
137
-
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.
138
+
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.
138
139
139
140
1. After you sign in, the Azure CLI displays all of your subscriptions and indicates your default subscription with an asterisk `*`. To continue with your default subscription, select `Enter`. Otherwise, type the number of the Azure subscription that you want to use.
140
141
@@ -238,6 +239,105 @@ By default, a Kubernetes cluster is created with a node pool that can run Linux
238
239
239
240
Then, once you have an Azure Arc-enabled Kubernetes cluster, you can [deploy Azure IoT Operations](howto-deploy-iot-operations.md).
240
241
242
+
### [TKG with a management cluster](#tab/tkgm)
243
+
244
+
To prepare a TKG workload cluster, you need:
245
+
246
+
- A single-node or multi-node TKG workload cluster. For guidance, see the [Tanzu documentation](https://techdocs.broadcom.com/us/en/vmware-tanzu/standalone-components/tanzu-kubernetes-grid/2-5/tkg/workload-clusters-index.html).
247
+
248
+
### Update pod security admission settings
249
+
250
+
Before deploying Azure IoT Operations, you will need to update the Pod Security Admission settings on your TKG cluster. Applying this file will pre-create namespace labels and set pod security to `privileged`.
Connect your cluster to Azure Arc so that it can be managed remotely.
261
+
262
+
1. On the machine where you deployed the Kubernetes cluster, sign into Azure CLI with your Microsoft Entra user account that has the required role(s) for the Azure subscription:
263
+
264
+
265
+
```azurecli
266
+
az login
267
+
```
268
+
269
+
1. After you sign in, the Azure CLI displays all of your subscriptions and indicates your default subscription with an asterisk `*`. To continue with your default subscription, select `Enter`. Otherwise, type the number of the Azure subscription that you want to use.
270
+
271
+
1. Register the required resource providers in your subscription.
272
+
273
+
> [!NOTE]
274
+
> 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).
275
+
276
+
```azurecli
277
+
az provider register -n "Microsoft.ExtendedLocation"
278
+
az provider register -n "Microsoft.Kubernetes"
279
+
az provider register -n "Microsoft.KubernetesConfiguration"
280
+
az provider register -n "Microsoft.IoTOperations"
281
+
az provider register -n "Microsoft.DeviceRegistry"
282
+
az provider register -n "Microsoft.SecretSyncController"
283
+
```
284
+
285
+
1. Use the [az connectedk8s connect](/cli/azure/connectedk8s) command to Arc-enable your Kubernetes cluster and manage it as part of your Azure resource group.
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) as needed.
293
+
294
+
> [!IMPORTANT]
295
+
> If your environment uses a proxy server or Azure Arc Gateway, modify the `az connectedk8s connect` command with your proxy information:
296
+
>
297
+
> 1. Follow the instructions in either [Connect using an outbound proxy server](/azure/azure-arc/kubernetes/quickstart-connect-cluster#connect-using-an-outbound-proxy-server) or [Onboard Kubernetes clusters to Azure Arc with Azure Arc Gateway](/azure/azure-arc/kubernetes/arc-gateway-simplify-networking#onboard-kubernetes-clusters-to-azure-arc-with-your-arc-gateway-resource).
298
+
> 1. Add `169.254.169.254` to the `--proxy-skip-range` parameter of the `az connectedk8s connect` command. [Azure Device Registry](../discover-manage-assets/overview-manage-assets.md#store-assets-as-azure-resources-in-a-centralized-registry) uses this local endpoint to get access tokens for authorization.
299
+
>
300
+
> Azure IoT Operations doesn't support proxy servers that require a trusted certificate.
301
+
302
+
1. Get the cluster's issuer URL.
303
+
304
+
305
+
```azurecli
306
+
az connectedk8s show --resource-group <RESOURCE_GROUP> --name <CLUSTER_NAME> --query oidcIssuerProfile.issuerUrl --output tsv
307
+
```
308
+
309
+
Save the output of this command to use in the next steps.
310
+
311
+
1. Connect to the TKG management cluster. Edit the custom resource for the workload cluster with the issuer URL from the previous step.
312
+
313
+
```azurecli
314
+
kubectl edit cluster <CLUSTER_NAME>
315
+
```
316
+
317
+
1. Add the following content to the `config.yaml` file, replacing the <OIDC_ISSUER_URL> placeholder with your cluster's issuer URL.
318
+
> [!NOTE]
319
+
> The URL should be copied exactly as printed by the prior command, including any characters such as `/`.
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.
327
+
328
+
```azurecli
329
+
export OBJECT_ID=$(az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv)
330
+
```
331
+
332
+
> [!NOTE]
333
+
>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).
334
+
335
+
1. Use the [az connectedk8s enable-features](/cli/azure/connectedk8s) 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. Run this command on the machine where you deployed the Kubernetes cluster:
description: include file with cluster prerequisites for Ubuntu and Tanzu
4
+
author: dominicbetts
5
+
ms.topic: include
6
+
ms.date: 06/16/2025
7
+
ms.author: dobett
8
+
---
9
+
10
+
* An Azure subscription with either the **Owner** role or a combination of **Contributor** and **User Access Administrator** roles. You can check your access level by navigating to your subscription, selecting **Access control (IAM)** on the left-hand side of the Azure portal, and then selecting **View my access**. If you don't have an Azure subscription, [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F) before you begin.
11
+
12
+
* An Azure resource group. Only one Azure IoT Operations instance is supported per resource group. To create a new resource group, use the [az group create](/cli/azure/group#az-group-create) command. For the list of currently supported Azure regions, see [Supported regions](../overview-iot-operations.md#supported-regions).
13
+
14
+
```azurecli
15
+
az group create --location <REGION> --resource-group <RESOURCE_GROUP> --subscription <SUBSCRIPTION_ID>
16
+
```
17
+
18
+
* Azure CLI version 2.62.0 or newer installed on your cluster 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).
19
+
20
+
* The latest version of the **connectedk8s** extension for Azure CLI:
0 commit comments