Prepare your Azure Arc-enabled Kubernetes cluster
Important
Azure IoT Operations Preview – enabled by Azure Arc is currently in preview. You shouldn't use this preview software in production environments.
You'll need to deploy a new Azure IoT Operations installation when a generally available release is made available. You won't be able to upgrade a preview installation.
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 a cluster before you Deploy Azure IoT Operations Preview to an Arc-enabled Kubernetes cluster. This article includes guidance for both Ubuntu and Windows.
Tip
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 Preview in GitHub Codespaces with K3s instead.
For more information about test settings and secure settings, see Deployment details > Choose your features.
Prerequisites
Azure IoT Operations should work on any Arc-enabled Kubernetes cluster that meets the Azure Arc-enabled Kubernetes system requirements. Currently Azure IoT Operations doesn't support Arm64 architectures.
Microsoft supports Azure Kubernetes Service (AKS) Edge Essentials for deployments on Windows and K3s for deployments on Ubuntu. For a list of specific hardware and software combinations that are tested and validated, see Validated environments.
If you want to deploy Azure IoT Operations to a multi-node solution, use K3s on Ubuntu.
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.64.0 or newer installed on your development machine. Use
az --version
to check your version andaz upgrade
to update if necessary. For more information, see How to install the Azure CLI.The latest version of the following extensions for Azure CLI:
az extension add --upgrade --name azure-iot-ops az extension add --upgrade --name connectedk8s
Hardware that meets the system requirements:
- Ensure that your machine has a minimum of 16-GB available RAM, 8 available vCPUs, and 52-GB free disk space reserved for Azure IoT Operations.
- Azure Arc-enabled Kubernetes system requirements.
- AKS Edge Essentials requirements and support matrix.
- AKS Edge Essentials networking guidance.
If you're going to deploy Azure IoT Operations to a multi-node cluster with fault tolerance enabled, review the hardware and storage requirements in Prepare Linux for Edge Volumes.
Create a cluster
This section provides steps to create clusters in validated environments on Linux and Windows.
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 that supports PC-class or "light" edge hardware.
The AksEdgeQuickStartForAio.ps1 script automates the process of creating and connecting a cluster, and is the recommended path for deploying Azure IoT Operations on AKS Edge Essentials.
Open an elevated PowerShell window and change the directory to a working folder.
Get the
objectId
of the Microsoft Entra ID application that the Azure Arc service uses in your tenant. Run the following command exactly as written, without changing the GUID value.az ad sp show --id bc313c14-388c-4e7d-a58e-70017303ee3b --query id -o tsv
Run the following commands, replacing the placeholder values with your information:
Placeholder Value SUBSCRIPTION_ID The ID of your Azure subscription. If you don't know your subscription ID, see Find your Azure subscription. TENANT_ID The ID of your Microsoft Entra tenant. If you don't know your tenant ID, see Find your Microsoft Entra tenant. RESOURCE_GROUP_NAME The name of an existing resource group or a name for a new resource group to be created. LOCATION An Azure region close to you. For the list of currently supported Azure regions, see Supported regions. CLUSTER_NAME A name for the new cluster to be created. ARC_APP_OBJECT_ID The object ID value that you retrieved in the previous step. $url = "https://raw.githubusercontent.com/Azure/AKS-Edge/main/tools/scripts/AksEdgeQuickStart/AksEdgeQuickStartForAio.ps1" 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>" -CustomLocationOid "<ARC_APP_OBJECT_ID>"
If there are any issues during deployment, including if your machine reboots as part of this process, run the whole set of commands again.
Run the following commands to check that the deployment was successful:
Import-Module AksEdge Get-AksEdgeDeploymentInfo
In the output of the
Get-AksEdgeDeploymentInfo
command, you should see that the cluster's Arc status isConnected
.
Arc-enable your cluster
Connect your cluster to Azure Arc so that it can be managed remotely.
The AksEdgeQuickStartForAio.ps1 script that you ran in the previous section handled the steps to connect your cluster. You don't need to take any extra steps to Arc-enable.
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 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
Next steps
Now that you have an Azure Arc-enabled Kubernetes cluster, you can deploy Azure IoT Operations.