Azure IoT Operations

Microsoft Azure Message Queue

Synopsis

Creates an Azure IoT Operations target that publishes records as messages to the IoT Operations MQTT broker, signing in with a client certificate, a Kubernetes service account token or a username and password. Supports topics taken from record fields, MQTT 5 and a last will.

Each record goes as one message, always over TLS. The target works like the MQTT target, with the rules of the IoT Operations broker added.

The broker runs in your own Kubernetes cluster. To send to the cloud service Azure IoT Hub instead, use the Azure IoT Hub target.

Schema

- name: <string>
  description: <string>
  type: aziotoperations
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    endpoint: <string>
    authentication: <string>
    port: <integer>
    protocol_version: <string>
    client_id: <string>
    clean_session: <boolean>
    keep_alive: <integer>
    auto_reconnect: <boolean>
    token_file: <string>
    username: <string>
    password: <string>
    tls:
      verify: <boolean>
      ca_name: <string>
      cert_name: <string>
      key_name: <string>
      passphrase: <string>
      server_name: <string>
      min_tls_version: <string>
      max_tls_version: <string>
    topic: <string>
    topic_missing_field: <string>
    topic_fallback: <string>
    topic_default_value: <string>
    qos: <integer>
    retained: <boolean>
    will:
      status: <boolean>
      topic: <string>
      payload: <string>
      qos: <integer>
      retained: <boolean>
    batch_size: <integer>
    timeout: <integer>
    max_messages_per_second: <integer>
    max_retries: <integer>
    retry_delay: <integer>
    disable_retries: <boolean>
    field_format: <string>
    debug:
      status: <boolean>
      dont_send_logs: <boolean>

Configuration

The following fields are used to define the target:

Field	Required	Default	Description
`name`	Y		Target name
`description`	N	-	Optional description
`type`	Y		Must be `aziotoperations`
`pipelines`	N	-	Optional post-processor pipelines
`status`	N	`true`	Enable/disable the target

Connection

Field	Required	Default	Description
`endpoint`	Y	-	The host name or IP address of a listener of the broker: `aio-broker.azure-iot-operations` for a director in the same cluster, or the address of a LoadBalancer or NodePort listener. The address alone: no scheme, port or path. Plain text or an environment variable. In the console: Address
`authentication`	N	`certificate`	How the target signs in: `certificate`, `serviceaccount` or `password` (see Which Sign-in Fits Where). In the console: Authentication method (Client certificate (X.509), Service account token, Username and password)
`port`	N	`18883` with `serviceaccount`, `8883` otherwise	The port of the listener. 18883 is the broker's default listener. In the console: Port
`protocol_version`	N	`5`	`3.1.1` or `5`. `serviceaccount` needs `5`. In the console: Protocol version, not offered under Service account token
`client_id`	N	Generated	The MQTT client ID. In the console: Client ID
`clean_session`	N	`true`	In the console: Clean session
`keep_alive`	N	`60`	How often the target pings the broker while the connection is idle, in seconds. In the console: Keep-alive interval
`auto_reconnect`	N	`true`	Reconnects after a lost connection. Not in the console

TLS

TLS is always on, so there is no TLS switch.

Field	Required	Default	Description
`tls.ca_name`	N	-	The CA that issued the broker's certificate. For the default listener, that is the `ca.crt` entry of the `azure-iot-operations-aio-ca-trust-bundle` ConfigMap (see The CA of the Default Listener). Empty uses the system trust store. In the console: CA certificate
`tls.verify`	N	`true`	Checks the broker's certificate
`tls.server_name`, `tls.min_tls_version`, `tls.max_tls_version`	N	-	As for the MQTT target. Not in the console
`tls.cert_name`	Y, with `certificate`	-	The client certificate. Its content, a file path, an environment variable or a secret. In the console: Certificate
`tls.key_name`	Y, with `certificate`	-	The certificate's private key, in the same forms. In the console: Private key
`tls.passphrase`	N	-	The private key's passphrase, with `certificate` only. In the console: Passphrase

Service Account Token

With authentication: serviceaccount only.

