From efdb6a06d568644b35e51951dac2e2953d0eca3b Mon Sep 17 00:00:00 2001
From: Hugo Meyronneinc <hugomeyronneinc@gmail.com>
Date: Mon, 22 Mar 2021 11:42:35 +0100
Subject: [PATCH] chore: add documentation on the binding mqtt based on the
 pubsub mqtt options

---
 .../setup-bindings/supported-bindings/mqtt.md | 87 +++++++++++++++++--
 1 file changed, 82 insertions(+), 5 deletions(-)

diff --git a/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/mqtt.md b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/mqtt.md
index 236eb22a8..712819040 100644
--- a/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/mqtt.md
+++ b/daprdocs/content/en/operations/components/setup-bindings/supported-bindings/mqtt.md
@@ -21,9 +21,15 @@ spec:
   version: v1
   metadata:
   - name: url
-    value: mqtt[s]://[username][:password]@host.domain[:port]
+    value: "tcp://[username][:password]@host.domain[:port]"
   - name: topic
-    value: topic1
+    value: "topic1"
+  - name: qos
+    value: 1
+  - name: retain
+    value: "false"
+  - name: cleanSession
+    value: "false"
 ```
 {{% alert title="Warning" color="warning" %}}
 The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
@@ -31,10 +37,81 @@ The above example uses secrets as plain strings. It is recommended to use a secr
 
 ## Spec metadata fields
 
-| Field              | Required | Binding support |  Details | Example |
-|--------------------|:--------:|------------|-----|---------|
-| url | Y | Input/Output | The MQTT broker url | `"mqtt[s]://[username][:password]@host.domain[:port]"` |
+| Field              | Required | Binding support | Details | Example |
+|--------------------|:--------:|---------|---------|---------|
+| url    | Y  | Input/Output | Address of the MQTT broker  | Use `**tcp://**` scheme for non-TLS communication.   Use`**tcps://**` scheme for TLS communication.  <br> "tcp://[username][:password]@host.domain[:port]"
 | topic | Y | Input/Output | The topic to listen on or send events to | `"mytopic"` |
+| qos    | N  | Input/Output | Indicates the Quality of Service Level (QoS) of the message. Default 0|`1`
+| retain | N  | Input/Output | Defines whether the message is saved by the broker as the last known good value for a specified topic. Default `"false"`  | `"true"`, `"false"`
+| cleanSession | N | Input/Output | will set the "clean session" in the connect message when client connects to an MQTT broker. Default `"true"`  | `"true"`, `"false"`
+| caCert | Required for using TLS | Input/Output | Certificate authority certificate. Can be `secretKeyRef` to use a secret reference | `0123456789-0123456789`
+| clientCert | Required for using TLS | Input/Output | Client certificate. Can be `secretKeyRef` to use a secret reference | `0123456789-0123456789`
+| clientKey | Required for using TLS | Input/Output | Client key. Can be `secretKeyRef` to use a secret reference | `012345`
+
+### 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.
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: mqtt-binding
+  namespace: default
+spec:
+  type: bindings.mqtt
+  version: v1
+  metadata:
+  - name: url
+    value: "tcps://host.domain[:port]"
+  - name: topic
+    value: "topic1"
+  - name: qos
+    value: 1
+  - name: retain
+    value: "false"
+  - name: cleanSession
+    value: "false"
+  - name: caCert
+    value: ''
+  - name: clientCert
+    value: ''
+  - name: clientKey
+    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:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: messagebus
+  namespace: default
+spec:
+  type: bindings.mqtt
+  version: v1
+  metadata:
+  - name: consumerID
+    value: "{uuid}"
+  - name: url
+    value: "tcp://admin:public@localhost:1883"
+  - name: topic
+    value: "topic1"
+  - name: qos
+    value: 1
+  - name: retain
+    value: "false"
+  - name: cleanSession
+    value: "false"
+```
+
+{{% alert title="Warning" color="warning" %}}
+The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}).
+{{% /alert %}}
 
 ## Binding support