MQTT binding spec

Detailed documentation on the MQTT binding component

Component format

To setup MQTT binding create a component of type bindings.mqtt. 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.   namespace: <NAMESPACE>
  6. spec:
  7.   type: bindings.mqtt
  8.   version: v1
  9.   metadata:
  10.   - name: url
  11.     value: "tcp://[username][:password]@host.domain[:port]"
  12.   - name: topic
  13.     value: "topic1"
  14.   - name: qos
  15.     value: 1
  16.   - name: retain
  17.     value: "false"
  18.   - name: cleanSession
  19.     value: "false"

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 brokerUse tcp:// scheme for non-TLS communication. Usessl:// scheme for TLS communication.
“tcp://[username][:password]@host.domain[:port]”
topicYInput/OutputThe topic to listen on or send events to“mytopic”
qosNInput/OutputIndicates the Quality of Service Level (QoS) of the message. Default 01
retainNInput/OutputDefines whether the message is saved by the broker as the last known good value for a specified topic. Default “false”“true”, “false”
cleanSessionNInput/Outputwill set the “clean session” in the connect message when client connects to an MQTT broker. Default “true”“true”, “false”
caCertRequired for using TLSInput/OutputCertificate authority certificate. Can be secretKeyRef to use a secret reference0123456789-0123456789
clientCertRequired for using TLSInput/OutputClient certificate. Can be secretKeyRef to use a secret reference0123456789-0123456789
clientKeyRequired for using TLSInput/OutputClient key. Can be secretKeyRef to use a secret reference012345

Communication using TLS

To configure communication using TLS, ensure mosquitto broker is configured to support certificates. Pre-requisite includes certficate authority certificate, ca issued client certificate, client private key. Here is an example.

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: mqtt-binding
  5.   namespace: default
  6. spec:
  7.   type: bindings.mqtt
  8.   version: v1
  9.   metadata:
  10.   - name: url
  11.     value: "ssl://host.domain[:port]"
  12.   - name: topic
  13.     value: "topic1"
  14.   - name: qos
  15.     value: 1
  16.   - name: retain
  17.     value: "false"
  18.   - name: cleanSession
  19.     value: "false"
  20.   - name: caCert
  21.     value: ''
  22.   - name: clientCert
  23.     value: ''
  24.   - name: clientKey
  25.     value: ''

Consuming a shared topic

When consuming a shared topic, each consumer must have a unique identifier. By default, the application Id is used to uniquely identify each consumer and publisher. In self-hosted mode, running each Dapr run with a different application Id is sufficient to have them consume from the same shared topic. However on Kubernetes, a pod with multiple application instances shares the same application Id, prohibiting all instances from consuming the same topic. To overcome this, configure the component’s ConsumerID metadata with a {uuid} tag, making each instance to have a randomly generated ConsumerID value on start up. For example:

  1. apiVersion: dapr.io/v1alpha1
  2. kind: Component
  3. metadata:
  4.   name: messagebus
  5.   namespace: default
  6. spec:
  7.   type: bindings.mqtt
  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: qos
  17.     value: 1
  18.   - name: retain
  19.     value: "false"
  20.   - name: cleanSession
  21.     value: "false"

Warning

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

Binding support

This component supports both input and output binding interfaces.

This component supports output binding with the following operations:

  • create

Last modified September 17, 2021 : Merge pull request #1757 from georgestevens99/1440SecretKeyRefExplanation (620a5f8)