From 201cd400898f6965e372fff4fabf97ca91d06ff1 Mon Sep 17 00:00:00 2001 From: Lynn Orrell Date: Tue, 5 May 2020 17:45:54 -0500 Subject: [PATCH 1/9] Added Event Grid binding spec (#569) --- reference/specs/bindings/eventgrid.md | 67 +++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 reference/specs/bindings/eventgrid.md diff --git a/reference/specs/bindings/eventgrid.md b/reference/specs/bindings/eventgrid.md new file mode 100644 index 000000000..c6f1c4d8e --- /dev/null +++ b/reference/specs/bindings/eventgrid.md @@ -0,0 +1,67 @@ +# Azure Event Grid Binding Spec + +See [this](https://docs.microsoft.com/en-us/azure/event-grid/) for Azure Event Grid documentation. + +```yml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: +spec: + type: bindings.azure.eventgrid + metadata: + # Required Input Binding Metadata + - name: tenantId + value: "[AzureTenantId]" + - name: subscriptionId + value: "[AzureSubscriptionId]" + - name: clientId + value: "[ClientId]" + - name: clientSecret + value: "[ClientSecret]" + - name: subscriberEndpoint + value: "[SubscriberEndpoint]" + - name: handshakePort + value: [HandshakePort] + - name: scope + value: "[Scope]" + + # Optional Input Binding Metadata + - name: eventSubscriptionName + value: "[EventSubscriptionName]" + + # Required Output Binding Metadata + - name: accessKey + value: "[AccessKey]" + - name: topicEndpoint + value: "[TopicEndpoint] +``` + +## Input Binding Metadata +- `tenantId` is the Azure tenant id in which this Event Grid Event Subscription should be created + +- `subscriptionId` is the Azure subscription id in which this Event Grid Event Subscription should be created + +- `clientId` is the client id that should be used by the binding to create or update the Event Grid Event Subscription + +- `clientSecret` is the client secret that should be used by the binding to create or update the Event Grid Event Subscription + +- `subscriberEndpoint` is the https (required) endpoint in which Event Grid will handshake and send Cloud Events. If you aren't re-writing URLs on ingress, it should be in the form of: `https://[YOUR HOSTNAME]/api/events` If testing on your local machine, you can use something like [ngrok](https://ngrok.com) to create a public endpoint. + +- `handshakePort` is the container port that the input binding will listen on for handshakes and events + +- `scope` is the identifier of the resource to which the event subscription needs to be created or updated. The scope can be a subscription, or a resource group, or a top level resource belonging to a resource provider namespace, or an Event Grid topic. For example: + - '/subscriptions/{subscriptionId}/' for a subscription + - '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}' for a resource group + - '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}' for a resource + - '/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.EventGrid/topics/{topicName}' for an Event Grid topic + > Values in braces {} should be replaced with actual values. + +- `eventSubscriptionName` (Optional) is the name of the event subscription. Event subscription names must be between 3 and 64 characters in length and should use alphanumeric letters only. + +## Output Binding Metadata +- `accessKey` is the Access Key to be used for publishing an Event Grid Event to a custom topic + +- `topicEndpoint` is the topic endpoint in which this output binding should publish events + +> **Note:** In production never place passwords or secrets within Dapr components. For information on securely storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store) From c699217a31f8a23a63fb13550c149245e33d2ef7 Mon Sep 17 00:00:00 2001 From: Yaron Schneider Date: Tue, 5 May 2020 15:47:51 -0700 Subject: [PATCH 2/9] Update README.md (#570) Update Event Grid index --- concepts/bindings/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index 88110c3d8..3fd514217 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -57,6 +57,7 @@ Every binding has its own unique set of properties. Click the name link to see t | [Azure Service Bus Queues](../../reference/specs/bindings/servicebusqueues.md) | ✅ | ✅ | Experimental | | [Azure SignalR](../../reference/specs/bindings/signalr.md) | | ✅ | Experimental | | [Azure Storage Queues](../../reference/specs/bindings/storagequeues.md) | ✅ | ✅ | Experimental | +| [Azure Event Grid](../../reference/specs/bindings/eventgrid.md) | ✅ | ✅ | Experimental | ## Input bindings From e14d0d0d84df019bfda7cb229cb148a8a2d4afb5 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 5 May 2020 20:09:14 -0700 Subject: [PATCH 3/9] Adding guidance to How To article contribution --- contributing/README.md | 17 +++++-- contributing/howto-template.md | 82 ++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+), 3 deletions(-) create mode 100644 contributing/howto-template.md diff --git a/contributing/README.md b/contributing/README.md index 53903f015..49f0f4133 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -5,6 +5,7 @@ High quality documentation is a core tenant of the Dapr project. Some contributi ## Style and tone - Use sentence-casing for headers. +- When referring to product names and technologies use capitalization (e.g. Kubernetes, Helm, Visual Studio Code, Azure Key Vault and of course Dapr). - Check the spelling and grammar in your articles. - Use a casual and friendly voice—like tone as if you're talking to another person one-on-one. - Use simple sentences. Easy-to-read sentences mean the reader can quickly use the guidance you share. @@ -13,7 +14,7 @@ High quality documentation is a core tenant of the Dapr project. Some contributi - Avoid the word “we”. We is generally not meaningful. We who? - Avoid the word “please”. This is not a letter asking for any help, this is technical documentation. - Assume a new developer audience. Some obvious steps can seem hard. E.g. Now set an environment variable DAPR to a value X. It is better to give the reader the explicit command to do this, rather than having them figure this out. -- Where possible give the reader links to next document/article for next steps. +- Where possible give the reader links to next document/article for next steps or related topics (this can be relevant "how-to", samples for reference or concepts). # Contributing to `Concepts` @@ -26,5 +27,15 @@ High quality documentation is a core tenant of the Dapr project. Some contributi # Contributing to `How-Tos` -- These should be practical. -- Include code/sample/config snippets that can be copy and pasted. +See [this template](./howto-template.md) for `How To` articles. + +- `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario. +- Location - `How To` articles should all be under the [howto](.\howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory. +- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces* +- Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all. +- How to articles should include the following sub sections: + - **Pre-requesties** + - **\** times X as needed + - **Cleanup** + - **Related links** +- Include code/sample/config snippets that can be easily copied and pasted. diff --git a/contributing/howto-template.md b/contributing/howto-template.md new file mode 100644 index 000000000..483c19c91 --- /dev/null +++ b/contributing/howto-template.md @@ -0,0 +1,82 @@ +# [Title] + +>Title should be descriptive of what this article helps achieve. Imagine it continues a sentence that starts with ***How to...*** so should start with a word such as "Setup", "Configure", "Implement" etc. +> +>Does not need to include the word *Dapr* in it (as it is in the context of the Dapr docs repo) +> +>If it is specific to an environment (e.g. Kubernetes), should call out the environment. +> +>Capital letters only for first word and product/technology names. +> +>Example: +># Set up Zipkin for distributed tracing in Kubernetes + +[Intro paragraph] + +> Intro paragraph should be a short description of what this article covers to set expectations of the reader. Include links if they can provide context and clarity to the reader. +> +> Example: +> +> This article will provide guidance on how to enable Dapr distributed tracing capabilities on Kubernetes using [Zipkin](https://zipkin.io/) as a tracing broker. + +## Pre-requisites + +>List the required setup this article assumes with links on how to achieve each prerequisite. +> +>Example: +> +> - [Setup Dapr on a Kubernetes cluster](https://github.com/dapr/docs/blob/master/getting-started/environment-setup.md#installing-dapr-on-a-kubernetes-cluster) +> - [Install Helm](https://helm.sh/docs/intro/install/) +> - [Install Python](https://www.python.org/downloads/) version >= 3.7 + +## [Step header] - (multiple) + +> +>Name each step section in a clear descriptive way which allows readers to understand what this section covers. Example: **Create a configuration file** +> +>If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions defer, make sure to include instructions for each. +> +>Example (note the indentation of the commands): +> +>- Clone the Dapr samples repository: +> ```bash +> git clone https://github.com/dapr/samples.git +> ``` +>- Go to the hello world sample: +> ``` +> cd 1.hello-world +> ``` +> +>Add sections as needed for multiple steps. +> + +## Cleanup + +> +> If possible, provide steps that undo the steps above. These should bring the user environment back to the pre-requisites stage. If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions defer, make sure to include instructions for each. +> +>Example: +> +>1. Delete the deployments from the cluster +> ``` +> kubectl delete -f file.yaml +> ``` +>2. Delete the Helm chart from the cluster +> ``` +> helm del --purge dapr-kafka +> ``` +> + +## Related links + +> +> Reference other documentation that may be relevant to a user interested in this How To. Include any of the following: +> +>- Other **How To** articles in related topics or alternative technology integrations. +>- **Concept** articles that are relevant. +>- **Reference** and **API** documentation that can be helpful +>- **Samples** that provide code reference relevant to this guidance. +>- Any other documentation link that may be a logical next step for a reader interested in this guidance (for example, if this is a how to on publishing to a pub/sub topic, a logical next step would be a how to which describes consuming from a topic). +> + + From 34533bbea54d2aa5ebcab54274471d15a53d5edd Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 5 May 2020 20:14:26 -0700 Subject: [PATCH 4/9] fix link --- contributing/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/README.md b/contributing/README.md index 49f0f4133..74d29da8c 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -30,8 +30,8 @@ High quality documentation is a core tenant of the Dapr project. Some contributi See [this template](./howto-template.md) for `How To` articles. - `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario. -- Location - `How To` articles should all be under the [howto](.\howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory. -- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces* +- Location - `How To` articles should all be under the [howto](../howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory. +- Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces*. - Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all. - How to articles should include the following sub sections: - **Pre-requesties** From e9e3d8ccda11ecd057e273fb70578972e60fdf67 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 5 May 2020 20:18:16 -0700 Subject: [PATCH 5/9] Adding guidance for interlinking --- contributing/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/contributing/README.md b/contributing/README.md index 74d29da8c..92e489ffc 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -32,6 +32,7 @@ See [this template](./howto-template.md) for `How To` articles. - `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario. - Location - `How To` articles should all be under the [howto](../howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory. - Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces*. +- When adding a new article make sure to add a link in the main [How To README.md](../README.md) as well as other articles or samples that may be relevant. - Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all. - How to articles should include the following sub sections: - **Pre-requesties** From cafc86e777e07f7c272599082fc40d6e3011680d Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 5 May 2020 20:20:19 -0700 Subject: [PATCH 6/9] Fixing link --- contributing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/contributing/README.md b/contributing/README.md index 92e489ffc..3db8846f5 100644 --- a/contributing/README.md +++ b/contributing/README.md @@ -32,7 +32,7 @@ See [this template](./howto-template.md) for `How To` articles. - `How To` articles are meant to provide step-by-step practical guidance on to readers who wish to enable a feature, integrate a technology or use Dapr in a specific scenario. - Location - `How To` articles should all be under the [howto](../howto) directory in a relevant sub directories - make sure to see if the article you are contributed should be included in an existing sub directory. - Sub directory naming - the directory name should be descriptive and if referring to specific component or concept should begin with the relevant name. Example *pubsub-namespaces*. -- When adding a new article make sure to add a link in the main [How To README.md](../README.md) as well as other articles or samples that may be relevant. +- When adding a new article make sure to add a link in the main [How To README.md](../howto/README.md) as well as other articles or samples that may be relevant. - Do not assume the reader is using a specific environment unless the article itself is specific to an environment. This include OS (Windows/Linux/MacOS), deployment target (Kubernetes, IoT etc.) or programming language. If instructions vary between operating systems, provide guidance for all. - How to articles should include the following sub sections: - **Pre-requesties** From 2d9dc0bb36a1561f241afefefce05f5ff887edd5 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Tue, 5 May 2020 20:22:53 -0700 Subject: [PATCH 7/9] Typo fix --- contributing/howto-template.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/contributing/howto-template.md b/contributing/howto-template.md index 483c19c91..d43cdb084 100644 --- a/contributing/howto-template.md +++ b/contributing/howto-template.md @@ -34,7 +34,7 @@ > >Name each step section in a clear descriptive way which allows readers to understand what this section covers. Example: **Create a configuration file** > ->If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions defer, make sure to include instructions for each. +>If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions differ, make sure to include instructions for each. > >Example (note the indentation of the commands): > @@ -53,7 +53,7 @@ ## Cleanup > -> If possible, provide steps that undo the steps above. These should bring the user environment back to the pre-requisites stage. If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions defer, make sure to include instructions for each. +> If possible, provide steps that undo the steps above. These should bring the user environment back to the pre-requisites stage. If using terminal commands, make sure to allow easy copy/paste by having each terminal command in a separate line with the markdown (indented as needed when appearing in bullets or numbered lists). If Windows/Linux/MacOS instructions differ, make sure to include instructions for each. > >Example: > From 2d1138ec92b02020ad9b8b3c97f4f5ef83fffa76 Mon Sep 17 00:00:00 2001 From: Alexandre Delarue Date: Thu, 7 May 2020 09:12:38 -0700 Subject: [PATCH 8/9] Fixing broken Keda Deployment doc hyperlink (#574) --- howto/autoscale-with-keda/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/howto/autoscale-with-keda/README.md b/howto/autoscale-with-keda/README.md index ccf5705c7..3b487c929 100644 --- a/howto/autoscale-with-keda/README.md +++ b/howto/autoscale-with-keda/README.md @@ -7,7 +7,7 @@ For apps that use these bindings, it is easy to configure a KEDA autoscaler. ## Install KEDA -To install KEDA, follow the [Deploying KEDA](https://keda.sh/deploy/) instructions on the KEDA website. +To install KEDA, follow the [Deploying KEDA](https://keda.sh/docs/deploy/) instructions on the KEDA website. ## Create KEDA enabled Dapr binding From 516848b786ba1197049399904b00f75b963c2158 Mon Sep 17 00:00:00 2001 From: Yaron Schneider Date: Mon, 11 May 2020 10:47:16 -0700 Subject: [PATCH 9/9] Update docs with pub/sub custom routes (#577) * add custom routes * update links --- howto/consume-topic/README.md | 28 +++++++++++++++++++++------- reference/api/pubsub_api.md | 20 +++++++++++++++----- 2 files changed, 36 insertions(+), 12 deletions(-) diff --git a/howto/consume-topic/README.md b/howto/consume-topic/README.md index 91f74312c..88c06d692 100644 --- a/howto/consume-topic/README.md +++ b/howto/consume-topic/README.md @@ -33,7 +33,7 @@ To deploy this into a Kubernetes cluster, fill in the `metadata` connection deta ## Subscribe to topics To subscribe to topics, start a web server in the programming language of your choice and listen on the following `GET` endpoint: `/dapr/subscribe`. -The Dapr instance will call into your app, and expect a JSON value of an array of topics. +The Dapr instance will call into your app, and expect a JSON response for the topic subscriptions. *Note: The following example is written in node, but can be in any programming language* @@ -47,23 +47,37 @@ const port = 3000 app.get('/dapr/subscribe', (req, res) => { res.json([ - 'topic1' - ]) + { + topic: "newOrder", + route: "orders" + } + ]); }) +app.post('/orders', (req, res) => { + res.sendStatus(200); +}); + app.listen(port, () => console.log(`consumer app listening on port ${port}!`)) ## Consume messages -To consume messages from a topic, start a web server in the programming language of your choice and listen on a `POST` endpoint with the route name that corresponds to the topic. - -For example, in order to receive messages for `topic1`, have your endpoint listen on `/topic1`. +To consume messages from a topic, start a web server in the programming language of your choice and listen on a `POST` endpoint with the route path you specified when subscribing. *Note: The following example is written in node, but can be in any programming language* ```javascript -app.post('/topic1', (req, res) => { +app.get('/dapr/subscribe', (req, res) => { + res.json([ + { + topic: "onCreated", + route: "custom/path" + } + ]); +}) + +app.post('/custom/path', (req, res) => { console.log(req.body) res.status(200).send() }) diff --git a/reference/api/pubsub_api.md b/reference/api/pubsub_api.md index 2d389c17c..6d39ef405 100644 --- a/reference/api/pubsub_api.md +++ b/reference/api/pubsub_api.md @@ -58,19 +58,24 @@ A json encoded array of strings. Example: ```json -"["TopicA","TopicB"]" +[ + { + "topic": "newOrder", + "route": "/orders" + } +] ``` ## Provide route(s) for Dapr to deliver topic events -In order to deliver topic events, a `POST` call will be made to user code with the name of the topic as the URL path. +In order to deliver topic events, a `POST` call will be made to user code with the route specified in the subscription response. -The following example illustrates this point, considering a subscription for topic `TopicA`: +The following example illustrates this point, considering a subscription for topic `TopicA` with route `orders`: ### HTTP Request ```http -POST http://localhost:/TopicA +POST http://localhost:/orders/TopicA ``` ### URL Parameters @@ -85,4 +90,9 @@ A JSON encoded payload. ## Message Envelope -Dapr Pub/Sub adheres to version 0.3 of Cloud Events. +Dapr Pub/Sub adheres to version 1.0 of Cloud Events. + +## Related links + +* [How to consume topics](https://github.com/dapr/docs/tree/master/howto/consume-topic) +* [Sample for pub/sub](https://github.com/dapr/samples/tree/master/4.pub-sub)