Prepare your Azure Arc-enabled Kubernetes cluster


Azure IoT Operations Preview – enabled by Azure Arc is currently in PREVIEW. You shouldn't use this preview software in production environments.

See the Supplemental Terms of Use for Microsoft Azure Previews for legal terms that apply to Azure features that are in beta, preview, or otherwise not yet released into general availability.

An Azure Arc-enabled Kubernetes cluster is a prerequisite for deploying Azure IoT Operations Preview. This article describes how to prepare an Azure Arc-enabled Kubernetes cluster before you Deploy Azure IoT Operations Preview extensions to a Kubernetes cluster to run your own workloads. This article includes guidance for both Ubuntu, Windows, and cloud environments.


If you want to deploy Azure IoT Operations and run a sample workload, see the Quickstart: Deploy Azure IoT Operations Preview to an Arc-enabled Kubernetes cluster.

Azure Iot Operations ships as a set of Azure Arc-enabled Kubernetes services and is intended for use with CNCF conformant Arc validated partner products. Currently, Microsoft has validated Azure IoT Operations against the following fixed-set of infrastructures and environments:

Environment Version
AKS-EE on Windows 11 IoT Enterprise
on a single-node AMD Ryzen-7 (8 core, 3.3 GHz), 16-GB RAM
K3s on Ubuntu 22.04.2
on a single-node AMD Ryzen-7 (8 core, 3.3 GHz), 16-GB RAM
K3s version 1.28.5


The environments listed previously are production-like environments that Microsoft has validated. They're not the only environments that Azure IoT Operations can run on. Azure IoT Operations can run on any Arc-enabled Kubernetes cluster that meets the Azure Arc-enabled Kubernetes system requirements.


To prepare your Azure Arc-enabled Kubernetes cluster, you need:

  • An Azure subscription. If you don't have an Azure subscription, create one for free before you begin.

  • Azure CLI version 2.46.0 or newer installed on your development 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.

  • The Azure IoT Operations extension for Azure CLI. Use the following command to add the extension or update it to the latest version:

    az extension add --upgrade --name azure-iot-ops
  • Hardware that meets the system requirements:

Create a cluster

This section provides steps to prepare and Arc-enable clusters in validated environments on Linux and Windows as well as GitHub Codespaces in the cloud.

Azure Kubernetes Service Edge Essentials is an on-premises Kubernetes implementation of Azure Kubernetes Service (AKS) that automates running containerized applications at scale. AKS Edge Essentials includes a Microsoft-supported Kubernetes platform that includes a lightweight Kubernetes distribution with a small footprint and simple installation experience, making it easy for you to deploy Kubernetes on PC-class or "light" edge hardware.


You can use the AksEdgeQuickStartForAio.ps1 script to automate the steps in this section and connect your cluster.

Open an elevated PowerShell window, change the directory to a working folder, then run the following commands:

$url = ""
Invoke-WebRequest -Uri $url -OutFile .\AksEdgeQuickStartForAio.ps1
Unblock-File .\AksEdgeQuickStartForAio.ps1
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process -Force
.\AksEdgeQuickStartForAio.ps1 -SubscriptionId "<SUBSCRIPTION_ID>" -TenantId "<TENANT_ID>" -ResourceGroupName "<RESOURCE_GROUP_NAME>"  -Location "<LOCATION>"  -ClusterName "<CLUSTER_NAME>"

Your machine might reboot as part of this process. If so, run the whole set of commands again.

Prepare your machine for AKS Edge Essentials.

  1. Download the installer for the validated AKS Edge Essentials version to your local machine.

  2. Complete the steps in Prepare your machine for AKS Edge Essentials. Be sure to use the validated installer you downloaded in the previous step and not the most recent version.

Set up an AKS Edge Essentials cluster on your machine.

  1. Complete the steps in Create a single machine deployment, but at the end of Step 1: single machine configuration parameters, modify the following values in the aksedge-config.json file:

    `Init.ServiceIPRangeSize` = 10
    `LinuxNode.DataSizeInGB` = 30
    `LinuxNode.MemoryInMB` = 8192
  2. Install local-path storage in the cluster by running the following command:

    kubectl apply -f

Run the following commands to check that the deployment was successful:

Import-Module AksEdge

In the output of the Get-AksEdgeDeploymentInfo command, you should see that the cluster's Arc status is Connected.

Arc-enable your cluster

Connect your cluster to Azure Arc so that it can be managed remotely.

To connect your cluster to Azure Arc, complete the steps in Connect your AKS Edge Essentials cluster to Arc.

Verify your cluster

To verify that your cluster is ready for Azure IoT Operations deployment, you can use the verify-host helper command in the Azure IoT Operations extension for Azure CLI. When run on the cluster host, this helper command checks connectivity to Azure Resource Manager and Microsoft Container Registry endpoints.

az iot ops verify-host

To verify that your Kubernetes cluster is now Azure Arc-enabled, run the following command:

kubectl get deployments,pods -n azure-arc

The output looks like the following example:

NAME                                         READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/clusterconnect-agent         1/1     1            1           10m
deployment.apps/extension-manager            1/1     1            1           10m
deployment.apps/clusteridentityoperator      1/1     1            1           10m
deployment.apps/controller-manager           1/1     1            1           10m
deployment.apps/flux-logs-agent              1/1     1            1           10m
deployment.apps/cluster-metadata-operator    1/1     1            1           10m
deployment.apps/extension-events-collector   1/1     1            1           10m
deployment.apps/config-agent                 1/1     1            1           10m
deployment.apps/kube-aad-proxy               1/1     1            1           10m
deployment.apps/resource-sync-agent          1/1     1            1           10m
deployment.apps/metrics-agent                1/1     1            1           10m

NAME                                              READY   STATUS    RESTARTS        AGE
pod/clusterconnect-agent-5948cdfb4c-vzfst         3/3     Running   0               10m
pod/extension-manager-65b8f7f4cb-tp7pp            3/3     Running   0               10m
pod/clusteridentityoperator-6d64fdb886-p5m25      2/2     Running   0               10m
pod/controller-manager-567c9647db-qkprs           2/2     Running   0               10m
pod/flux-logs-agent-7bf6f4bf8c-mr5df              1/1     Running   0               10m
pod/cluster-metadata-operator-7cc4c554d4-nck9z    2/2     Running   0               10m
pod/extension-events-collector-58dfb78cb5-vxbzq   2/2     Running   0               10m
pod/config-agent-7579f558d9-5jnwq                 2/2     Running   0               10m
pod/kube-aad-proxy-56d9f754d8-9gthm               2/2     Running   0               10m
pod/resource-sync-agent-769bb66b79-z9n46          2/2     Running   0               10m
pod/metrics-agent-6588f97dc-455j8                 2/2     Running   0               10m

Create sites

To manage which clusters your OT users have access to, you can group your clusters into sites. To learn more, see What is Azure Arc site manager (preview)?.

Next steps

Now that you have an Azure Arc-enabled Kubernetes cluster, you can deploy Azure IoT Operations.