diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index c78eb34cc..b8fe5026e 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -16,7 +16,43 @@ Bindings are developed independently of Dapr runtime. You can view and contribut Every binding has its own unique set of properties. Click the name link to see the component YAML for each binding. -View the full list in the [Components-Contrib Repo](https://github.com/dapr/components-contrib/tree/master/bindings). +### Generic + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [HTTP](./specs/http.md) | | ✅ | Experimental | +| [Kafka](./specs/kafka.md) | ✅ | ✅ | Experimental | +| [Kubernetes Events](./kubernetes) | ✅ | | Experimental | +| [MQTT](./specs/mqtt.md) | ✅ | ✅ | Experimental | +| [RabbitMQ](./specs/rabbitmq.md) | ✅ | ✅ | Experimental | +| [Redis](./specs/redis.md) | | ✅ | Experimental | +| [Twilio](./specs/twilio.md) | | ✅ | Experimental | + +### Amazon Web Service (AWS) + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [AWS DynamoDB](./specs/dynamodb.md) | | ✅ | Experimental | +| [AWS S3](./specs/s3.md) | | ✅ | Experimental | +| [AWS SNS](./specs/sns.md) | | ✅ | Experimental | +| [AWS SQS](./specs/sqs.md) | ✅ | ✅ | Experimental | + +### Google Cloud Platform (GCP) + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [GCP Cloud Pub/Sub](./specs/gcppubsub.md) | ✅ | ✅ | Experimental | +| [GCP Storage Bucket](./specs/gcpbucket.md) | | ✅ | Experimental | + +### Microsoft Azure + +| Name | Input
Binding | Output
Binding | Status | +|------|:----------------:|:-----------------:|--------| +| [Azure Blob Storage](./specs/blobstorage.md) | | ✅ | Experimental | +| [Azure EventHubs](./specs/eventhubs.md) | ✅ | ✅ | Experimental | +| [Azure CosmosDB](./specs/cosmosdb.md) | | ✅ | Experimental | +| [Azure Service Bus Queues](./specs/servicebusqueues.md) | ✅ | ✅ | Experimental | +| [Azure SignalR](./specs/signalr.md) | | ✅ | Experimental | ## Input Bindings @@ -30,7 +66,7 @@ In order to receive events from an input binding: > On startup Dapr sends a ```OPTIONS``` request for all defined input bindings to the application and expects a different status code as ```NOT FOUND (404)``` if this application wants to subscribe to the binding. -Read the [How To](../../howto) section to get started with input bindings. +Read the [How To](../../howto/trigger-app-with-input-binding) section to get started with input bindings. ## Output Bindings @@ -42,4 +78,4 @@ In order to invoke an output binding: 1. Define the component YAML that describes the type of binding and its metadata (connection info, etc.) 2. Use the HTTP endpoint or gRPC method to invoke the binding with an optional payload - Read the [How To](../../howto) section to get started with output bindings. + Read the [How To](../../howto/send-events-with-output-bindings) section to get started with output bindings. diff --git a/concepts/bindings/specs/blobstorage.md b/concepts/bindings/specs/blobstorage.md new file mode 100644 index 000000000..3ecf11993 --- /dev/null +++ b/concepts/bindings/specs/blobstorage.md @@ -0,0 +1,21 @@ +# Azure Blob Storage Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.azure.blobstorage + metadata: + - name: storageAccount + value: myStorageAccountName + - name: storageAccessKey + value: *********** + - name: container + value: container1 +``` + +`storageAccount` is the Blob Storage account name. +`storageAccessKey` is the Blob Storage access key. +`container` is the name of the Blob Storage container to write to. diff --git a/concepts/bindings/specs/cosmosdb.md b/concepts/bindings/specs/cosmosdb.md new file mode 100644 index 000000000..3b1065344 --- /dev/null +++ b/concepts/bindings/specs/cosmosdb.md @@ -0,0 +1,27 @@ +# Azure CosmosDB Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.azure.cosmosdb + metadata: + - name: url + value: https://******.documents.azure.com:443/ + - name: masterKey + value: ***** + - name: database + value: db + - name: collection + value: collection + - name: partitionKey + value: message +``` + +`url` is the CosmosDB url. +`masterKey` is the CosmosDB account master key. +`database` is the name of the CosmosDB database. +`collection` is name of the collection inside the database. +`partitionKey` is the name of the partitionKey to extract from the payload. \ No newline at end of file diff --git a/concepts/bindings/specs/dynamodb.md b/concepts/bindings/specs/dynamodb.md new file mode 100644 index 000000000..21d8df581 --- /dev/null +++ b/concepts/bindings/specs/dynamodb.md @@ -0,0 +1,24 @@ +# AWS DynamoDB Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.aws.dynamodb + metadata: + - name: region + value: us-west-2 + - name: accessKey + value: ***************** + - name: secretKey + value: ***************** + - name: table + value: items +``` + +`region` is the AWS region. +`accessKey` is the AWS access key. +`secretKey` is the AWS secret key. +`table` is the DynamoDB table name. diff --git a/concepts/bindings/specs/eventhubs.md b/concepts/bindings/specs/eventhubs.md new file mode 100644 index 000000000..c4235aa96 --- /dev/null +++ b/concepts/bindings/specs/eventhubs.md @@ -0,0 +1,21 @@ +# Azure EventHubs Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.azure.eventhubs + metadata: + - name: connectionString # connectionString of EventHub, not namespace + value: Endpoint=sb://***************** + - name: consumerGroup # Optional + value: group1 + - name: messageAge + value: 5s # Optional. Golang duration +``` + +- `connectionString` is the [EventHubs connection string](https://docs.microsoft.com/en-us/azure/event-hubs/authorize-access-shared-access-signature). Note that this is the EventHub itself and not the EventHubs namespace. Make sure to use the child EventHub shared access policy connection string. +- `consumerGroup` is the name of an [EventHubs consumerGroup](https://docs.microsoft.com/en-us/azure/event-hubs/event-hubs-features#consumer-groups) to listen on. +- `messageAge` allows to receive messages that are not older than the specified age. diff --git a/concepts/bindings/specs/gcpbucket.md b/concepts/bindings/specs/gcpbucket.md new file mode 100644 index 000000000..bbc96843e --- /dev/null +++ b/concepts/bindings/specs/gcpbucket.md @@ -0,0 +1,45 @@ +# GCP Storage Bucket Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.gcp.bucket + metadata: + - name: bucket + value: mybucket + - name: type + value: service_account + - name: project_id + value: project_111 + - name: private_key_id + value: ************* + - name: client_email + value: name@domain.com + - name: client_id + value: '1111111111111111' + - name: auth_uri + value: https://accounts.google.com/o/oauth2/auth + - name: token_uri + value: https://oauth2.googleapis.com/token + - 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 + - name: private_key + value: PRIVATE KEY +``` + +`bucket` is the bucket 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. diff --git a/concepts/bindings/specs/gcppubsub.md b/concepts/bindings/specs/gcppubsub.md new file mode 100644 index 000000000..9150b9a34 --- /dev/null +++ b/concepts/bindings/specs/gcppubsub.md @@ -0,0 +1,48 @@ +# GCP Cloud Pub/Sub Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.gcp.pubsub + metadata: + - name: topic + value: topic1 + - name: subscription + value: subscription1 + - name: type + value: service_account + - name: project_id + value: project_111 + - name: private_key_id + value: ************* + - name: client_email + value: name@domain.com + - name: client_id + value: '1111111111111111' + - name: auth_uri + value: https://accounts.google.com/o/oauth2/auth + - name: token_uri + value: https://oauth2.googleapis.com/token + - 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 + - name: private_key + value: PRIVATE KEY +``` + +`topic` is the Pub/Sub topic name. +`subscription` is the Pub/Sub subscription 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. diff --git a/concepts/bindings/specs/http.md b/concepts/bindings/specs/http.md new file mode 100644 index 000000000..a1813d240 --- /dev/null +++ b/concepts/bindings/specs/http.md @@ -0,0 +1,18 @@ +# HTTP Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.http + metadata: + - name: url + value: http://something.com + - name: method + value: GET +``` + +`url` is the HTTP url to invoke. +`method` is the HTTP verb to use for the request. diff --git a/concepts/bindings/specs/kafka.md b/concepts/bindings/specs/kafka.md new file mode 100644 index 000000000..a3a7456be --- /dev/null +++ b/concepts/bindings/specs/kafka.md @@ -0,0 +1,33 @@ +# Kafka Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.kafka + metadata: + - name: topics # Optional. in use for input bindings + value: topic1,topic2 + - name: brokers + value: localhost:9092,localhost:9093 + - name: consumerGroup + value: group1 + - name: publishTopic # Optional. in use for output bindings + value: topic3 + - name: authRequired # Required. default: "true" + value: "false" + - name: saslUsername # Optional. + value: "user" + - name: saslPassword # Optional. + value: "password" +``` + +`topics` is a comma separated string of topics for an input binding. +`brokers` is a comma separated string of kafka brokers. +`consumerGroup` is a kafka consumer group to listen on. +`publishTopic` is the topic to publish for an output binding. +`authRequired` determines whether to use SASL authentication or not. +`saslUsername` is the SASL username for authentication. Only used if `authRequired` is set to `"true"`. +`saslPassword` is the SASL password for authentication. Only used if `authRequired` is set to `"true"`. diff --git a/concepts/bindings/specs/kubernetes.md b/concepts/bindings/specs/kubernetes.md new file mode 100644 index 000000000..0b238dd16 --- /dev/null +++ b/concepts/bindings/specs/kubernetes.md @@ -0,0 +1,15 @@ +# Kubernetes Events Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.kubernetes + metadata: + - name: namespace + value: default +``` + +`namespace` is the Kubernetes namespace to read events from. Default is `default`. diff --git a/concepts/bindings/specs/mqtt.md b/concepts/bindings/specs/mqtt.md new file mode 100644 index 000000000..8ee4ea36b --- /dev/null +++ b/concepts/bindings/specs/mqtt.md @@ -0,0 +1,18 @@ +# MQTT Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.mqtt + metadata: + - name: url + value: mqtt[s]://[username][:password]@host.domain[:port] + - name: topic + value: topic1 +``` + +`url` is the MQTT broker url. +`topic` is the topic to listen on or send events to. diff --git a/concepts/bindings/specs/rabbitmq.md b/concepts/bindings/specs/rabbitmq.md new file mode 100644 index 000000000..00588cf38 --- /dev/null +++ b/concepts/bindings/specs/rabbitmq.md @@ -0,0 +1,24 @@ +# RabbitMQ Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.rabbitmq + metadata: + - name: queueName + value: queue1 + - name: host + value: amqp://guest:guest@localhost:5672 + - name: durable + value: true + - name: deleteWhenUnused + value: false +``` + +`queueName` is the RabbitMQ queue name. +`host` is the RabbitMQ host address. +`durable` tells RabbitMQ to persist message in storage. +`deleteWhenUnused` enables or disables auto-delete. \ No newline at end of file diff --git a/concepts/bindings/specs/redis.md b/concepts/bindings/specs/redis.md new file mode 100644 index 000000000..a0ee05f4a --- /dev/null +++ b/concepts/bindings/specs/redis.md @@ -0,0 +1,18 @@ +# Redis Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.redis + metadata: + - name: redisHost + value:
:6379 + - name: redisPassword + value: ************** +``` + +`redisHost` is the Redis host address. +`redisPassword` is the Redis password. diff --git a/concepts/bindings/specs/s3.md b/concepts/bindings/specs/s3.md new file mode 100644 index 000000000..9813feb7b --- /dev/null +++ b/concepts/bindings/specs/s3.md @@ -0,0 +1,24 @@ +# AWS S3 Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.aws.s3 + metadata: + - name: region + value: us-west-2 + - name: accessKey + value: ***************** + - name: secretKey + value: ***************** + - name: bucket + value: mybucket +``` + +`region` is the AWS region. +`accessKey` is the AWS access key. +`secretKey` is the AWS secret key. +`table` is the name of the S3 bucket to write to. \ No newline at end of file diff --git a/concepts/bindings/specs/servicebusqueues.md b/concepts/bindings/specs/servicebusqueues.md new file mode 100644 index 000000000..a6a694593 --- /dev/null +++ b/concepts/bindings/specs/servicebusqueues.md @@ -0,0 +1,18 @@ +# Azure Service Bus Queues Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.azure.servicebusqueues + metadata: + - name: connectionString + value: sb://************ + - name: queueName + value: queue1 +``` + +`connectionString` is the Service Bus connection string. +`queueName` is the Service Bus queue name. diff --git a/concepts/bindings/specs/signalr.md b/concepts/bindings/specs/signalr.md new file mode 100644 index 000000000..72ff97a94 --- /dev/null +++ b/concepts/bindings/specs/signalr.md @@ -0,0 +1,46 @@ +# Azure SignalR Binding Spec + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.azure.signalr + metadata: + - name: connectionString + value: Endpoint=https://.service.signalr.net;AccessKey=;Version=1.0; + - name: hub # Optional + value: +``` + +The metadata `connectionString` contains the Azure SignalR connection string. +The optional `hub` metadata value defines the hub in which the message will be send. The hub can be dynamically defined as a metadata value when publishing to an output binding (key is "hub"). + +## Additional information + +By default the Azure SignalR output binding will broadcast messages to all connected users. To narrow the audience there are two options, both configurable in the Metadata property of the message: + +- group: will send the message to a specific Azure SignalR group +- user: will send the message to a specific Azure SignalR user + +Applications publishing to an Azure SignalR output binding should send a message with the following contract: + +```json +{ + "data": { + "Target": "", + "Arguments": [ + { + "sender": "dapr", + "text": "Message from dapr output binding" + } + ] + }, + "metadata": { + "group": "chat123" + } +} +``` + +For more information on integration Azure SignalR into a solution check the [documentation](https://docs.microsoft.com/en-us/azure/azure-signalr/) \ No newline at end of file diff --git a/concepts/bindings/specs/sns.md b/concepts/bindings/specs/sns.md new file mode 100644 index 000000000..d0722a5ee --- /dev/null +++ b/concepts/bindings/specs/sns.md @@ -0,0 +1,24 @@ +# AWS SNS Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.aws.sns + metadata: + - name: region + value: us-west-2 + - name: accessKey + value: ***************** + - name: secretKey + value: ***************** + - name: topicArn + value: mytopic +``` + +`region` is the AWS region. +`accessKey` is the AWS access key. +`secretKey` is the AWS secret key. +`topicArn` is the SNS topic name. diff --git a/concepts/bindings/specs/sqs.md b/concepts/bindings/specs/sqs.md new file mode 100644 index 000000000..85f6446da --- /dev/null +++ b/concepts/bindings/specs/sqs.md @@ -0,0 +1,24 @@ +# AWS SQS Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.aws.sqs + metadata: + - name: region + value: us-west-2 + - name: accessKey + value: ***************** + - name: secretKey + value: ***************** + - name: queueName + value: items +``` + +`region` is the AWS region. +`accessKey` is the AWS access key. +`secretKey` is the AWS secret key. +`queueName` is the SQS queue name. diff --git a/concepts/bindings/specs/twilio.md b/concepts/bindings/specs/twilio.md new file mode 100644 index 000000000..156f0b134 --- /dev/null +++ b/concepts/bindings/specs/twilio.md @@ -0,0 +1,24 @@ +# Twilio SMS Binding Spec + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.twilio.sms + metadata: + - name: toNumber # required. + value: 111-111-1111 + - name: fromNumber # required. + value: 222-222-2222 + - name: accountSid # required. + value: ***************** + - name: authToken # required. + value: ***************** +``` + +`toNumber` is the target number to send the sms to. +`fromNumber` is the sender phone number. +`accountSid` is the Twilio account SID. +`authToken` is the Twilio auth token.