Configure the connector for MQTT

By using the connector for MQTT, you can model MQTT endpoints as assets in Azure IoT Operations. These MQTT endpoints can be on external MQTT brokers or on the built-in MQTT broker in Azure IoT Operations. The MQTT connector detects new topic paths as they appear, and you can view the custom resources that represent the detected topics.

An asset in Azure IoT Operations is a logical entity that you create to represent a physical asset or device. An Azure IoT Operations asset can have custom properties, data points, streams, and events that describe its behavior and characteristics. An asset is associated with one or more devices. Azure IoT Operations stores asset definitions in the Azure Device Registry.

A device in Azure IoT Operations is a logical entity that defines the connections to physical assets or devices. Without a device, data can't flow from a physical device or asset to the MQTT broker. When you configure a device and asset, a connection is established to the physical asset or device and data point values, events, and streams arrive in Azure IoT Operations instance. A device has one or more inbound endpoints. Azure IoT Operations stores device definitions in the Azure Device Registry.

The following table summarizes the features that the connector for MQTT supports:

The connector for MQTT:

1. Detects new topics that appear under a given topic path or MQTT wildcard path and communicates with Akri.
2. Akri creates the discovered asset custom resource ready for OT approval and import into Azure Device Registry.
3. For approved assets, the connector for MQTT subscribes to the topics and forwards the data to the unified namespace topics you specify.

This article explains how to use the connector for MQTT to perform tasks such as:

• Define the devices that connect MQTT endpoints to your Azure IoT Operations instance.
• Import discovered assets, and define the data points to enable the data flow from the MQTT source to the MQTT broker.
• Configure management actions that let you send commands to the MQTT source by publishing messages to MQTT topics.
• Configure data transformations by using WebAssembly (WASM) modules.

Prerequisites

The Azure CLI examples in this article use environment variables so that you can set each value once and then copy and paste the commands as-is. If you're using the Azure IoT Operations Codespaces environment from the quickstart, these variables are already set for you and you can skip this step. Otherwise, set the following environment variables in your shell before you run the commands.

The following scripts set the most commonly used environment variables:

SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

$SUBSCRIPTION_ID = "<subscription-id>"
$RESOURCE_GROUP = "<resource-group-name>"
$AIO_INSTANCE_NAME = "<instance-name>"
$CLUSTER_NAME = "<cluster-name>"
$LOCATION = "<region>"

You only need to set the variables that this article uses. This article might use additional environment variables for resource names that you choose. The article explains how to set them where they're introduced.

A deployed instance of Azure IoT Operations with resource sync rules enabled. To enable resource sync rules run the following command on your Azure IoT Operations instance. This command also sets the required permissions on the custom location:

az iot ops enable-rsync -n $AIO_INSTANCE_NAME -g $RESOURCE_GROUP

To sign in to the operations experience web UI, you need a Microsoft Entra ID account with at least contributor permissions for the resource group that contains your Kubernetes - Azure Arc instance. You can't sign in with a Microsoft account (MSA). For more information, see Troubleshoot access to the operations experience web UI.

Your IT administrator must configure the connector for MQTT template for your Azure IoT Operations instance in the Azure portal.

You need credentials to access the MQTT source. If the MQTT source requires authentication, you need to create a Kubernetes secret that contains the username and password for the MQTT source.

MQTT connector template instance

Before an OT user can create a device that uses the connector for MQTT, an IT administrator must add an MQTT connector template instance to your Azure IoT Operations instance. To learn more, see Create and manage connector template instances.

Configure a certificate trust list for the connector

Each connector has its own trust list: the set of certificates the connector uses to validate the TLS certificate that a southbound endpoint presents when the connector establishes a secure connection to it. Add a certificate to the trust list when the southbound endpoint uses a TLS certificate that's signed by a private or enterprise certificate authority (CA), or a self-signed certificate that the connector doesn't already trust. Client certificates that the connector presents to the southbound endpoint for mutual TLS are configured separately as part of the device's user authentication.

You can add a certificate to a connector's trust list in two ways:

