# Azure IoT Operations Integration

This guide shows you how to connect Cybus Connectware to Microsoft Azure IoT Operations (AIO) using MQTT. By following these steps, you will establish a bidirectional data connection between your industrial systems and Azure IoT Operations running on an Azure Arc-enabled Kubernetes cluster.

## What You Will Learn

In this guide, you will:

* Obtain the necessary credentials from Azure IoT Operations.
* Configure an MQTT connection in Connectware.
* Deploy the integration service.
* Verify that data flows correctly in both directions.

## Prerequisites

Before you begin, ensure you have:

**Azure Environment**

* Access to the Azure Portal.
* An Azure Arc-enabled Kubernetes cluster (created via Azure Portal or Azure CLI).
* Azure IoT Operations installed as a service/addon on the cluster.
* In case you want to use SAT or X.509 authentication: `kubectl` command-line tool configured to access your cluster.

**Cybus Connectware**

* Cybus Connectware installed on the same Kubernetes cluster as Azure IoT Operations. Connectware must be installed using the standard Connectware [installation process](https://docs.cybus.io/documentation/installation-and-upgrades/installing-connectware), not through the Azure Portal.
* Access to the Connectware [Admin UI](https://docs.cybus.io/getting-started/admin-ui).

## Step 1: Determine Your Authentication Method

Azure IoT Operations supports multiple authentication methods for MQTT connections. Connectware supports all of these methods.

**Supported Authentication Methods:**

* **Kubernetes Service Account Token (SAT)**: Default authentication method using cluster service accounts.
* **X.509 Certificates**: Mutual TLS authentication using client certificates.
* **No Authentication**: For development/testing only.

For detailed instructions on configuring authentication in Azure IoT Operations, see the [Azure IoT Operations Authentication Guide](https://learn.microsoft.com/en-us/azure/iot-operations/manage-mqtt-broker/howto-configure-authentication).

### Kubernetes Service Account Token (SAT)

This is the default authentication method in Azure IoT Operations.

{% hint style="warning" %}
SAT tokens expire after a maximum of one week.
{% endhint %}

* To configure SAT authentication in the [service commissioning file](#step-3-create-the-service-commissioning-file), use the following [MQTT Connection Properties](https://docs.cybus.io/connectors/enterprise-connectors/mqtt/mqttconnection):

{% code lineNumbers="true" %}

```yaml
authenticationMethod: 'K8S-SAT'
authenticationData: !ref SAT-Token
```

{% endcode %}

For more information, refer to the [Azure IoT Operations documentation](https://learn.microsoft.com/en-us/azure/iot-operations/manage-mqtt-broker/howto-configure-authentication?tabs=portal#kubernetes-service-account-tokens).

### X.509 Certificate Authentication

For production environments, X.509 certificates provide long-term authentication.

For detailed configuration instructions, see [MQTT User Authentication](https://docs.cybus.io/documentation/user-management/mqtt-user-authentication) and the [Azure IoT Operations documentation](https://learn.microsoft.com/en-us/azure/iot-operations/manage-mqtt-broker/howto-configure-authentication?tabs=portal#x509).

### No Authentication

For development or testing environments, you can configure the AIO broker to allow anonymous connections (Authentication = None). This is not recommended for production use.

## Step 2: Obtain the MQTT Broker Endpoint and Port

To connect Connectware to the Azure IoT Operations MQTT broker, you need to identify the broker's hostname and port number.

### Obtain the Broker Hostname

You can find the MQTT broker hostname in the Azure Portal.

* The MQTT broker hostname follows the pattern `<service-name>.<namespace-name>`.
* **Default hostname**: `aio-broker.azure-iot-operations`

If you are using a custom service name or namespace, adjust the hostname accordingly.

### Obtain the Broker Port

* **Default port**: `18883` (SAT authentication)

You can verify these values in the Azure Portal under your Azure IoT Operations instance.

## Step 3: Create the Service Commissioning File

Now you will create a service commissioning file that defines the MQTT connection and data mappings between Connectware and Azure IoT Operations.

{% hint style="danger" %}
**Security Warning**: Do not commit real tokens or certificates to version control in production environments. Use secure secret management or templating instead.
{% endhint %}

Key configuration requirements:

* **MQTT Protocol Version**: Azure IoT Operations requires MQTT v5. Set `protocolVersion: 5` (Connectware's default v3.1 is not supported).
* **Authentication**: Configure based on your choice in [Step 1](#step-1-determine-your-authentication-method).
  * For SAT: Use `authenticationMethod: 'K8S-SAT'` and `authenticationData: !ref SAT-Token`.
  * For X.509: Configure `clientCert` and `clientKey` properties.
  * For no authentication: Omit authentication properties.

Create a YAML file named `azure-iot-operations.commissioning.yml` with the following content:

{% file src="<https://2355450750-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FGzXPesVecsUM1eHBfwea%2Fuploads%2Fgit-blob-d8eef18c975406d2a255f870b9e23ab0ee48dc23%2Fazure-iot-operations.commissioning.yml?alt=media>" %}

{% code title="azure-iot-operations.commissioning.yml" lineNumbers="true" expandable="true" %}

```yaml
metadata:
  name: Azure IoT Operations Integration
  version: 1.0.0
description: Bidirectional MQTT integration between Cybus Connectware and Azure IoT Operations
parameters:
  mqttHost:
    type: string
    description: Hostname or IP address of the Azure IoT Operations MQTT broker
  mqttPort:
    type: integer
    description: MQTT broker port (default 18883 for SAT authentication)
    default: 18883

definitions:
  SAT-Token: <Your SAT Token>
  ca-cert: <Your Cert>

resources:
  # MQTT Connection to Azure IoT Operations
  aioMqttConnection:
    type: Cybus::Connection
    properties:
      protocol: Mqtt
      connection:
        host: !ref mqttHost
        port: !ref mqttPort
        # Azure IoT Operations requires MQTT v5
        protocolVersion: 5
        # Only for TLS connections:
        caCert: !ref ca-cert # Use the provided CA certificate from Azure IoT Operations MQTT broker
        scheme: tls # Use MQTT over TLS for secure communication
        trustAllCertificates: true
        # Only for SAT authentication:
        authenticationMethod: 'K8S-SAT'
        authenticationData: !ref SAT-Token

  # Bidirectional Data Mapping
  mqttMap:
    type: Cybus::Mapping
    properties:
      mappings:
        # Azure IoT Operations → Cybus Connectware
        - subscribe:
            connection: !ref aioMqttConnection
            topic: 'topic/from/aio-broker'
          publish:
            topic: 'publish/to/cybus'
          rules:
            - transform:
                expression: |
                  {
                    "aioTimeStamp": $fromMillis($),
                    "cybusTimeStamp": $fromMillis($now()),
                    "payload": $
                  }

        # Cybus Connectware → Azure IoT Operations
        - subscribe:
            topic: 'subscribe/from/cybus'
          publish:
            connection: !ref aioMqttConnection
            topic: 'topic/to/aio-broker'
          rules:
            - transform:
                expression: |
                  {
                    "source": "cybus",
                    "timestamp": $fromMillis($now()),
                    "data": $
                  }
```

{% endcode %}

This service commissioning file configures a bidirectional MQTT connection that:

* Subscribes to `topic/from/aio-broker` in Azure IoT Operations and publishes to `publish/to/cybus` in Connectware.
* Subscribes to `subscribe/from/cybus` in Connectware and publishes to `topic/to/aio-broker` in Azure IoT Operations.

You can customize the topic names and data transformations to match your specific requirements.

## Step 4: Deploy the Service to Connectware

Once you have created the service commissioning file with the correct credentials, deploy it to Connectware.

For detailed instructions on how to install and enable service commissioning files, refer to the following documentation:

* [Installing Services](https://docs.cybus.io/documentation/services/setting-up-and-configuring-services/installing-services)
* [Enabling Services](https://docs.cybus.io/documentation/services/setting-up-and-configuring-services/enabling-services)

After deploying the service, proceed to verify that the connection is established.

## Step 5: Verify and Test the Integration

After deploying the service, verify that Connectware has successfully connected to Azure IoT Operations and test bidirectional data flow.

### Verify the Connection

1. Open the Connectware [Admin UI](https://docs.cybus.io/getting-started/admin-ui).
2. Navigate to the **Services** view and locate your Azure IoT Operations Integration service.
3. Check that the service status shows as **Enabled** and **No Deviation**.

### Test Bidirectional Data Flow

**From Connectware to Azure IoT Operations:**

1. Publish a test message to the Connectware topic `subscribe/from/cybus`.
2. Use an MQTT Explorer connected to Azure IoT Operations to subscribe to `topic/to/aio-broker`.
3. Verify the message appears with the transformed payload.

**From Azure IoT Operations to Connectware:**

1. Using an MQTT Explorer, publish a test message to `topic/from/aio-broker` in Azure IoT Operations.
2. In the Connectware Admin UI, subscribe to `publish/to/cybus`.
3. Verify the message appears with the transformed payload.

### Troubleshooting

If the connection or data flow fails, check the protocol mapper logs in the Admin UI's [Service Logs](https://docs.cybus.io/documentation/services/service-logs/service-logs-of-individual-services) section. Common issues include incorrect SAT tokens, network connectivity problems, or MQTT protocol version mismatches.