MQTT3 binding spec

Detailed documentation on the MQTT3 binding component

Component format

To setup a MQTT3 binding create a component of type bindings.mqtt3. See this guide on how to create and apply a binding configuration.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: <NAME>
  5. spec:
  6.   type: bindings.mqtt3
  7.   version: v1
  8.   metadata:
  9.     - name: url
  10.       value: "tcp://[username][:password]@host.domain[:port]"
  11.     - name: topic
  12.       value: "mytopic"
  13.     - name: consumerID
  14.       value: "myapp"
  15.     # Optional
  16.     - name: retain
  17.       value: "false"
  18.     - name: cleanSession
  19.       value: "false"
  20.     - name: backOffMaxRetries
  21.       value: "0"
  22.     - name: direction
  23.       value: "input, output"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

Spec metadata fields

FieldRequiredBinding supportDetailsExample
urlYInput/OutputAddress of the MQTT broker. Can be secretKeyRef to use a secret reference.
Use the tcp:// URI scheme for non-TLS communication.
Use the ssl:// URI scheme for TLS communication.		“tcp://[username][:password]@host.domain[:port]”
topicYInput/OutputThe topic to listen on or send events to.“mytopic”
consumerIDYInput/OutputThe client ID used to connect to the MQTT broker.“myMqttClientApp”
retainNInput/OutputDefines whether the message is saved by the broker as the last known good value for a specified topic. Defaults to “false”.“true”, “false”
cleanSessionNInput/OutputSets the clean_session flag in the connection message to the MQTT broker if “true”. Defaults to “false”.“true”, “false”
caCertRequired for using TLSInput/OutputCertificate Authority (CA) certificate in PEM format for verifying server TLS certificates.See example below
clientCertRequired for using TLSInput/OutputTLS client certificate in PEM format. Must be used with clientKey.See example below
clientKeyRequired for using TLSInput/OutputTLS client key in PEM format. Must be used with clientCert. Can be secretKeyRef to use a secret reference.See example below
backOffMaxRetriesNInputThe maximum number of retries to process the message before returning an error. Defaults to “0”, which means that no retries will be attempted. “-1” can be specified to indicate that messages should be retried indefinitely until they are successfully processed or the application is shutdown. The component will wait 5 seconds between retries.“3”
directionNInput/OutputThe direction of the binding“input”, “output”, “input, output”

Communication using TLS

To configure communication using TLS, ensure that the MQTT broker (e.g. emqx) is configured to support certificates and provide the caCert, clientCert, clientKey metadata in the component configuration. For example:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: mqtt-binding
  5. spec:
  6.   type: bindings.mqtt3
  7.   version: v1
  8.   metadata:
  9.     - name: url
  10.       value: "ssl://host.domain[:port]"
  11.     - name: topic
  12.       value: "topic1"
  13.     - name: consumerID
  14.       value: "myapp"
  15.     # TLS configuration
  16.     - name: caCert
  17.       value: |
  18.         -----BEGIN CERTIFICATE-----
  19.         ...
  20.         -----END CERTIFICATE-----        
  21.     - name: clientCert
  22.       value: |
  23.         -----BEGIN CERTIFICATE-----
  24.         ...
  25.         -----END CERTIFICATE-----        
  26.     - name: clientKey
  27.       secretKeyRef:
  28.         name: myMqttClientKey
  29.         key: myMqttClientKey
  30.     # Optional
  31.     - name: retain
  32.       value: "false"
  33.     - name: cleanSession
  34.       value: "false"
  35.     - name: backoffMaxRetries
  36.       value: "0"

Note that while the caCert and clientCert values may not be secrets, they can be referenced from a Dapr secret store as well for convenience.

Consuming a shared topic

When consuming a shared topic, each consumer must have a unique identifier. If running multiple instances of an application, you configure the component’s consumerID metadata with a {uuid} tag, which will give each instance a randomly generated consumerID value on start up. For example:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: mqtt-binding
  5.   namespace: default
  6. spec:
  7.   type: bindings.mqtt3
  8.   version: v1
  9.   metadata:
  10.   - name: consumerID
  11.     value: "{uuid}"
  12.   - name: url
  13.     value: "tcp://admin:public@localhost:1883"
  14.   - name: topic
  15.     value: "topic1"
  16.   - name: retain
  17.     value: "false"
  18.   - name: cleanSession
  19.     value: "true"
  20.   - name: backoffMaxRetries
  21.     value: "0"

Warning

The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described here.

In this case, the value of the consumer ID is random every time Dapr restarts, so you should set cleanSession to true as well.

Binding support

This component supports both input and output binding interfaces.

This component supports output binding with the following operations:

  • create: publishes a new message

Set topic per-request

You can override the topic in component metadata on a per-request basis:

  1. {
  2.   "operation": "create",
  3.   "metadata": {
  4.     "topic": "myTopic"
  5.   },
  6.   "data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
  7. }

Set retain property per-request

You can override the retain property in component metadata on a per-request basis:

  1. {
  2.   "operation": "create",
  3.   "metadata": {
  4.     "retain": "true"
  5.   },
  6.   "data": "<h1>Testing Dapr Bindings</h1>This is a test.<br>Bye!"
  7. }

Last modified October 11, 2024: Fixed typo (#4389) (fe17926)