• Operations experience. In the operations experience web UI, you can either upload a certificate file directly or pick an existing secret from Azure Key Vault. The operations experience adds the certificate to Azure Key Vault as a secret (if needed), creates the synced secret resource on the cluster, and wires it into the connector's trust list for you. To learn more, see Manage certificates for external communications.

• Azure CLI. The Azure CLI flow assumes the certificate is already stored as a secret in Azure Key Vault. You use az iot ops secretsync secret set to create a synced secret on the cluster that references the Key Vault secret, and then az iot ops connector template update to add a reference to the synced secret in the connector template's trust list. To learn more, see Add and use certificates. To learn how to add a certificate to Azure Key Vault, see Add certificates as secrets to Azure Key Vault.

The operations experience and the Azure CLI flows partially overlap. The operations experience can both upload a new certificate to Azure Key Vault and sync it to the cluster in one experience. The Azure CLI flow assumes the certificate is already in Azure Key Vault and only handles the sync and trust-list wiring.

Create a device

To configure the connector for MQTT, first create a device that defines the connection to the MQTT topic to subscribe from. The device includes the address of the MQTT topic and any credentials you need to access it. You can configure the inbound endpoint to connect to an external MQTT broker or the built-in MQTT broker in Azure IoT Operations:

• External MQTT broker: Use this option when connecting to an MQTT broker other than the built-in MQTT broker on your Azure IoT Operations instance. You must supply the server URL in the specified format and any required authentication credentials.
• Built-in MQTT broker: Use this option when you want to subscribe to topics on the built-in MQTT broker that's part of your Azure IoT Operations instance. This option is useful for bridging data between the built-in broker and other parts of the system by routing it through the asset model.

The connector also discovers assets from MQTT topics based on a topic filter and forwards data to a unified namespace path defined by a topic mapping prefix:

• The topic filter specifies which topics the connector subscribes to. The filter supports the single-level wildcard (+). The connector detects a new asset each time a message arrives on a topic that matches the filter at the wildcard position. For example, the filter A/B/+ detects A/B/asset1 and A/B/asset2 as separate assets. Topic filters don't support the multilevel wildcard (#) or system topics (topics that start with $SYS/).
• The topic mapping prefix maps the incoming topic to a unified namespace path. For example, if the prefix is X/Y and the incoming topic is A/B/asset1, the connector forwards data to X/Y/A/B/asset1.

az iot ops ns device create \
  -n mqtt-connector-cli \
  -g {your resource group name} \
  --instance {your instance name}

az iot ops ns device endpoint inbound add mqtt \
  --device mqtt-connector-cli \
  -g {your resource group name} \
  -i {your instance name} \
  --name mqtt-connector-0 \
  --endpoint-address "mqtt://my-broker:1883" \
  --topic-filter "A/B/+" \
  --topic-mapping-prefix "X/Y"

az iot ops ns device endpoint inbound add mqtt \
  --device mqtt-connector-cli \
  -g {your resource group name} \
  -i {your instance name} \
  --name mqtt-connector-0 \
  --endpoint-address "aio-broker:18883" \
  --topic-filter "A/B/+" \
  --topic-mapping-prefix "X/Y"

param adrNamespaceName string = '<AIO_NAMESPACE_NAME>'
param customLocationName string = '<CUSTOM_LOCATION_NAME>'

resource adrNamespace 'Microsoft.DeviceRegistry/namespaces@2026-04-01' existing = {
  name: adrNamespaceName
}

resource customLocation 'Microsoft.ExtendedLocation/customLocations@2021-08-31-preview' existing = {
  name: customLocationName
}

resource device 'Microsoft.DeviceRegistry/namespaces/devices@2026-04-01' = {
  name: 'mqtt-connector'
  parent: adrNamespace
  location: resourceGroup().location
  extendedLocation: {
    type: 'CustomLocation'
    name: customLocation.id
  }
  properties: {
    endpoints: {
      outbound: {
        assigned: {}
      }
      inbound: {
        'mqtt-connector-0': {
          endpointType: 'Microsoft.Mqtt'
          address: 'mqtt://my-broker:1883'
          additionalConfiguration: string({
            topicFilter: 'A/B/+'
            topicMappingPrefix: 'X/Y'
          })
        }
      }
    }
  }
}

