diff --git a/daprdocs/content/en/concepts/components-concept.md b/daprdocs/content/en/concepts/components-concept.md index 10eb40b86..0326a1262 100644 --- a/daprdocs/content/en/concepts/components-concept.md +++ b/daprdocs/content/en/concepts/components-concept.md @@ -14,18 +14,34 @@ Dapr uses a modular design where functionality is delivered as a component. Each The following are the component types provided by Dapr: -* [Bindings](https://github.com/dapr/components-contrib/tree/master/bindings) -* [Pub/sub](https://github.com/dapr/components-contrib/tree/master/pubsub) -* [Middleware](https://github.com/dapr/components-contrib/tree/master/middleware) +* [State stores](https://github.com/dapr/components-contrib/tree/master/state) * [Service discovery name resolution](https://github.com/dapr/components-contrib/tree/master/nameresolution) +* [Middleware](https://github.com/dapr/components-contrib/tree/master/middleware) +* [Pub/sub brokers](https://github.com/dapr/components-contrib/tree/master/pubsub) +* [Bindings](https://github.com/dapr/components-contrib/tree/master/bindings) * [Secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores) -* [State](https://github.com/dapr/components-contrib/tree/master/state) -### Service invocation and service discovery components + +## State stores + +State store components are databases that store key-value pairs as part of the [state management]({{< ref "state-management-overview.md" >}}) building block. + +## Service discovery + Service discovery components are used with the [service invocation]({{}}) building block to integrate with the hosting environment to provide service-to-service discovery. For example, the Kubernetes service discovery component integrates with the Kubernetes DNS service and self hosted uses mDNS. -### Service invocation and middleware components +## Middleware + Dapr allows custom [middleware]({{}}) to be plugged into the request processing pipeline. Middleware can perform additional actions on a request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the request is returned to the client. The middleware components are used with the [service invocation]({{}}) building block. -### Secret store components +## Pub/sub brokers + +Pub/sub broker components are message busses that can pass messages to/from services as part of the [publish & subscribe]({{< ref pubsub-overview.md >}}) building block. + +## Bindings + +External resources can connect to Dapr in order to trigger a service or be invoked from a service as part of the [bindings]({{< ref bindings-overview.md >}}) building block. + +## Secret stores + In Dapr, a [secret]({{}}) is any piece of private information that you want to guard against unwanted users. Secrets stores, used to store secrets, are Dapr components and can be used by any of the building blocks. diff --git a/daprdocs/content/en/concepts/configuration-concept.md b/daprdocs/content/en/concepts/configuration-concept.md index e9f3a407e..edc78d1ec 100644 --- a/daprdocs/content/en/concepts/configuration-concept.md +++ b/daprdocs/content/en/concepts/configuration-concept.md @@ -6,7 +6,27 @@ weight: 400 description: "Change the behavior of Dapr sidecars or globally on Dapr system services" --- -Dapr configurations are settings that enable you to change the behavior of individual Dapr application sidecars or globally on the system services in the Dapr control plane. -An example of a per Dapr application sidecar setting is configuring trace settings. An example of a Dapr control plane setting is mutual TLS which is a global setting on the Sentry system service. +Dapr configurations are settings that enable you to change both the behavior of individual Dapr application sidecars, the the global behavior of the system services in the Dapr control plane. + +Configurations are defined and deployed as a YAML file. An example would look like: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: default + namespace: default +spec: + mtls: + enabled: true + allowedClockSkew: 15m + workloadCertTTL: 24h + tracing: + samplingRate: "1" + zipkin: + endpointAddress: "https://..." +``` + +This configuration configures mtls for secure communication and tracing for telemetry recording. It can be loaded in self-hosted mode by editing the default configuration file in your `.dapr` directory, or by applying it to your Kubernetes cluster with kubectl/helm. Read [this page]({{}}) for a list of all configuration options. diff --git a/daprdocs/content/en/concepts/overview.md b/daprdocs/content/en/concepts/overview.md index 216a5661e..7566ab31b 100644 --- a/daprdocs/content/en/concepts/overview.md +++ b/daprdocs/content/en/concepts/overview.md @@ -9,7 +9,7 @@ description: > Dapr is a portable, event-driven runtime that makes it easy for any developer to build resilient, stateless and stateful applications that run on the cloud and edge and embraces the diversity of languages and developer frameworks. -{{< youtube 9o9iDAgYBA8 >}} + ## Any language, any framework, anywhere @@ -29,7 +29,7 @@ Using Dapr you can easily build microservice applications using any language, an There are many considerations when architecting microservices applications. Dapr provides best practices for common capabilities when building microservice applications that developers can use in a standard way and deploy to any environment. It does this by providing distributed system building blocks. -Each of these building blocks is independent, meaning that you can use one, some or all of them in your application. In this initial release of Dapr, the following building blocks are provided: +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 | |----------------|-------------| @@ -43,84 +43,78 @@ Each of these building blocks is independent, meaning that you can use one, some ## Sidecar architecture -Dapr exposes its APIs as a sidecar architecture, either as a container or as a process, not requiring the application code to include any Dapr runtime code. This makes integration with Dapr easy from other runtimes, as well as providing separation of the application logic for improved supportability. +Dapr exposes its HTTP and gRPC APIs as a sidecar architecture, either as a container or as a process, not requiring the application code to include any Dapr runtime code. This makes integration with Dapr easy from other runtimes, as well as providing separation of the application logic for improved supportability. -## Hosting Environments -Dapr can be hosted in multiple environments, including self hosted for local development or to deploy to a group of VMs, Kubernetes and edge environments such as Azure IoT Edge. + -### Self hosted +## Hosting environments -In self hosted mode Dapr runs as a separate side-car process which your service code can call via HTTP or gRPC. In self hosted mode, you can also deploy Dapr onto a set of VMs. +Dapr can be hosted in multiple environments, including self-hosted for local development and Kubernetes for production workloads. - +### Self-hosted -### Kubernetes hosted - -In container hosting environments such as Kubernetes, Dapr runs as a side-car container with the application container in the same pod. - - - -## Developer language SDKs and frameworks - -To make using Dapr more natural for different languages, it also includes [language specific SDKs]({{}}) for C++, Go, Java, JavaScript, Python, Rust .NET and PHP. These SDKs expose the functionality in the Dapr building blocks, such as saving state, publishing an event or creating an actor, through a typed, language API rather than calling the http/gRPC API. This enables you to write a combination of stateless and stateful functions and actors all in the language of their choice. And because these SDKs share the Dapr runtime, you get cross-language actor and functions support. - -### SDKs - -- **[C++ SDK](https://github.com/dapr/cpp-sdk)** -- **[Go SDK](https://github.com/dapr/go-sdk)** -- **[Java SDK](https://github.com/dapr/java-sdk)** -- **[Javascript SDK](https://github.com/dapr/js-sdk)** -- **[Python SDK](https://github.com/dapr/python-sdk)** -- **[RUST SDK](https://github.com/dapr/rust-sdk)** -- **[.NET SDK](https://github.com/dapr/dotnet-sdk)** -- **[PHP SDK](https://github.com/dapr/php-sdk)** - -> Note: Dapr is language agnostic and provides a [RESTful HTTP API]({{< ref api >}}) in addition to the protobuf clients. - -### Developer frameworks -Dapr can be used from any developer framework. Here are some that have been integrated with Dapr. - -#### Web - In the Dapr [.NET SDK](https://github.com/dapr/dotnet-sdk) you can find [ASP.NET Core](https://dotnet.microsoft.com/apps/aspnet) integration, which brings stateful routing controllers that respond to pub/sub events from other services. - - In the Dapr [Java SDK](https://github.com/dapr/java-sdk) you can find [Spring Boot](https://spring.io/) integration. - -Dapr integrates easily with Python [Flask](https://pypi.org/project/Flask/) and node [Express](http://expressjs.com/). See examples in the [Dapr quickstarts](https://github.com/dapr/quickstarts). - -In the Dapr [PHP-SDK](https://github.com/dapr/php-sdk) you can serve with Apache, Nginx, or Caddyserver. - -#### Actors -Dapr SDKs support for [virtual actors]({{< ref actors >}}) which are stateful objects that make concurrency simple, have method and state encapsulation, and are designed for scalable, distributed applications. - -#### Azure Functions -Dapr integrates with the Azure Functions runtime via an extension that lets a function seamlessly interact with Dapr. Azure Functions provides an event-driven programming model and Dapr provides cloud-native building blocks. With this extension, you can bring both together for serverless and event-driven apps. For more information read -[Azure Functions extension for Dapr](https://cloudblogs.microsoft.com/opensource/2020/07/01/announcing-azure-functions-extension-for-dapr/) and visit the [Azure Functions extension](https://github.com/dapr/azure-functions-extension) repo to try out the samples. - -#### Dapr workflows -To enable developers to easily build workflow applications that use Dapr’s capabilities including diagnostics and multi-language support, you can use Dapr workflows. Dapr integrates with workflow engines such as Logic Apps. For more information read -[cloud-native workflows using Dapr and Logic Apps](https://cloudblogs.microsoft.com/opensource/2020/05/26/announcing-cloud-native-workflows-dapr-logic-apps/) and visit the [Dapr workflow](https://github.com/dapr/workflows) repo to try out the samples. - -## Designed for Operations -Dapr is designed for [operations](/operations/). The [services dashboard](https://github.com/dapr/dashboard), installed via the Dapr CLI, provides a web-based UI enabling you to see information, view logs and more for the Dapr sidecars. - -The [monitoring tools support](/operations/monitoring/) provides deeper visibility into the Dapr system services and side-cars and the [observability capabilities]({{}}) of Dapr provide insights into your application such as tracing and metrics. - -## Run anywhere - -### Running Dapr on a local developer machine in self hosted mode - -Dapr can be configured to run on your local developer machine in [self-hosted mode]({{< ref self-hosted >}}). Each running service has a Dapr runtime process (or sidecar) which is configured to use state stores, pub/sub, binding components and the other building blocks. +In self hosted mode 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 >}}). - +Architecture diagram of Dapr in self-hosted mode -### Running Dapr in Kubernetes mode +### Kubernetes hosted -Dapr can be configured to run on any [Kubernetes cluster]({{< ref kubernetes >}}). In Kubernetes the `dapr-sidecar-injector` and `dapr-operator` services provide first class integration to launch Dapr as a sidecar container in the same pod as the service container and provide notifications of Dapr component updates provisioned into the cluster. +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-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. You can see some examples [here](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes/deploy) in the Kubernetes getting started sample. Try this out with the [Kubernetes quickstart](https://github.com/dapr/quickstarts/tree/master/hello-kubernetes). +Architecture diagram of Dapr in Kubernetes mode + +## Developer language SDKs and frameworks + +Dapr offers a variety of SDKs and frameworks to make it easy to begin developing with Dapr in your preferred language. + +### Dapr SDKs + +To make using Dapr more natural for different languages, it also includes [language specific SDKs]({{}}) for: +- C++ +- Go +- Java +- JavaScript +- Python +- Rust +- .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. + +### Developer frameworks + +Dapr can be used from any developer framework. Here are some that have been integrated with Dapr: + +#### Web + +| Language | Frameworks | Description | +|----------|------------|-------------| +| [.NET]({{< ref dotnet >}}) | [ASP.NET]({{< ref dotnet-aspnet.md >}}) | Brings stateful routing controllers that respond to pub/sub events from other services. +| [Java](https://github.com/dapr/java-sdk) | [Spring Boot](https://spring.io/) +| [Python]({{< ref python >}}) | [Flask]({{< ref python-flask.md >}}) +| [Javascript](https://github.com/dapr/js-sdk) | [Express](http://expressjs.com/) +| [PHP]({{< ref php >}}) | | You can serve with Apache, Nginx, or Caddyserver. + +#### Integrations + +Visit the [integrations]({{< ref integrations >}}) page to learn about some of the first-class support Dapr has for various frameworks and external products, including: +- Visual Studio Code +- Azure Functions +- Azure Logic Apps +- KEDA + +## Designed for operations + +Dapr is designed for [operations]({{< ref operations >}}) and security. The Dapr sidecars, runtime, components, and configuration can all be managed and deployed easily and securly to match your organization's needs. + +The [services dashboard](https://github.com/dapr/dashboard), installed via the Dapr CLI, provides a web-based UI enabling you to see information, view logs and more for the Dapr sidecars. + +The [monitoring tools support]({{< ref monitoring >}}) provides deeper visibility into the Dapr system services and side-cars and the [observability capabilities]({{}}) of Dapr provide insights into your application such as tracing and metrics. diff --git a/daprdocs/content/en/concepts/terminology.md b/daprdocs/content/en/concepts/terminology.md new file mode 100644 index 000000000..1051f884b --- /dev/null +++ b/daprdocs/content/en/concepts/terminology.md @@ -0,0 +1,21 @@ +--- +type: docs +title: "Dapr terminology and definitions" +linkTitle: "Terminology" +weight: 800 +description: Definitions for common terms and acronyms in the Dapr documentation +--- + +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. +| Building block | A piece of functionality that Dapr provides to users to help in the creation of microservices and applications. | [Dapr building blocks]({{< ref building-blocks-concept.md >}}) +| Component | A modular piece of functionality that make up, either by itself or with a collection of other components, a Dapr building block. | [Dapr components]({{< ref components-concept.md >}}) +| Configuration | A YAML file declaring all of the settings for Dapr sidecars and the Dapr control plane. It is here where you can configure mTLS, tracing, and middleware. | [Dapr configuration]({{< ref configuration-concept.md >}}) +| Dapr | Distributed Application Runtime. | [Dapr overview]({{< ref overview.md >}}) +| Self-hosted | Your local Windows/macOS/Linux machine where you run your applications with Dapr. Dapr provides capabilities to run on your machine 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 applicaiton. +| Sidecar | A program that runs along side your application as a separate binary or pod. | [Sidecar pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar) +| System services | Applications that run as part of the Dapr control plane, which take care of the various jobs that Dapr handles such as service discovery or sidecar injection. | [Self-hosted overview]({{< ref self-hosted-overview >}})
[Kubernetes overview]({{< ref kubernetes-overview >}}) \ No newline at end of file diff --git a/daprdocs/static/images/overview-sidecar-model.png b/daprdocs/static/images/overview-sidecar-model.png new file mode 100644 index 000000000..902f0c6de Binary files /dev/null and b/daprdocs/static/images/overview-sidecar-model.png differ diff --git a/daprdocs/static/images/overview_kubernetes.png b/daprdocs/static/images/overview_kubernetes.png index c233f379a..673c8182c 100644 Binary files a/daprdocs/static/images/overview_kubernetes.png and b/daprdocs/static/images/overview_kubernetes.png differ diff --git a/daprdocs/static/images/overview_standalone.png b/daprdocs/static/images/overview_standalone.png index 52bbb6a42..8a23394d6 100644 Binary files a/daprdocs/static/images/overview_standalone.png and b/daprdocs/static/images/overview_standalone.png differ