mirror of https://github.com/dapr/docs.git
Merge branch 'use-cases' of github.com:arschles/docs into use-cases
This commit is contained in:
Aaron Schlesinger
commit
2bce91cdf5
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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,16 @@ 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*.
|
||||
- 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**
|
||||
- **\<Steps\>** times X as needed
|
||||
- **Cleanup**
|
||||
- **Related links**
|
||||
- Include code/sample/config snippets that can be easily copied and pasted.
|
||||
|
|
|
|||
|
|
@ -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 differ, 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 differ, 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).
|
||||
>
|
||||
|
||||
|
||||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
|||
|
||||
<b>app.get('/dapr/subscribe', (req, res) => {
|
||||
res.json([
|
||||
'topic1'
|
||||
])
|
||||
{
|
||||
topic: "newOrder",
|
||||
route: "orders"
|
||||
}
|
||||
]);
|
||||
})</b>
|
||||
|
||||
app.post('/orders', (req, res) => {
|
||||
res.sendStatus(200);
|
||||
});
|
||||
|
||||
app.listen(port, () => console.log(`consumer app listening on port ${port}!`))
|
||||
</pre>
|
||||
|
||||
## 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()
|
||||
})
|
||||
|
|
|
|||
|
|
@ -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:<appPort>/TopicA
|
||||
POST http://localhost:<appPort>/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)
|
||||
|
|
|
|||
|
|
@ -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: <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)
|
||||
Loading…
Reference in New Issue