From c601927d5c441392c6760a07a969a8b43b020f80 Mon Sep 17 00:00:00 2001 From: Mark Fussell Date: Tue, 12 Jan 2021 21:24:23 -0800 Subject: [PATCH] Reformating the pubsub components --- .../supported-pubsub/setup-apache-kafka.md | 4 +- .../supported-pubsub/setup-aws-snssqs.md | 98 +++++++------ .../supported-pubsub/setup-azure-eventhubs.md | 5 +- .../setup-azure-servicebus.md | 93 +++++++----- .../supported-pubsub/setup-gcp.md | 53 ++++--- .../supported-pubsub/setup-hazelcast.md | 60 ++++---- .../supported-pubsub/setup-mqtt.md | 138 ++++++++++-------- .../supported-pubsub/setup-nats-streaming.md | 112 +++++++------- .../supported-pubsub/setup-pulsar.md | 60 ++++---- 9 files changed, 330 insertions(+), 293 deletions(-) diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-apache-kafka.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-apache-kafka.md index c0f852204..b7e5d9001 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-apache-kafka.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-apache-kafka.md @@ -40,8 +40,8 @@ The above example uses secrets as plain strings. It is recommended to use a secr |--------------------|:--------:|---------|---------| | brokers | Y | Comma separated list of kafka brokers | `localhost:9092`, `dapr-kafka.myapp.svc.cluster.local:9092` | authRequired | N | Enable authentication on the Kafka broker. Defaults to `"false"`. |`"true"`, `"false"` -| saslUsername | N | Username used for authentication. Only required if authRequired is set to true | `"adminuser"` -| saslPassword | N | Password used for authentication. Can be `secretKeyRef` to use a secret reference. Only required if authRequired is set to true | `""`, `"KeFg23!"` +| saslUsername | N | Username used for authentication. Only required if authRequired is set to true. | `"adminuser"` +| saslPassword | N | Password used for authentication. Can be `secretKeyRef` to use a secret reference. Only required if authRequired is set to true. Can be `secretKeyRef` to use a secret reference | `""`, `"KeFg23!"` ## Create a Kafka instance diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-aws-snssqs.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-aws-snssqs.md index 696772dad..cbbb3b82e 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-aws-snssqs.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-aws-snssqs.md @@ -5,9 +5,56 @@ linkTitle: "AWS SNS/SQS" description: "Detailed documentation on the AWS SNS/SQS pubsub component" --- -This article describes configuring Dapr to use AWS SNS/SQS for pub/sub on local and Kubernetes environments. +## Component Format +To setup AWS SNS/SQS for pub/sub, you create a component of type `pubsub.snssqs`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. -## Setup SNS/SQS +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: snssqs-pubsub + namespace: default +spec: + type: pubsub.snssqs + version: v1 + metadata: + - name: accessKey + value: "AKIAIOSFODNN7EXAMPLE" + - name: secretKey + value: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY" + - name: region + value: "us-east-1" + - name: sessionToken + value: "TOKEN" + - name: messageVisibilityTimeout + value: 10 + - name: messageRetryLimit + value: 10 + - name: messageWaitTimeSeconds + value: 1 + - name: messageMaxNumber + value: 10 +``` + +{{% 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 %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| accessKey | Y | ID of the AWS account with appropriate permissions to SNS and SQS. Can be `secretKeyRef` to use a secret reference | `"AKIAIOSFODNN7EXAMPLE"` +| secretKey | Y | Secret for the AWS user. Can be `secretKeyRef` to use a secret reference |`"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"` +| region | Y | The AWS region to the instance. See this page for valid regions: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html. Ensure that SNS and SQS are available in that region.| `"us-east-1"` +| endpoint | N |AWS endpoint for the component to use. Only used for local development. The `endpoint` is unncessary when running against production AWS | `"http://localhost:4566"` +| sessionToken | N |AWS session token to use. A session token is only required if you are using temporary security credentials. | `"TOKEN"` +| messageVisibilityTimeout | N |Amount of time in seconds that a message is hidden from receive requests after it is sent to a subscriber. Default: `10` | `10` +| messageRetryLimit | N |Number of times to resend a message after processing of that message fails before removing that message from the queue. Default: `10` | `10` +| messageWaitTimeSeconds | N |amount of time to await receipt of a message before making another request. Default: `1` | `1` +| messageMaxNumber | N |maximum number of messages to receive from the queue at a time. Default: `10`, Maximum: `10` | `10` + +## Create an SNS/SQS instance {{< tabs "Self-Hosted" "Kubernetes" "AWS" >}} @@ -23,7 +70,7 @@ See [Authenticating to AWS]({{< ref authenticating-aws.md >}}) for information a apiVersion: dapr.io/v1alpha1 kind: Component metadata: - name: messagebus + name: snssqs-pubsub spec: type: pubsub.snssqs version: v1 @@ -31,7 +78,7 @@ spec: - name: endpoint value: http://localhost:4566 # Use us-east-1 for localstack - - name: awsRegion + - name: region value: us-east-1 ``` {{% /codetab %}} @@ -45,6 +92,7 @@ apiVersion: apps/v1 kind: Deployment metadata: name: localstack + namespace: default spec: # using the selector, we will expose the running deployments # this is how Kubernetes knows, that a given service belongs to a deployment @@ -84,51 +132,15 @@ spec: {{% codetab %}} In order to run in AWS, you should create an IAM user with permissions to the SNS and SQS services. -Use the account ID and account secret and plug them into the `awsAccountID` and `awsAccountSecret` -in the component metadata using kubernetes secrets. +Use the `AWS account ID` and `AWS account secret` and plug them into the `accessKey` and `secretKey` in the component metadata using Kubernetes secrets and `secretKeyRef`. {{% /codetab %}} {{< /tabs >}} -## Create a Dapr component - -The next step is to create a Dapr component for SNS/SQS. - -Create the following YAML file named `snssqs.yaml`: - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: - namespace: -spec: - type: pubsub.snssqs - version: v1 - metadata: - # ID of the AWS account with appropriate permissions to SNS and SQS - - name: accessKey - value: ********** - # Secret for the AWS user - - name: secretKey - value: ********** - # The AWS region you want to operate in. - # See this page for valid regions: https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/Concepts.RegionsAndAvailabilityZones.html - # Make sure that SNS and SQS are available in that region. - - name: region - value: us-east-1 -``` - -{{% 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 %}} - -## Apply the configuration - -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. - ## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) - [Pub/Sub building block]({{< ref pubsub >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [AWS SQS as subscriber to SNS](https://docs.aws.amazon.com/sns/latest/dg/sns-sqs-as-subscriber.html) - [AWS SNS API refernce](https://docs.aws.amazon.com/sns/latest/api/Welcome.html) - [AWS SQS API refernce](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/APIReference/Welcome.html) diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-eventhubs.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-eventhubs.md index 1d0b040a9..5f822cf4f 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-eventhubs.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-eventhubs.md @@ -36,9 +36,9 @@ The above example uses secrets as plain strings. It is recommended to use a secr | Field | Required | Details | Example | |--------------------|:--------:|---------|---------| -| connectionString | Y | Connection-string for the Event Hubs | `Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}` +| connectionString | Y | Connection-string for the Event Hubs | `"Endpoint=sb://{EventHubNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={EventHub}"` | storageAccountName | Y | Storage account name to use for the EventProcessorHost |`"myeventhubstorage"` -| storageAccountKey | Y | Storage account key to use for the EventProcessorHost | `"112233445566778899"` +| storageAccountKey | Y | Storage account key to use for the EventProcessorHost. Can be `secretKeyRef` to use a secret reference | `"112233445566778899"` | storageContainerName | Y | Storage container name for the storage account name. | `"myeventhubstoragecontainer"` @@ -56,7 +56,6 @@ For example, a Dapr app running on Kubernetes with `dapr.io/app-id: "myapp"` wil Note: Dapr passes the name of the Consumer group to the EventHub and so this is not supplied in the metadata. - ## Related links - [Basic schema for a Dapr component]({{< ref component-schema >}}) - Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-servicebus.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-servicebus.md index fddaeb2c1..0920abaa6 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-servicebus.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-azure-servicebus.md @@ -5,52 +5,45 @@ linkTitle: "Azure Service Bus" description: "Detailed documentation on the Azure Service Bus pubsub component" --- -## Setup Azure Service Bus - -Follow the instructions [here](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quickstart-topics-subscriptions-portal) on setting up Azure Service Bus Topics. - -## Create a Dapr component - -The next step is to create a Dapr component for Azure Service Bus. - -Create the following YAML file named `azuresb.yaml`: +## Component format +To setup Azure Event Hubs pubsub create a component of type `pubsub.azure.servicebus`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. ```yaml apiVersion: dapr.io/v1alpha1 kind: Component metadata: - name: - namespace: + name: servicebus-pubsub + namespace: default spec: type: pubsub.azure.servicebus version: v1 metadata: - - name: connectionString - value: # Required. - - name: timeoutInSec - value: # Optional. Default: "60". Timeout for sending messages and management operations. - - name: handlerTimeoutInSec - value: # Optional. Default: "60". Timeout for invoking app handler. - - name: disableEntityManagement - value: # Optional. Default: false. When set to true, topics and subscriptions do not get created automatically. - - name: maxDeliveryCount - value: # Optional. Defines the number of attempts the server will make to deliver a message. - - name: lockDurationInSec - value: # Optional. Defines the length in seconds that a message will be locked for before expiring. - - name: lockRenewalInSec - value: # Optional. Default: "20". Defines the frequency at which buffered message locks will be renewed. - - name: maxActiveMessages - value: # Optional. Default: "10000". Defines the maximum number of messages to be buffered or processing at once. - - name: maxActiveMessagesRecoveryInSec - value: # Optional. Default: "2". Defines the number of seconds to wait once the maximum active message limit is reached. - - name: maxConcurrentHandlers - value: # Optional. Defines the maximum number of concurrent message handlers - - name: prefetchCount - value: # Optional. Defines the number of prefetched messages (use for high throughput / low latency scenarios) - - name: defaultMessageTimeToLiveInSec - value: # Optional. - - name: autoDeleteOnIdleInSec - value: # Optional. + - name: connectionString # Required + value: "Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}" + - name: timeoutInSec # Optional + value: 60 + - name: handlerTimeoutInSec # Optional + value: 60 + - name: disableEntityManagement # Optional + value: "false" + - name: maxDeliveryCount # Optional + value: 3 + - name: lockDurationInSec # Optional + value: 60 + - name: lockRenewalInSec # Optional + value: 20 + - name: maxActiveMessages # Optional + value: 2000 + - name: maxActiveMessagesRecoveryInSec # Optional + value: 2 + - name: maxConcurrentHandlers # Optional + value: 10 + - name: prefetchCount # Optional + value: 5 + - name: defaultMessageTimeToLiveInSec # Optional + value: 10 + - name: autoDeleteOnIdleInSec # Optional + value: 10 ``` > __NOTE:__ The above settings are shared across all topics that use this component. @@ -59,9 +52,29 @@ spec: 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 %}} -## Apply the configuration +## Spec metadata fields -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| connectionString | Y | Connection-string for the Event Hubs | "`Endpoint=sb://{ServiceBusNamespace}.servicebus.windows.net/;SharedAccessKeyName={PolicyName};SharedAccessKey={Key};EntityPath={ServiceBus}`" +| timeoutInSec | N | Timeout for sending messages and management operations. Default: `60` |`30` +| handlerTimeoutInSec| N | Timeout for invoking app handler. # Optional. Default: `60` | `30` +| disableEntityManagement | N | When set to true, topics and subscriptions do not get created automatically. Default: `"false"` | `"true"`, `"false"` +| maxDeliveryCount | N |Defines the number of attempts the server will make to deliver a message. Default set by server| `10` +| lockDurationInSec | N |Defines the length in seconds that a message will be locked for before expiring. Default set by server | `30` +| lockRenewalInSec | N |Defines the frequency at which buffered message locks will be renewed. Default: `20`. | `20` +| maxActiveMessages | N |Defines the maximum number of messages to be buffered or processing at once. Default: `10000` | `2000` +| maxActiveMessagesRecoveryInSec | N |Defines the number of seconds to wait once the maximum active message limit is reached. Default: `2` | `10` +| maxConcurrentHandlers | N |Defines the maximum number of concurrent message handlers | `10` +| prefetchCount | N |Defines the number of prefetched messages (use for high throughput / low latency scenarios)| `5` +| defaultMessageTimeToLiveInSec | N |Default message time to live. | `10` +| autoDeleteOnIdleInSec | N |Time in seconds to wait before auto deleting messages. | `10` + +## Create an Azure Service Bus + +Follow the instructions [here](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-quickstart-topics-subscriptions-portal) on setting up Azure Service Bus Topics. ## Related links -- [Pub/Sub building block]({{< ref pubsub >}}) \ No newline at end of file +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- [Pub/Sub building block]({{< ref pubsub >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-gcp.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-gcp.md index 66bde32ff..d42767d49 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-gcp.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-gcp.md @@ -5,28 +5,20 @@ linkTitle: "GCP Pub/Sub" description: "Detailed documentation on the GCP Pub/Sub component" --- -## Setup GCP Pub/Sub - -Follow the instructions [here](https://cloud.google.com/pubsub/docs/quickstart-console) on setting up Google Cloud Pub/Sub system. - ## Create a Dapr component -The next step is to create a Dapr component for Google Cloud Pub/Sub - -Create the following YAML file named `messagebus.yaml`: +To setup GCP pubsub create a component of type `pubsub.gcp.pubsub`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration ```yaml apiVersion: dapr.io/v1alpha1 kind: Component metadata: - name: - namespace: + name: gcp-pubsub + namespace: default spec: type: pubsub.gcp.pubsub version: v1 metadata: - - name: topic - value: - name: type value: service_account - name: project_id @@ -44,33 +36,38 @@ spec: - name: auth_provider_x509_cert_url value: https://www.googleapis.com/oauth2/v1/certs - name: client_x509_cert_url - value: https://www.googleapis.com/robot/v1/metadata/x509/.iam.gserviceaccount.com + value: https://www.googleapis.com/robot/v1/metadata/x509/.iam.gserviceaccount.com #replace PROJECT_NAME - name: private_key - value: # replace x509 cert here + value: # replace x509 cert - name: disableEntityManagement - value: # Optional. Default: false. When set to true, topics and subscriptions do not get created automatically. + value: "false" ``` -- `topic` is the Pub/Sub topic name. -- `type` is the GCP credentials type. -- `project_id` is the GCP project id. -- `private_key_id` is the GCP private key id. -- `client_email` is the GCP client email. -- `client_id` is the GCP client id. -- `auth_uri` is Google account OAuth endpoint. -- `token_uri` is Google account token uri. -- `auth_provider_x509_cert_url` is the GCP credentials cert url. -- `client_x509_cert_url` is the GCP credentials project x509 cert url. -- `private_key` is the GCP credentials private key. -- `disableEntityManagement` Optional. Default: false. When set to true, topics and subscriptions do not get created automatically. +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| type | Y | GCP credentials type | `service_account` +| project_id | Y | GCP project id| `projectId` +| private_key_id | Y | GCP private key id | `"privateKeyId"` +| private_key | Y | GCP credentials private key. Replace with x509 cert | `12345-12345` +| client_email | Y | GCP client email | `"client@email.com"` +| client_id | Y | GCP client id | `0123456789-0123456789` +| auth_uri | Y | Google account OAuth endpoint | `https://accounts.google.com/o/oauth2/auth` +| token_uri | Y | Google account token uri | `https://oauth2.googleapis.com/token` +| auth_provider_x509_cert_url | Y | GCP credentials cert url | `https://www.googleapis.com/oauth2/v1/certs` +| client_x509_cert_url | Y | GCP credentials project x509 cert url | `https://www.googleapis.com/robot/v1/metadata/x509/.iam.gserviceaccount.com` +| disableEntityManagement | N | When set to `"true"`, topics and subscriptions do not get created automatically. Default: `"false"` | `"true"`, `"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 %}} -## Apply the configuration +## Create a GCP Pub/Sub -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. +Follow the instructions [here](https://cloud.google.com/pubsub/docs/quickstart-console) on setting up Google Cloud Pub/Sub system. ## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [Pub/Sub building block]({{< ref pubsub >}}) \ No newline at end of file diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-hazelcast.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-hazelcast.md index 90684ccc2..8fc2b78ae 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-hazelcast.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-hazelcast.md @@ -5,7 +5,35 @@ linkTitle: "Hazelcast" description: "Detailed documentation on the Hazelcast pubsub component" --- -## Setup Hazelcast +## Component format +To setup hazelcast pubsub create a component of type `pubsub.hazelcast`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: hazelcast-pubsub + namespace: default +spec: + type: pubsub.hazelcast + version: v1 + metadata: + - name: hazelcastServers + value: "hazelcast:3000,hazelcast2:3000" +``` + +{{% 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 %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| connectionString | Y | A comma delimited string of servers. Example: "hazelcast:3000,hazelcast2:3000" | `"hazelcast:3000,hazelcast2:3000"` + + +## Create a Hazelcast instance {{< tabs "Self-Hosted" "Kubernetes">}} @@ -25,33 +53,7 @@ The easiest way to install Hazelcast on Kubernetes is by using the [Helm chart]( {{< /tabs >}} -## Create a Dapr component - -The next step is to create a Dapr component for Hazelcast. - -Create the following YAML file named `hazelcast.yaml`: - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: - namespace: -spec: - type: pubsub.hazelcast - version: v1 - metadata: - - name: hazelcastServers - value: # Required. A comma delimited string of servers. Example: "hazelcast:3000,hazelcast2:3000" -``` - -{{% 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 %}} - -## Apply the configuration - -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. - ## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [Pub/Sub building block]({{< ref pubsub >}}) \ No newline at end of file diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-mqtt.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-mqtt.md index 150bde6c0..ab2d6f97f 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-mqtt.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-mqtt.md @@ -5,7 +5,78 @@ linkTitle: "MQTT" description: "Detailed documentation on the MQTT pubsub component" --- -## Setup MQTT +## Create a Dapr component + +To setup Azure Event Hubs pubsub create a component of type `pubsub.mqtt`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: mqtt-pubsub + namespace: default +spec: + type: pubsub.mqtt + version: v1 + metadata: + - name: url + value: "tcp://[username][:password]@host.domain[:port]" + - name: qos + value: 1 + - name: retain + value: "false" + - name: cleanSession + value: "false" +``` +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| url | Y | Address of the MQTT broker | Use `**tcp://**` scheme for non-TLS communication. Use`**tcps://**` scheme for TLS communication.
"tcp://[username][:password]@host.domain[:port]" +| qos | N | Indicates the Quality of Service Level (QoS) of the message. Default 0|`1` +| retain | N | 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 | 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 | Certificate authority certificate. Can be `secretKeyRef` to use a secret reference | `0123456789-0123456789` +| clientCert | Required for using TLS | Client certificate. Can be `secretKeyRef` to use a secret reference | `0123456789-0123456789` +| clientKey | Required for using TLS | 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-pubsub + namespace: default +spec: + type: pubsub.mqtt + metadata: + - name: url + value: "tcps://host.domain[:port]" + - name: qos + value: 1 + - name: retain + value: "false" + - name: cleanSession + value: "false" + - name: caCert + value: '' + - name: clientCert + value: '' + - name: clientKey + value: '' +``` + +{{% 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 %}} + + +## Create a MQTT broker {{< tabs "Self-Hosted" "Kubernetes">}} @@ -75,68 +146,7 @@ You can then interact with the server using the client port: `tcp://mqtt-broker. {{< /tabs >}} -## Create a Dapr component - -The next step is to create a Dapr component for MQTT. - -Create the following yaml file named `mqtt.yaml` - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: - namespace: -spec: - type: pubsub.mqtt - version: v1 - metadata: - - name: url - value: "tcp://[username][:password]@host.domain[:port]" - - name: qos - value: 1 - - name: retain - value: "false" - - name: cleanSession - value: "false" -``` - -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`. -Make following additional changes to mqtt pubsub components for supporting TLS. -```yaml -... -spec: - type: pubsub.mqtt - metadata: - - name: url - value: "tcps://host.domain[:port]" - - name: caCert - value: '' - - name: clientCert - value: '' - - name: clientKey - value: '' -``` - -Where: -- **url** (required) is the address of the MQTT broker. -- - use **tcp://** scheme for non-TLS communication. -- - use **tcps://** scheme for TLS communication. -- **qos** (optional) indicates the Quality of Service Level (QoS) of the message. (Default 0) -- **retain** (optional) defines whether the message is saved by the broker as the last known good value for a specified topic. (Default false) -- **cleanSession** (optional) will set the "clean session" in the connect message when client connects to an MQTT broker . (Default true) -- **caCert** (required for using TLS) is the certificate authority certificate. -- **clientCert** (required for using TLS) is the client certificate. -- **clientKey** (required for using TLS) is the client key. - -{{% 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 %}} - -## Apply the configuration - -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. - ## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [Pub/Sub building block]({{< ref pubsub >}}) \ No newline at end of file diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-nats-streaming.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-nats-streaming.md index 0cb33ebea..30ab1d8df 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-nats-streaming.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-nats-streaming.md @@ -5,7 +5,61 @@ linkTitle: "NATS streaming" description: "Detailed documentation on the NATS pubsub component" --- -## Setup NATS +## Component format +To setup NATS streaming pubsub create a component of type `pubsub.natsstreaming`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: natsstreaming-pubsub + namespace: default +spec: + type: pubsub.natsstreaming + version: v1 + metadata: + - name: natsURL + value: "nats://localhost:4222" + - name: natsStreamingClusterID + value: "clusterId" + # below are subscription configuration. + - name: subscriptionType + value: # Required. Allowed values: topic, queue. + - name: deliverNew + value: true + # - name: ackWaitTime + # value: "" # Optional. See: https://docs.nats.io/developing-with-nats-streaming/acks#acknowledgements + # - name: maxInFlight + # value: "" # Optional. See: https://docs.nats.io/developing-with-nats-streaming/acks#acknowledgements + # - name: durableSubscriptionName + # value: "" + # following subscription options - only one can be used + # - name: startAtSequence + # value: 1 + # - name: startWithLastReceived + # value: false + # - name: deliverAll + # value: false + # - name: startAtTimeDelta + # value: "" + # - name: startAtTime + # value: "" + # - name: startAtTimeFormat + # value: "" +``` + +{{% 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 %}} + +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| natsURL | Y | NATS server address URL | "`nats://localhost:4222`" +| natsStreamingClusterID | Y | NATS cluster ID |`"clusterId"` + +## Create a NATS server {{< tabs "Self-Hosted" "Kubernetes">}} @@ -40,59 +94,7 @@ For example, if installing using the example above, the NATS Streaming address w {{< /tabs >}} -## Create a Dapr component - -The next step is to create a Dapr component for NATS-Streaming. - -Create the following YAML file named `nats-stan.yaml`: - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: - namespace: -spec: - type: pubsub.natsstreaming - version: v1 - metadata: - - name: natsURL - value: # Required. example nats://localhost:4222 - - name: natsStreamingClusterID - value: # Required. - # blow are subscription configuration. - - name: subscriptionType - value: # Required. Allowed values: topic, queue. - - name: deliverNew - value: true - # - name: ackWaitTime - # value: "" # Optional. See: https://docs.nats.io/developing-with-nats-streaming/acks#acknowledgements - # - name: maxInFlight - # value: "" # Optional. See: https://docs.nats.io/developing-with-nats-streaming/acks#acknowledgements - # - name: durableSubscriptionName - # value: "" - # following subscription options - only one can be used - # - name: startAtSequence - # value: 1 - # - name: startWithLastReceived - # value: false - # - name: deliverAll - # value: false - # - name: startAtTimeDelta - # value: "" - # - name: startAtTime - # value: "" - # - name: startAtTimeFormat - # value: "" -``` - -{{% 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 %}} - -## Apply the configuration - -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. - ## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [Pub/Sub building block]({{< ref pubsub >}}) diff --git a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-pulsar.md b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-pulsar.md index 90fca4c45..4e40dcba0 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-pulsar.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/supported-pubsub/setup-pulsar.md @@ -5,7 +5,34 @@ linkTitle: "Pulsar" description: "Detailed documentation on the Pulsar pubsub component" --- -## Setup Pulsar +## Component format +To setup Pulsar pubsub create a component of type `pubsub.pulsar`. See [this guide]({{< ref "howto-publish-subscribe.md#step-1-setup-the-pubsub-component" >}}) on how to create and apply a pubsub configuration. + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: pulsar-pubsub + namespace: default +spec: + type: pubsub.pulsar + version: v1 + metadata: + - name: host + value: "localhost:6650" + - name: enableTLS + value: "false" + +``` +## Spec metadata fields + +| Field | Required | Details | Example | +|--------------------|:--------:|---------|---------| +| host | Y | Address of the Pulsar broker. Default is `"localhost:6650"` | `"localhost:6650"` +| enableTLS | Y | Enable TLS. Default: `"false"` | `"true"`, `"false"` + + +## Create a Pulsar instance {{< tabs "Self-Hosted" "Kubernetes">}} @@ -23,37 +50,12 @@ docker run -it \ {{% /codetab %}} {{% codetab %}} -Please refer to the following [Helm chart](https://pulsar.apache.org/docs/en/kubernetes-helm/) Documentation. +Refer to the following [Helm chart](https://pulsar.apache.org/docs/en/kubernetes-helm/) Documentation. {{% /codetab %}} {{< /tabs >}} -## Create a Dapr component - -The next step is to create a Dapr component for Pulsar. - -Create the following YAML file named pulsar.yaml: - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: - namespace: -spec: - type: pubsub.pulsar - version: v1 - metadata: - - name: host - value: #default is localhost:6650 - - name: enableTLS - value: - -``` - -## Apply the configuration - -Visit [this guide]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components. - ## Related links +- [Basic schema for a Dapr component]({{< ref component-schema >}}) +- Read [this topic]({{< ref "howto-publish-subscribe.md#step-2-publish-a-topic" >}}) for instructions on configuring pub/sub components - [Pub/Sub building block]({{< ref pubsub >}}) \ No newline at end of file