Field	Required	Default	Description
`token_file`	N	`/var/run/secrets/tokens/broker-sat`	The file in the director's pod that holds the service account token (see The Service Account Token). In the console: Service account token file

Username and Password

With authentication: password only.

Field	Required	Default	Description
`username`	Y	-	Plain text, an environment variable or a secret. In the console: Username
`password`	N	-	Plain text, an environment variable or a secret. In the console: Password

Topic

Field	Required	Default	Description
`topic`	Y	-	The topic of each message. It can take part of its name from each record, as in `plant/{site}/telemetry`. See Topic per Record. In the console: Topic
`topic_missing_field`	N	`drop`	What happens to a record that lacks a field the topic names: `drop`, `fallback` or `default_value`, as for the MQTT target. In the console: the Missing topic field choice
`topic_fallback`	Y, with `fallback`	-	The topic such a record goes to when Missing topic field is `fallback`. In the console: Fallback topic
`topic_default_value`	N	`unknown`	The text that takes the place of a missing value when Missing topic field is `default_value`. In the console: Default value
`qos`	N	`1`	`0` or `1`; the broker has no QoS 2. In the console: Quality of service
`retained`	N	`false`	Publishes each message as a retained message. In the console: Retained messages

Azure IoT Operations Settings

Field	Required	Default	Description
`batch_size`	N	`1000`	The most records in one batch. In the console: Batch size
`timeout`	N	`30`	The seconds the connection, or one publish, may take. In the console: Timeout
`field_format`	N	-	The format each record is converted to before the target publishes it. See applicable Normalization section. In the console: Field format
`max_messages_per_second`	N	No limit	The most messages the target publishes in one second, all its workers together. `0` or no value means no limit. In the console: Maximum messages per second
`max_retries`	N	`3`	How often the target tries a failed message again. In the console: Maximum retries
`retry_delay`	N	`1`	The longest wait before the first retry, in seconds. The wait is random, and its limit doubles with each retry up to 30 seconds. In the console: Retry delay
`disable_retries`	N	`false`	`true` makes one attempt for each message, with no retry and no wait. A message that this attempt fails still goes back to the director, which delivers it again, as it does any failed send. In the console: Disable retries

Last Will

The will block.

Field	Required	Default	Description
`will.status`	N	`false`	The broker publishes the last will when the director drops off without closing its connection. In the console: the Last will switch
`will.topic`	Y, when the last will is on	-	It cannot hold `+`, `#` or a NUL character. In the console: Last will topic
`will.payload`	N	-	In the console: Last will payload
`will.qos`	N	`0`	`0` or `1`. In the console: Last will QoS
`will.retained`	N	`false`	In the console: Retained last will

Scheduling

See Scheduling and Pool Behavior for interval and cron fields shared by all targets.

Debug Options

Field	Required	Default	Description
`debug.status`	N	`false`	Enable debug logging
`debug.dont_send_logs`	N	`false`	Process logs but don't send to target (testing)

Details

Client certificate: any director, wherever it runs. It connects to a listener that the operator adds to the broker, usually a LoadBalancer listener on port 8883. That listener's authentication must have the X.509 method, and the broker must trust the CA that signed the client certificate.
Service account token: a director that runs as a pod in the broker's cluster. It connects to the broker's default listener, aio-broker.azure-iot-operations:18883, which needs no change. It sends its Kubernetes service account token with MQTT 5 enhanced authentication, so it needs MQTT 5, which is the default.
Username and password: a listener whose authentication asks a custom authentication server.

The broker's authorization rules must let the director publish to the topics that Topic builds. Without such a rule, the broker does not take the messages.

The CA of the Default Listener

The default listener's certificate comes from IoT Operations' own root CA, which is not in the system trust store. Its certificate is the ca.crt entry of a ConfigMap, which this command prints:

kubectl get configmap azure-iot-operations-aio-ca-trust-bundle -n azure-iot-operations -o jsonpath='{.data.ca\.crt}'

The Service Account Token

The token has to be in the director's pod, as a projected service account token whose audience the broker accepts. That is aio-internal on the default listener.

The Kubernetes manifest that the platform renders for a director does not carry the token. Add the following to the director's Deployment, and add it again each time you download the manifest again:

