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)