dapr
/
docs
mirror of https://github.com/dapr/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #381 from dapr/aacrawfi_docs 

Update docs structure and content
This commit is contained in:
Aaron Crawfis 2020-03-09 09:58:52 -07:00 committed by GitHub
parent 2a64439b6f 504fe8e02f
commit 734d5eae92
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
68 changed files with 1000 additions and 985 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
README.md
View File

@ -1,36 +1,35 @@
# Dapr documentation
# 📖 Dapr documentation
Welcome to the Dapr documentation repository. You can learn more about Dapr from the links below.
- **[Overview](./overview.md)** - An overview of Dapr and how it enables you to build distributed applications
- **[Getting Started](./getting-started)** - Set up your environment
- **[Quickstarts and samples](./quickstart)** - Quickstart guides and samples for developing applications
- **[Concepts](./concepts)** - Dapr concepts explained
- **[How-Tos](./howto)** - Guides explaining how to accomplish specific tasks
- **[Best practices](./best-practices)** - Guides explaining best practices using Dapr including [debugging and troubleshooting](https://github.com/dapr/docs/tree/master/best-practices/troubleshooting)
- **[Reference](./reference)** - Detailed reference documentation
- **[FAQ](FAQ.md)** - Frequently asked questions, mostly around differentiation to existing frameworks
| Topic | Description |
|-------|-------------|
|**[Overview](./overview)** | An overview of Dapr and how it enables you to build distributed |applications
|**[Getting Started](./getting-started)** | Set up your environment
|**[Concepts](./concepts)** | Dapr concepts explained
|**[How-Tos](./howto)** | Guides explaining how to accomplish specific tasks
|**[Best practices](./best-practices)** | Guides explaining best practices using Dapr including |[debugging and troubleshooting](https://github.com/dapr/docs/tree/master/best-practices/|troubleshooting)
|**[Reference](./reference)** | Detailed reference documentation
|**[FAQ](FAQ.md)** | Frequently asked questions, mostly around differentiation to existing frameworks
## Further documentation
| Area | Description |
|------|-------------|
| **[Command Line Interface (CLI)](https://github.com/dapr/cli)** | The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, launches and manages Dapr instances.
| **[Dapr Runtime](https://github.com/dapr/dapr)** | Dapr runtime code and overview documentation.
| **[Componenets Contribution](https://github.com/dapr/components-contrib)** | Open, community driven reusable components for building distributed applications.
| **SDKs** | - [Go SDK](https://github.com/dapr/go-sdk)<br>- [Java SDK](https://github.com/dapr/java-sdk)<br>- [Javascript SDK](https://github.com/dapr/js-sdk)<br>- [Python SDK](https://github.com/dapr/python-sdk)<br>- [.NET SDK](https://github.com/dapr/dotnet-sdk)<br><br>**Note:** Dapr is language agnostic and provides a [RESTful HTTP API](./reference/api/README.md) in addition to the protobuf clients.
## Document versions
Dapr is currently under community development in preview phase and master branch could include breaking changes. Therefore, please ensure that you refer to the right version of the documents for your Dapr runtime version.
| Document Version | Dapr Runtime Version |
|:--------------------:|:--------------------:|
| [v0.4.0](https://github.com/dapr/docs/tree/v0.4.0) | [v0.4.0](https://github.com/dapr/dapr/tree/v0.4.0) |
| [v0.3.0](https://github.com/dapr/docs/tree/v0.3.0) | [v0.3.0](https://github.com/dapr/dapr/tree/v0.3.0) |
| [v0.2.0](https://github.com/dapr/docs/tree/v0.2.0) | [v0.2.0](https://github.com/dapr/dapr/tree/v0.2.0) |
| [v0.1.0](https://github.com/dapr/docs/tree/v0.1.0) | [v0.1.0](https://github.com/dapr/dapr/tree/v0.1.0) |
| Version | Repo |
|:-------:|:----:|
| v0.4.0 | [Docs](https://github.com/dapr/docs/tree/v0.4.0) - [Runtime](https://github.com/dapr/dapr/tree/v0.4.0) - [CLI](https://github.com/dapr/cli/tree/release-0.4)
| v0.3.0 | [Docs](https://github.com/dapr/docs/tree/v0.3.0) - [Runtime](https://github.com/dapr/dapr/tree/v0.3.0) - [CLI](https://github.com/dapr/cli/tree/release-0.3)
| v0.2.0 | [Docs](https://github.com/dapr/docs/tree/v0.2.0) - [Runtime](https://github.com/dapr/dapr/tree/v0.2.0) - [CLI](https://github.com/dapr/cli/tree/release-0.2)
| v0.1.0 | [Docs](https://github.com/dapr/docs/tree/v0.1.0) - [Runtime](https://github.com/dapr/dapr/tree/v0.1.0) - [CLI](https://github.com/dapr/cli/tree/release-0.1)
## SDKs
- **[Go SDK](https://github.com/dapr/go-sdk)** - Get started with the Dapr proto client for Go
- **[Java SDK](https://github.com/dapr/java-sdk)** - Get started with the Dapr proto client for Java
- **[Example for Java Actors](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/actors/http)** - Example for developing an actor application using the Java SDK.
- **[Javascript SDK](https://github.com/dapr/js-sdk)** - Get started with the Dapr proto client for Javascript
- **[Python SDK](https://github.com/dapr/python-sdk)** - Get started with the Dapr proto client for Python
- **[.NET SDK](https://github.com/dapr/dotnet-sdk)** - Get started with the Dapr proto client for .NET Core
- **[Getting Started with .NET Actors](https://github.com/dapr/dotnet-sdk/blob/master/docs/get-started-dapr-actor.md)** - Tutorial for developing actor applications using the Dapr .NET SDK including **[actor samples](https://github.com/dapr/dotnet-sdk/tree/master/samples/Actor)**
- **[Getting Started with ASP.NET Core](https://github.com/dapr/dotnet-sdk/tree/master/samples/AspNetCore)** - Samples for developing ASP.NET applications using the Dapr .NET SDK
> Note: Dapr is language agnostic and provides a [RESTful HTTP API](./reference/api/README.md) in addition to the protobuf clients.

0
best-practices/security/security.md → best-practices/security/README.md
View File

80
concepts/README.md
View File

@ -1,42 +1,36 @@
# Dapr concepts
This directory contains Dapr concepts. The goal of these documents provide an understanding of the key concepts used in the Dapr documentation and the [Dapr spec](../reference/api/README.md).
This directory contains Dapr concepts. The goal of these documents provide an understanding of the key concepts used in the Dapr documentation.
## Contents
- [Building Blocks](#building-blocks)
- [Components](#components)
- [Configuration](#configuration)
- [Secrets](#secrets)
- [Hosting Environments](#hosting-environments)
## Building blocks
A [building block](./architecture/building_blocks.md) is as an Http or gRPC API that can be called from user code and uses one or more Dapr components. Dapr consists of a set of building blocks, with extensibility to add new building blocks.
A [building block](./architecture/building_blocks.md) is as an HTTP or gRPC API that can be called from user code and uses one or more Dapr components. Dapr consists of a set of building blocks, with extensibility to add new building blocks.
<img src="../images/building_blocks.png" width=800>
The diagram below shows how building blocks expose a public API that is called from your code, using components to implement the building blocks capability.
![Dapr Building Blocks and Components](../images/concepts-building-blocks.png)
<img src="../images/concepts-building-blocks.png" width=250>
The following are the building blocks provided by Dapr:
* [**Resource Bindings**](./bindings/README.md)
A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the Dapr binding API, and it allows your application to be triggered by events sent by the connected service.
* [**Distributed Tracing**](./distributed-tracing/README.md)
Distributed tracing collects and aggregates trace events, metrics and performance numbers between Dapr instances. It allows you to trace the entire call chain across multiple services, or see call metrics on a user service. Dapr currently integrates with [Open Census](https://opencensus.io/) and when ready [OpenTelemetry](https://opentelemetry.io/) for distributed tracing and metrics collection.
* [**Publish/Subscribe Messaging**](./publish-subscribe-messaging/README.md)
Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications.
* [**Service Invocation**](./service-invocation/service-invocation.md)
Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
* [**State Management**](./state-management/state-management.md)
Application state is anything an application wants to preserve beyond a single session. Dapr provides a key/value-based state API with pluggable state stores for persistence.
* [**Actors**](./actor/actor_overview.md)
An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use.
* [Actor Overview](./actor/actor_overview.md)
* [Actor Features](./actor/actors_features.md)
| Building Block | Endpoint | Description |
|----------------|----------|-------------|
| [**Resource Bindings**](./bindings/README.md)| `/v1.0/bindings` | A binding provides a bi-directional connection to an external cloud/on-premise service or system. Dapr allows you to invoke the external service through the Dapr binding API, and it allows your application to be triggered by events sent by the connected service.
| [**Publish/Subscribe Messaging**](./publish-subscribe-messaging/README.md) | `/v1.0/publish` | Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr supports the pub/sub pattern between applications.
| [**Service Invocation**](./service-invocation/README.md) | `/v1.0/invoke` | Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
| [**State Management**](./state-management/README.md) | `/v1.0/state` | Application state is anything an application wants to preserve beyond a single session. Dapr provides a key/value-based state API with pluggable state stores for persistence.
| [**Secrets**](./secrets/README.md) | `/v1.0/secrets` | Service code can call the secrets API to retrieve secrets out of the Dapr supported secret store.
| [**Distributed Tracing**](./distributed-tracing/README.md) | `TBD` | Distributed tracing collects and aggregates trace events, metrics and performance numbers between Dapr instances. It allows you to trace the entire call chain across multiple services, or see call metrics on a user service. Dapr currently integrates with [Open Census](https://opencensus.io/) and when ready [OpenTelemetry](https://opentelemetry.io/) for distributed tracing and metrics collection.
| [**Actors**](./actors/README.md) | `/v1.0/actors` | An actor is an isolated, independent unit of compute and state with single-threaded execution. Dapr provides an actor implementation based on the Virtual Actor pattern which provides a single-threaded programming model and where actors are garbage collected when not in use. See * [Actor Overview](./actor/actor_overview.md)
## Components
@ -49,30 +43,30 @@ Dapr uses a modular design where functionality is delivered as a component. Each
The following are the component types provided by Dapr:
* Bindings
* Tracing exporters
* Middleware
* Pub/sub
* Secret store
* Service discovery
* Middleware
* State
* Secret store
* Tracing exporters
### Middleware components
Dapr allows custom [**middleware**](./middleware/README.md) to be plugged into the request processing pipeline. Middleware can perform additional actions on a request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the request is returned to the client. The middleware components is used with the Service Invocation building block.
## Secrets
In Dapr, a [**secret**](./secrets/README.md) is any piece of private information that you want to guard against unwanted users. Dapr offers a secrets building block API and integrates with secret stores such as Azure Key Vault and Kubernetes to store the secrets. Secretstores, used to store secrets, are Dapr components.
## Configuration
Dapr [Configuration](./configuration/README.md) defines a policy that affects how any Dapr sidecar instance behaves, such as using [distributed tracing](distributed-tracing/README.md) or a [custom pipeline](middleware/middleware.md). Configuration can be applied to Dapr sidecar instances dynamically.
Dapr [Configuration](./configuration/README.md) defines a policy that affects how any Dapr sidecar instance behaves, such as using [distributed tracing](distributed-tracing/README.md) or a [custom pipeline](./middleware/middleware.md). Configuration can be applied to Dapr sidecar instances dynamically.
You can get a list of current configurations available in the current the hosting environment using the `dapr configuration` CLI command.
## Middleware
Dapr allows custom [**middleware**](./middleware/middleware.md) to be plugged into the request processing pipeline. Middleware are components. Middleware can perform additional actions on a request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the request is returned to the client.
## Secrets
In Dapr, a [**Secret**](./components/secrets.md) is any piece of private information that you want to guard against unwanted users. Dapr offers a simple secret API and integrates with secret stores such as Azure Key Vault and Kubernetes secret stores to store the secrets. Secretstores, used to store secrets, are Dapr components.
## Hosting environments
Dapr can run on multiple hosting platforms. The supported hosting platforms are:
* [**Self hosted**](../overview.md#running-dapr-on-a-local-developer-machine-in-standalone-mode). Dapr runs on a single machine either as a process or in a container. Used for local development or running on a single machine execution
* [**Kubernetes**](../overview.md#running-dapr-in-kubernetes-mode). Dapr runs on any Kubernetes cluster either from a cloud provider or on-premises.
* [**Self hosted**](../overview/README.md#running-dapr-on-a-local-developer-machine-in-standalone-mode). Dapr runs on a single machine either as a process or in a container. Used for local development or running on a single machine execution
* [**Kubernetes**](../overview/README.md#running-dapr-in-kubernetes-mode). Dapr runs on any Kubernetes cluster either from a cloud provider or on-premises.

157
concepts/actor/actors_features.md
View File

@ -1,157 +0,0 @@
# Dapr Actors Runtime
Dapr Actors runtime provides following capabilities:
## Actor State Management
Actors can save state reliably using state management capability.
You can interact with Dapr through Http/gRPC endpoints for state management.
To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The following state stores implement this interface:
- Redis
- MongoDB
- SQL Server
### Save the Actor State
You can save the Actor state of a given key of actorId of type actorType by calling
```http
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>
```
Value of the key is passed as request body.
```json
{
"key": "value"
}
```
If you want to save multiple items in a single transaction, you can call
```http
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state
```
### Retrieve the Actor State
Once you have saved the actor state, you can retrieve the saved state by calling
```http
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>
```
### Remove the Actor State
You can remove state permanently from the saved Actor state by calling
```http
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/state/<key>
```
Refer [dapr spec](../../reference/api/actors.md) for more details.
## Actor Timers and Reminders
Actors can schedule periodic work on themselves by registering either timers or reminders.
### Actor timers
You can register a callback on actor to be executed based on timer.
Dapr Actor runtime ensures that the callback methods respect the turn-based concurrency guarantees.This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
The next period of the timer starts after the callback completes execution. This implies that the timer is stopped while the callback is executing and is started when the callback finishes.
The Dapr Actors runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object will be deactivated and a new instance will be activated.
All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr Actors runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
You can create a timer for an actor by calling the Http/gRPC request to Dapr.
```http
POST,PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
The timer due time and callback are specified in the request body. The due time represents when the timer will first fire after registration. The period represents how often the timer will fire after that. A due time of 0 means to fire immediately. Negative due times and periods are invalid.
The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
```json
{
"dueTime":"0h0m9s0ms",
"period":"0h0m3s0ms"
}
```
The following request body configures a timer with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it will fire immediately after registration, then every 3 seconds after that.
```json
{
"dueTime":"0h0m0s0ms",
"period":"0h0m3s0ms"
}
```
You can remove the actor timer by calling
```http
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
Refer [dapr spec](../../reference/api/actors.md) for more details.
### Actor reminders
Reminders are a mechanism to trigger persistent callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr Actors runtime persists information about the actor's reminders using Dapr actor state provider.
You can create a persistent reminder for an actor by calling the Http/gRPC request to Dapr.
```http
POST,PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
The reminder due time and callback can be specified in the request body. The due time represents when the reminder will first fire after registration. The period represents how often the reminder will fire after that. A due time of 0 means to fire immediately. Negative due times and periods are invalid. To register a reminder that fires only once, set the period to an empty string.
The following request body configures a reminder with a `dueTime` 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
```json
{
"dueTime":"0h0m9s0ms",
"period":"0h0m3s0ms"
}
```
The following request body configures a reminder with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it will fire immediately after registration, then every 3 seconds after that.
```json
{
"dueTime":"0h0m0s0ms",
"period":"0h0m3s0ms"
}
```
The following request body configures a reminder with a `dueTime` 15 seconds and a `period` of empty string. This means it will first fire after 15 seconds, then never fire again.
```json
{
"dueTime":"0h0m15s0ms",
"period":""
}
```
#### Retrieve Actor Reminder
You can retrieve the actor reminder by calling
```http
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
#### Remove the Actor Reminder
You can remove the actor reminder by calling
```http
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
Refer [dapr spec](../../reference/api/actors.md) for more details.

40
concepts/actor/actor_overview.md → concepts/actors/README.md
View File

@ -1,14 +1,27 @@
# Introduction to Actors
# Introduction to actors
Dapr runtime provides an actor implementation which is based on Virtual Actor pattern. The Dapr actors API provides a single-threaded programming model leveraging the scalability and reliability guarantees provided by underlying platform on which Dapr is running.
## Quick links
- [Dapr Actor Features](./actors_features.md)
- [Dapr Actor API Spec](./actors_api.md)
## Contents
- [Understanding Actors](#understanding-actors)
- [Actors in Dapr](#actors-in-dapr)
- [Actor Lifetime](#actor-lifetime)
- [Distribution and Failover](#distribution-and-failover)
- [Actor Communication](#actor-communication)
## Understanding actors
An actor is an isolated, independent unit of compute and state with single-threaded execution.
The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) is a computational model for concurrent or distributed systems in which a large number of these actors can execute simultaneously and independently of each other. Actors can communicate with each other and they can create more actors.
### When to use Actors
### When to use actors
Dapr actors is an implementation of the actor design pattern. As with any software design pattern, the decision whether to use a specific pattern is made based on whether or not a software design problem fits the pattern.
@ -18,11 +31,13 @@ Although the actor design pattern can be a good fit to a number of distributed s
* You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors.
* Your actor instances won't block callers with unpredictable delays by issuing I/O operations.
## Actors in Dapr
## Actors in dapr
Every actor is defined as an instance of an actor type, identical to the way an object is an instance of a class. For example, there may be an actor type that implements the functionality of a calculator and there could be many actors of that type that are distributed on various nodes across a cluster. Each such actor is uniquely identified by an actor ID.
## Actor Lifetime
<img src="../../images/actor_game_example.png" width=400>
## Actor lifetime
Dapr actors are virtual, meaning that their lifetime is not tied to their in-memory representation. As a result, they do not need to be explicitly created or destroyed. The Dapr actors runtime automatically activates an actor the first time it receives a request for that actor ID. If an actor is not used for a period of time, the Dapr Actors runtime garbage-collects the in-memory object. It will also maintain knowledge of the actor's existence should it need to be reactivated later.
@ -40,7 +55,8 @@ To provide scalability and reliability, actors instances are distributed through
Actors are distributed across the instances of the actor service, and those instance are distributed across the nodes in a cluster. Each service instance contains a set of actors for a given actor type.
The Dapr actor runtime manages distribution scheme and key range settings for you. This is done by the actor Placement service. When a new instance of a service is created, the corresponding Dapr runtime register the actor types it can create and the Placement service calculates the partitioning across all the instances for a given actor type. This table of partition information for each actor type is updated and stored in each Dapr instance running in the environment and can change dynamically as new instance of actor services are created and destroyed. This is shown in the diagram below.
### Actor placement service
The Dapr actor runtime manages distribution scheme and key range settings for you. This is done by the actor `Placement` service. When a new instance of a service is created, the corresponding Dapr runtime register the actor types it can create and the `Placement` service calculates the partitioning across all the instances for a given actor type. This table of partition information for each actor type is updated and stored in each Dapr instance running in the environment and can change dynamically as new instance of actor services are created and destroyed. This is shown in the diagram below.
![Placement service registration](../../images/actors_placement_service_registration.png)
@ -51,21 +67,21 @@ When a client calls an actor with a particular id (for example, actor id 123), t
This simplifies some choices but also carries some consideration:
* By default, actors are randomly placed into pods resulting in uniform distribution.
* Because actors are randomly placed, it should be expected that actor operations will always require network communication, including serialization and deserialization of method call data, incurring latency and overhead.
* Because actors are randomly placed, it should be expected that actor operations always require network communication, including serialization and deserialization of method call data, incurring latency and overhead.
Note: The Dapr actor Placement service is only used for actor placement and therefore is not needed if your services are not using Dapr actors. The Placement service can run in all environments (Standalone, Kubernetes etc)
Note: The Dapr actor Placement service is only used for actor placement and therefore is not needed if your services are not using Dapr actors. The Placement service can run in all hosting environments for example, self hosted, Kubernetes
## Actor communication
You can interact with Dapr to invoke the actor method by calling Http/gRPC endpoint
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint
```bash
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/<method/state/timers/reminders>
```
You can provide any data for actor method in the request body and response for the request would be in response body which is data from actor call.
You can provide any data for the actor method in the request body, and the response for the request would be in the response body which is the data from actor call.
Refer [dapr spec](../../reference/api/actors.md) for more details.
Refer to [Dapr Actor Features](./actors_features.md) for more details.
### Concurrency
@ -73,7 +89,7 @@ The Dapr Actors runtime provides a simple turn-based access model for accessing
A single actor instance cannot process more than one request at a time. An actor instance can cause a throughput bottleneck if it is expected to handle concurrent requests.
Actors can deadlock on each other if there is a circular request between two actors while an external request is made to one of the actors simultaneously. The Dapr actor runtime will automatically time out on actor calls and throw an exception to the caller to interrupt possible deadlock situations.
Actors can deadlock on each other if there is a circular request between two actors while an external request is made to one of the actors simultaneously. The Dapr actor runtime automatically times out on actor calls and throw an exception to the caller to interrupt possible deadlock situations.
!["Actor concurrency"](../../images/actors_communication.png)

133
concepts/actors/actors_features.md Normal file
View File

@ -0,0 +1,133 @@
# Dapr actors runtime
The Dapr actors runtime provides following capabilities:
- [Method Invocation](#actor-method-invocation)
- [State Management](#actor-state-management)
- [Timers and Reminders](#actor-timers-and-reminders)
## Actor method invocation
You can interact with Dapr to invoke the actor method by calling HTTP/gRPC endpoint
```bash
POST/GET/PUT/DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/method/<method>
```
You can provide any data for the actor method in the request body and the response for the request is in response body which is data from actor method call.
Refer [api spec](./actors_api.md#invoke-actor-method) for more details.
## Actor state management
Actors can save state reliably using state management capability.
You can interact with Dapr through HTTP/gRPC endpoints for state management.
To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The following state stores implement this interface:
- Redis
- MongoDB
- SQL Server
## Actor timers and reminders
Actors can schedule periodic work on themselves by registering either timers or reminders.
### Actor timers
You can register a callback on actor to be executed based on a timer.
The Dapr actor runtime ensures that the callback methods respect the turn-based concurrency guarantees.This means that no other actor methods or timer/reminder callbacks will be in progress until this callback completes execution.
The next period of the timer starts after the callback completes execution. This implies that the timer is stopped while the callback is executing and is started when the callback finishes.
The Dapr actors runtime saves changes made to the actor's state when the callback finishes. If an error occurs in saving the state, that actor object is deactivated and a new instance will be activated.
All timers are stopped when the actor is deactivated as part of garbage collection. No timer callbacks are invoked after that. Also, the Dapr actors runtime does not retain any information about the timers that were running before deactivation. It is up to the actor to register any timers that it needs when it is reactivated in the future.
You can create a timer for an actor by calling the HTTP/gRPC request to Dapr.
```http
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
The timer `duetime` and callback are specified in the request body. The due time represents when the timer will first fire after registration. The `period` represents how often the timer fires after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid.
The following request body configures a timer with a `dueTime` of 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
```json
{
"dueTime":"0h0m9s0ms",
"period":"0h0m3s0ms"
}
```
The following request body configures a timer with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it fires immediately after registration, then every 3 seconds after that.
```json
{
"dueTime":"0h0m0s0ms",
"period":"0h0m3s0ms"
}
```
You can remove the actor timer by calling
```http
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
Refer [api spec](./actors_api.md#invoke-timer) for more details.
### Actor reminders
Reminders are a mechanism to trigger *persistent* callbacks on an actor at specified times. Their functionality is similar to timers. But unlike timers, reminders are triggered under all circumstances until the actor explicitly unregisters them or the actor is explicitly deleted. Specifically, reminders are triggered across actor deactivations and failovers because the Dapr actors runtime persists the information about the actors' reminders using Dapr actor state provider.
You can create a persistent reminder for an actor by calling the Http/gRPC request to Dapr.
```http
POST/PUT http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
The reminder `duetime` and callback can be specified in the request body. The due time represents when the reminder first fires after registration. The `period` represents how often the reminder will fire after that. A due time of 0 means to fire immediately. Negative due times and negative periods are invalid. To register a reminder that fires only once, set the period to an empty string.
The following request body configures a reminder with a `dueTime` 9 seconds and a `period` of 3 seconds. This means it will first fire after 9 seconds, then every 3 seconds after that.
```json
{
"dueTime":"0h0m9s0ms",
"period":"0h0m3s0ms"
}
```
The following request body configures a reminder with a `dueTime` 0 seconds and a `period` of 3 seconds. This means it will fire immediately after registration, then every 3 seconds after that.
```json
{
"dueTime":"0h0m0s0ms",
"period":"0h0m3s0ms"
}
```
The following request body configures a reminder with a `dueTime` 15 seconds and a `period` of empty string. This means it will first fire after 15 seconds, then never fire again.
```json
{
"dueTime":"0h0m15s0ms",
"period":""
}
```
#### Retrieve Actor Reminder
You can retrieve the actor reminder by calling
```http
GET http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
#### Remove the Actor Reminder
You can remove the actor reminder by calling
```http
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
Refer [api spec](./actors_api.md#invoke-reminder) for more details.

3
concepts/architecture/README.md Normal file
View File

@ -0,0 +1,3 @@
# Dapr architecture
- [Building Blocks](./building_blocks.md)

3
concepts/architecture/architecture.md
View File

@ -1,3 +0,0 @@
# documentation
Content for this file to be added

69
concepts/bindings/README.md
View File

@ -12,33 +12,50 @@ Bindings allow for on-demand, event-driven compute scenarios, and dapr bindings
Bindings are developed independently of Dapr runtime. You can view and contribute to the bindings [here](https://github.com/dapr/components-contrib/tree/master/bindings).
## Supported Bindings and Specs
## Supported bindings and specs
Every binding has its own unique set of properties. Click the name link to see the component YAML for each binding.
| Name | Input Binding | Output Binding | Status
| ------------- | -------------- | ------------- | ------------- |
| [HTTP](./specs/http.md) | | V | Experimental |
| [Kafka](./specs/kafka.md) | V | V | Experimental |
| [Kubernetes Events](./specs/kubernetes.md) | V | | Experimental |
| [MQTT](./specs/mqtt.md) | V | V | Experimental |
| [RabbitMQ](./specs/rabbitmq.md) | V | V | Experimental |
| [Redis](./specs/redis.md) | | V | Experimental |
| [Twilio SMS](./specs/twilio.md) | | V | Experimental |
| [AWS DynamoDB](./specs/dynamodb.md) | | V | Experimental |
| [AWS S3](./specs/s3.md) | | V | Experimental |
| [AWS SNS](./specs/sns.md) | | V | Experimental |
| [AWS SQS](./specs/sqs.md) | V | V | Experimental |
| [Azure Blob Storage](./specs/blobstorage.md) | | V | Experimental |
| [Azure CosmosDB](./specs/cosmosdb.md) | | V | Experimental |
| [Azure EventHubs](./specs/eventhubs.md) | V | V | Experimental |
| [Azure Service Bus Queues](./specs/servicebusqueues.md) | V | V | Experimental |
| [Azure Storage Queues](./specs/storagequeues.md) | V | V | Experimental |
| [Azure SignalR](./specs/signalr.md) | | V | Experimental |
| [GCP Cloud Pub/Sub](./specs/gcppubsub.md) | V | V | Experimental |
| [GCP Storage Bucket](./specs/gcpbucket.md) | | V | Experimental |
### Generic
## Input Bindings
| Name | Input<br>Binding | Output<br>Binding | Status |
|------|:----------------:|:-----------------:|--------|
| [HTTP](../../reference/specs/bindings/http.md) | | ✅ | Experimental |
| [Kafka](../../reference/specs/bindings/kafka.md) | ✅ | ✅ | Experimental |
| [Kubernetes Events](../../reference/specs/bindings/kubernetes) | ✅ | | Experimental |
| [MQTT](../../reference/specs/bindings/mqtt.md) | ✅ | ✅ | Experimental |
| [RabbitMQ](../../reference/specs/bindings/rabbitmq.md) | ✅ | ✅ | Experimental |
| [Redis](../../reference/specs/bindings/redis.md) | | ✅ | Experimental |
| [Twilio](../../reference/specs/bindings/twilio.md) | | ✅ | Experimental |
### Amazon Web Service (AWS)
| Name | Input<br>Binding | Output<br>Binding | Status |
|------|:----------------:|:-----------------:|--------|
| [AWS DynamoDB](../../reference/specs/bindings/dynamodb.md) | | ✅ | Experimental |
| [AWS S3](../../reference/specs/bindings/s3.md) | | ✅ | Experimental |
| [AWS SNS](../../reference/specs/bindings/sns.md) | | ✅ | Experimental |
| [AWS SQS](../../reference/specs/bindings/sqs.md) | ✅ | ✅ | Experimental |
### Google Cloud Platform (GCP)
| Name | Input<br>Binding | Output<br>Binding | Status |
|------|:----------------:|:-----------------:|--------|
| [GCP Cloud Pub/Sub](../../reference/specs/bindings/gcppubsub.md) | ✅ | ✅ | Experimental |
| [GCP Storage Bucket](../../reference/specs/bindings/gcpbucket.md) | | ✅ | Experimental |
### Microsoft Azure
| Name | Input<br>Binding | Output<br>Binding | Status |
|------|:----------------:|:-----------------:|--------|
| [Azure Blob Storage](../../reference/specs/bindings/blobstorage.md) | | ✅ | Experimental |
| [Azure EventHubs](../../reference/specs/bindings/eventhubs.md) | ✅ | ✅ | Experimental |
| [Azure CosmosDB](../../reference/specs/bindings/cosmosdb.md) | | ✅ | Experimental |
| [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 |
## Input bindings
Input bindings are used to trigger your application when an event from an external resource has occurred.
An optional payload and metadata might be sent with the request.
@ -50,9 +67,9 @@ 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
## Output bindings
Output bindings allow users to invoke external resources
An optional payload and metadata can be sent with the invocation request.
@ -62,4 +79,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.

21
concepts/bindings/specs/blobstorage.md
View File

@ -1,21 +0,0 @@
# Azure Blob Storage Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

27
concepts/bindings/specs/cosmosdb.md
View File

@ -1,27 +0,0 @@
# Azure CosmosDB Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

24
concepts/bindings/specs/dynamodb.md
View File

@ -1,24 +0,0 @@
# AWS DynamoDB Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

33
concepts/bindings/specs/kafka.md
View File

@ -1,33 +0,0 @@
# Kafka Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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"`.

18
concepts/bindings/specs/redis.md
View File

@ -1,18 +0,0 @@
# Redis Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <name>
spec:
type: bindings.redis
metadata:
- name: redisHost
value: <address>:6379
- name: redisPassword
value: **************
```
`redisHost` is the Redis host address.
`redisPassword` is the Redis password.

24
concepts/bindings/specs/s3.md
View File

@ -1,24 +0,0 @@
# AWS S3 Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

18
concepts/bindings/specs/servicebusqueues.md
View File

@ -1,18 +0,0 @@
# Azure Service Bus Queues Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

24
concepts/bindings/specs/sns.md
View File

@ -1,24 +0,0 @@
# AWS SNS Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

24
concepts/bindings/specs/sqs.md
View File

@ -1,24 +0,0 @@
# AWS SQS Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.

2
concepts/configuration/README.md
View File

@ -5,4 +5,4 @@ Dapr configuration is a configuration file (in local mode) or a Kubernetes confi
A Dapr configuration configures:
* [distributed tracing](../distributed-tracing/README.md)
* [custom pipeline](../middleware/middleware.md)
* [custom pipeline](../middleware/README.md)

9
concepts/distributed-tracing/README.md
View File

@ -4,7 +4,14 @@ Dapr uses OpenTelemetry (previously known as OpenCensus) for distributed traces
![Tracing](../../images/tracing.png)
## Tracing Design
## Contents
- [Tracing Design](#tracing-design)
- [Correlation ID](#correlation-id)
- [Configuration](#configuration)
- [References](#references)
## Tracing design
Dapr adds a HTTP/gRPC middleware to the Dapr sidecar. The middleware intercepts all Dapr and application traffic and automatically injects correlation IDs to trace distributed transactions. This design has several benefits:

0
concepts/middleware/middleware.md → concepts/middleware/README.md
View File

4
concepts/publish-subscribe-messaging/README.md
View File

@ -11,7 +11,7 @@ These implementations are pluggable, and developed outside of the Dapr runtime i
The API for Publish/Subscribe can be found in the [spec repo](../../reference/api/pubsub.md).
## Behavior and Guarantees
## Behavior and guarantees
Dapr guarantees At-Least-Once semantics for message delivery.
That is, when an application publishes a message to a topic using the Publish/Subscribe API, it can assume the message is delivered at least once to any subscriber when the response status code from that endpoint is `200`, or returns no error if using the gRPC client.
@ -24,7 +24,7 @@ Dapr has the concept of an `id`. This is specified in Kubernetes using the `dapr
When multiple instances of the same application ID subscribe to a topic, Dapr will make sure to deliver the message to only one instance. If two different applications with different IDs subscribe to a topic, at least one instance in each application receives a copy of the same message.
## Cloud Events
## Cloud events
Dapr follows the [Cloud Events 0.3 Spec](https://github.com/cloudevents/spec/tree/v0.3) and wraps any payload sent to a topic inside a Cloud Events envelope.

14
concepts/secrets/README.md Normal file
View File

@ -0,0 +1,14 @@
# Dapr Secrets Management
Dapr offers developers a consistent way to extract application secrets, without needing to know the specifics of the secret store being used.
Secret stores are components in Dapr. Dapr allows users to write new secret stores component implementations that can be used both to hold secrets for other Dapr components (for example secrets used by a state store components to read/write state) as well as serving the application with a dedicated secret building block API. Using the secrets building block API, you can easily read secrets that can be used by the application from the a named secrets store.
Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores)
## Referencing Secret Stores in Dapr Components
Instead of including credentials within a Dapr component, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. For more information read [Referencing Secret Stores in Components](./component-secrets.md)
## Retrieving Secrets
Service code can call the secrets building block API to retrieve secrets out of the Dapr supported secret store. Read [Secrets API Specification](./secrets_api.md) for more information.

2
concepts/components/secrets.md → concepts/secrets/component-secrets.md
View File

@ -1,4 +1,4 @@
# Secrets
# Referencing Secret Stores in Components
Components can reference secrets for the `spec.metadata` section.

12
concepts/security/security.md → concepts/security/README.md
View File

@ -1,10 +1,18 @@
# Security
- [Dapr-to-App Communication](#dapr-to-app-communication)
- [Dapr-to-Dapr Communication](#dapr-to-dapr-communication)
- [Network Security](#network-security)
- [Bindings Security](#bindings-security)
- [State Store Security](#state-store-security)
- [Management Security](#management-security)
- [Component Secrets](#component-secets)
## Dapr-to-app communication
Dapr sidecar runs close to the application through **localhost**. Dapr assumes it runs in the same security domain of the application. So, there are no authentication, authorization or encryption between a Dapr sidecar and the application.
## Dapr-to-Dapr communication
## Dapr-to-dapr communication
Dapr includes an on by default, automatic mutual TLS that provides in-transit encryption for traffic between Dapr instances.
To achieve this, Dapr leverages a system component named `Sentry` which acts as a Certificate Authority (CA) and signs workload certificate requests originating from the Dapr instances.
@ -31,7 +39,7 @@ Specific details for how to do that can be found [here](../../howto/configure-mt
<a href="https://ibb.co/4VXWJ3d"><img src="https://i.ibb.co/rwzkvNs/Screen-Shot-2020-02-10-at-8-35-59-PM.png" alt="Screen-Shot-2020-02-10-at-8-35-59-PM" border="0"></a>
### mTLS Self Hosted
### mTLS self hosted
<a href="https://ibb.co/XWFYsfY"><img src="https://i.ibb.co/rQ5d6Kd/Screen-Shot-2020-02-10-at-8-34-33-PM.png" alt="Screen-Shot-2020-02-10-at-8-34-33-PM" border="0"></a>

2
concepts/service-invocation/service-invocation.md → concepts/service-invocation/README.md
View File

@ -25,5 +25,5 @@ Steps 4-5 are the same as the list above.
For more information, see:
- The [Service Invocation Spec](../../reference/api/service_invocation.md)
- The [Service Invocation API Spec](.service_invocation_api.md)
- A [HowTo](../../howto/invoke-and-discover-services/README.md) on Service Invocation

23
concepts/state-management/state-management.md → concepts/state-management/README.md
View File

@ -4,22 +4,33 @@ Dapr makes it simple for you to store key/value data in a store of your choice.
![State management](../../images/state_management.png)
## Contents:
- [State Management API](#state-management-api)
- [State Store Behaviors](#state-store-behaviors)
- [Concurrency](#concurrency)
- [Consistency](#consistency)
- [Retry Policies](#retry-policies)
- [Bulk Operations](#bulk-operations)
- [Querying State Store Directly](#querying-state-store-directly)
- [References](#references)
## State management API
Dapr brings reliable state management to applications through a simple state API. Developers can use this API to retrieve, save and delete states by keys.
Dapr provides reliable state management to applications through a state management buidling block API. Developers can use this API to retrieve, save and delete state values by providing keys.
Dapr data stores are pluggable. Dapr ships with [Redis](https://redis.io
) out-of-box. And it allows you to plug in other data stores such as [Azure CosmosDB](https://azure.microsoft.com/services/cosmos-db/), [SQL Server](https://azure.microsoft.com/services/sql-database/), [AWS DynamoDB](https://aws.amazon.com/DynamoDB
Dapr data stores are components. Dapr ships with [Redis](https://redis.io
) out-of-box for local development in self hosted mode. Dapr allows you to plug in other data stores as components such as [Azure CosmosDB](https://azure.microsoft.com/services/cosmos-db/), [SQL Server](https://azure.microsoft.com/services/sql-database/), [AWS DynamoDB](https://aws.amazon.com/DynamoDB
), [GCP Cloud Spanner](https://cloud.google.com/spanner
) and [Cassandra](http://cassandra.apache.org/).
See the Dapr API specification for details on [state management API](../../reference/api/state.md))
Visit [State API](./state_api.md) for more information.
> **NOTE:** Dapr prefixes state keys with the ID of the current Dapr instance/sidecar. This allows multiple Dapr instances to share the same state store.
> **NOTE:** Dapr prefixes state keys with the ID of the current Dapr instance. This allows multiple Dapr instances to share the same state store.
## State store behaviors
Dapr allows developers to attach to a state operation request additional metadata that describes how the request is expected to be handled. For example, you can attach concurrency requirement, consistency requirement, and retry policy to any state operation requests.
Dapr allows developers to attach to a state operation request additional metadata that describes how the request is expected to be handled. For example, you can attach concurrency requirements, consistency requirements, and retry policy to any state operation requests.
By default, your application should assume a data store is **eventually consistent** and uses a **last-write-wins** concurrency pattern. On the other hand, if you do attach metadata to your requests, Dapr passes the metadata along with the requests to the state store and expects the data store to fulfil the requests.

6
getting-started/README.md
View File

@ -1,14 +1,14 @@
# Getting started
# Getting Started
Dapr is a portable, event-driven runtime that makes it easy for enterprise developers to build resilient, microservice stateless and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.
## Core concepts
## Core Concepts
* **Building blocks** are a collection of components that implement distributed system capabilities, such as pub/sub, state management, resource bindings, and distributed tracing.
* **Components** encapsulate the implementation for a building block API. Example implementations for the state building block may include Redis, Azure Storage, Azure Cosmos DB, and AWS DynamoDB. Many of the components are pluggable so that one implementation can be swapped out for another.
To learn more, see [Dapr Concepts](../concepts/README.md).
To learn more, see [Dapr Concepts](../concepts).
## Setup the development environment

0
concepts/components/redis.md → howto/configure-redis/README.md
View File

5
howto/setup-secret-store/README.md Normal file
View File

@ -0,0 +1,5 @@
# How To: Setup a Dapr Secret Store
It is important to securly store and retrieve secrets in Dapr to prevent unwanted people from accessing connection strings, passwords, and auth tokens.
The guides within this directory contain guides on how to deploy, configure, and connect to secret stores.

BIN
images/actor_game_example.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 303 KiB

BIN
images/building_blocks.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 217 KiB

BIN
images/concepts-building-blocks.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

81
overview.md
View File

@ -1,81 +0,0 @@
# Dapr overview
Dapr is a portable, event-driven runtime that makes it easy for enterprise developers to build resilient, microservice stateless and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.
## Any language, any framework, anywhere
Today we are experiencing a wave of cloud adoption. Developers are comfortable with web + database application architectures (for example classic 3-tier designs) but not with microservice application architectures which are inherently distributed. It’s hard to become a distributed systems expert, nor should you have to. Developers want to focus on business logic, while leaning on the platforms to imbue their applications with scale, resiliency, maintainability, elasticity and the other attributes of cloud-native architectures.
This is where Dapr comes in. Dapr codifies the *best practices* for building microservice applications into open, independent, building blocks that enable you to build portable applications with the language and framework of your choice. Each building block is completely independent and you can use one, some, or all of them in your application.
In addition Dapr is platform agnostic meaning you can run your applications locally, on any Kubernetes cluster, and other hosting environments that Dapr integrates with. This enables you to build microservice applications that can run on the cloud and edge.
Using Dapr you can easily build microservice applications using any language, any framework, and run them anywhere.
## Microservice building blocks for cloud and edge
There are many considerations when architecting microservices applications. Dapr provides best practices for common capabilities when building microservice applications that developers can use in a standard way and deploy to any environment. It does this by providing distributed system building blocks.
Each of these building blocks is independent, meaning that you can use one, some or all of them in your application. In this initial release of Dapr, the following building blocks are provided:
• **Service invocation** Resilient service-to-service invocation enables method calls, including retries, on remote services wherever they are located in the supported hosting environment.
• **State Management** With state management for storing key/value pairs, long running, highly available, stateful services can be easily written alongside stateless services in your application. The state store is pluggable and can include Azure CosmosDB, AWS DynamoDB or Redis among others.
• **Publish and subscribe messaging between services** Publishing events and subscribing to topics between services enables event-driven architectures to simplify horizontal scalability and make them resilient to failure. Dapr provides at least once message delivery guarantee.
• **Event driven resource bindings** Resource bindings with triggers builds further on event-driven architectures for scale and resiliency by receiving and sending events to and from any external resource such as databases, queues, file systems, etc.
•**Distributed tracing between services** Dapr supports distributed tracing to easily diagnose and observe inter-service calls in production using the W3C Trace Context standard.
•**Actors** A pattern for stateful and stateless objects that make concurrency simple with method and state encapsulation. Dapr provides many capabilities in its actor runtime including concurrency, state, life-cycle management for actor activation/deactivation and timers and reminders to wake-up actors.
The diagram below shows the distributed system building blocks provides by Dapr, exposed with standard APIs. These APIs can be used from any developer code over http or gRPC. Dapr integrates with any hosting platform, for example Kubernetes, to enable application portability including across cloud and edge.
![Dapr overview](images/overview.png)
## Sidecar architecture
Dapr exposes its APIs as a sidecar architecture, either as a container or as a process, not requiring the application code to include any Dapr runtime code. This makes integration with Dapr easy from other runtimes, as well as providing separation of the application logic for improved supportability.
![Dapr overview](images/overview-sidecar.png)
In container hosting environments such as Kubernetes, Dapr runs as a side-car container with the application container in the same pod.
![Dapr overview](images/overview-sidecar-kubernetes.png)
## Developer language SDKs and frameworks
To make using Dapr more natural for different languages, it also includes language specific SDKs for Go, Java, JavaScript, .NET and Python. These SDKs expose the functionality in the Dapr building blocks, such as saving state, publishing an event or creating an actor, through a typed, language API rather than calling the http/gRPC API. This enables you to write a combination of stateless and stateful functions and actors all in the language of their choice. And because these SDKs share the Dapr runtime, you get cross-language actor and functions support.
Furthermore, Dapr can be integrated with any developer framework. For example, in the Dapr [.NET SDK](https://github.com/dapr/dotnet-sdk) you can find ASP.NET Core integration, which brings stateful routing controllers that respond to pub/sub events from other services.
## Running Dapr on a local developer machine in self hosted mode
Dapr can be configured to run on your local developer machine in [self hosted mode](./getting-started). Each running service has a Dapr runtime process which is configured to use state stores, pub/sub, binding components and the other building block.
In self hosted mode, Redis running locally in a container, is installed as default a state store and pub/sub message bus components.
The `dapr-placement` service is responsible for managing the actor distribution scheme and key range settings. For more information on the actor `Placement` service read [actor overview](/concepts/actor/actor_overview.md#distribution-and-failover)
![Dapr overview](images/overview_standalone.png)
## Running Dapr in Kubernetes mode
Dapr can be configured to run on any [Kubernetes cluster](https://github.com/dapr/samples/tree/master/2.hello-kubernetes). In Kubernetes the `dapr-sidecar-injector` and `dapr-operator` services provide first class integration to launch Dapr as a sidecar container in the same pod as the service and provide notifications of Dapr component updates provisioned into the cluster.
The `dapr-sentry` service is a certificate authority that enables mutual TLS between Dapr sidecar instances for secure data encryption. For more information on the `Sentry` service read the [security overview](/concepts/security/security.md#dapr-to-dapr-communication)
![Dapr overview](images/overview_kubernetes.png)
Deploying a Dapr enabled application into your kubernetes cluster is a simple as adding a few annotations to the deployment schemes. To give your service an id and port known to Dapr, turn on tracing information and launch the Dapr sidecar container, you annotate your deployment like this.
```yml
annotations:
dapr.io/enabled: "true"
dapr.io/id: "nodeapp"
dapr.io/port: "3000"
dapr.io/config: "tracing"
```
You can see some examples [here](https://github.com/dapr/samples/tree/master/2.hello-kubernetes/deploy) in the kubernetes getting started guide.

108
overview/README.md Normal file
View File

@ -0,0 +1,108 @@
# Dapr Overview
Dapr is a portable, event-driven runtime that makes it easy for enterprise developers to build resilient, microservice stateless and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks.
## Contents:
- [Any language, any framework, anywhere](#any-language-any-framework-anywhere)
- [Microservice building blocks for cloud and edge](#microservice-building-blocks-for-cloud-and-edge)
- [Sidecar architecture](#sidecar-architecture)
- [Developer language SDKs and frameworks](#developer-language-sdks-and-frameworks)
- [Running Dapr on a local developer machine in self hosted mode](#running-dapr-on-a-local-developer-machine-in-self-hosted-mode)
- [Running Dapr in Kubernetes mode](#running-dapr-in-kubernetes-mode)
## Any language, any framework, anywhere
<img src="../images/overview.png" width=800>
Today we are experiencing a wave of cloud adoption. Developers are comfortable with web + database application architectures (for example classic 3-tier designs) but not with microservice application architectures which are inherently distributed. It’s hard to become a distributed systems expert, nor should you have to. Developers want to focus on business logic, while leaning on the platforms to imbue their applications with scale, resiliency, maintainability, elasticity and the other attributes of cloud-native architectures.
This is where Dapr comes in. Dapr codifies the *best practices* for building microservice applications into open, independent, building blocks that enable you to build portable applications with the language and framework of your choice. Each building block is completely independent and you can use one, some, or all of them in your application.
In addition Dapr is platform agnostic meaning you can run your applications locally, on any Kubernetes cluster, and other hosting environments that Dapr integrates with. This enables you to build microservice applications that can run on the cloud and edge.
Using Dapr you can easily build microservice applications using any language, any framework, and run them anywhere.
## Microservice building blocks for cloud and edge
<img src="../images/building_blocks.png" width=800>
There are many considerations when architecting microservices applications. Dapr provides best practices for common capabilities when building microservice applications that developers can use in a standard way and deploy to any environment. It does this by providing distributed system building blocks.
Each of these building blocks is independent, meaning that you can use one, some or all of them in your application. In this initial release of Dapr, the following building blocks are provided:
| Building Block | Description |
|----------------|-------------|
| **[Service Invocation](../concepts/service-invocation)** | Resilient service-to-service invocation enables method calls, including retries, on remote services wherever they are located in the supported hosting environment.
| **[State Management](../concepts/state)** | With state management for storing key/value pairs, long running, highly available, stateful services can be easily written alongside stateless services in your application. The state store is pluggable and can include Azure CosmosDB, AWS DynamoDB or Redis among others.
| **[Publish and Subscribe Messaging](../concepts/publish-subscribe-messaging)** | Publishing events and subscribing to topics | tween services enables event-driven architectures to simplify horizontal scalability and make them | silient to failure. Dapr provides at least once message delivery guarantee.
| **[Resource Bindings](../concepts/bindings)** | Resource bindings with triggers builds further on event-driven | chitectures for scale and resiliency by receiving and sending events to and from any external | source such as databases, queues, file systems, etc.
| **[Distributed Tracing](../concepts/distributed-tracing)** | Dapr supports distributed tracing to easily diagnose and | serve inter-service calls in production using the W3C Trace Context standard.
| **[Actors](../concepts/actors)** | A pattern for stateful and stateless objects that make concurrency simple with method and state encapsulation. Dapr provides many capabilities in its actor runtime including concurrency, state, life-cycle management for actor activation/deactivation and timers and reminders to wake-up actors.
## Sidecar architecture
Dapr exposes its APIs as a sidecar architecture, either as a container or as a process, not requiring the application code to include any Dapr runtime code. This makes integration with Dapr easy from other runtimes, as well as providing separation of the application logic for improved supportability.
### Standalone
In standaline mode dapr runs as a separate process from which your service code can call via HTTP or gRPC.
<img src="../images/overview-sidecar.png" width=600>
### Kubernetes
In container hosting environments such as Kubernetes, Dapr runs as a side-car container with the application container in the same pod.
<img src="../images/overview-sidecar-kubernetes.png" width=600>
## Developer language SDKs and frameworks
To make using Dapr more natural for different languages, it also includes language specific SDKs for Go, Java, JavaScript, .NET and Python. These SDKs expose the functionality in the Dapr building blocks, such as saving state, publishing an event or creating an actor, through a typed, language API rather than calling the http/gRPC API. This enables you to write a combination of stateless and stateful functions and actors all in the language of their choice. And because these SDKs share the Dapr runtime, you get cross-language actor and functions support.
### SDKs
- **[C++ SDK](https://github.com/dapr/cpp-sdk)**
- **[Go SDK](https://github.com/dapr/go-sdk)**
- **[Java SDK](https://github.com/dapr/java-sdk)**
- **[Javascript SDK](https://github.com/dapr/js-sdk)**
- **[Python SDK](https://github.com/dapr/python-sdk)**
- **[.NET SDK](https://github.com/dapr/dotnet-sdk)**
> Note: Dapr is language agnostic and provides a [RESTful HTTP API](./reference/api/README.md) in addition to the protobuf clients.
### Developer frameworks
Furthermore, Dapr can be integrated with any developer framework. For example, in the Dapr [.NET SDK](https://github.com/dapr/dotnet-sdk) you can find ASP.NET Core integration, which brings stateful routing controllers that respond to pub/sub events from other services. And in the Dapr [Java SDK](https://github.com/dapr/java-sdk) you can find Spring Boot integration. Others are planned for the future including Django for Python, Azure Functions runtime, Azure LogicApps runtime and server side Blazor.
## Running Dapr on a local developer machine in self hosted mode
Dapr can be configured to run on your local developer machine in [self hosted mode](../getting-started). Each running service has a Dapr runtime process (or sidecar) which is configured to use state stores, pub/sub, binding components and the other building blocks.
In self hosted mode, Redis running locally in a container, is installed as the both a default a state store and pub/sub message bus components. See the local Components folder for the yaml files.
The `dapr-placement` service is responsible for managing the actor distribution scheme and key range settings. This service is only required if you are using Dapr actors. For more information on the actor `Placement` service read [actor overview](../concepts/actors).
<img src="../images/overview_standalone.png" width=800>
You can use the [Dapr CLI](https://github.com/dapr/cli#launch-dapr-and-your-app) to run a Dapr enabled application on your local machine.
## Running Dapr in Kubernetes mode
Dapr can be configured to run on any [Kubernetes cluster](https://github.com/dapr/samples/tree/master/2.hello-kubernetes). In Kubernetes the `dapr-sidecar-injector` and `dapr-operator` services provide first class integration to launch Dapr as a sidecar container in the same pod as the service container and provide notifications of Dapr component updates provisioned into the cluster.
The `dapr-sentry` service is a certificate authority that enables mutual TLS between Dapr sidecar instances for secure data encryption. For more information on the `Sentry` service read the [security overview](../concepts/security/readme.md#dapr-to-dapr-communication)
<img src="../images/overview_kubernetes.png" width=800>
Deploying and running a Dapr enabled application into your kubernetes cluster is a simple as adding a few annotations to the deployment schemes. To give your service an id and port known to Dapr, turn on tracing information and launch the Dapr sidecar container, you annotate your Kubernetes deployment like this.
```yml
annotations:
dapr.io/enabled: "true"
dapr.io/id: "nodeapp"
dapr.io/port: "3000"
dapr.io/config: "tracing"
```
You can see some examples [here](https://github.com/dapr/samples/tree/master/2.hello-kubernetes/deploy) in the kubernetes getting started guide.

3
quickstart/readme.md
View File

@ -1,3 +0,0 @@
# Dapr Quickstarts and Samples
- The **[Dapr Samples repo](https://github.com/dapr/samples/blob/master/README.md)** has samples for getting started building applications

11
reference/README.md
View File

@ -1,4 +1,11 @@
# Dapr References
# Dapr references
- **[Dapr CLI](https://github.com/dapr/cli)**: The Dapr CLI allows you to setup Dapr on your local dev machine or on a Kubernetes cluster, provides debugging support, launches and manages Dapr instances.
- **[Dapr API](./api)**: Provides a clear understanding of the Dapr runtime HTTP API surface and help evolve it for the benefit of developers everywhere.
- **[Dapr APIs](./api)**: Dapr provides a variety of APIs to allow developers to access building block capabilities:
- [Actors](./api/actors_api.md)
- [Bindings](./api/bindings_api.md)
- [Publish/Subscribe Messaging](./api/pubsub_api.md)
- [Secrets](./api/secrets_api.md)
- [Service Invocation](./api/service_invocation_api.md)
- [State Management](./api/state_api.md)
- **[Dapr Binding Specs](./specs/bindings)**: Bindings provide triggers and interactions with external resources and services

141
reference/api/CONTRIBUTING.md
View File

@ -1,141 +0,0 @@
# Contributing Guidelines
Thank you for your interest in Dapr!
This project welcomes contributions and suggestions. Most contributions require you to
agree to a Contributor License Agreement (CLA) declaring that you have the right to,
and actually do, grant us the rights to use your contribution.
For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need
to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the
instructions provided by the bot. You will only need to do this once across all repositories using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct.
For more information see the Code of Conduct FAQ
or contact opencode@microsoft.com with any additional questions or comments.
Contributions come in many forms: submitting issues, writing code, participating in discussions and community calls.
This document provides the guidelines for how to contribute to the Dapr project.
## Issues
Issues are used as the primary method for tracking anything to do with the Dapr API Specification project.
### Issue Types
There are 4 types of issues (each with their own corresponding [label](#labels)):
- Discussion: These are support or functionality inquiries that we want to have a record of for
future reference. Depending on the discussion, these can turn into "Spec Change" issues.
- Proposal: Used for items that propose a new ideas or functionality that require
a larger discussion. This allows for feedback from others teams before a
spec change is actually written. All issues that are proposals should
both have a label and an issue title of "Proposal: [the rest of the title]." A proposal can become
a "Spec Change" and does not require a milestone.
- Spec Change: These track specific spec changes and ideas until they are complete. They can evolve
from "Proposal" and "Discussion" items, or can be submitted individually depending on the size.
### Issue Lifecycle
The issue lifecycle is mainly driven by the core maintainers, but is good information for those
contributing to Helm. All issue types follow the same general lifecycle. Differences are noted below.
1. Issue creation
2. Triage
- The maintainer in charge of triaging will apply the proper labels for the issue. This
includes labels for priority, type, and metadata.
- (If needed) Clean up the title to succinctly and clearly state the issue. Also ensure
that proposals are prefaced with "Proposal".
- We attempt to do this process at least once per work day.
3. Discussion
- "Spec Change" issues should be connected to the PR that resolves it.
- Whoever is working on a "Spec Change" issue should either assign the issue to themself or make a comment in the issue
saying that they are taking it.
- "Proposal" and "Discussion" issues should stay open until resolved.
4. Issue closure
## How to Contribute a Patch
1. Fork the repo, modify the specification to address the issue.
2. Submit a pull request.
The next section contains more information on the workflow followed for Pull Requests.
## Pull Requests and Issues
Like any good open source project, we use Pull Requests (PRs) to track code changes.
### PR Lifecycle
1. PR creation
- We more than welcome PRs that are currently in progress. They are a great way to keep track of
important work that is in-flight, but useful for others to see. If a PR is a work in progress,
it **should** be prefaced with "WIP: [title]". You should also add the `wip` **label** Once the PR is ready for review, remove "WIP" from the title and label.
- It is preferred, but not required, to have a PR tied to a specific issue. There can be
circumstances where if it is a quick fix then an issue might be overkill. The details provided
in the PR description would suffice in this case.
2. Triage
- The maintainer in charge of triaging will apply the proper labels for the issue. This should
include at least a size label, a milestone, and `awaiting review` once all labels are applied.
See the [Labels section](#labels) for full details on the definitions of labels.
3. Assigning reviews
- All PRs require at least 2 review approvals before it can be merged.
4. Reviewing/Discussion
- All reviews will be completed using Github review tool.
- A "Comment" review should be used when there are questions about the spec that should be
answered, but that don't involve spec changes. This type of review does not count as approval.
- A "Changes Requested" review indicates that changes to the spec need to be made before they will be
merged.
- Reviewers should update labels as needed (such as `needs rebase`).
- When a review is approved, the reviewer should add `LGTM` as a comment.
- Final approval is required by a designated owner (see `.github/CODEOWNERS` file). Merging is blocked without this final approval. Approvers will factor reviews from all other reviewers into their approval process.
5. PR owner should try to be responsive to comments by answering questions or changing text. Once all comments have been addressed,
the PR is ready to be merged.
6. Merge or close
- A PR should stay open until a Final Approver (see above) has marked the PR approved.
- PRs can be closed by the author without merging
- PRs may be closed by a Final Approver if the decision is made that the PR is not going to be merged
## The Triager
Each week, someone from the Dapr team should act as the triager. This person will be in charge triaging new PRs and issues throughout the day.
## Labels
The following tables define all label types used for the Dapr API Specification. It is split up by category.
### Common
| Label | Description |
| ----- | ----------- |
| `high priority` | Marks an issue or PR as critical. This means that addressing the PR or issue is top priority and will be handled first |
| `duplicate` | Indicates that the issue or PR is a duplicate of another |
| `spec change` | Marks the issue or a PR as an agreed upon change to the spec |
| `wip` | Identifies an issue or PR as a work in progress |
### Issue Specific
| Label | Description |
| ----- | ----------- |
| `proposal` | This issue is a proposal |
| `discussion` | This issue is a question or discussion point to capture feedback |
### PR Specific
| Label | Description |
| ----- | ----------- |
| `awaiting review` | The PR has been triaged and is ready for someone to review |
| `needs rebase` | A helper label used to indicate that the PR needs to be rebased before it can be merged. Used for easy filtering |
#### Size labels
Size labels are used to indicate how much change is in a given PR. This is helpful for estimating review time.
| Label | Description |
| ----- | ----------- |
| `size/small` | Anything less than or equal to 4 files and 150 lines. |
| `size/medium` | Anything greater than `size/small` and less than or equal to 8 files and 300 lines. |
| `size/large` | Anything greater than `size/medium`. This also should be applied to anything that is a significant specification change.

21
reference/api/LICENSE
View File

@ -1,21 +0,0 @@
Copyright (c) Microsoft Corporation.
MIT License
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

28
reference/api/README.md
View File

@ -1,28 +0,0 @@
# Dapr API reference
This documentation contains the API reference for the Dapr runtime.
Dapr is an open source runtime that provides a set of building blocks for building scalable distributed apps.
Building blocks include pub/sub, state management, bindings, messaging and invocation, actor runtime capabilities, and more.
Dapr aims to provide an open, community driven approach to solving real world problems at scale.
These building blocks are provided in a platform agnostic and language agnostic way over common protocols such as HTTP 1.1/2.0 and gRPC.
### Goals
The goal of the Dapr API reference is to provide a clear understanding of the Dapr runtime API surface and help evolve it for the benefit of developers everywhere.
Any changes/proposals to the Dapr API should adhere to the following:
* Must be platform agnostic
* Must be programming language agnostic
* Must be backward compatible
## Table of Contents
1. [Service Invocation](service_invocation.md)
2. [Bindings](bindings.md)
3. [Pub Sub/Broadcast](pubsub.md)
4. [State Management](state.md)
5. [Actors](actors.md)

174
reference/api/actors.md → reference/api/actors_api.md
View File

@ -1,13 +1,34 @@
# Actors
# Dapr actors API reference
Dapr provides native, cross-platform and cross-language virtual actor capabilities.
Besides the language specific Dapr SDKs, a developer can invoke an actor using the API endpoints below.
## Specifications for user service code calling to Dapr
## Endpoints
### Invoke Actor Method
- [Service Code Calling to Dapr](#specifications-for-user-service-code-calling-to-dapr)
- [Invoke Actor Method](#invoke-actor-method)
- [Save Actor State](#save-actor-state)
- [Actor State Transactions](#actor-state-transactions)
- [Get Actor State](#get-actor-state)
- [Create Actor Reminder](#create-actor-reminder)
- [Get Actor Reminder](#get-actor-reminder)
- [Delete Actor Reminder](#delete-actor-reminder)
- [Create Actor Timer](#create-actor-timer)
- [Delete Actor Timer](#delete-actor-timer)
- [Dapr Calling to Service Code](#specifications-for-dapr-calling-to-user-service-code)
- [Get Registered Actors](#get-registered-actors)
- [Activate Actor](#activate-actor)
- [Deactivate Actor](#deactivate-actor)
- [Invoke Actor Method](#invoke-actor-method-1)
- [Invoke Reminder](#invoke-reminder)
- [Invoke Timer](#invoke-timer)
- [Querying Actor State Externally](#querying-actor-state-externally)
Invokes a method on an actor.
## User service code calling dapr
### Invoke actor method
Invoke an actor method through Dapr.
#### HTTP Request
@ -32,14 +53,17 @@ actorType | The actor type.
actorId | The actor ID.
method | The name of the method to invoke.
> Example of invoking a method on an actor:
#### Examples
Example of invoking a method on an actor:
```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/method/shoot \
-H "Content-Type: application/json"
```
> Example of invoking a method on an actor with a payload:
Example of invoking a method on an actor that takes parameters: You can provided the method parameters and values in the body of the request, for example in curl using -d "{\"param\":\"value\"}"
```shell
curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
@ -48,18 +72,24 @@ curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
"destination": "Hoth"
}'
```
or
> The response from the remote endpoint will be returned in the request body.
```shell
curl -X POST http://localhost:3500/v1.0/actors/x-wing/33/method/fly \
-H "Content-Type: application/json"
-d "{\"destination\":\"Hoth\"}"
```
The response (the method return) from the remote endpoint is returned in the request body.
### Actor State Changes - Transaction
### Save actor state
Persists the changed to the state for an actor as a multi-item transaction.
***Note that this operation is dependant on a state store that supports multi-item transactions.***
Persists the changed to the state for an actor
#### HTTP Request
`POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state`
```http
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state
```
#### HTTP Response Codes
@ -77,6 +107,43 @@ daprPort | The Dapr port.
actorType | The actor type.
actorId | The actor ID.
Value of the key is passed as request body:
```shell
{
"key": "value"
}
```
### Actor state transactions
Persists the changed to the state for an actor as a multi-item transaction.
***Note that this operation is dependant on a using state store component that supports multi-item transactions.***
#### HTTP Request
```http
POST/PUT http://localhost:<daprPort>/v1.0/actors/<actorType>/<actorId>/state
```
#### HTTP Response Codes
Code | Description
---- | -----------
201 | Request successful
500 | Request failed
404 | Actor not found
#### URL Parameters
Parameter | Description
--------- | -----------
daprPort | The Dapr port.
actorType | The actor type.
actorId | The actor ID.
#### Examples
```shell
curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
-H "Content-Type: application/json"
@ -97,7 +164,7 @@ curl -X POST http://localhost:3500/v1.0/actors/stormtrooper/50/state \
]'
```
### Get Actor State
### Get actor state
Gets the state for an actor using a specified key.
@ -124,12 +191,14 @@ actorType | The actor type.
actorId | The actor ID.
key | The key for the state value.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
-H "Content-Type: application/json"
```
> The above command returns the state:
The above command returns the state:
```json
{
@ -137,7 +206,7 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/state/location \
}
```
### Create Actor Reminder
### Create actor reminder
Creates a persistent reminder for an actor.
@ -190,6 +259,8 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the reminder to create.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-H "Content-Type: application/json"
@ -200,7 +271,7 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
}'
```
### Get Actor Reminder
### Get actor reminder
Gets a reminder for an actor.
@ -227,12 +298,14 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the reminder to get.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
"Content-Type: application/json"
```
> The above command returns the reminder:
The above command returns the reminder:
```json
{
@ -242,7 +315,7 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
}
```
### Delete Actor Reminder
### Delete actor reminder
Deletes a reminder for an actor.
@ -269,12 +342,14 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the reminder to delete.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \
-X "Content-Type: application/json"
```
### Create Actor Timer
### Create actor timer
Creates a timer for an actor.
@ -319,6 +394,8 @@ actorType | The actor type.
actorId | The actor ID.
name | The name of the timer to create.
#### Examples
```shell
curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
-H "Content-Type: application/json"
@ -330,7 +407,7 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
}'
```
### Delete Actor Timer
### Delete actor timer
Deletes a timer for an actor.
@ -362,11 +439,11 @@ curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \
-X "Content-Type: application/json"
```
## Specifications for Dapr calling to user service code
## Dapr calling to user service code
### Get Registered Actors
### Get registered actors
Gets the registered actors in Dapr.
Gets the registered actors types for this app and the Dapr actor configuration settings.
#### HTTP Request
@ -387,14 +464,16 @@ Parameter | Description
--------- | -----------
appPort | The application port.
> Example of getting the registered actors:
#### Examples
Example of getting the registered actors:
```shell
curl -X GET http://localhost:3000/dapr/config \
-H "Content-Type: application/json"
```
> The above command returns the config (all fields are optional):
The above command returns the config (all fields are optional):
Parameter | Description
@ -415,9 +494,9 @@ drainRebalancedActors | A bool. If true, Dapr will wait for `drainOngoingCallTi
}
```
### Activate Actor
### Activate actor
Activates an actor.
Activates an actor by creating an instance of the actor with the specified actorId
#### HTTP Request
@ -441,16 +520,18 @@ appPort | The application port.
actorType | The actor type.
actorId | The actor ID.
> Example of activating an actor:
#### Examples:
Example of activating an actor: The example creates an actor of type stormtrooper with an actorId of 50
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50 \
-H "Content-Type: application/json"
```
### Deactivate Actor
### Deactivate actor
Deactivates an actor.
Deactivates an actor by persisting the instance of the actor to the state store with the specified actorId
#### HTTP Request
@ -474,16 +555,18 @@ appPort | The application port.
actorType | The actor type.
actorId | The actor ID.
> Example of deactivating an actor:
#### Examples
Example of deactivating an actor: The example deactives the actor type stormtrooper that has actorId of 50
```shell
curl -X DELETE http://localhost:3000/actors/stormtrooper/50 \
-H "Content-Type: application/json"
```
### Invoke Actor method
### Invoke actor method
Invokes a method for an actor.
Invokes a method for an actor with the specified methodName where parameters to the method are passed in the body of the request message and return values are provided in the body of the response message
#### HTTP Request
@ -508,16 +591,18 @@ actorType | The actor type.
actorId | The actor ID.
methodName | The name of the method to invoke.
> Example of invoking a method for an actor:
#### Examples
Example of invoking a method for an actor: The example calls the performAction method on the actor type stormtrooper that has actorId of 50
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/performAction \
-H "Content-Type: application/json"
```
### Invoke Reminder
### Invoke reminder
Invokes a reminder for an actor.
Invokes a reminder for an actor with the specified reminderName
#### HTTP Request
@ -542,16 +627,18 @@ actorType | The actor type.
actorId | The actor ID.
reminderName | The name of the reminder to invoke.
> Example of invoking a reminder for an actor:
#### Examples
Example of invoking a reminder for an actor: The example calls the checkRebels reminder method on the actor type stormtrooper that has actorId of 50
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/remind/checkRebels \
-H "Content-Type: application/json"
```
### Invoke Timer
### Invoke timer
Invokes a timer for an actor.
Invokes a timer for an acto rwith the specified timerName
#### HTTP Request
@ -576,18 +663,19 @@ actorType | The actor type.
actorId | The actor ID.
timerName | The name of the timer to invoke.
> Example of invoking a timer for an actor:
#### Examples
Example of invoking a timer for an actor: The example calls the checkRebels timer method on the actor type stormtrooper that has actorId of 50
```shell
curl -X POST http://localhost:3000/actors/stormtrooper/50/method/timer/checkRebels \
-H "Content-Type: application/json"
```
## Querying Actor State Externally
## Querying actor state externally
In order to promote visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external databases.
In order to enable visibility into the state of an actor and allow for complex scenarios such as state aggregation, Dapr saves actor state in external state stores such as databases. As such, it is possible to query for an actor state externally by composing the correct key or query.
As such, it is possible to query for an actor state externally by composing the correct key or query.
The state namespace created by Dapr for actors is composed of the following items:
* Dapr ID - Represents the unique ID given to the Dapr application.

67
reference/api/azure-pipelines.yml
View File

@ -1,67 +0,0 @@
# dapr/spec
trigger:
- master
pr : none
pool:
vmImage: 'ubuntu-latest'
steps:
- task: UseNode@1
inputs:
version: '10.16.3'
- task: Bash@3
displayName: 'Install md-to-pdf'
inputs:
targetType: 'inline'
script: |
npm install -g md-to-pdf
workingDirectory: '$(Build.SourcesDirectory)'
- task: Bash@3
displayName: 'Create pdf output directory'
inputs:
targetType: 'inline'
script: |
mkdir ./output_pdf
mkdir ./output_md
workingDirectory: '$(Build.SourcesDirectory)'
- task: Bash@3
displayName: 'Generate PDF files'
inputs:
targetType: 'inline'
script: |
echo Copying *.md to ./output_md/
cp *.md ./output_md/
pushd ./output_md
rm -f README.md CONTRIBUTING.md
echo Genereating PDFs from markdown documents
for filename in *.md; do
md-to-pdf $filename ../output_pdf/$(basename $filename .md).pdf
done
popd
workingDirectory: '$(Build.SourcesDirectory)'
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(Build.SourcesDirectory)/output_pdf/'
includeRootFolder: false
archiveType: 'zip'
archiveFile: '$(Build.ArtifactStagingDirectory)/dapr-spec-pdf.zip'
replaceExistingArchive: true
- task: ArchiveFiles@2
inputs:
rootFolderOrFile: '$(Build.SourcesDirectory)/output_md/'
includeRootFolder: false
archiveType: 'zip'
archiveFile: '$(Build.ArtifactStagingDirectory)/dapr-spec-md.zip'
replaceExistingArchive: true
- task: PublishBuildArtifacts@1
inputs:
PathtoPublish: '$(Build.ArtifactStagingDirectory)'
ArtifactName: 'drop'
publishLocation: 'Container'

32
reference/api/bindings.md → reference/api/bindings_api.md
View File

@ -5,7 +5,15 @@ Developers can invoke output bindings using the Dapr API, and have the Dapr runt
Examples for bindings include ```Kafka```, ```Rabbit MQ```, ```Azure Event Hubs```, ```AWS SQS```, ```GCP Storage``` to name a few.
An Dapr Binding has the following structure:
## Contents
- [Bindings Structure](#bindings-structure)
- [Invoking Service Code Through Input Bindings](#invoking-service-code-through-input-bindings)
- [Sending Messages to Output Bindings](#sending-messages-to-output-bindings)
## Bindings Structure
A Dapr Binding yaml file has the following structure:
```yml
apiVersion: dapr.io/v1alpha1
@ -19,13 +27,25 @@ spec:
value: <VALUE>
```
The ```metadata.name``` is the name of the binding. A developer who wants to trigger her app using an input binding can listen on a ```POST``` http endpoint with the route name being the same as ```metadata.name```.
The ```metadata.name``` is the name of the binding.
If running self hosted locally, place this file in your `components` folder next to your state store and message queue yml configurations.
If running on kubernetes apply the component to your cluster.
> **Note:** In production never place passwords or secrets within Dapr component files. For information on securely storing and retrieving secrets using secret stores refer to [Setup Secret Store](../../../howto/setup-secret-store)
## Invoking Service Code Through Input Bindings
A developer who wants to trigger their app using an input binding can listen on a ```POST``` http endpoint with the route name being the same as ```metadata.name```.
On startup Dapr sends a ```OPTIONS``` request to the ```metadata.name``` endpoint and expects a different status code as ```NOT FOUND (404)``` if this application wants to subscribe to the binding.
The ```metadata``` section is an open key/value metadata pair that allows a binding to define connection properties, as well as custom properties unique to the implementation.
The ```metadata``` section is an open key/value metadata pair that allows a binding to define connection properties, as well as custom properties unique to the component implementation.
For example, here's how a Python application subscribes for events from ```Kafka``` using an Dapr API compliant platform:
### Examples
For example, here's how a Python application subscribes for events from ```Kafka``` using a Dapr API compliant platform. Note how the metadata.name value `kafkaevent` in the components matches the POST route name in the Python code.
#### Kafka Component
@ -60,7 +80,7 @@ def incoming():
return "Kafka Event Processed!"
```
## Sending messages to output bindings
## Sending Messages to Output Bindings
This endpoint lets you invoke an Dapr output binding.
@ -100,6 +120,8 @@ Parameter | Description
daprPort | the Dapr port
name | the name of the binding to invoke
### Examples
```shell
curl -X POST http://localhost:3500/v1.0/bindings/myKafka \
-H "Content-Type: application/json" \

0
reference/api/pubsub.md → reference/api/pubsub_api.md
View File

9
reference/api/secrets.md → reference/api/secrets_api.md
View File

@ -1,11 +1,10 @@
# Secrets
# Secrets API Specification
Dapr offers developers a consistent way to extract application secrets, without needing to know the specifics of the secret store being used.
Secret stores are components in Dapr. Dapr allows users to write new secret stores implementations that can be used both to hold secrets for other Dapr components (for example secrets used by a state store to read/write state) as well as serving the application with a dedicated secret API. Using the secrets API, you can easily read secrets that can be used by the application from the a named secrets store.
## Endpoints
Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores)
- [Get Secret](#get-secret)
## Get secret
## Get Secret
This endpoint lets you get the key-identified value of secret for a given secret store.

46
reference/api/service_invocation.md
View File

@ -1,46 +0,0 @@
# Service Invocation
Dapr provides users with the ability to call other applications that have unique ids.
This functionality allows apps to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.
## Invoke a method on a remote Dapr app
This endpoint lets you invoke a method in another Dapr enabled app.
### HTTP Request
```http
POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appId>/method/<method-name>
```
### HTTP Response codes
Code | Description
---- | -----------
200 | Request successful
500 | Request failed
### URL Parameters
Parameter | Description
--------- | -----------
daprPort | the Dapr port
appId | the App ID associated with the remote app
method-name | the name of the method or url to invoke on the remote app
```shell
curl http://localhost:3500/v1.0/invoke/countService/method/sum \
-H "Content-Type: application/json"
```
### Sending data
You can send data by posting it as part of the request body.
```shell
curl http://localhost:3500/v1.0/invoke/countService/method/calculate \
-H "Content-Type: application/json"
-d '{ "arg1": 10, "arg2": 23, "operator": "+" }'
```
> The response from the remote endpoint will be returned in the request body.

87
reference/api/service_invocation_api.md Normal file
View File

@ -0,0 +1,87 @@
# Service Invocation API Specification
Dapr provides users with the ability to call other applications that have unique ids.
This functionality allows apps to interact with one another via named identifiers and puts the burden of service discovery on the Dapr runtime.
## Contents
- [Invoke a Method on a Remote Dapr App](#invoke-a-method-on-a-remote-dapr-app)
## Invoke a method on a remote dapr app
This endpoint lets you invoke a method in another Dapr enabled app.
### HTTP Request
```http
POST/GET/PUT/DELETE http://localhost:<daprPort>/v1.0/invoke/<appId>/method/<method-name>
```
### HTTP Response codes
Code | Description
---- | -----------
200 | Request successful
500 | Request failed
### URL Parameters
Parameter | Description
--------- | -----------
daprPort | the Dapr port
appId | the App ID associated with the remote app
method-name | the name of the method or url to invoke on the remote app
### Request Contents
In the request you can pass along headers:
```json
{
"Content-Type": "application/json"
}
```
Within the body of the request place the data you want to send to the service:
```json
{
"arg1": 10,
"arg2": 23,
"operator": "+"
}
```
### Request received by invoked service
Once your service code invokes a method in another Dapr enabled app, Dapr will send the request, along with the headers and body, to the app on the `<method-name>` endpoint.
The Dapr app being invoked will need to be listening for and responding to requests on that endpoint.
### Examples
You can invoke the `add` method on the `mathService` service by sending the following:
```shell
curl http://localhost:3500/v1.0/invoke/mathService/method/add \
-H "Content-Type: application/json"
-d '{ "arg1": 10, "arg2": 23}'
```
The `mathService` service will need to be listening on the `/add` endpoint to receive and process the request.
For a Node app this would look like:
```js
app.post('/add', (req, res) => {
let args = req.body;
const [operandOne, operandTwo] = [Number(args['arg1']), Number(args['arg2'])];
let result = operandOne / operandTwo;
res.send(result.toString());
});
app.listen(port, () => console.log(`Listening on port ${port}!`));
```
> The response from the remote endpoint will be returned in the request body.

22
reference/api/state.md → reference/api/state_api.md
View File

@ -1,11 +1,17 @@
# State management
# State Management API Specification
Dapr offers a reliable state endpoint that allows developers to save and retrieve state via an API.
Dapr has a pluggable architecture and allows binding to a multitude of cloud/on-premises state stores.
## Endpoints
- [Component File](#component-file)
- [Key Scheme](#key-scheme)
- [Save State](#save-state)
- [Get State](#get-state)
- [Delete State](#delete-state)
- [Configuring State Store for Actors](#configuring-state-store-for-actors)
- [Optional Behaviors](#optional-behaviors)
Examples for state stores include ```Redis```, ```Azure CosmosDB```, ```AWS DynamoDB```, ```GCP Cloud Spanner```, ```Cassandra``` to name a few.
## Component file
An Dapr State Store has the following structure:
A Dapr State Store component yaml file has the following structure:
```yml
apiVersion: dapr.io/v1alpha1
@ -33,13 +39,13 @@ Please refer https://github.com/dapr/dapr/blob/master/docs/decision_records/api/
Dapr state stores are key/value stores. To ensure data compatibility, Dapr requires these data stores follow a fixed key scheme. For general states, the key format is:
```bash
```
<Dapr id>||<state key>
```
For Actor states, the key format is:
```bash
```
<Dapr id>||<Actor type>||<Actor id>||<state key>
```
@ -210,7 +216,7 @@ None.
curl -X "DELETE" http://localhost:3500/v1.0/state/starwars/planet -H "ETag: xxxxxxx"
```
## Configuring State Store for Actors
## Configuring state store for actors
Actors don't support multiple state stores and require a transactional state store to be used with Dapr. Currently mongodb and redis implement the transactional state store interface.
To specify which state store to be used for actors, specify value of property `actorStateStore` as true in the metadata section of the state store component yaml file.

10
reference/specs/bindings/README.md Normal file
View File

@ -0,0 +1,10 @@
# Binding component specs
The files within this directory contain the detailed information for each binding component, including the applicable fields, structure, and explanation.
## Quick links
- [Concept: Bindings](../../../concepts/bindings/README.md)
- [Implementing a new binding](https://github.com/dapr/components-contrib/blob/master/bindings/Readme.md#implementing-a-new-binding)
- [How-to: Trigger app with input binding](../../../howto/trigger-app-with-input-binding/README.md)
- [How-to: Send events with output bindings](../../../howto/send-events-with-output-bindings/README.md)

23
reference/specs/bindings/blobstorage.md Normal file
View File

@ -0,0 +1,23 @@
# Azure Blob Storage Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

29
reference/specs/bindings/cosmosdb.md Normal file
View File

@ -0,0 +1,29 @@
# Azure CosmosDB Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

26
reference/specs/bindings/dynamodb.md Normal file
View File

@ -0,0 +1,26 @@
# AWS DynamoDB Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

2
concepts/bindings/specs/eventhubs.md → reference/specs/bindings/eventhubs.md
View File

@ -19,3 +19,5 @@ spec:
- `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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

24
concepts/bindings/specs/gcpbucket.md → reference/specs/bindings/gcpbucket.md
View File

@ -32,14 +32,16 @@ spec:
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.
- `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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

26
concepts/bindings/specs/gcppubsub.md → reference/specs/bindings/gcppubsub.md
View File

@ -34,15 +34,17 @@ spec:
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.
- `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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

4
concepts/bindings/specs/http.md → reference/specs/bindings/http.md
View File

@ -14,5 +14,5 @@ spec:
value: GET
```
`url` is the HTTP url to invoke.
`method` is the HTTP verb to use for the request.
- `url` is the HTTP url to invoke.
- `method` is the HTTP verb to use for the request.

35
reference/specs/bindings/kafka.md Normal file
View File

@ -0,0 +1,35 @@
# Kafka Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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"`.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

2
concepts/bindings/specs/kubernetes.md → reference/specs/bindings/kubernetes.md
View File

@ -12,4 +12,4 @@ spec:
value: default
```
`namespace` is the Kubernetes namespace to read events from. Default is `default`.
- `namespace` is the Kubernetes namespace to read events from. Default is `default`.

4
concepts/bindings/specs/mqtt.md → reference/specs/bindings/mqtt.md
View File

@ -14,5 +14,5 @@ spec:
value: topic1
```
`url` is the MQTT broker url.
`topic` is the topic to listen on or send events to.
- `url` is the MQTT broker url.
- `topic` is the topic to listen on or send events to.

8
concepts/bindings/specs/rabbitmq.md → reference/specs/bindings/rabbitmq.md
View File

@ -18,7 +18,7 @@ spec:
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.
- `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.

20
reference/specs/bindings/redis.md Normal file
View File

@ -0,0 +1,20 @@
# Redis Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <name>
spec:
type: bindings.redis
metadata:
- name: redisHost
value: <address>:6379
- name: redisPassword
value: **************
```
- `redisHost` is the Redis host address.
- `redisPassword` is the Redis password.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

26
reference/specs/bindings/s3.md Normal file
View File

@ -0,0 +1,26 @@
# AWS S3 Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

20
reference/specs/bindings/servicebusqueues.md Normal file
View File

@ -0,0 +1,20 @@
# Azure Service Bus Queues Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

6
concepts/bindings/specs/signalr.md → reference/specs/bindings/signalr.md
View File

@ -14,8 +14,10 @@ spec:
value: <hub name>
```
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").
- 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").
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)
## Additional information

26
reference/specs/bindings/sns.md Normal file
View File

@ -0,0 +1,26 @@
# AWS SNS Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

26
reference/specs/bindings/sqs.md Normal file
View File

@ -0,0 +1,26 @@
# AWS SQS Binding Spec
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)

0
concepts/bindings/specs/storagequeues.md → reference/specs/bindings/storagequeues.md
View File

10
concepts/bindings/specs/twilio.md → reference/specs/bindings/twilio.md
View File

@ -18,7 +18,9 @@ spec:
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.
- `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.
> **Note:** In production never place passwords or secrets within Dapr components. For information on securly storing and retrieving secrets refer to [Setup Secret Store](../../../howto/setup-secret-store)