volumeMounts:            # in the director's container
  - name: broker-sat
    mountPath: /var/run/secrets/tokens
volumes:                 # in the pod spec
  - name: broker-sat
    projected:
      sources:
        - serviceAccountToken:
            path: broker-sat
            audience: aio-internal
            expirationSeconds: 86400

The broker drops a client whose token has expired. Kubernetes writes a new token to the file before then. The target reads the file each time it connects, and it looks at it once a minute while it is connected. When the token has changed, it signs in again on the open connection, so the connection stays up. If the broker refuses the new token, it drops the connection, and the target connects again with the token that the file holds by then.

The Broker's Limits

QoS 0 and 1 only: the broker refuses QoS 2, so qos: 2 and will.qos: 2 are configuration errors.
Under MQTT 5, the broker says how large a packet it takes when the director connects: between 4 MB and 256 MB, depending on its memory profile. The target drops a record whose message is larger, because the broker would refuse it every time and drop the connection. It counts the record as dropped, and the batch still succeeds. With debug on, the log names the reason.
Under MQTT 3.1.1, the broker does not state its limit, so the target drops nothing.

Examples

A Director in the Broker's Cluster

A director in the broker's cluster, on the default listener...

targets:
  - name: aio_in_cluster
    type: aziotoperations
    properties:
      endpoint: "aio-broker.azure-iot-operations"
      authentication: serviceaccount
      topic: "plant/telemetry"
      tls:
        ca_name: "$path{certs/aio-ca.crt}"

A Client Certificate

A client certificate, on a LoadBalancer listener...

targets:
  - name: aio_certificate
    type: aziotoperations
    properties:
      endpoint: "10.0.0.20"
      topic: "plant/{site}/telemetry"
      topic_missing_field: fallback
      topic_fallback: "plant/unknown/telemetry"
      tls:
        ca_name: "$path{certs/aio-ca.crt}"
        cert_name: "$path{certs/director.crt}"
        key_name: "$path{certs/director.key}"

A Username and Password

A username and password, kept in secrets...

targets:
  - name: aio_password
    type: aziotoperations
    properties:
      endpoint: "aio.example.com"
      authentication: password
      username: "$secret{aio-username}"
      password: "$secret{aio-password}"
      topic: "plant/telemetry"
      tls:
        ca_name: "$path{certs/aio-ca.crt}"

Troubleshooting

Configuration Errors

The director refuses a configuration it cannot use, with these messages:

endpoint is required for aziotoperations target: use the host name or the IP address of a listener of the MQTT broker, for example aio-broker.azure-iot-operations for a director in the same cluster; endpoint must be a host name or an IP address alone: leave out the scheme, the port and the path
authentication must be "certificate", "serviceaccount" or "password"
port must be between 1 and 65535
protocol_version must be "3.1.1" or "5"; protocol_version must be 5 when authentication is serviceaccount: the token is sent with MQTT 5 enhanced authentication
qos must be 0 or 1: the MQTT broker of Azure IoT Operations does not take QoS 2; will.qos must be 0 or 1: the MQTT broker of Azure IoT Operations does not take QoS 2
tls.cert_name and tls.key_name are required when authentication is certificate: the client certificate signs the target in to the broker
username is required when authentication is password
max_messages_per_second must be 0 or more
will.topic is required when will.status is on; will.topic must not contain the wildcard characters + or #, or a NUL character
The topic template's own checks, as for the MQTT target.

Errors While It Runs

failed to read the service account token: … and the service account token file "…" is empty mean the token is not in the file that Service account token file (token_file) names.
failed to load the TLS settings: … means the certificate, its key or the CA could not be read.
A dropped record, with debug on: … exceeded the largest packet that the broker takes.

Synopsis​

Schema​

Configuration​

Connection​

TLS​

Service Account Token​

Username and Password​

Topic​

Azure IoT Operations Settings​

Last Will​

Scheduling​

Debug Options​

Details​

Which Sign-in Fits Where​

The CA of the Default Listener​

The Service Account Token​

The Broker's Limits​

Examples​

A Director in the Broker's Cluster​

A Client Certificate​

A Username and Password​

Troubleshooting​

Configuration Errors​

Errors While It Runs​