Configure a device to use a username and password

The previous example uses the Anonymous authentication mode. This mode doesn't require a username or password.

To use the Username password authentication mode, complete the following steps:

Configure a device to use an X.509 certificate

Discover and create assets

When you send a message to a topic that matches the topic filter on the asset discovery configuration for a device, the connector for MQTT detects the new topic and creates a detected asset custom resource. For example, if you specify the topic filter as A/B/+, and you send a message to the topic A/B/asset1, the connector for MQTT detects the new topic and creates a discovered asset that you can view in the operations experience web UI:

To create an asset from the discovered asset, follow these steps:

1. In the operations experience, select the discovered asset from the list and then select Import and create asset.

2. On the Asset details page, the inbound endpoint is already selected from the device. Add a name, a description, and any custom properties you want to associate with the asset. Then select Next to continue.

3. On the Datasets page, you see a dataset that the connector created automatically from the discovered asset using the topic filter and asset name:

   

   Select Next to continue.

4. On the review page, review the details of the asset and select Create to create the asset. After a few minutes, the asset appears on the Assets page:

   

In this example, the imported asset has a dataset definition with the following settings:

Now, the connector copies any messages published to the topic A/B/asset1 to the unified namespace topic X/Y/A/B/asset1.

Add management groups and actions

A management group is a logical grouping of actions that you can invoke against an MQTT asset. An action lets you publish a message to a topic that a subscriber can act on. Actions must belong to a management group.

To add a management group and define actions for it:

1. In the operations experience, select the asset from the Assets list and select the Management groups tab.
2. Select Add management group and give it a name.
3. Within the management group, select Add action and configure the action:
   • Name: A friendly name for the action.
   • Target URI: The MQTT topic on your device endpoint to publish the action payload to. For example, A/B/asset1/commands.
   • Topic: The MQTT topic to publish action execution request to.
   • Action type: Write is the only supported action type for the connector for MQTT.
   • Time out: The time-out value before the action execution request times out.

When you invoke the action, the connector publishes the action payload to the Target URI topic on the device's inbound endpoint. A downstream subscriber on that topic receives the message and can act on it.

For background on how management groups and actions work across connectors, see:

• Enable and run management actions
• Control OPC UA servers — explains the action invocation pattern and the MQTT RPC protocol used to trigger actions.
• Manage and control the camera — shows how a similar pattern is used for the connector for ONVIF.

Transform incoming data

To transform the incoming data by using a WASM module and graph, complete the following steps:

1. Develop a WASM module to perform the custom transformation. For more information, see Develop WebAssembly (WASM) modules.

2. Configure your transformation graph. For more information, see Configure WebAssembly (WASM) graph definitions.

3. Deploy both the module and graph to your container registry. For more information, see Deploy WebAssembly (WASM) modules and graph definitions.

4. Set up authentication and connection details so Azure IoT Operations can access the container registry.

5. Configure your asset's dataset with the URL of the deployed WASM graph in the Transform field:

   

A data transformation in the connector only requires a single map operator, but WASM graphs are fully supported with the following restrictions:

• The graph must have a single source node and a single sink node.
• The graph must consume and emit the DataModel::Message datatype.
• The graph must be stateless. Currently, this restriction means that accumulate operators aren't supported.

Known issues

The following known issue applies to the connector for MQTT:

Misconfigured asset discovery settings produce no diagnostic output

If the asset discovery configuration - topic filter or topic mapping prefix - is invalid or inconsistent, the connector doesn't report an error. No discovered assets appear and no warning is surfaced in the UI or logs.

To diagnose a misconfiguration, verify that:

• Messages are being published to a topic that matches the topic filter.
• The connector pod logs don't show connection errors to the broker endpoint.

If you need to correct the configuration, delete and recreate the device.