From 6d474695b8e04814f86a107ea288da88cd0c670d Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Mon, 23 Mar 2020 12:35:19 -0700 Subject: [PATCH 01/21] Adding use cases documentation --- README.md | 1 + use-cases/README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 91 insertions(+) create mode 100644 use-cases/README.md diff --git a/README.md b/README.md index dbf5886b8..46b1440c2 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ Welcome to the Dapr documentation repository. You can learn more about Dapr from | Topic | Description | |-------|-------------| |**[Overview](./overview)** | An overview of Dapr and how it enables you to build event driven, distributed applications +|**[Use cases](./use-cases)** | Common use cases that Dapr enables |**[Getting Started](./getting-started)** | Set up your development environment |**[Concepts](./concepts)** | Dapr concepts explained |**[How-Tos](./howto)** | Guides explaining how to accomplish specific tasks diff --git a/use-cases/README.md b/use-cases/README.md new file mode 100644 index 000000000..280aa895f --- /dev/null +++ b/use-cases/README.md @@ -0,0 +1,90 @@ +# Dapr use cases + +This document briefly describes scenarios that Dapr enables for your microservices. Each use case is accompanied with a link to learn more details. + +## Service invocation + +Dapr provides a uniform API that your microservice can use to find and reliably communicate with other microservices in your system. By using this API, your code can seamlessly take advantage of several built-in features: + +- HTTP and [gRPC](https://grpc.io) support +- Robust retry logic +- Intelligent error handling +- Distributed tracing + +Visit the following documents to learn more: + +- [More details on service invocation](https://github.com/dapr/docs/blob/master/concepts/service-invocation/README.md) +- [How to get started with service invocation](https://github.com/dapr/docs/tree/master/howto/invoke-and-discover-services) + + +## State management + +Dapr provides an abstraction API that abstracts over [many different databases](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md). Your microservice can leverage these APIs to utilize any supported database without finding or adding a third party SDK to your codebase. + +Visit the following documents to learn more: + +- [More details on state management](https://github.com/dapr/docs/blob/master/concepts/state-management/README.md) +- [How to get started with state management](https://github.com/dapr/docs/tree/master/howto/setup-state-store) + +## Pub/Sub + +Dapr provides an API that enables event-driven architectures in your system. Each microservice can utilize the same API to leverage one of [many supported event buses](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker#reference). Microservices can communicate each other by sending or subscribing to _events_ on specific _topics_. By leveraging this communication style, your microservices remain flexible and loosely coupled. + +Visit the following documents to learn more: + +- [More details on pub/sub](https://github.com/dapr/docs/blob/master/concepts/publish-subscribe-messaging/README.md) +- [How to get started with pub/sub](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker) + +## Bindings + +Similar to pub/sub, Dapr provides a mechanism that can trigger your app in response to an event. Dapr provides bindings to enable your app to respond to events that come from external (outside your system) sources, while pub/sub events come from internal sources. + +For example, your microservice can respond to incoming Twilio/SMS messages using bindings. Your app can focus on the business logic to _responds_ to the incoming SMS event rather than adding and configuring a third party Twilio SDK. + +Similarly, your application can _send_ messages to external destinations using the bindings feature. In the Twilio example, your application would send an SMS, again without adding or configuring a third party Twilio SDK. + +Visit the following documents to learn more: + +- [More details on bindings](https://github.com/dapr/docs/tree/master/concepts/bindings) +- [How to get started with receiving events using bindings](https://github.com/dapr/docs/tree/master/howto/trigger-app-with-input-binding) +- [How to get started with sending events using bindings](https://github.com/dapr/docs/tree/master/howto/send-events-with-output-bindings) + +## Actors + +Dapr provides an API and runtime that allows you to write your business logic as an isolated unit, without worrying about concurrency or other actors. Dapr calls this single isolated unit an "actor". Your running actors can send a message to another actor or can request to create a new actor. In the former case, Dapr manages routing the message to the proper destination. In the latter case, Dapr manages all the state management, synchronization, and concurrency involved with starting the new actor. + +The [actor model](https://en.wikipedia.org/wiki/Actor_model) is a battle-tested programming pattern and as such, comes with very specific use cases: + +- You have a large system composed of many (thousands or more) small microservices, in which the code to _manage_ these microservices (e.g. distribution across nodes, failover, ...) is very complex +- Your microservice(s) do not need concurrent access to state and can instead can [share state by communicating](https://blog.golang.org/codelab-share) +- Your code does operations that have unpredictable latency, such as I/O operations to external web services + +Visit the following documents to learn more: + +- [More details on actors](https://github.com/dapr/docs/tree/master/concepts/actors) +- [Getting started with actors on the .Net platform](https://github.com/dapr/dotnet-sdk/blob/master/docs/get-started-dapr-actor.md) +- [Getting started with actors with the Java SDK](https://github.com/dapr/java-sdk) + +## Mutual TLS + +Dapr enables code-free end-to-end encryption in communication between microservices, called [mutual TLS (mTLS)](https://www.codeproject.com/articles/326574/an-introduction-to-mutual-ssl-authentication). In short, mTLS is a commonly-used security mechanism that provides the following features: + +- Two way authentication - the client proving its identify to the server, and vice-versa +- An encrypted channel for all in-flight communication, after two-way authentication is established + +Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). + +Visit the following documents to learn more: + +- [More details on mTLS](https://github.com/dapr/docs/blob/master/concepts/security/README.md) +- [How to set up mTLS](https://github.com/dapr/docs/tree/master/howto/configure-mtls) + +## Secrets storage + +Dapr provides a consistent, secure API for accessing sensitive data, such as private keys for cloud services or database passwords, that your business logic needs. Using secret stores, you can remove secrets from your source code repositories and replace them with references to secrets in a Dapr secret store. Not only is doing so more secure, it also enables best security practices such as [key rotation](https://docs.microsoft.com/en-us/azure/key-vault/key-vault-key-rotation-log-monitoring). + +Visit the following documents to learn more: + +- [More details on secrets storage](https://github.com/dapr/docs/tree/master/concepts/secrets) +- [How to set up secrets storage](https://github.com/dapr/docs/tree/master/howto/setup-secret-store) + From f769050cdeb657126ad406e2b0690f5bbe7031c4 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Wed, 1 Apr 2020 15:06:00 -0700 Subject: [PATCH 02/21] Responding to comments --- use-cases/README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/use-cases/README.md b/use-cases/README.md index 280aa895f..7e7d97917 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -7,7 +7,6 @@ This document briefly describes scenarios that Dapr enables for your microservic Dapr provides a uniform API that your microservice can use to find and reliably communicate with other microservices in your system. By using this API, your code can seamlessly take advantage of several built-in features: - HTTP and [gRPC](https://grpc.io) support -- Robust retry logic - Intelligent error handling - Distributed tracing @@ -19,7 +18,11 @@ Visit the following documents to learn more: ## State management -Dapr provides an abstraction API that abstracts over [many different databases](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md). Your microservice can leverage these APIs to utilize any supported database without finding or adding a third party SDK to your codebase. +Dapr provides an abstraction API that abstracts over [many different databases](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md). Your microservice can leverage these APIs to utilize any supported database without finding or adding a third party SDK to your codebase. The Dapr state management system also gives your app some features for free that are otherwise complicated and error-prone to build yourself: + +- Distributed concurrency and data consistency +- Retry policies +- Bulk [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations Visit the following documents to learn more: From ec8bcb59812c129fd440d4303df1fbb40ebc1478 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:18:16 -0700 Subject: [PATCH 03/21] Moving service invocation use case out And into the concepts doc --- concepts/service-invocation/README.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/concepts/service-invocation/README.md b/concepts/service-invocation/README.md index 2a98409fe..4f81aefa6 100644 --- a/concepts/service-invocation/README.md +++ b/concepts/service-invocation/README.md @@ -2,6 +2,10 @@ Dapr-enabled apps can communicate with each other through well-known endpoints in the form of http or gRPC messages. +Using the service invocation API, your microservice can find and reliably communicate with other microservices in your system. + +Below is a high level overview of how Dapr's service invocation system works. + ![Service Invocation Diagram](../../images/service-invocation.png) 1. Service A makes a http/gRPC call meant for Service B. The call goes to the local Dapr sidecar. @@ -23,7 +27,8 @@ The following describes items 1-6 again in the context of this sample: Steps 4-5 are the same as the list above. -For more information, see: +# Next Steps -- The [Service Invocation API Spec](../../reference/api/service_invocation_api.md) -- A [HowTo](../../howto/invoke-and-discover-services/README.md) on Service Invocation +**If you're ready to get started**, follow this how-to guide on [how to get started with service invocation](https://github.com/dapr/docs/tree/master/howto/invoke-and-discover-services) + +If you'd like more technical detail on how service invocation works, move on to the [API Spec](../../reference/api/service_invocation_api.md) From 5727fea80a3fd0f802f8537698d4630fae12d0a2 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:35:49 -0700 Subject: [PATCH 04/21] Moving state management use cases into concepts --- concepts/state-management/README.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/concepts/state-management/README.md b/concepts/state-management/README.md index d7d20fc63..29bb297fe 100644 --- a/concepts/state-management/README.md +++ b/concepts/state-management/README.md @@ -1,6 +1,14 @@ # State management -Dapr makes it simple for you to store key/value data in a store of your choice. +Dapr comes with APIs for a key/value storage system, called "state management" in Dapr terminology. If your microservice uses state management, it automatically gets access to any of the [supported databases](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK. + +State management requires that you build your application with several rules in mind, and if you follow those rules, your app will also be able to leverage several other features that would otherwise be complicated and error-prone to build yourself: + +- Distributed concurrency and data consistency +- Retry policies +- Bulk [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations + +See below for a diagram of state management's high level architecture. ![State management](../../images/state_management.png) @@ -17,7 +25,7 @@ Dapr makes it simple for you to store key/value data in a store of your choice. ## State management API -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. +Developers can use the state managment API to retrieve, save and delete state values by providing keys. 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 @@ -32,7 +40,7 @@ Visit [State API](../../reference/api/state_api.md) for more information. 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. +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 fulfill the requests. Not all stores are created equal. To ensure portability of your application, you can query the capabilities of the store and make your code adaptive to different store capabilities. From a22c0a8a48382aef1e1062424427db6332d3c376 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:36:08 -0700 Subject: [PATCH 05/21] Removing state management and service invocation From use cases. More deletions to come --- use-cases/README.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/use-cases/README.md b/use-cases/README.md index 7e7d97917..f7fb61189 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -2,33 +2,6 @@ This document briefly describes scenarios that Dapr enables for your microservices. Each use case is accompanied with a link to learn more details. -## Service invocation - -Dapr provides a uniform API that your microservice can use to find and reliably communicate with other microservices in your system. By using this API, your code can seamlessly take advantage of several built-in features: - -- HTTP and [gRPC](https://grpc.io) support -- Intelligent error handling -- Distributed tracing - -Visit the following documents to learn more: - -- [More details on service invocation](https://github.com/dapr/docs/blob/master/concepts/service-invocation/README.md) -- [How to get started with service invocation](https://github.com/dapr/docs/tree/master/howto/invoke-and-discover-services) - - -## State management - -Dapr provides an abstraction API that abstracts over [many different databases](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md). Your microservice can leverage these APIs to utilize any supported database without finding or adding a third party SDK to your codebase. The Dapr state management system also gives your app some features for free that are otherwise complicated and error-prone to build yourself: - -- Distributed concurrency and data consistency -- Retry policies -- Bulk [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations - -Visit the following documents to learn more: - -- [More details on state management](https://github.com/dapr/docs/blob/master/concepts/state-management/README.md) -- [How to get started with state management](https://github.com/dapr/docs/tree/master/howto/setup-state-store) - ## Pub/Sub Dapr provides an API that enables event-driven architectures in your system. Each microservice can utilize the same API to leverage one of [many supported event buses](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker#reference). Microservices can communicate each other by sending or subscribing to _events_ on specific _topics_. By leveraging this communication style, your microservices remain flexible and loosely coupled. From 4916a604ef9bbe91b86f03a10d2d2ce88e605627 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:41:01 -0700 Subject: [PATCH 06/21] Moving bindings out of use cases --- concepts/bindings/README.md | 12 ++++++------ use-cases/README.md | 14 -------------- 2 files changed, 6 insertions(+), 20 deletions(-) diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index 6b02f95ac..94624d97a 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -1,12 +1,12 @@ # Bindings -Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems. -Bindings allow for on-demand, event-driven compute scenarios, and dapr bindings help developers with the following: +Dapr provides a mechanism that can either (a) trigger your app in response to an event or (b) trigger an external system when your app does something. -* Remove the complexities of connecting to, and polling from, messaging systems such as queues, message buses, etc. -* Focus on business logic and not the implementation details of how interact with a system -* Keep the code free from SDKs or libraries -* Handles retries and failure recovery +For example, bindings allow your microservice to respond to incoming Twilio/SMS messages without adding/configuring a third-party Twilio SDK, worrying about polling from Twilio (or doing websockets, etc...). + +Bindings give you some additional advantages: + +* Handle retries and failure recovery * Switch between bindings at runtime time * Enable portable applications where environment-specific bindings are set-up and no code changes are required diff --git a/use-cases/README.md b/use-cases/README.md index f7fb61189..f85ebf1c2 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -11,20 +11,6 @@ Visit the following documents to learn more: - [More details on pub/sub](https://github.com/dapr/docs/blob/master/concepts/publish-subscribe-messaging/README.md) - [How to get started with pub/sub](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker) -## Bindings - -Similar to pub/sub, Dapr provides a mechanism that can trigger your app in response to an event. Dapr provides bindings to enable your app to respond to events that come from external (outside your system) sources, while pub/sub events come from internal sources. - -For example, your microservice can respond to incoming Twilio/SMS messages using bindings. Your app can focus on the business logic to _responds_ to the incoming SMS event rather than adding and configuring a third party Twilio SDK. - -Similarly, your application can _send_ messages to external destinations using the bindings feature. In the Twilio example, your application would send an SMS, again without adding or configuring a third party Twilio SDK. - -Visit the following documents to learn more: - -- [More details on bindings](https://github.com/dapr/docs/tree/master/concepts/bindings) -- [How to get started with receiving events using bindings](https://github.com/dapr/docs/tree/master/howto/trigger-app-with-input-binding) -- [How to get started with sending events using bindings](https://github.com/dapr/docs/tree/master/howto/send-events-with-output-bindings) - ## Actors Dapr provides an API and runtime that allows you to write your business logic as an isolated unit, without worrying about concurrency or other actors. Dapr calls this single isolated unit an "actor". Your running actors can send a message to another actor or can request to create a new actor. In the former case, Dapr manages routing the message to the proper destination. In the latter case, Dapr manages all the state management, synchronization, and concurrency involved with starting the new actor. From 5fc96fe2f8e92f4eed85564fb5894f4c29eeba47 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:51:46 -0700 Subject: [PATCH 07/21] Moving secrets stores out of use cases --- concepts/secrets/README.md | 10 ++++++++-- use-cases/README.md | 10 ---------- 2 files changed, 8 insertions(+), 12 deletions(-) diff --git a/concepts/secrets/README.md b/concepts/secrets/README.md index ddd53d8d2..d65784fc4 100644 --- a/concepts/secrets/README.md +++ b/concepts/secrets/README.md @@ -1,7 +1,13 @@ # 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 a named secrets store. +Almost all non-trivial applications need to _securely_ store secret data like API keys, database passwords, and more. By nature, these secrets cannot be checked into the version control system, but they also need to be accessible to code running in production. This is generally a hard problem, but it's critical to get it right. Otherwise, critical production systems can be compromised. + +Dapr's solution to this problem is the secrets API and secrets stores. + +Here's how it works: + +- Dapr is set up to use a **secret store** - a place to securely store secret data +- Application code uses the standard Dapr secrets API to retrieve secrets. Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores) for the list of supported stores. diff --git a/use-cases/README.md b/use-cases/README.md index f85ebf1c2..754201380 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -40,13 +40,3 @@ Visit the following documents to learn more: - [More details on mTLS](https://github.com/dapr/docs/blob/master/concepts/security/README.md) - [How to set up mTLS](https://github.com/dapr/docs/tree/master/howto/configure-mtls) - -## Secrets storage - -Dapr provides a consistent, secure API for accessing sensitive data, such as private keys for cloud services or database passwords, that your business logic needs. Using secret stores, you can remove secrets from your source code repositories and replace them with references to secrets in a Dapr secret store. Not only is doing so more secure, it also enables best security practices such as [key rotation](https://docs.microsoft.com/en-us/azure/key-vault/key-vault-key-rotation-log-monitoring). - -Visit the following documents to learn more: - -- [More details on secrets storage](https://github.com/dapr/docs/tree/master/concepts/secrets) -- [How to set up secrets storage](https://github.com/dapr/docs/tree/master/howto/setup-secret-store) - From d08a06f641bc56d32f94f79a4b36a474990ec373 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:54:54 -0700 Subject: [PATCH 08/21] removing use cases from the top-level readme --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index 73c767c76..315754426 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,6 @@ Welcome to the Dapr documentation repository. You can learn more about Dapr from | Topic | Description | |-------|-------------| |**[Overview](./overview)** | An overview of Dapr and how it enables you to build event driven, distributed applications -|**[Use cases](./use-cases)** | Common use cases that Dapr enables |**[Getting Started](./getting-started)** | Set up your development environment |**[Concepts](./concepts)** | Dapr concepts explained |**[How-Tos](./howto)** | Guides explaining how to accomplish specific tasks From dca303e919d308b6603a82d9f9eb3ac0aab1a9c9 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 13:55:24 -0700 Subject: [PATCH 09/21] Making service invocation README more concise --- concepts/service-invocation/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/concepts/service-invocation/README.md b/concepts/service-invocation/README.md index 4f81aefa6..db61468e3 100644 --- a/concepts/service-invocation/README.md +++ b/concepts/service-invocation/README.md @@ -1,8 +1,6 @@ # Service Invocation -Dapr-enabled apps can communicate with each other through well-known endpoints in the form of http or gRPC messages. - -Using the service invocation API, your microservice can find and reliably communicate with other microservices in your system. +Using the service invocation API, your microservice can find and reliably communicate with other microservices in your system using standard protocols ([gRPC](https://grpc.io) or HTTP are currently supported). Below is a high level overview of how Dapr's service invocation system works. From 1018d45ce7a97fb4abf6721ca73e7f226c9935dc Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 14:04:03 -0700 Subject: [PATCH 10/21] Moving mTLS out And into the security concepts doc --- concepts/security/README.md | 10 +++++++++- use-cases/README.md | 13 ------------- 2 files changed, 9 insertions(+), 14 deletions(-) diff --git a/concepts/security/README.md b/concepts/security/README.md index 88bd1bed0..36641c65d 100644 --- a/concepts/security/README.md +++ b/concepts/security/README.md @@ -1,5 +1,14 @@ # Security +End-to-end encryption for communication between microservices is generally a best practice, but it's also hard to set up. This feature is often called [mutual TLS (mTLS)](https://www.codeproject.com/articles/326574/an-introduction-to-mutual-ssl-authentication). `mTLS` offers a few key features for network traffic inside your app: + +- Two way authentication - the client proving its identify to the server, and vice-versa +- An encrypted channel for all in-flight communication, after two-way authentication is established + +Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). + +Dapr supports mTLS in your application with a variety of different deployments, all without adding any code to your application, and usually without complex configuration inside your production systems: + - [Sidecar-to-App Communication](#sidecar-to-app-communication) - [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication) - [Sidecar-to-system-services-communication](#Sidecar-to-system-services-communication) @@ -9,7 +18,6 @@ - [State Store Security](#state-store-security) - [Management Security](#management-security) - ## Sidecar-to-App communication The Dapr sidecar runs close to the application through **localhost**. Dapr assumes it runs in the same security domain of the application. As a result, there are no authentication, authorization or encryption between a Dapr sidecar and the application. diff --git a/use-cases/README.md b/use-cases/README.md index 754201380..4d9828ab8 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -27,16 +27,3 @@ Visit the following documents to learn more: - [Getting started with actors on the .Net platform](https://github.com/dapr/dotnet-sdk/blob/master/docs/get-started-dapr-actor.md) - [Getting started with actors with the Java SDK](https://github.com/dapr/java-sdk) -## Mutual TLS - -Dapr enables code-free end-to-end encryption in communication between microservices, called [mutual TLS (mTLS)](https://www.codeproject.com/articles/326574/an-introduction-to-mutual-ssl-authentication). In short, mTLS is a commonly-used security mechanism that provides the following features: - -- Two way authentication - the client proving its identify to the server, and vice-versa -- An encrypted channel for all in-flight communication, after two-way authentication is established - -Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). - -Visit the following documents to learn more: - -- [More details on mTLS](https://github.com/dapr/docs/blob/master/concepts/security/README.md) -- [How to set up mTLS](https://github.com/dapr/docs/tree/master/howto/configure-mtls) From b873a79cf3efcc7e57dee2dfd5b0e8b9b036179f Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 14:18:27 -0700 Subject: [PATCH 11/21] Breaking out the actors docs --- concepts/actors/README.md | 19 +++++++++---------- use-cases/README.md | 15 --------------- 2 files changed, 9 insertions(+), 25 deletions(-) diff --git a/concepts/actors/README.md b/concepts/actors/README.md index f4c61f7af..73d654129 100644 --- a/concepts/actors/README.md +++ b/concepts/actors/README.md @@ -1,6 +1,12 @@ # 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. +The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) describes **actors** as the lowest-level "unit of computation". In other words, you write your code in a self-contained unit (called an actor) that receives messages and processes them one at a time, without any kind of concurrency or threading. + +While your code processes a message, it can send one or more messages to other actors, or create new actors. An underlying **runtime** manages how, when and where each actor runs, and also routes messages between actors. + +A large number of actors can execute simultaneously, and actors execute independently from each other. + +Dapr includes a runtime that specifically implements the [Virtual Actor pattern](https://www.microsoft.com/en-us/research/project/orleans-virtual-actors/). With Dapr's implementation, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability guarantees that the underlying platform provides. ## Quick links @@ -9,23 +15,16 @@ Dapr runtime provides an actor implementation which is based on Virtual Actor pa ## 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 -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. +As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve. -Although the actor design pattern can be a good fit to a number of distributed systems problems and scenarios, careful consideration of the constraints of the pattern and the framework implementing it must be made. As general guidance, consider the actor pattern to model your problem or scenario if: +The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraings of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if: * Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic. * 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. diff --git a/use-cases/README.md b/use-cases/README.md index 4d9828ab8..72e442df1 100644 --- a/use-cases/README.md +++ b/use-cases/README.md @@ -11,19 +11,4 @@ Visit the following documents to learn more: - [More details on pub/sub](https://github.com/dapr/docs/blob/master/concepts/publish-subscribe-messaging/README.md) - [How to get started with pub/sub](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker) -## Actors - -Dapr provides an API and runtime that allows you to write your business logic as an isolated unit, without worrying about concurrency or other actors. Dapr calls this single isolated unit an "actor". Your running actors can send a message to another actor or can request to create a new actor. In the former case, Dapr manages routing the message to the proper destination. In the latter case, Dapr manages all the state management, synchronization, and concurrency involved with starting the new actor. - -The [actor model](https://en.wikipedia.org/wiki/Actor_model) is a battle-tested programming pattern and as such, comes with very specific use cases: - -- You have a large system composed of many (thousands or more) small microservices, in which the code to _manage_ these microservices (e.g. distribution across nodes, failover, ...) is very complex -- Your microservice(s) do not need concurrent access to state and can instead can [share state by communicating](https://blog.golang.org/codelab-share) -- Your code does operations that have unpredictable latency, such as I/O operations to external web services - -Visit the following documents to learn more: - -- [More details on actors](https://github.com/dapr/docs/tree/master/concepts/actors) -- [Getting started with actors on the .Net platform](https://github.com/dapr/dotnet-sdk/blob/master/docs/get-started-dapr-actor.md) -- [Getting started with actors with the Java SDK](https://github.com/dapr/java-sdk) From 75e1d26d7a8d0fa7cded63cb8d1dca5b69c2995e Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 5 May 2020 14:26:43 -0700 Subject: [PATCH 12/21] Breaking the pub/sub docs out This deletes the use cases README --- concepts/publish-subscribe-messaging/README.md | 9 ++++----- use-cases/README.md | 14 -------------- 2 files changed, 4 insertions(+), 19 deletions(-) delete mode 100644 use-cases/README.md diff --git a/concepts/publish-subscribe-messaging/README.md b/concepts/publish-subscribe-messaging/README.md index 9b9f8bbe3..09cabaef6 100644 --- a/concepts/publish-subscribe-messaging/README.md +++ b/concepts/publish-subscribe-messaging/README.md @@ -1,11 +1,10 @@ # Publish/Subscribe Messaging -Dapr enables developers to design their application with a pub/sub pattern using a message broker, where event consumers and producers are decoupled from one another, and communicate by sending and receiving messages that are associated with a namespace, usually in the form of topics. +The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows your microservices to communicate with each other purely by sending messages. In this system, the **producer** of a message sends it to a **topic**, with no knowledge of what service will receive the message. A messages can even be sent if there's no consumer for it. -This allows event producers to send messages to consumers that aren't running, and consumers to receive messages based on subscriptions to topics. +Similarly, a **consumer** will receive messages from a topic without knowledge of what producer sent it. This pattern is especially useful when you need to decouple microservices from one another. -Dapr provides At-Least-Once messaging guarantees, and integrates with various message brokers implementations. -These implementations are pluggable, and developed outside of the Dapr runtime in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub). +Dapr provides a publish/subscribe API that provides at-least-once guarantees and integrates with various message brokers implementations. These implementations are pluggable, and developed outside of the Dapr runtime in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub). ## Publish/Subscribe API @@ -14,7 +13,7 @@ The API for Publish/Subscribe can be found in the [spec repo](../../reference/ap ## 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. +That means that 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. The burden of dealing with concepts like consumer groups and multiple instances inside consumer groups is all catered for by Dapr. diff --git a/use-cases/README.md b/use-cases/README.md deleted file mode 100644 index 72e442df1..000000000 --- a/use-cases/README.md +++ /dev/null @@ -1,14 +0,0 @@ -# Dapr use cases - -This document briefly describes scenarios that Dapr enables for your microservices. Each use case is accompanied with a link to learn more details. - -## Pub/Sub - -Dapr provides an API that enables event-driven architectures in your system. Each microservice can utilize the same API to leverage one of [many supported event buses](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker#reference). Microservices can communicate each other by sending or subscribing to _events_ on specific _topics_. By leveraging this communication style, your microservices remain flexible and loosely coupled. - -Visit the following documents to learn more: - -- [More details on pub/sub](https://github.com/dapr/docs/blob/master/concepts/publish-subscribe-messaging/README.md) -- [How to get started with pub/sub](https://github.com/dapr/docs/tree/master/howto/setup-pub-sub-message-broker) - - From b72165a5302e1fe2235b52d22fa4cede7ad18ef9 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 12 May 2020 15:05:18 -0700 Subject: [PATCH 13/21] s/constrainings/constraints --- concepts/actors/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/actors/README.md b/concepts/actors/README.md index 73d654129..77c04b935 100644 --- a/concepts/actors/README.md +++ b/concepts/actors/README.md @@ -24,7 +24,7 @@ Dapr includes a runtime that specifically implements the [Virtual Actor pattern] As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve. -The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraings of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if: +The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraints of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if: * Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic. * 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. From f8781d14a88f84d94f4e45feb4b6cdf61f4b9d8e Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 12 May 2020 15:08:21 -0700 Subject: [PATCH 14/21] s/cannot/should not --- concepts/secrets/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/secrets/README.md b/concepts/secrets/README.md index d65784fc4..b77f8b011 100644 --- a/concepts/secrets/README.md +++ b/concepts/secrets/README.md @@ -1,6 +1,6 @@ # Dapr secrets management -Almost all non-trivial applications need to _securely_ store secret data like API keys, database passwords, and more. By nature, these secrets cannot be checked into the version control system, but they also need to be accessible to code running in production. This is generally a hard problem, but it's critical to get it right. Otherwise, critical production systems can be compromised. +Almost all non-trivial applications need to _securely_ store secret data like API keys, database passwords, and more. By nature, these secrets should not be checked into the version control system, but they also need to be accessible to code running in production. This is generally a hard problem, but it's critical to get it right. Otherwise, critical production systems can be compromised. Dapr's solution to this problem is the secrets API and secrets stores. From 0ffd73e00e4c0d38163aec331c69f436665105b9 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 12 May 2020 15:10:13 -0700 Subject: [PATCH 15/21] Rephrase mTLS description and use a better link --- concepts/security/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/concepts/security/README.md b/concepts/security/README.md index 36641c65d..9ddbd8e59 100644 --- a/concepts/security/README.md +++ b/concepts/security/README.md @@ -1,6 +1,6 @@ # Security -End-to-end encryption for communication between microservices is generally a best practice, but it's also hard to set up. This feature is often called [mutual TLS (mTLS)](https://www.codeproject.com/articles/326574/an-introduction-to-mutual-ssl-authentication). `mTLS` offers a few key features for network traffic inside your app: +End-to-end encryption for communication between microservices is generally a best practice, but it's also hard to set up. A common way to secure microservice inter-communication is to use [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. `mTLS` offers a few key features for network traffic inside your app: - Two way authentication - the client proving its identify to the server, and vice-versa - An encrypted channel for all in-flight communication, after two-way authentication is established From 9793cfd251fecb6cb35b2eee8685c106cd3ff5fa Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Tue, 12 May 2020 15:11:14 -0700 Subject: [PATCH 16/21] Removing the "database" nomenclature In favor of state store, since that's a better description of what Dapr provides --- concepts/state-management/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/concepts/state-management/README.md b/concepts/state-management/README.md index 29bb297fe..ce23becbd 100644 --- a/concepts/state-management/README.md +++ b/concepts/state-management/README.md @@ -1,6 +1,6 @@ # State management -Dapr comes with APIs for a key/value storage system, called "state management" in Dapr terminology. If your microservice uses state management, it automatically gets access to any of the [supported databases](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK. +Dapr comes with APIs for a key/value storage system, called "state management" in Dapr terminology. If your microservice uses state management, it automatically gets access to any of the [supported state stores](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK. State management requires that you build your application with several rules in mind, and if you follow those rules, your app will also be able to leverage several other features that would otherwise be complicated and error-prone to build yourself: @@ -55,7 +55,7 @@ SQL Server | Yes | Yes | Yes ## Concurrency -Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. And when the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the database. +Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. And when the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the state store. Dapr chooses OCC because in many applications, data update conflicts are rare because clients are naturally partitioned by business contexts to operate on different data. However, if your application chooses to use ETags, a request may get rejected because of mismatched ETags. It's recommended that you use a [Retry Policy](#Retry-Policies) to compensate for such conflicts when using ETags. From 1da68e34e297b4e4a6c4b1f35ce1a0939ab5de32 Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Fri, 5 Jun 2020 16:10:34 -0700 Subject: [PATCH 17/21] Additional clarifications --- concepts/bindings/README.md | 12 ++++++------ concepts/security/README.md | 18 ++++++++++-------- 2 files changed, 16 insertions(+), 14 deletions(-) diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index 8a703fd1a..b300d1277 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -1,14 +1,14 @@ # Bindings -Dapr provides a mechanism that can either (a) trigger your app in response to an event or (b) trigger an external system when your app does something. - -For example, bindings allow your microservice to respond to incoming Twilio/SMS messages without adding/configuring a third-party Twilio SDK, worrying about polling from Twilio (or doing websockets, etc...). +Dapr provides a mechanism that can either trigger your app with events coming in from external systems, or invoke external systems. Bindings give you some additional advantages: -* Handle retries and failure recovery -* Switch between bindings at runtime time -* Enable portable applications where environment-specific bindings are set-up and no code changes are required +* Your code doesn't have to deal with the complexities of connecting to, and polling from, messaging systems such as queues, message buses, etc... +* You can focus on business logic and not the implementation details of how interact with a system +* You can keep your code free from SDKs or libraries + +For a specific example, bindings allow your microservice to respond to incoming Twilio/SMS messages without adding/configuring a third-party Twilio SDK, worrying about polling from Twilio (or doing websockets, etc...). 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). diff --git a/concepts/security/README.md b/concepts/security/README.md index 9ddbd8e59..3b0355ac1 100644 --- a/concepts/security/README.md +++ b/concepts/security/README.md @@ -1,13 +1,6 @@ # Security -End-to-end encryption for communication between microservices is generally a best practice, but it's also hard to set up. A common way to secure microservice inter-communication is to use [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. `mTLS` offers a few key features for network traffic inside your app: - -- Two way authentication - the client proving its identify to the server, and vice-versa -- An encrypted channel for all in-flight communication, after two-way authentication is established - -Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). - -Dapr supports mTLS in your application with a variety of different deployments, all without adding any code to your application, and usually without complex configuration inside your production systems: +Security is a general term in Dapr that encompasses several important features that your microservices automatically takes advantage of: - [Sidecar-to-App Communication](#sidecar-to-app-communication) - [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication) @@ -18,6 +11,15 @@ Dapr supports mTLS in your application with a variety of different deployments, - [State Store Security](#state-store-security) - [Management Security](#management-security) +Many (but not all) of these security features centralize around encryption, which is a way to secure data. One of the security mechanisms that Dapr employs is called [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. `mTLS` offers a few key features for network traffic inside your app: + +- Two way authentication - the client proving its identify to the server, and vice-versa +- An encrypted channel for all in-flight communication, after two-way authentication is established + +Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). + +Dapr enables mTLS and all the features described in this document in your application with little to no extra code or complex configuration inside your production systems + ## Sidecar-to-App communication The Dapr sidecar runs close to the application through **localhost**. Dapr assumes it runs in the same security domain of the application. As a result, there are no authentication, authorization or encryption between a Dapr sidecar and the application. From 23b217e8dd5584ba457d046553928f3d850b261b Mon Sep 17 00:00:00 2001 From: Aaron Schlesinger Date: Fri, 5 Jun 2020 16:19:39 -0700 Subject: [PATCH 18/21] Cleaning up bindings docs --- concepts/bindings/README.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index 7d89b1cd2..9ca0a8662 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -1,17 +1,15 @@ # Bindings -Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems. +Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems. This feature provides several advantages for you and your code: -Specifically, bindings give you some additional advantages: +* You can remove the complexities of connecting to, and polling from, messaging systems such as queues, message buses, etc... +* You can focus on business logic and not implementation details of how to interact with a system +* You can keep your code free from SDKs or libraries +* You can handle retries and failure recovery +* You can switch between bindings at run time +* You can build portable applications where environment-specific bindings are set-up and no code changes are required -* Remove the complexities of connecting to, and polling from, messaging systems such as queues, message buses, etc. -* Focus on business logic and not the implementation details of how to interact with a system -* Keep the code free from SDKs or libraries -* Handles retries and failure recovery -* Switch between bindings at run time -* Enable portable applications where environment-specific bindings are set-up and no code changes are required - -For a specific example, bindings allow your microservice to respond to incoming Twilio/SMS messages without adding/configuring a third-party Twilio SDK, worrying about polling from Twilio (or doing websockets, etc...). +For a specific example, bindings would allow your microservice to respond to incoming Twilio/SMS messages without adding/configuring a third-party Twilio SDK, worrying about polling from Twilio (or doing websockets, etc...). 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). From 0a1cb857b51da6afd41f347843e04e6082fea1a9 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Fri, 5 Jun 2020 17:10:21 -0700 Subject: [PATCH 19/21] Minor style changes --- concepts/bindings/README.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/concepts/bindings/README.md b/concepts/bindings/README.md index 9ca0a8662..9db291128 100644 --- a/concepts/bindings/README.md +++ b/concepts/bindings/README.md @@ -1,15 +1,15 @@ # Bindings -Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems. This feature provides several advantages for you and your code: +Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems. This building block provides several benefits for you and your code: -* You can remove the complexities of connecting to, and polling from, messaging systems such as queues, message buses, etc... -* You can focus on business logic and not implementation details of how to interact with a system -* You can keep your code free from SDKs or libraries -* You can handle retries and failure recovery -* You can switch between bindings at run time -* You can build portable applications where environment-specific bindings are set-up and no code changes are required +* Remove the complexities of connecting to, and polling from, messaging systems such as queues and message buses +* Focus on business logic and not implementation details of how to interact with a system +* Keep your code free from SDKs or libraries +* Handle retries and failure recovery +* Switch between bindings at run time +* Build portable applications where environment-specific bindings are set-up and no code changes are required -For a specific example, bindings would allow your microservice to respond to incoming Twilio/SMS messages without adding/configuring a third-party Twilio SDK, worrying about polling from Twilio (or doing websockets, etc...). +For a specific example, bindings would allow your microservice to respond to incoming Twilio/SMS messages without adding or configuring a third-party Twilio SDK, worrying about polling from Twilio (or using websockets, etc.). 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). From 71f2c1b7415962c825ed4bcf0b61e3db59d9d268 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Fri, 5 Jun 2020 17:27:03 -0700 Subject: [PATCH 20/21] Internal link fix and phrasing changes to intro --- concepts/security/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/concepts/security/README.md b/concepts/security/README.md index 152ff2e4c..d41c180fe 100644 --- a/concepts/security/README.md +++ b/concepts/security/README.md @@ -1,17 +1,17 @@ # Security -Security is a general term in Dapr that encompasses several important features that your microservices automatically takes advantage of: +This article addresses multiple security considerations when using Dapr in a distributed application including: - [Sidecar-to-App Communication](#sidecar-to-app-communication) - [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication) -- [Sidecar-to-system-services-communication](#Sidecar-to-system-services-communication) -- [Component namespace scopes and secrets](#Component-namespace-scopes-and-secrets) +- [Sidecar-to-system-services-communication](#sidecar-to-system-services-communication) +- [Component namespace scopes and secrets](#component-namespace-scopes-and-secrets) - [Network Security](#network-security) - [Bindings Security](#bindings-security) - [State Store Security](#state-store-security) - [Management Security](#management-security) -Many (but not all) of these security features centralize around encryption, which is a way to secure data. One of the security mechanisms that Dapr employs is called [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. `mTLS` offers a few key features for network traffic inside your app: +Several of the areas above are addressed through encryption of data in transit. One of the security mechanisms that Dapr employs for encrypting data in transit is [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. mTLS offers a few key features for network traffic inside your application: - Two way authentication - the client proving its identify to the server, and vice-versa - An encrypted channel for all in-flight communication, after two-way authentication is established From 87be8c0738ebe12829c55989130c45ea4d1ffff8 Mon Sep 17 00:00:00 2001 From: Ori Zohar Date: Fri, 5 Jun 2020 17:39:34 -0700 Subject: [PATCH 21/21] Minor phrasing changes to state management intro --- concepts/state-management/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/concepts/state-management/README.md b/concepts/state-management/README.md index ce23becbd..b374df2d8 100644 --- a/concepts/state-management/README.md +++ b/concepts/state-management/README.md @@ -1,8 +1,8 @@ # State management -Dapr comes with APIs for a key/value storage system, called "state management" in Dapr terminology. If your microservice uses state management, it automatically gets access to any of the [supported state stores](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK. +Dapr offers key/value storage APIs for state management. If a microservice uses state management, it can use these APIs to leverage any of the [supported state stores](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK. -State management requires that you build your application with several rules in mind, and if you follow those rules, your app will also be able to leverage several other features that would otherwise be complicated and error-prone to build yourself: +When using state management your application will also be able to leverage several other features that would otherwise be complicated and error-prone to build yourself such as: - Distributed concurrency and data consistency - Retry policies @@ -25,7 +25,7 @@ See below for a diagram of state management's high level architecture. ## State management API -Developers can use the state managment API to retrieve, save and delete state values by providing keys. +Developers can use the state management API to retrieve, save and delete state values by providing keys. 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