diff --git a/.github/ISSUE_TEMPLATE/new-content-needed.md b/.github/ISSUE_TEMPLATE/new-content-needed.md index 20564eb2a7c..5a1ec2bafc1 100644 --- a/.github/ISSUE_TEMPLATE/new-content-needed.md +++ b/.github/ISSUE_TEMPLATE/new-content-needed.md @@ -1,8 +1,8 @@ --- name: New Content Needed about: Topic is missing and needs to be written -title: "[CONTENT]" -labels: content/missing-information +title: '' +labels: needs-triage,content/missing-information assignees: '' --- @@ -16,5 +16,12 @@ assignees: '' **Where should the new material be placed?** +**The associated pull request from dapr/dapr, dapr/components-contrib, or other Dapr code repos** + + **Additional context** diff --git a/.github/ISSUE_TEMPLATE/typo.md b/.github/ISSUE_TEMPLATE/typo.md index 1a7a32fd95f..9ad74454f26 100644 --- a/.github/ISSUE_TEMPLATE/typo.md +++ b/.github/ISSUE_TEMPLATE/typo.md @@ -1,8 +1,8 @@ --- name: Typo about: Report incorrect language/small updates to fix readability -title: "[TYPO]" -labels: content/typo +title: '' +labels: needs-triage,content/typo assignees: '' --- diff --git a/.github/ISSUE_TEMPLATE/website-issue.md b/.github/ISSUE_TEMPLATE/website-issue.md index 12afec0a33c..3f23d75cd69 100644 --- a/.github/ISSUE_TEMPLATE/website-issue.md +++ b/.github/ISSUE_TEMPLATE/website-issue.md @@ -1,8 +1,8 @@ --- name: Website Issue about: The website is broken or not working correctly. -title: "[WEBSITE]" -labels: website/functionality +title: '' +labels: needs-triage,website/functionality assignees: AaronCrawfis --- diff --git a/.github/ISSUE_TEMPLATE/wrong-information-code-steps.md b/.github/ISSUE_TEMPLATE/wrong-information-code-steps.md index 16896b6711c..150371fe400 100644 --- a/.github/ISSUE_TEMPLATE/wrong-information-code-steps.md +++ b/.github/ISSUE_TEMPLATE/wrong-information-code-steps.md @@ -1,8 +1,8 @@ --- name: Wrong Information/Code/Steps about: Something in the docs is incorrect -title: "[CONTENT]" -labels: P1, content/incorrect-information +title: '' +labels: needs-triage,content/incorrect-information assignees: '' --- diff --git a/daprdocs/content/en/concepts/faq.md b/daprdocs/content/en/concepts/faq.md index c02644aecdd..fbe8a3219a2 100644 --- a/daprdocs/content/en/concepts/faq.md +++ b/daprdocs/content/en/concepts/faq.md @@ -7,7 +7,7 @@ description: "Common questions asked about Dapr" --- ## How does Dapr compare to service meshes such as Istio, Linkerd or OSM? -Dapr is not a service mesh. While service meshes focus on fine grained network control, Dapr is focused on helping developers build distributed applications. Both Dapr and service meshes use the sidecar pattern and run alongside the application and they do have some overlapping features but also offer unique benefits. For more information please read the [Dapr & service meshes]({{}}) concept page. +Dapr is not a service mesh. While service meshes focus on fine-grained network control, Dapr is focused on helping developers build distributed applications. Both Dapr and service meshes use the sidecar pattern and run alongside the application. They do have some overlapping features, but also offer unique benefits. For more information please read the [Dapr & service meshes]({{}}) concept page. ## Performance Benchmarks The Dapr project is focused on performance due to the inherent discussion of Dapr being a sidecar to your application. See [here]({{< ref perf-service-invocation.md >}}) for updated performance numbers. @@ -16,26 +16,24 @@ The Dapr project is focused on performance due to the inherent discussion of Dap ### What is the relationship between Dapr, Orleans and Service Fabric Reliable Actors? -The actors in Dapr are based on the same virtual actor concept that [Orleans](https://www.microsoft.com/research/project/orleans-virtual-actors/) started, meaning that they are activated when called and deactivated after a period of time. If you are familiar with Orleans, Dapr C# actors will be familiar. Dapr C# actors are based on [Service Fabric Reliable Actors](https://docs.microsoft.com/azure/service-fabric/service-fabric-reliable-actors-introduction) (which also came from Orleans) and enable you to take Reliable Actors in Service Fabric and migrate them to other hosting platforms such as Kubernetes or other on-premise environments. -Also Dapr is about more than just actors. It provides you with a set of best practice building blocks to build into any microservices application. See [Dapr overview]({{< ref overview.md >}}). +The actors in Dapr are based on the same virtual actor concept that [Orleans](https://www.microsoft.com/research/project/orleans-virtual-actors/) started, meaning that they are activated when called and deactivated after a period of time. If you are familiar with Orleans, Dapr C# actors will be familiar. Dapr C# actors are based on [Service Fabric Reliable Actors](https://docs.microsoft.com/azure/service-fabric/service-fabric-reliable-actors-introduction) (which also came from Orleans) and enable you to take Reliable Actors in Service Fabric and migrate them to other hosting platforms such as Kubernetes or other on-premisis environments. +Moreover, Dapr is about more than just actors. It provides you with a set of best-practice building blocks to build into any microservices application. See [Dapr overview]({{< ref overview.md >}}). -### Differences between Dapr from an actor framework +### Differences between Dapr and an actor framework -Virtual actors capabilities are one of the building blocks that Dapr provides in its runtime. With Dapr because it is programming language agnostic with an http/gRPC API, the actors can be called from any language. This allows actors written in one language to invoke actors written in a different language. +Virtual actor capabilities are one of the building blocks that Dapr provides in its runtime. With Dapr, because it is programming-language agnostic with an http/gRPC API, the actors can be called from any language. This allows actors written in one language to invoke actors written in a different language. -Creating a new actor follows a local call like `http://localhost:3500/v1.0/actors///…`, for example `http://localhost:3500/v1.0/actors/myactor/50/method/getData` to call the `getData` method on the newly created `myactor` with id `50`. +Creating a new actor follows a local call like `http://localhost:3500/v1.0/actors///…`. For example, `http://localhost:3500/v1.0/actors/myactor/50/method/getData` calls the `getData` method on the newly created `myactor` with id `50`. -The Dapr runtime SDKs have language specific actor frameworks. The .NET SDK for example has C# actors. The goal is for all the Dapr language SDKs to have an actor framework. Currently .NET, Java and Python SDK have actor frameworks. +The Dapr runtime SDKs have language-specific actor frameworks. For example, the .NET SDK has C# actors. The goal is for all the Dapr language SDKs to have an actor framework. Currently .NET, Java and Python SDK have actor frameworks. ## Developer language SDKs and frameworks -### Does Dapr have any SDKs if I want to work with a particular programming language or framework? +### Does Dapr have any SDKs I can use if I want to work with a particular programming language or framework? -To make using Dapr more natural for different languages, it includes [language specific SDKs]({{}}) for Go, Java, JavaScript, .NET, Python, PHP, Rust and C++. +To make using Dapr more natural for different languages, it includes [language specific SDKs]({{}}) for Go, Java, JavaScript, .NET, Python, PHP, Rust and C++. 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 your choice. And because these SDKs share the Dapr runtime, you get cross-language actor and functions support. -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. - -### What frameworks does Dapr integrated with? +### What frameworks does Dapr integrate with? Dapr can be integrated with any developer framework. For example, in the Dapr .NET SDK you can find ASP.NET Core integration, which brings stateful routing controllers that respond to pub/sub events from other services. Dapr is integrated with the following frameworks; diff --git a/daprdocs/content/en/concepts/observability-concept.md b/daprdocs/content/en/concepts/observability-concept.md index 33c5761e72b..afb37f138d8 100644 --- a/daprdocs/content/en/concepts/observability-concept.md +++ b/daprdocs/content/en/concepts/observability-concept.md @@ -7,14 +7,14 @@ description: > Monitor applications through tracing, metrics, logs and health --- -When building an applications, understanding how the system is behaving is an important part of operating it - this includes having the ability to observe the internal calls of an application, gauging its performance and becoming aware of problems as soon as they occur. This is challenging for any system but even more so for a distributed system comprised of multiple microservices where a flow, made of several calls, may start in one microservices but continue in another. Observability is critical in production environments but also useful during development to understand bottlenecks, improve performance and perform basic debugging across the span of microservices. +When building an application, understanding how the system is behaving is an important part of operating it - this includes having the ability to observe the internal calls of an application, gauging its performance and becoming aware of problems as soon as they occur. This is challenging for any system, but even more so for a distributed system comprised of multiple microservices where a flow, made of several calls, may start in one microservices but continue in another. Observability is critical in production environments, but also useful during development to understand bottlenecks, improve performance and perform basic debugging across the span of microservices. -While some data points about an application can be gathered from the underlying infrastructure (e.g. memory consumption, CPU usage), other meaningful information must be collected from an "application aware" layer - one that can show how an important series of calls is executed across microservices. This usually means a developer must add some code to instrument an application for this purpose. Often, instrumentation code is simply meant to send collected data such as traces and metrics to an external monitoring tool or service that can help store, visualize and analyze all this information. +While some data points about an application can be gathered from the underlying infrastructure (e.g. memory consumption, CPU usage), other meaningful information must be collected from an "application-aware" layer - one that can show how an important series of calls is executed across microservices. This usually means a developer must add some code to instrument an application for this purpose. Often, instrumentation code is simply meant to send collected data such as traces and metrics to an external monitoring tool or service that can help store, visualize and analyze all this information. -Having to maintain this code, which is not part of the core logic of the application, is another burden on the developer, sometimes requiring understanding monitoring tools APIs, using additional SDKs etc. This instrumentation may also add to the portability challenges of an application which may require different instrumentation depending on where the application is deployed. For example, different cloud providers offer different monitoring solutions and an on-prem deployment might require an on-prem solution. +Having to maintain this code, which is not part of the core logic of the application, is another burden on the developer, sometimes requiring understanding the monitoring tools' APIs, using additional SDKs etc. This instrumentation may also add to the portability challenges of an application, which may require different instrumentation depending on where the application is deployed. For example, different cloud providers offer different monitoring solutions and an on-prem deployment might require an on-prem solution. ## Observability for your application with Dapr -When building an application which is leveraging Dapr building blocks to perform service-to-service calls and pub/sub messaging, Dapr offers an advantage in respect to [distributed tracing]({{}}) because this inter-service communication flows through the Dapr sidecar, the sidecar is in a unique position to offload the burden of application level instrumentation. +When building an application which leverages Dapr building blocks to perform service-to-service calls and pub/sub messaging, Dapr offers an advantage with respect to [distributed tracing]({{}}). Because this inter-service communication flows through the Dapr sidecar, the sidecar is in a unique position to offload the burden of application-level instrumentation. ### Distributed tracing Dapr can be [configured to emit tracing data]({{}}), and because Dapr does so using widely adopted protocols such as the [Zipkin](https://zipkin.io) protocol, it can be easily integrated with multiple [monitoring backends]({{}}). @@ -27,10 +27,10 @@ Dapr can also be configured to work with the [OpenTelemetry Collector]({{ ### Tracing context -Dapr uses [W3C tracing]({{}}) specification for tracing context and can generate and propagate the context header itself or propagate user provided context headers. +Dapr uses [W3C tracing]({{}}) specification for tracing context and can generate and propagate the context header itself or propagate user-provided context headers. ## Observability for the Dapr sidecar and system services -As for other parts of your system, you will want to be able to observe Dapr itself and collect metrics and logs emitted by the Dapr sidecar that runs along each microservice as well as the Dapr related services in your environment such as the control plane services that are deployed for a Dapr enabled Kubernetes cluster. +As for other parts of your system, you will want to be able to observe Dapr itself and collect metrics and logs emitted by the Dapr sidecar that runs along each microservice, as well as the Dapr-related services in your environment such as the control plane services that are deployed for a Dapr-enabled Kubernetes cluster. Dapr sidecar metrics, logs and health checks @@ -38,7 +38,7 @@ As for other parts of your system, you will want to be able to observe Dapr itse Dapr generates [logs]({{}}) to provide visibility into sidecar operation and to help users identify issues and perform debugging. Log events contain warning, error, info, and debug messages produced by Dapr system services. Dapr can also be configured to send logs to collectors such as [Fluentd]({{< ref fluentd.md >}}) and [Azure Monitor]({{< ref azure-monitor.md >}}) so they can be easily searched, analyzed and provide insights. ### Metrics -Metrics are the series of measured values and counts that are collected and stored over time. [Dapr metrics]({{}}) provide monitoring capabilities to understand the behavior of the Dapr sidecar and system services. For example, the metrics between a Dapr sidecar and the user application show call latency, traffic failures, error rates of requests etc. Dapr [system services metrics](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md) show sidecar injection failures, health of the system services including CPU usage, number of actor placements made etc. +Metrics are the series of measured values and counts that are collected and stored over time. [Dapr metrics]({{}}) provide monitoring capabilities to understand the behavior of the Dapr sidecar and system services. For example, the metrics between a Dapr sidecar and the user application show call latency, traffic failures, error rates of requests, etc. Dapr [system services metrics](https://github.com/dapr/dapr/blob/master/docs/development/dapr-metrics.md) show sidecar injection failures and the health of system services, including CPU usage, number of actor placements made, etc. ### Health checks The Dapr sidecar exposes an HTTP endpoint for [health checks]({{}}). With this API, user code or hosting environments can probe the Dapr sidecar to determine its status and identify issues with sidecar readiness. diff --git a/daprdocs/content/en/concepts/overview.md b/daprdocs/content/en/concepts/overview.md index 08a669b3721..d0785771510 100644 --- a/daprdocs/content/en/concepts/overview.md +++ b/daprdocs/content/en/concepts/overview.md @@ -17,29 +17,29 @@ Dapr is a portable, event-driven runtime that makes it easy for any developer to 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. +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. +In addition, Dapr is platform agnostic, meaning you can run your applications locally, on any Kubernetes cluster, and in 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. +Using Dapr you can easily build microservice applications using any language and 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. +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. Today, the following building blocks are available: +Each of these building blocks is independent, meaning that you can use one, some, or all of them in your application. Today, the following building blocks are available: | Building Block | Description | |----------------|-------------| -| [**Service-to-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, Azure SQL Server, PostgreSQL, AWS DynamoDB or Redis among others. -| [**Publish and subscribe**]({{}}) | 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. +| [**Service-to-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, Azure SQL Server, PostgreSQL, AWS DynamoDB or Redis, among others. +| [**Publish and subscribe**]({{}}) | 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**]({{}}) | Resource bindings with triggers builds further on event-driven architectures for scale and resiliency by receiving and sending events to and from any external source such as databases, queues, file systems, etc. -| [**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. -| [**Observability**]({{}}) | Dapr emit metrics, logs, and traces to debug and monitor both Dapr and user applications. Dapr supports distributed tracing to easily diagnose and serve inter-service calls in production using the W3C Trace Context standard and Open Telemetry to send to different monitoring tools. -| [**Secrets**]({{}}) | Dapr provides secrets management and integrates with public cloud and local secret stores to retrieve the secrets for use in application code. +| [**Actors**]({{}}) | A pattern for stateful and stateless objects that makes concurrency simple, with method and state encapsulation. Dapr provides many capabilities in its actor runtime, including concurrency, state, and life-cycle management for actor activation/deactivation, and timers and reminders to wake up actors. +| [**Observability**]({{}}) | Dapr emits metrics, logs, and traces to debug and monitor both Dapr and user applications. Dapr supports distributed tracing to easily diagnose and serve inter-service calls in production using the W3C Trace Context standard and Open Telemetry to send to different monitoring tools. +| [**Secrets**]({{}}) | Dapr provides secrets management, and integrates with public-cloud and local-secret stores to retrieve the secrets for use in application code. ## Sidecar architecture @@ -55,7 +55,7 @@ Dapr can be hosted in multiple environments, including self-hosted on a Windows/ In [self-hosted mode]({{< ref self-hosted-overview.md >}}) Dapr runs as a separate sidecar process which your service code can call via HTTP or gRPC. 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. -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. Try this out with the [getting started samples]({{< ref getting-started >}}). +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. Try this out with the [getting started samples]({{< ref getting-started >}}). Architecture diagram of Dapr in self-hosted mode @@ -63,11 +63,11 @@ You can use the [Dapr CLI](https://github.com/dapr/cli#launch-dapr-and-your-app) In container hosting environments such as Kubernetes, Dapr runs as a sidecar container with the application container in the same pod. -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-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 in 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]({{< ref "security-concept.md#dapr-to-dapr-communication" >}}) +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]({{< ref "security-concept.md#dapr-to-dapr-communication" >}}) -Deploying and running a Dapr enabled application into your Kubernetes cluster is as simple as adding a few annotations to the deployment schemes. Visit the [Dapr on Kubernetes docs]({{< ref kubernetes >}}) +Deploying and running a Dapr-enabled application into your Kubernetes cluster is as simple as adding a few annotations to the deployment schemes. Visit the [Dapr on Kubernetes docs]({{< ref kubernetes >}}) Architecture diagram of Dapr in Kubernetes mode @@ -87,7 +87,7 @@ To make using Dapr more natural for different languages, it also includes [langu - .NET - PHP -These SDKs expose the functionality of the Dapr building blocks 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. +These SDKs expose the functionality of the Dapr building blocks 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 your choice. And because these SDKs share the Dapr runtime, you get cross-language actor and function support. ### Developer frameworks diff --git a/daprdocs/content/en/concepts/security-concept.md b/daprdocs/content/en/concepts/security-concept.md index c72c9d47537..480b3ba3c56 100644 --- a/daprdocs/content/en/concepts/security-concept.md +++ b/daprdocs/content/en/concepts/security-concept.md @@ -20,7 +20,7 @@ Dapr enables mTLS and all the features described in this document in your applic ## Sidecar-to-app communication -The Dapr sidecar runs close to the application through **localhost**, and is recommended to run under the same network boundary as the app. While many cloud-native systems today consider the pod level (on Kubernetes, for example) as a trusted security boundary, Dapr provides user with API level authentication using tokens. This feature guarantees that even on localhost, only an authenticated caller may call into Dapr. +The Dapr sidecar runs close to the application through **localhost**, and is recommended to run under the same network boundary as the app. While many cloud-native systems today consider the pod level (on Kubernetes, for example) as a trusted security boundary, Dapr provides the user with API level authentication using tokens. This feature guarantees that even on localhost, only an authenticated caller may call into Dapr. ## Sidecar-to-sidecar communication @@ -29,20 +29,20 @@ To achieve this, Dapr leverages a system service named `Sentry` which acts as a Dapr also manages workload certificate rotation, and does so with zero downtime to the application. -Sentry, the CA service, automatically creates and persists self signed root certificates valid for one year, unless existing root certs have been provided by the user. +Sentry, the CA service, automatically creates and persists self-signed root certificates valid for one year, unless existing root certs have been provided by the user. -When root certs are replaced (secret in Kubernetes mode and filesystem for self hosted mode), the Sentry picks them up and re-builds the trust chain without needing to restart, with zero downtime to Sentry. +When root certs are replaced (secret in Kubernetes mode and filesystem for self-hosted mode), the Sentry picks them up and rebuilds the trust chain without needing to restart, with zero downtime to Sentry. When a new Dapr sidecar initializes, it first checks if mTLS is enabled. If it is, an ECDSA private key and certificate signing request are generated and sent to Sentry via a gRPC interface. The communication between the Dapr sidecar and Sentry is authenticated using the trust chain cert, which is injected into each Dapr instance by the Dapr Sidecar Injector system service. -In a Kubernetes cluster, the secret that holds the root certificates is scoped to the namespace in which the Dapr components are deployed to and is only accessible by the Dapr system pods. +In a Kubernetes cluster, the secret that holds the root certificates is scoped to the namespace in which the Dapr components are deployed and is only accessible by the Dapr system pods. Dapr also supports strong identities when deployed on Kubernetes, relying on a pod's Service Account token which is sent as part of the certificate signing request (CSR) to Sentry. By default, a workload cert is valid for 24 hours and the clock skew is set to 15 minutes. Mutual TLS can be turned off/on by editing the default configuration that is deployed with Dapr via the `spec.mtls.enabled` field. -This can be done for both Kubernetes and self hosted modes. Details for how to do this can be found [here]({{< ref mtls.md >}}). +This can be done for both Kubernetes and self-hosted modes. Details for how to do this can be found [here]({{< ref mtls.md >}}). ### mTLS self hosted The diagram below shows how the Sentry system service issues certificates for applications based on the root/issuer certificate that is provided by an operator or generated by the Sentry service as stored in a file @@ -58,13 +58,13 @@ The diagram below shows how the Sentry system service issues certificates for ap In addition to automatic mTLS between Dapr sidecars, Dapr offers mandatory mTLS between the Dapr sidecar and the Dapr system services, namely the Sentry service (Certificate Authority), Placement service (actor placement) and the Kubernetes Operator. -When mTLS is enabled, Sentry writes the root and issuer certificates to a Kubernetes secret that is scoped to the namespace where the control plane is installed. In self hosted mode, Sentry writes the certificates to a configurable filesystem path. +When mTLS is enabled, Sentry writes the root and issuer certificates to a Kubernetes secret that is scoped to the namespace where the control plane is installed. In self-hosted mode, Sentry writes the certificates to a configurable file system path. -In Kubernetes, when the Dapr system services start, they automatically mount the secret containing the root and issuer certs and use those to secure the gRPC server that is used by the Dapr sidecar. +In Kubernetes, when Dapr system services start, they automatically mount the secret containing the root and issuer certs and use those to secure the gRPC server that is used by the Dapr sidecar. -In self hosted mode, each system service can be mounted to a filesystem path to get the credentials. +In self-hosted mode, each system service can be mounted to a filesystem path to get the credentials. -When the Dapr sidecar initializes, it authenticates with the system pods using the mounted leaf certificates and issuer private key. these are mounted as environment variables on the sidecar container. +When the Dapr sidecar initializes, it authenticates with the system pods using the mounted leaf certificates and issuer private key. These are mounted as environment variables on the sidecar container. ### mTLS to system services in Kubernetes The diagram below shows secure communication between the Dapr sidecar and the Dapr Sentry (Certificate Authority), Placement (actor placement) and the Kubernetes Operator system services @@ -77,13 +77,11 @@ Dapr components are namespaced. That means a Dapr runtime sidecar instance can o Dapr components uses Dapr's built-in secret management capability to manage secrets. See the [secret store overview]({{}}) for more details. -In addition, Dapr offers application-level scoping for components by allowing users to specify which applications can consume given components.For more information about application level scoping, see [here]({{}}). +In addition, Dapr offers application-level scoping for components by allowing users to specify which applications can consume given components. For more information about application level scoping, see [here]({{}}). ## 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. +You can adopt common network security technologies such as network security groups (NSGs), demilitarized zones (DMZs) and firewalls to provide layers of protection 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 @@ -95,7 +93,7 @@ Dapr doesn't transform the state data from applications. This means Dapr doesn't Dapr does not store any data at rest. -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. +Dapr uses the configured authentication method to authenticate with the underlying state store. Many state store implementations use official client libraries that generally use secured communication channels with the servers. ## Management security @@ -104,7 +102,7 @@ When deploying on Kubernetes, you can use regular [Kubernetes RBAC]( https://kub 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. ## Threat model -Threat modeling is a process by which potential threats, such as structural vulnerabilities or the absence of appropriate safeguards, can be identified, enumerated, and mitigations can be prioritized. The Dapr threat model is below. +Threat modeling is a process by which potential threats, such as structural vulnerabilities or the absence of appropriate safeguards, can be identified and enumerated, and mitigations can be prioritized. The Dapr threat model is below. Dapr threat model @@ -112,10 +110,10 @@ Threat modeling is a process by which potential threats, such as structural vuln ### February 2021 -In February 2021, Dapr has gone through a 2nd security audit targetting it's 1.0 release by Cure53. +In February 2021, Dapr went through a 2nd security audit targeting it's 1.0 release by Cure53. The test focused on the following: -* Dapr runtime code base evaluation since last audit +* Dapr runtime codebase evaluation since last audit * Access control lists * Secrets management * Penetration testing @@ -128,12 +126,12 @@ As of February 16th 2021, Dapr has 0 criticals, 0 highs, 0 mediums, 2 lows, 2 in ### June 2020 -In June 2020, Dapr has undergone a security audit from Cure53, a CNCF approved cybersecurity firm. +In June 2020, Dapr underwent a security audit from Cure53, a CNCF-approved cybersecurity firm. The test focused on the following: -* Dapr runtime code base evaluation -* Dapr components code base evaluation -* Dapr CLI code base evaluation +* Dapr runtime codebase evaluation +* Dapr components codebase evaluation +* Dapr CLI codebase evaluation * Privilege escalation * Traffic spoofing * Secrets management diff --git a/daprdocs/content/en/concepts/service-mesh.md b/daprdocs/content/en/concepts/service-mesh.md index bee67a399d3..a5554515b93 100644 --- a/daprdocs/content/en/concepts/service-mesh.md +++ b/daprdocs/content/en/concepts/service-mesh.md @@ -4,15 +4,15 @@ title: "Dapr and service meshes" linkTitle: "Service meshes" weight: 700 description: > - How Dapr compares to, and works with service meshes + How Dapr compares to, and works with, service meshes --- -Dapr uses a sidecar architecture, running as a separate process alongside the application and includes features such as, service invocation, network security and distributed tracing. This often raises the question - how does Dapr compare to service mesh solutions such as Linkerd, Istio and Open Service Mesh (OSM)? +Dapr uses a sidecar architecture, running as a separate process alongside the application and includes features such as service invocation, network security, and distributed tracing. This often raises the question: how does Dapr compare to service mesh solutions such as Linkerd, Istio and Open Service Mesh (OSM)? ## How Dapr and service meshes compare -While Dapr and service meshes do offer some overlapping capabilities, **Dapr is not a service mesh** where a service mesh, is defined as a *networking* service mesh. Unlike a service mesh which is focused on networking concerns, Dapr is focused on providing building blocks that make it easier for developers to build applications as microservices. Dapr is developer-centric versus service meshes being infrastructure-centric. +While Dapr and service meshes do offer some overlapping capabilities, **Dapr is not a service mesh**, where a service mesh is defined as a *networking* service mesh. Unlike a service mesh which is focused on networking concerns, Dapr is focused on providing building blocks that make it easier for developers to build applications as microservices. Dapr is developer-centric, versus service meshes which are infrastructure-centric. -In most cases, developers do not need to be aware that the application they are building will be deployed in an environment which includes a service mesh since a service mesh intercepts network traffic. Service meshes are mostly managed and deployed by system operators. However, Dapr building block APIs are intended to be used by developers explicitly in their code. +In most cases, developers do not need to be aware that the application they are building will be deployed in an environment which includes a service mesh, since a service mesh intercepts network traffic. Service meshes are mostly managed and deployed by system operators, whereas Dapr building block APIs are intended to be used by developers explicitly in their code. Some common capabilities that Dapr shares with service meshes include: - Secure service-to-service communication with mTLS encryption @@ -20,9 +20,9 @@ Some common capabilities that Dapr shares with service meshes include: - Service-to-service distributed tracing - Resiliency through retries - Importantly Dapr provides service discovery and invocation via names which is a developer centric concern. This means that through Dapr's service invocation API, developers call a method on a service name, whereas service meshes deal with network concepts such as IPs and DNS addresses. However, Dapr does not provide capabilities for traffic behavior such as routing or traffic splitting. Traffic routing is often addressed with ingress proxies to an application and does not have to use a service mesh. In addition, Dapr does provides other application level building blocks for state management, pub/sub messaging, actors and more. + Importantly, Dapr provides service discovery and invocation via names, which is a developer-centric concern. This means that through Dapr's service invocation API, developers call a method on a service name, whereas service meshes deal with network concepts such as IP addresses and DNS addresses. However, Dapr does not provide capabilities for traffic behavior such as routing or traffic splitting. Traffic routing is often addressed with ingress proxies to an application and does not have to use a service mesh. In addition, Dapr provides other application-level building blocks for state management, pub/sub messaging, actors, and more. -Another difference between Dapr and service meshes is with observability (tracing and metrics). Service meshes operate at the network level and trace the network calls between services. Dapr does this with service invocation, however Dapr also provides observability (tracing and metrics) over pub/sub calls using trace ids written into the Cloud Events envelope. This means that the metrics and tracing with Dapr is more extensive than with a service mesh for applications that use both service-to-service invocation and pub/sub to communicate. +Another difference between Dapr and service meshes is observability (tracing and metrics). Service meshes operate at the network level and trace the network calls between services. Dapr does this with service invocation. Moreover, Dapr also provides observability (tracing and metrics) over pub/sub calls using trace IDs written into the Cloud Events envelope. This means that metrics and tracing with Dapr is more extensive than with a service mesh for applications that use both service-to-service invocation and pub/sub to communicate. The illustration below captures the overlapping features and unique capabilities that Dapr and service meshes offer: @@ -35,11 +35,11 @@ Watch these recordings from the Dapr community calls showing presentations on ru - General overview and a demo of [Dapr and Linkerd](https://youtu.be/xxU68ewRmz8?t=142) - Demo of running [Dapr and Istio](https://youtu.be/ngIDOQApx8g?t=335) -## When to choose using Dapr, a service mesh or both -Should you be using Dapr, a service mesh or both? The answer depends on your requirements. If, for example, you are looking to use Dapr for one or more building blocks such as state management or pub/sub and considering using a service mesh just for network security or observability, you may find that Dapr is a good fit and a service mesh is not required. +## When to choose using Dapr, a service mesh, or both +Should you be using Dapr, a service mesh, or both? The answer depends on your requirements. If, for example, you are looking to use Dapr for one or more building blocks such as state management or pub/sub, and you are considering using a service mesh just for network security or observability, you may find that Dapr is a good fit and that a service mesh is not required. -Typically you would use a service mesh with Dapr where there is a corporate policy that traffic on the network needs to be encrypted regardless for all applications. For example, you may be using Dapr in only part of your application and other services and processes that are not using Dapr in your application also need encrypted traffic. In this scenario a service mesh is the better option and most likely you should use mTLS and distributed tracing on the service mesh and disable this on Dapr. +Typically you would use a service mesh with Dapr where there is a corporate policy that traffic on the network must be encrypted for all applications. For example, you may be using Dapr in only part of your application, and other services and processes that are not using Dapr in your application also need their traffic encrypted. In this scenario a service mesh is the better option, and most likely you should use mTLS and distributed tracing on the service mesh and disable this on Dapr. If you need traffic splitting for A/B testing scenarios you would benefit from using a service mesh, since Dapr does not provide these capabilities. -In some cases, where you require capabilities that are unique to both you will find it useful to leverage both Dapr and a service mesh - as mentioned above, there is no limitation for using them together. +In some cases, where you require capabilities that are unique to both, you will find it useful to leverage both Dapr and a service mesh; as mentioned above, there is no limitation to using them together. diff --git a/daprdocs/content/en/concepts/terminology.md b/daprdocs/content/en/concepts/terminology.md index 87731d1ba71..5e97b8f7a51 100644 --- a/daprdocs/content/en/concepts/terminology.md +++ b/daprdocs/content/en/concepts/terminology.md @@ -10,12 +10,12 @@ This page details all of the common terms you may come across in the Dapr docs. | Term | Definition | More information | |:-----|------------|------------------| -| App/Application | A running service/binary, usually that you as the user create and run. +| App/Application | A running service/binary, usually one that you as the user create and run. | Building block | An API that Dapr provides to users to help in the creation of microservices and applications. | [Dapr building blocks]({{< ref building-blocks-concept.md >}}) | Component | Modular types of functionality that are used either individually or with a collection of other components, by a Dapr building block. | [Dapr components]({{< ref components-concept.md >}}) -| Configuration | A YAML file declaring all of the settings for Dapr sidecars or the Dapr control plane. It is here where you can configure control plane mTLS settings, or the tracing, and middleware settings for an application instance. | [Dapr configuration]({{< ref configuration-concept.md >}}) +| Configuration | A YAML file declaring all of the settings for Dapr sidecars or the Dapr control plane. This is where you can configure control plane mTLS settings, or the tracing and middleware settings for an application instance. | [Dapr configuration]({{< ref configuration-concept.md >}}) | Dapr | Distributed Application Runtime. | [Dapr overview]({{< ref overview.md >}}) -| Dapr control plane | A collection of services that are part of a Dapr installation on a hosting platform such as a Kubernetes cluster. Allow Dapr enabled applications to run on that platform and handles Dapr capabilities such as actor placement, Dapr sidecar injection or certificate issuance/rollover. | [Self-hosted overview]({{< ref self-hosted-overview >}})
[Kubernetes overview]({{< ref kubernetes-overview >}}) -| Self-hosted | Windows/macOS/Linux machine(s) where you can run your applications with Dapr. Dapr provides capabilities to run on machines in "self-hosted" mode. | [Self-hosted mode]({{< ref self-hosted-overview.md >}}) -| Service | A running application or binary. Can be used to refer to your application, or a Dapr application. +| Dapr control plane | A collection of services that are part of a Dapr installation on a hosting platform such as a Kubernetes cluster. This allows Dapr-enabled applications to run on the platform and handles Dapr capabilities such as actor placement, Dapr sidecar injection, or certificate issuance/rollover. | [Self-hosted overview]({{< ref self-hosted-overview >}})
[Kubernetes overview]({{< ref kubernetes-overview >}}) +| Self-hosted | Windows/macOS/Linux machine(s) where you can run your applications with Dapr. Dapr provides the capability to run on machines in "self-hosted" mode. | [Self-hosted mode]({{< ref self-hosted-overview.md >}}) +| Service | A running application or binary. This can refer to your application or to a Dapr application. | Sidecar | A program that runs alongside your application as a separate process or container. | [Sidecar pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar) diff --git a/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md b/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md index fe459cd013e..0ba0043dc70 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md +++ b/daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md @@ -129,3 +129,78 @@ DELETE http://localhost:3500/v1.0/actors///reminders/ ``` Refer [api spec]({{< ref "actors_api.md#invoke-reminder" >}}) for more details. + +## Actor runtime configuration + +You can configure the Dapr Actors runtime configuration to modify the default runtime behavior. + +### Configuration parameters +- `actorIdleTimeout` - The timeout before deactivating an idle actor. Checks for timeouts occur every `actorScanInterval` interval. **Default: 60 minutes** +- `actorScanInterval` - The duration which specifies how often to scan for actors to deactivate idle actors. Actors that have been idle longer than actor_idle_timeout will be deactivated. **Default: 30 seconds** +- `drainOngoingCallTimeout` - The duration when in the process of draining rebalanced actors. This specifies the timeout for the current active actor method to finish. If there is no current actor method call, this is ignored. **Default: 60 seconds** +- `drainRebalancedActors` - If true, Dapr will wait for `drainOngoingCallTimeout` duration to allow a current actor call to complete before trying to deactivate an actor. **Default: true** +- `reentrancy` (ActorReentrancyConfig) - Configure the reentrancy behavior for an actor. If not provided, reentrancy is diabled. **Default: disabled** + +{{< tabs Java Dotnet Python >}} + +{{% codetab %}} +```java +// import io.dapr.actors.runtime.ActorRuntime; +// import java.time.Duration; + +ActorRuntime.getInstance().getConfig().setActorIdleTimeout(Duration.ofMinutes(60)); +ActorRuntime.getInstance().getConfig().setActorScanInterval(Duration.ofSeconds(30)); +ActorRuntime.getInstance().getConfig().setDrainOngoingCallTimeout(Duration.ofSeconds(60)); +ActorRuntime.getInstance().getConfig().setDrainBalancedActors(true); +ActorRuntime.getInstance().getConfig().setActorReentrancyConfig(false, null); +``` + +See [this example](https://github.com/dapr/java-sdk/blob/master/examples/src/main/java/io/dapr/examples/actors/DemoActorService.java) +{{% /codetab %}} + +{{% codetab %}} +```csharp +// In Startup.cs +public void ConfigureServices(IServiceCollection services) +{ + // Register actor runtime with DI + services.AddActors(options => + { + // Register actor types and configure actor settings + options.Actors.RegisterActor(); + + // Configure default settings + options.ActorIdleTimeout = TimeSpan.FromMinutes(60); + options.ActorScanInterval = TimeSpan.FromSeconds(30); + options.DrainOngoingCallTimeout = TimeSpan.FromSeconds(60); + options.DrainRebalancedActors = true; + // reentrancy not implemented in the .NET SDK at this time + }); + + // Register additional services for use with actors + services.AddSingleton(); +} +``` +See the .NET SDK [documentation](https://github.com/dapr/dotnet-sdk/blob/master/daprdocs/content/en/dotnet-sdk-docs/dotnet-actors/dotnet-actors-usage.md#registering-actors). +{{% /codetab %}} + +{{% codetab %}} +```python +from datetime import timedelta +from dapr.actor.runtime.config import ActorRuntimeConfig, ActorReentrancyConfig + +ActorRuntime.set_actor_config( + ActorRuntimeConfig( + actor_idle_timeout=timedelta(hours=1), + actor_scan_interval=timedelta(seconds=30), + drain_ongoing_call_timeout=timedelta(minutes=1), + drain_rebalanced_actors=True, + reentrancy=ActorReentrancyConfig(enabled=False) + ) +) +``` +{{% /codetab %}} + +{{< /tabs >}} + +Refer to the documentation and examples of the [Dapr SDKs]({{< ref "developing-applications/sdks/#sdk-languages" >}}) for more details. diff --git a/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md b/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md index 77d421e2065..de8e1d22193 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md +++ b/daprdocs/content/en/developing-applications/building-blocks/secrets/howto-secrets.md @@ -14,7 +14,7 @@ Before retrieving secrets in your application's code, you must have a secret sto >Note: The component used in this example is not secured and is not recommended for production deployments. You can find other alternatives [here]({{}}). -Create a file named `secrets.json` with the following contents: +Create a file named `mysecrets.json` with the following contents: ```json { diff --git a/daprdocs/content/en/developing-applications/ides/intellij.md b/daprdocs/content/en/developing-applications/ides/intellij.md index 108770a104d..80bc755e552 100644 --- a/daprdocs/content/en/developing-applications/ides/intellij.md +++ b/daprdocs/content/en/developing-applications/ides/intellij.md @@ -146,4 +146,8 @@ Happy debugging! ## Related links + + - [Change](https://intellij-support.jetbrains.com/hc/en-us/articles/206544519-Directories-used-by-the-IDE-to-store-settings-caches-plugins-and-logs) in IntelliJ configuration directory location + + \ No newline at end of file diff --git a/daprdocs/content/en/developing-applications/middleware/middleware-overview.md b/daprdocs/content/en/developing-applications/middleware/middleware-overview.md index 8bc5df72b2d..751bac28f76 100644 --- a/daprdocs/content/en/developing-applications/middleware/middleware-overview.md +++ b/daprdocs/content/en/developing-applications/middleware/middleware-overview.md @@ -49,7 +49,7 @@ spec: ## Writing a custom middleware -Dapr uses [FastHTTP](https://github.com/valyala/fasthttp) to implement its HTTP server. Hence, your HTTP middleware needs to be written as a FastHTTP handler. Your middleware needs to implement a middleware interface, which defines a **GetHandler** method that returns a **fasthttp.RequestHandler**: +Dapr uses [FastHTTP](https://github.com/valyala/fasthttp) to implement its HTTP server. Hence, your HTTP middleware needs to be written as a FastHTTP handler. Your middleware needs to implement a middleware interface, which defines a **GetHandler** method that returns **fasthttp.RequestHandler** and **error**: ```go type Middleware interface { @@ -60,14 +60,16 @@ type Middleware interface { Your handler implementation can include any inbound logic, outbound logic, or both: ```go -func GetHandler(metadata Metadata) fasthttp.RequestHandler { + +func (m *customMiddleware) GetHandler(metadata Metadata) (func(fasthttp.RequestHandler) fasthttp.RequestHandler, error) { + var err error return func(h fasthttp.RequestHandler) fasthttp.RequestHandler { return func(ctx *fasthttp.RequestCtx) { // inboud logic h(ctx) // call the downstream handler // outbound logic } - } + }, err } ``` diff --git a/daprdocs/content/en/getting-started/configure-state-pubsub.md b/daprdocs/content/en/getting-started/configure-state-pubsub.md index e1f943cf0af..84faafa3bfb 100644 --- a/daprdocs/content/en/getting-started/configure-state-pubsub.md +++ b/daprdocs/content/en/getting-started/configure-state-pubsub.md @@ -52,8 +52,8 @@ You can use [Helm](https://helm.sh/) to quickly create a Redis instance in our K $ kubectl get pods NAME READY STATUS RESTARTS AGE redis-master-0 1/1 Running 0 69s - redis-slave-0 1/1 Running 0 69s - redis-slave-1 1/1 Running 0 22s + redis-replicas-0 1/1 Running 0 69s + redis-replicas-1 1/1 Running 0 22s ``` Note that the hostname is `redis-master.default.svc.cluster.local:6379`, and a Kubernetes secret, `redis`, is created automatically. @@ -228,4 +228,4 @@ kubectl apply -f redis-pubsub.yaml {{< /tabs >}} ## Next steps -- [Try out a Dapr quickstart]({{< ref quickstarts.md >}}) \ No newline at end of file +- [Try out a Dapr quickstart]({{< ref quickstarts.md >}}) diff --git a/daprdocs/content/en/operations/components/setup-pubsub/pubsub-namespaces.md b/daprdocs/content/en/operations/components/setup-pubsub/pubsub-namespaces.md index bd042668441..b70fc73ba47 100644 --- a/daprdocs/content/en/operations/components/setup-pubsub/pubsub-namespaces.md +++ b/daprdocs/content/en/operations/components/setup-pubsub/pubsub-namespaces.md @@ -24,7 +24,7 @@ The table below shows which resources are deployed to which namespaces: | Resource | namespace-a | namespace-b | |------------------------ |-------------|-------------| | Redis master | X | | -| Redis slave | X | | +| Redis replicas | X | | | Dapr's PubSub component | X | X | | Node subscriber | X | | | Python subscriber | X | | diff --git a/daprdocs/content/en/reference/components-reference/supported-secret-stores/azure-keyvault-managed-identity.md b/daprdocs/content/en/reference/components-reference/supported-secret-stores/azure-keyvault-managed-identity.md index f73f4ada5bb..55d4abd88ff 100644 --- a/daprdocs/content/en/reference/components-reference/supported-secret-stores/azure-keyvault-managed-identity.md +++ b/daprdocs/content/en/reference/components-reference/supported-secret-stores/azure-keyvault-managed-identity.md @@ -13,7 +13,7 @@ To setup Azure Key Vault secret store with Managed Identies create a component o In Kubernetes mode, you store the certificate for the service principal into the Kubernetes Secret Store and then enable Azure Key Vault secret store with this certificate in Kubernetes secretstore. -The component yaml uses the name of your key vault and the Cliend ID of the managed identity to setup the secret store. +The component yaml uses the name of your key vault and the Client ID of the managed identity to setup the secret store. ```yaml apiVersion: dapr.io/v1alpha1