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

Standard README filenames

This commit is contained in:
Aaron Crawfis 2020-03-03 12:54:40 -08:00
parent a34aad00f7
commit fe45e47b3c
14 changed files with 172 additions and 72 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@ -2,13 +2,11 @@
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
- **[Overview](./overview/README.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
## Document versions

11
concepts/actor/actor_overview.md → concepts/actor/README.md
View File

@ -2,6 +2,11 @@
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)
## Understanding actors
An actor is an isolated, independent unit of compute and state with single-threaded execution.
@ -55,17 +60,17 @@ When a client calls an actor with a particular id (for example, actor id 123), t
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)
## Actor communication
## Actor Communication
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.
Refer [dapr spec](../../reference/api/actors.md) for more details.
Refer to [Dapr Actor Features](./actors_features.md) for more details.
### Concurrency

68
concepts/actor/actors_features.md
View File

@ -2,11 +2,27 @@
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 actor method in the request body and response for the request would be in response body which is data from actor 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.
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:
@ -14,46 +30,6 @@ To use actors, your state store must support multi-item transactions. This mean
- 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.
@ -73,7 +49,7 @@ All timers are stopped when the actor is deactivated as part of garbage collecti
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>
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.
@ -100,16 +76,16 @@ You can remove the actor timer by calling
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/timers/<name>
```
Refer [dapr spec](../../reference/api/actors.md) for more details.
Refer [api spec](./actors_api.md#invoke-timer) for more details.
### Actor reminders
### 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>
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.
@ -154,4 +130,4 @@ You can remove the actor reminder by calling
DELETE http://localhost:3500/v1.0/actors/<actorType>/<actorId>/reminders/<name>
```
Refer [dapr spec](../../reference/api/actors.md) for more details.
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

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)

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

@ -4,6 +4,13 @@ Dapr uses OpenTelemetry (previously known as OpenCensus) for distributed traces
![Tracing](../../images/tracing.png)
## 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

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 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.
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 API to retrieve secrets out of the Dapr supported secret store. Read [Secrets API Specification](./secrets_api.md) for more information.

81
concepts/secrets/component-secrets.md Normal file
View File

@ -0,0 +1,81 @@
# Referencing Secret Stores in Components
Components can reference secrets for the `spec.metadata` section.
In order to reference a secret, you need to set the `auth.secretStore` field to specify the name of the secret store that holds the secrets.
When running in Kubernetes, if the `auth.secretStore` is empty, the Kubernetes secret store is assumed.
## Examples
Using plain text:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
spec:
type: state.redis
metadata:
- name: redisHost
value: localhost:6379
- name: redisPassword
value: MyPassword
```
Using a Kubernetes secret:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: statestore
spec:
type: state.redis
metadata:
- name: redisHost
value: localhost:6379
- name: redisPassword
secretKeyRef:
name: redis-secret
key: redis-password
auth:
secretStore: kubernetes
```
The above example tells Dapr to use the `kubernetes` secret store, extract a secret named `redis-secret` and assign the value of the `redis-password` key in the secret to the `redisPassword` field in the Component.
### Creating a secret and referencing it in a Component
The following example shows you how to create a Kubernetes secret to hold the connection string for an Event Hubs binding.
First, create the Kubernetes secret:
```bash
kubectl create secret generic eventhubs-secret --from-literal=connectionString=*********
```
Next, reference the secret in your binding:
```yml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: eventhubs
spec:
type: bindings.azure.eventhubs
metadata:
- name: connectionString
secretKeyRef:
name: eventhubs-secret
key: connectionString
```
Finally, apply the component to the Kubernetes cluster:
```bash
kubectl apply -f ./eventhubs.yaml
```
All done!

22
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-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.
@ -35,28 +43,28 @@ Specific details for how to do that can be found [here](../../howto/configure-mt
<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>
## Network security
## Network Security
You can adopt common network security technologies such as network security groups (NSGs), demilitarized zones (DMZs) and firewalls to provide layers of protections over your networked resources.
For example, unless configured to talk to an external binding target, Dapr sidecars don’t open connections to the Internet. And most binding implementations use outbound connections only. You can design your firewall rules to allow outbound connections only through designated ports.
## Bindings security
## Bindings Security
Authentication with a binding target is configured by the binding’s configuration file. Generally, you should configure the minimum required access rights. For example, if you only read from a binding target, you should configure the binding to use an account with read-only access rights.
## State store security
## State Store Security
Dapr doesn't transform the state data from applications. This means Dapr doesn't attempt to encrypt/decrypt state data. However, your application can adopt encryption/decryption methods of your choice, and the state data remains opaque to Dapr.
Dapr uses the configured authentication method to authenticate with the underlying state store. And many state store implementations use official client libraries that generally use secured communication channels with the servers.
## Management security
## Management Security
When deploying on Kubernetes, you can use regular [Kubernetes RBAC]( https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to control access to management activities.
When deploying on Azure Kubernetes Service (AKS), you can use [Azure Active Directory (AD) service principals]( https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) to control access to management activities and resource management.
## Component secrets
## Component Secrets
Dapr components uses Dapr's built-in secret management capability to manage secrets. Please see the [secret topic](../components/secrets.md) for more details.

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

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

@ -4,20 +4,31 @@ Dapr makes it simple for you to store key/value data in a store of your choice.
![State management](../../images/state_management.png)
## State management API
## Contents:
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.
- [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 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
), [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.
## State store behaviors
## 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.
@ -50,15 +61,15 @@ Dapr supports both **strong consistency** and **eventual consistency**, with eve
When strong consistency is used, Dapr waits for all replicas (or designated quorums) to acknowledge before it acknowledges a write request. When eventual consistency is used, Dapr returns as soon as the write request is accepted by the underlying data store, even if this is a single replica.
## Retry policies
## Retry Policies
Dapr allows you to attach a retry policy to any write request. A policy is described by an **retryInterval**, a **retryPattern** and a **retryThreshold**. Dapr keeps retrying the request at the given interval up to the specified threshold. You can choose between a **linear** retry pattern or an **exponential** (backoff) pattern. When the **exponential** pattern is used, the retry interval is doubled after each attempt.
## Bulk operations
## Bulk Operations
Dapr supports two types of bulk operations - **bulk** or **multi**. You can group several requests of the same type into a bulk (or a batch). Dapr submits requests in the bulk as individual requests to the underlying data store. In other words, bulk operations are not transactional. On the other hand, you can group requests of different types into a multi-operation, which is handled as an atomic transaction.
## Querying state store directly
## Querying State Store Directly
Dapr saves and retrieves state values without any transformation. You can query and aggregate state directly from the underlying state store. For example, to get all state keys associated with an application ID "myApp" in Redis, use:
@ -69,7 +80,7 @@ KEYS "myApp*"
> **NOTE:** See [How to query Redis store](../../howto/query-state-store/query-redis-store.md) for details on how to query a Redis store.
>
### Querying actor state
### Querying Actor State
If the data store supports SQL queries, you can query an actor's state using SQL queries. For example use:

0
overview.md → overview/README.md
View File