Deploy Azure IoT operations to a test cluster

2025-08-06

Learn how to deploy Azure IoT Operations to a test cluster, which is an Arc-enabled Kubernetes cluster that you can use for testing and evaluation scenarios.

If you want to deploy Azure IoT Operations to a production cluster, see Deploy Azure IoT Operations to a production cluster.

Before you begin

This article discusses Azure IoT Operations deployments and instances, which are two different concepts:

An Azure IoT Operations deployment describes all of the components and resources that enable the Azure IoT Operations scenario. These components and resources include:
- An Azure IoT Operations instance
- Arc extensions
- Custom locations
- Resources that you can configure in your Azure IoT Operations solution, like namespace assets and devices.
An Azure IoT Operations instance is the parent resource that bundles the suite of services that are defined in What is Azure IoT Operations? like MQTT broker, data flows, and connector for OPC UA.

When we talk about deploying Azure IoT Operations, we mean the full set of components that make up a deployment. Once the deployment exists, you can view, manage, and update the instance.

Prerequisites

Cloud resources:

An Azure subscription.
Azure access permissions. For more information, see Deployment details > Required permissions.

Development resources:

Azure CLI installed on your development machine. This scenario requires Azure CLI version 2.53.0 or higher. 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
```

A cluster host:

Have an Azure Arc-enabled Kubernetes cluster with the custom location and workload identity features enabled. If you don't have one, follow the steps in Prepare your Azure Arc-enabled Kubernetes cluster.

If you deployed Azure IoT Operations to your cluster previously, uninstall those resources before continuing. For more information, see Update Azure IoT Operations.

Deploy in Azure portal

The Azure portal deployment experience is a helper tool that generates a deployment command based on your resources and configuration. The final step is to run an Azure CLI command, so you still need the Azure CLI prerequisites described in the previous section.

Sign in to Azure portal.
In the search box, search for and select Azure IoT Operations.
Select Create.

On the Basics tab, provide the following information:

Parameter	Value
Subscription	Select the subscription that contains your Arc-enabled cluster.
Resource group	Select the resource group that contains your Arc-enabled cluster.
Cluster name	Select the cluster that you want to deploy Azure IoT Operations to.
Custom location name	Optional: Replace the default name for the custom location.
Deployment version	Select 1.1 (GA version) or 1.2 (Preview version). If you select 1.2 (Preview version), check the box to consent to the preview terms. For more information, see IoT Operations versions.

A screenshot that shows the first tab for deploying Azure IoT Operations from the portal.

Select Next: Configuration.

On the Configuration tab, provide the following information:

Parameter	Value
Azure IoT Operations name	Optional: Replace the default name for the Azure IoT Operations instance.
MQTT broker configuration	Optional: Edit the default settings for the MQTT broker. In Azure portal it's possible to configure cardinality and memory profile settings. To configure other settings including disk-backed message buffer and advanced MQTT client options, see Azure CLI support for advanced MQTT broker configuration.
Data flow profile configuration	Optional: Edit the default settings for data flows. For more information, see Configure data flow profile.

A screenshot that shows the second tab for deploying Azure IoT Operations from the portal.

Select Next: Dependency management.
On the Dependency management tab, select an existing schema registry or use these steps to create one:
1. Select Create new.
2. Provide a Schema registry name and Schema registry namespace.
3. Select Select Azure Storage container.
4. Choose a storage account from the list of hierarchical namespace-enabled accounts, or select Create to create one.
  
  Schema registry requires an Azure Storage account with hierarchical namespace and public network access enabled. When creating a new storage account, choose a General purpose v2 storage account type and set Hierarchical namespace to Enabled.
  
  For more information on configuring your storage account, see Production deployment guidelines.
5. Select a container in your storage account or select Container to create one.
6. Select Apply to confirm the schema registry configurations.
On the Dependency management tab, select the Test settings deployment option. This option uses default settings that are recommended for testing purposes.
Select Next: Automation.

Run Azure CLI commands

The final step in the Azure portal deployment experience is to run a set of Azure CLI commands to deploy Azure IoT Operations to your cluster. The commands are generated based on the information you provided in the previous steps.

One at a time, run each Azure CLI command on the Automation tab in a terminal:

Sign in to Azure CLI interactively with a browser even if you already signed in before. If you don't sign in interactively, you might get an error that says Your device is required to be managed to access your resource.
```
az login
```
Install the latest Azure IoT Operations CLI extension if you haven't already.
```
az extension add --upgrade --name azure-iot-ops
```
Important

For preview releases, you need to append the --allow-preview flag to the az extension add command to install the preview version of the Azure IoT Operations CLI extension.
```
az extension add --upgrade --name azure-iot-ops --allow-preview
```
Copy and run the provided az iot ops schema registry create command to create a schema registry which is used by Azure IoT Operations components. If you chose to use an existing schema registry, this command isn't displayed on the Automation tab.
Azure IoT Operations uses namespaces to organize assets and devices. Each Azure IoT Operations instance uses a single namespace for its assets and devices. You can use an existing namespace or run the az iot ops ns create command to create an Azure Device Registry namespace. Replace <my namespace name> with a unique name for your namespace.
```
az iot ops ns create -n <my namespace name> -g $RESOURCE_GROUP
```
Alternatively, you can create a new Azure Device Registry namespace in Azure portal:
1. In the search box, type and select Azure Device Registry.
2. In the left menu, select Namespaces.
3. Then select + Create to create a new namespace. Make sure to use the same resource group as your Arc-enabled Kubernetes cluster.
Note

Namespace resources are available from 2507 preview release. If you're using an earlier release version, namespaces aren't available and you can skip this step.
Prepare the cluster for Azure IoT Operations deployment. Copy and run the provided az iot ops init command.

Tip

The init command only needs to be run once per cluster. If you followed the optional prerequisite to set up your own certificate authority issuer, follow the steps in Bring your own issuer.

This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
To deploy Azure IoT Operations, copy and run the provided az iot ops create command. This command might take several minutes to complete. You can watch the progress in the deployment progress display in the terminal.
- If you want to use an existing namespace, add the following parameter to the create command:
```
--ns-resource-id $(az iot ops ns show --name <my namespace name> --resource-group $RESOURCE_GROUP -o tsv --query id)
```
- If you want to use the preview connector configuration, add the following parameter to the create command:
```
--feature connectors.settings.preview=Enabled
```
  Note
  
  The --feature configuration parameter is only available in the latest GA version. If you're using the 2507 preview release, this parameter isn't available.
Once all of the Azure CLI commands complete successfully, you can close the Install Azure IoT Operations wizard.

Once the create command completes successfully, you have a working Azure IoT Operations instance running on your cluster. At this point, your instance is configured for most testing and evaluation scenarios.

Verify deployment

After the deployment is complete, run az iot ops check to evaluate IoT Operations service deployment for health, configuration, and usability. The check command can help you find problems in your deployment and configuration.

az iot ops check

The check command displays a warning about missing data flows, which is normal and expected until you create a data flow. For more information, see Process and route data with data flows.

You can check the configurations of topic maps, QoS, and message routes by adding the --detail-level 2 parameter to the check command for a verbose view.

You can view all versions of the Azure IoT Operations CLI extension that are available by running the following command:

az iot ops get-versions

Next steps

The Azure IoT Operations instance you deployed is configured for testing scenarios. If you want to enable secure setting and prepare the instance for production scenarios, follow the steps in Enable secure settings on an existing Azure IoT Operations instance.