diff --git a/daprdocs/content/en/concepts/components-concept.md b/daprdocs/content/en/concepts/components-concept.md index f5e84cde790..8331dbd8293 100644 --- a/daprdocs/content/en/concepts/components-concept.md +++ b/daprdocs/content/en/concepts/components-concept.md @@ -29,7 +29,7 @@ Service discovery components are used with the [service invocation]({{}}) 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. +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. - [Middleware implementations](https://github.com/dapr/components-contrib/tree/master/middleware) diff --git a/daprdocs/content/en/concepts/middleware-concept.md b/daprdocs/content/en/concepts/middleware-concept.md deleted file mode 100644 index 2f382f8672a..00000000000 --- a/daprdocs/content/en/concepts/middleware-concept.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -type: docs -title: "Middleware pipelines" -linkTitle: "Middleware" -weight: 400 -description: "Custom processing pipelines of chained middleware components" ---- - -Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. A request goes through all defined middleware components before it's routed to user code, and then goes through the defined middleware, in reverse order, before it's returned to the client, as shown in the following diagram. - - - -## Customize processing pipeline - -When launched, a Dapr sidecar constructs a middleware processing pipeline. By default the pipeline consists of [tracing middleware]({{< ref tracing-overview.md >}}) and CORS middleware. Additional middleware, configured by a Dapr [configuration]({{< ref configuration-concept.md >}}), can be added to the pipeline in the order they are defined. The pipeline applies to all Dapr API endpoints, including state, pub/sub, service invocation, bindings, security and others. - -> **NOTE:** Dapr provides a **middleware.http.uppercase** pre-registered component that changes all text in a request body to uppercase. You can use it to test/verify if your custom pipeline is in place. - -The following configuration example defines a custom pipeline that uses a [OAuth 2.0 middleware]({{< ref oauth.md >}}) and an uppercase middleware component. In this case, all requests are authorized through the OAuth 2.0 protocol, and transformed to uppercase text, before they are forwarded to user code. - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: pipeline - namespace: default -spec: - httpPipeline: - handlers: - - name: oauth2 - type: middleware.http.oauth2 - - name: uppercase - type: middleware.http.uppercase -``` - -## Next steps - -* [Middleware overview]({{< ref middleware-overview.md >}}) -* [How-To: Configure API authorization with OAuth]({{< ref oauth.md >}}) 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 0ba0043dc70..1511ec40f1e 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 @@ -23,10 +23,9 @@ Refer [api spec]({{< ref "actors_api.md#invoke-actor-method" >}}) for more detai ## Actor state management Actors can save state reliably using state management capability. - You can interact with Dapr through HTTP/gRPC endpoints for state management. -To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The list of components that support transactions/actors can be found here: [supported state stores]({{< ref supported-state-stores.md >}}). +To use actors, your state store must support multi-item transactions. This means your state store [component](https://github.com/dapr/components-contrib/tree/master/state) must implement the [TransactionalStore](https://github.com/dapr/components-contrib/blob/master/state/transactional_store.go) interface. The list of components that support transactions/actors can be found here: [supported state stores]({{< ref supported-state-stores.md >}}). Only a single state store component can be used as the statestore for all actors. ## Actor timers and reminders diff --git a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md index a8e2fad0dae..1b5198f23e1 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md @@ -12,10 +12,10 @@ Using service invocation, your application can reliably and securely communicate In many environments with multiple services that need to communicate with each other, developers often ask themselves the following questions: -* How do I discover and invoke methods on different services? -* How do I call other services securely with encryption and apply access control on the methods? -* How do I handle retries and transient errors? -* How do I use tracing to see a call graph with metrics to diagnose issues in production? +- How do I discover and invoke methods on different services? +- How do I call other services securely with encryption and apply access control on the methods? +- How do I handle retries and transient errors? +- How do I use tracing to see a call graph with metrics to diagnose issues in production? Dapr addresses these challenges by providing a service invocation API that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing, metrics, error handling, encryption and more. @@ -28,11 +28,9 @@ The diagram below is an overview of how Dapr's service invocation works. Diagram showing the steps of service invocation 1. Service A makes an HTTP or gRPC call targeting Service B. The call goes to the local Dapr sidecar. -2. Dapr discovers Service B's location using the [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) which is running on the given [hosting platform]({{< ref "hosting" >}}). +2. Dapr discovers Service B's location using the [name resolution component]({{< ref supported-name-resolution >}}) which is running on the given [hosting platform]({{< ref "hosting" >}}). 3. Dapr forwards the message to Service B's Dapr sidecar - - **Note**: All calls between Dapr sidecars go over gRPC for performance. Only calls between services and Dapr sidecars can be either HTTP or gRPC - + - **Note**: All calls between Dapr sidecars go over gRPC for performance. Only calls between services and Dapr sidecars can be either HTTP or gRPC 4. Service B's Dapr sidecar forwards the request to the specified endpoint (or method) on Service B. Service B then runs its business logic code. 5. Service B sends a response to Service A. The response goes to Service B's sidecar. 6. Dapr forwards the response to Service A's Dapr sidecar. @@ -43,18 +41,21 @@ Service invocation provides several features to make it easy for you to call met ### Namespaces scoping -Service invocation supports calls across namespaces. On all supported hosting platforms, Dapr app IDs conform to a valid FQDN format that includes the target namespace. - -For example, the following string contains the app ID `nodeapp` in addition to the namespace the app runs in `production`. +By default, users can invoke services within the same namespaces by simply referencing the app ID (`nodeapp`): +```sh +localhost:3500/v1.0/invoke/nodeapp/method/neworder ``` -localhost:3500/v1.0/invoke/nodeapp.production/method/neworder -``` -This is especially useful in cross namespace calls in a Kubernetes cluster. Watch this video for a demo on how to use namespaces with service invocation. +Service invocation also supports calls across namespaces. On all supported hosting platforms, Dapr app IDs conform to a valid FQDN format that includes the target namespace. + +Users can specify both the app ID (`nodeapp`) in addition to the namespace the app runs in (`production`): - +```sh +localhost:3500/v1.0/invoke/nodeapp.production/method/neworder +``` +This is especially useful in cross namespace calls in a Kubernetes cluster. ### Service-to-service security @@ -62,44 +63,37 @@ All calls between Dapr applications can be made secure with mutual (mTLS) authen For more information read the [service-to-service security]({{< ref "security-concept.md#sidecar-to-sidecar-communication" >}}) article. - -### Service access policies security +### Access control Applications can control which other applications are allowed to call them and what they are authorized to do via access policies. This enables you to restrict sensitive applications, that say have personnel information, from being accessed by unauthorized applications, and combined with service-to-service secure communication, provides for soft multi-tenancy deployments. For more information read the [access control allow lists for service invocation]({{< ref invoke-allowlist.md >}}) article. -#### Example service invocation security -The diagram below is an example deployment on a Kubernetes cluster with a Daprized `Ingress` service that calls onto `Service A` using service invocation with mTLS encryption and an applies access control policy. `Service A` then calls onto `Service B` also using service invocation and mTLS. Each service is running in different namespaces for added isolation. - - - ### Retries Service invocation performs automatic retries with backoff time periods in the event of call failures and transient errors. Errors that cause retries are: -* Network errors including endpoint unavailability and refused connections. -* Authentication errors due to a renewing certificate on the calling/callee Dapr sidecars. +- Network errors including endpoint unavailability and refused connections. +- Authentication errors due to a renewing certificate on the calling/callee Dapr sidecars. Per call retries are performed with a backoff interval of 1 second up to a threshold of 3 times. Connection establishment via gRPC to the target sidecar has a timeout of 5 seconds. ### Pluggable service discovery -Dapr can run on any [hosting platform]({{< ref hosting >}}). For the supported hosting platforms this means they have a [name resolution component](https://github.com/dapr/components-contrib/tree/master/nameresolution) developed for them that enables service discovery. For example, the Kubernetes name resolution component uses the Kubernetes DNS service to resolve the location of other applications running in the cluster. For local and multiple physical machines this uses the mDNS protocol. - -> Note: [For local and physical machines, ensure mDNS is functioning properly.]({{< ref "common_issues.md#service-invocation-is-failing-and-my-dapr-service-is-missing-an-appId-macos" >}}) +Dapr can run on a variety of [hosting platforms]({{< ref hosting >}}). To enable service discovery and service invocation, Dapr uses pluggable [name resolution components]({{< ref supported-name-resolution >}}). For example, the Kubernetes name resolution component uses the Kubernetes DNS service to resolve the location of other applications running in the cluster. Self-hosted machines can use the mDNS name resolution component. The Consul name resolution component can be used in any hosting environment including Kubernetes or self-hosted. ### Round robin load balancing with mDNS + Dapr provides round robin load balancing of service invocation requests with the mDNS protocol, for example with a single machine or with multiple, networked, physical machines. The diagram below shows an example of how this works. If you have 1 instance of an application with app ID `FrontEnd` and 3 instances of application with app ID `Cart` and you call from `FrontEnd` app to `Cart` app, Dapr round robins' between the 3 instances. These instance can be on the same machine or on different machines. . -Diagram showing the steps of service invocation +Diagram showing the steps of service invocation -Note: You can have N instances of the same app with the same app ID as app ID is unique per app. And you can have multiple instances of that app where all those instances have the same app ID. +**Note**: You can have N instances of the same app with the same app ID as app ID is unique per app. And you can have multiple instances of that app where all those instances have the same app ID. ### Tracing and metrics with observability @@ -110,11 +104,12 @@ By default, all calls between applications are traced and metrics are gathered t The API for service invocation can be found in the [service invocation API reference]({{< ref service_invocation_api.md >}}) which describes how to invoke a method on another service. ## Example + Following the above call sequence, suppose you have the applications as described in the [hello world quickstart](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md), where a python app invokes a node.js app. In such a scenario, the python app would be "Service A" , and a Node.js app would be "Service B". The diagram below shows sequence 1-7 again on a local machine showing the API calls: - + 1. The Node.js app has a Dapr app ID of `nodeapp`. The python app invokes the Node.js app's `neworder` method by POSTing `http://localhost:3500/v1.0/invoke/nodeapp/method/neworder`, which first goes to the python app's local Dapr sidecar. 2. Dapr discovers the Node.js app's location using name resolution component (in this case mDNS while self-hosted) which runs on your local machine. @@ -126,9 +121,9 @@ The diagram below shows sequence 1-7 again on a local machine showing the API ca ## Next steps -* Follow these guides on: - * [How-to: Invoke services using HTTP]({{< ref howto-invoke-discover-services.md >}}) - * [How-To: Configure Dapr to use gRPC]({{< ref grpc >}}) -* Try out the [hello world quickstart](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) which shows how to use HTTP service invocation or try the samples in the [Dapr SDKs]({{< ref sdks >}}) -* Read the [service invocation API specification]({{< ref service_invocation_api.md >}}) -* Understand the [service invocation performance]({{< ref perf-service-invocation.md >}}) numbers +- Follow these guides on: + - [How-to: Invoke services using HTTP]({{< ref howto-invoke-discover-services.md >}}) + - [How-To: Configure Dapr to use gRPC]({{< ref grpc >}}) +- Try out the [hello world quickstart](https://github.com/dapr/quickstarts/blob/master/hello-world/README.md) which shows how to use HTTP service invocation or try the samples in the [Dapr SDKs]({{< ref sdks >}}) +- Read the [service invocation API specification]({{< ref service_invocation_api.md >}}) +- Understand the [service invocation performance]({{< ref perf-service-invocation.md >}}) numbers diff --git a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md index f414b9376ab..dc7149d1f2d 100644 --- a/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md +++ b/daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md @@ -65,7 +65,7 @@ Dapr supports two types of bulk operations - **bulk** or **multi**. You can grou Read the [API reference]({{< ref state_api.md >}}) to learn how use bulk and multi options. ### Actor state -Transactional state stores can be used to store actor state. To specify which state store to be used for actors, specify value of property `actorStateStore` as `true` in the metadata section of the state store component. Actors state is stored with a specific scheme in transactional state stores, which allows for consistent querying. Read the [API reference]({{< ref state_api.md >}}) to learn more about state stores for actors and the [actors API reference]({{< ref actors_api.md >}}) +Transactional state stores can be used to store actor state. To specify which state store to be used for actors, specify value of property `actorStateStore` as `true` in the metadata section of the state store component. Actors state is stored with a specific scheme in transactional state stores, which allows for consistent querying. Only a single state store component can be used as the statestore for all actors. Read the [API reference]({{< ref state_api.md >}}) to learn more about state stores for actors and the [actors API reference]({{< ref actors_api.md >}}) ### Query state store directly diff --git a/daprdocs/content/en/developing-applications/middleware/middleware-overview.md b/daprdocs/content/en/developing-applications/middleware.md similarity index 51% rename from daprdocs/content/en/developing-applications/middleware/middleware-overview.md rename to daprdocs/content/en/developing-applications/middleware.md index 751bac28f76..a48ceac16d0 100644 --- a/daprdocs/content/en/developing-applications/middleware/middleware-overview.md +++ b/daprdocs/content/en/developing-applications/middleware.md @@ -1,52 +1,43 @@ --- type: docs -title: "Overview" -linkTitle: "Overview" -description: "General overview on set up of middleware components for Dapr" -weight: 10000 -type: docs +title: "Middleware" +linkTitle: "Middleware" +weight: 50 +description: "Customize processing pipelines by adding middleware components" +aliases: +- /developing-applications/middleware/middleware-overview/ +- /concepts/middleware-concept/ --- -Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. Middleware pipelines are defined in Dapr configuration files. -As with other [building block components]({{< ref component-schema.md >}}), middleware components are extensible and can be found in the [components-contrib repo](https://github.com/dapr/components-contrib/tree/master/middleware/http). +Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. A request goes through all defined middleware components before it's routed to user code, and then goes through the defined middleware, in reverse order, before it's returned to the client, as shown in the following diagram. -Middleware in Dapr is described using a `Component` file with the following schema: + -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: - namespace: -spec: - type: middleware.http. - version: v1 - metadata: - - name: - value: - - name: - value: -... -``` -The type of middleware is determined by the `type` field. Component setting values such as rate limits, OAuth credentials and other settings are put in the `metadata` section. -Even though metadata values can contain secrets in plain text, it is recommended that you use a [secret store]({{< ref component-secrets.md >}}). +## Configuring middleware pipelines + +When launched, a Dapr sidecar constructs a middleware processing pipeline. By default the pipeline consists of [tracing middleware]({{< ref tracing-overview.md >}}) and CORS middleware. Additional middleware, configured by a Dapr [configuration]({{< ref configuration-concept.md >}}), can be added to the pipeline in the order they are defined. The pipeline applies to all Dapr API endpoints, including state, pub/sub, service invocation, bindings, security and others. -Next, a Dapr [configuration]({{< ref configuration-overview.md >}}) defines the pipeline of middleware components for your application. +The following configuration example defines a custom pipeline that uses a [OAuth 2.0 middleware]({{< ref middleware-oauth2.md >}}) and an [uppercase middleware component]({{< ref middleware-uppercase.md >}}). In this case, all requests are authorized through the OAuth 2.0 protocol, and transformed to uppercase text, before they are forwarded to user code. ```yaml apiVersion: dapr.io/v1alpha1 kind: Configuration metadata: - name: appconfig + name: pipeline + namespace: default spec: httpPipeline: handlers: - - name: - type: middleware.http. - - name: - type: middleware.http. + - name: oauth2 + type: middleware.http.oauth2 + - name: uppercase + type: middleware.http.uppercase ``` +As with other building block components, middleware components are extensible and can be found in the [supported Middleware reference]({{< ref supported-middleware >}}) and in the [components-contrib repo](https://github.com/dapr/components-contrib/tree/master/middleware/http). + +{{< button page="supported-middleware" text="See all middleware components">}} + ## 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 **fasthttp.RequestHandler** and **error**: @@ -81,7 +72,6 @@ After the components-contrib change has been accepted, submit another pull reque ## Related links -* [Middleware pipelines concept]({{< ref middleware-concept.md >}}) * [Component schema]({{< ref component-schema.md >}}) * [Configuration overview]({{< ref configuration-overview.md >}}) * [Middleware quickstart](https://github.com/dapr/quickstarts/tree/master/middleware) diff --git a/daprdocs/content/en/developing-applications/middleware/_index.md b/daprdocs/content/en/developing-applications/middleware/_index.md deleted file mode 100644 index 48d145843a4..00000000000 --- a/daprdocs/content/en/developing-applications/middleware/_index.md +++ /dev/null @@ -1,7 +0,0 @@ ---- -type: docs -title: "Middleware" -linkTitle: "Middleware" -weight: 50 -description: "Customize processing pipelines by adding middleware components" ---- diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-bearer.md b/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-bearer.md deleted file mode 100644 index 476c7a17dc3..00000000000 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-bearer.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -type: docs -title: "Bearer" -linkTitle: "Bearer" -weight: 4000 -description: "Use bearer middleware to secure HTTP endpoints by verifying bearer tokens" -type: docs ---- - -The bearer [HTTP middleware]({{< ref middleware-concept.md >}}) verifies a [Bearer Token](https://tools.ietf.org/html/rfc6750) using [OpenID Connect](https://openid.net/connect/) on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code. - -## Component format - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: bearer-token -spec: - type: middleware.http.bearer - version: v1 - metadata: - - name: clientId - value: "" - - name: issuerURL - value: "https://accounts.google.com" -``` -## Spec metadata fields - -| Field | Details | Example | -|----------------|---------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| -| clientId | The client ID of your application that is created as part of a credential hosted by a OpenID Connect platform | | -| issuerURL | URL identifier for the service. | `"https://accounts.google.com"`, `"https://login.salesforce.com"` | - -## Dapr configuration - -To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - httpPipeline: - handlers: - - name: bearer-token - type: middleware.http.bearer -``` - -## Related links - -- [Middleware concept]({{< ref middleware-concept.md >}}) -- [Configuration concept]({{< ref configuration-concept.md >}}) -- [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2.md b/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2.md deleted file mode 100644 index ca6f671867e..00000000000 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -type: docs -title: "OAuth2" -linkTitle: "OAuth2" -weight: 2000 -description: "Use OAuth2 middleware to secure HTTP endpoints" ---- - -The OAuth2 [HTTP middleware]({{< ref middleware-concept.md >}}) enables the [OAuth2 Authorization Code flow](https://tools.ietf.org/html/rfc6749#section-4.1) on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code. - -## Component format - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: oauth2 -spec: - type: middleware.http.oauth2 - version: v1 - metadata: - - name: clientId - value: "" - - name: clientSecret - value: "" - - name: scopes - value: "https://www.googleapis.com/auth/userinfo.email" - - name: authURL - value: "https://accounts.google.com/o/oauth2/v2/auth" - - name: tokenURL - value: "https://accounts.google.com/o/oauth2/token" - - name: redirectURL - value: "http://dummy.com" - - name: authHeaderName - value: "authorization" - - name: forceHTTPS - value: "false" -``` -## Spec metadata fields -| Field | Details | Example | -|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------| -| clientId | The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform | | -| clientSecret | The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform | | -| scopes | A list of space-delimited, case-sensitive strings of [scopes](https://tools.ietf.org/html/rfc6749#section-3.3) which are typically used for authorization in the application | `"https://www.googleapis.com/auth/userinfo.email"` | -| authURL | The endpoint of the OAuth2 authorization server | `"https://accounts.google.com/o/oauth2/v2/auth"` | -| tokenURL | The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token | `"https://accounts.google.com/o/oauth2/token"` | -| redirectURL | The URL of your web application that the authorization server should redirect to once the user has authenticated | `"https://myapp.com"` | -| authHeaderName | The authorization header name to forward to your application | `"authorization"` | -| forceHTTPS | If true, enforces the use of TLS/SSL | `"true"`,`"false"` | - -## Dapr configuration - -To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - httpPipeline: - handlers: - - name: oauth2 - type: middleware.http.oauth2 -``` - -## Related links -- [Configure API authorization with OAuth]({{< ref oauth >}}) -- [Middleware OAuth quickstart](https://github.com/dapr/quickstarts/tree/master/middleware) -- [Middleware concept]({{< ref middleware-concept.md >}}) -- [Configuration concept]({{< ref configuration-concept.md >}}) -- [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2clientcredentials.md b/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2clientcredentials.md deleted file mode 100644 index 0f96cb28aa2..00000000000 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2clientcredentials.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -type: docs -title: "OAuth2 client credentials" -linkTitle: "OAuth2 client credentials" -weight: 3000 -description: "Use OAuth2 client credentials middleware to secure HTTP endpoints" ---- - -The OAuth2 client credentials [HTTP middleware]({{< ref middleware-concept.md >}}) enables the [OAuth2 Client Credentials flow](https://tools.ietf.org/html/rfc6749#section-4.4) on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code. - -## Component format - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Component -metadata: - name: oauth2clientcredentials -spec: - type: middleware.http.oauth2clientcredentials - version: v1 - metadata: - - name: clientId - value: "" - - name: clientSecret - value: "" - - name: scopes - value: "https://www.googleapis.com/auth/userinfo.email" - - name: tokenURL - value: "https://accounts.google.com/o/oauth2/token" - - name: headerName - value: "authorization" -``` -## Spec metadata fields - -| Field | Details | Example | -|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------| -| clientId | The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform | | -| clientSecret | The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform | | -| scopes | A list of space-delimited, case-sensitive strings of [scopes](https://tools.ietf.org/html/rfc6749#section-3.3) which are typically used for authorization in the application | `"https://www.googleapis.com/auth/userinfo.email"` | -| tokenURL | The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token | `"https://accounts.google.com/o/oauth2/token"` | -| headerName | The authorization header name to forward to your application | `"authorization"` | -| endpointParamsQuery | Specifies additional parameters for requests to the token endpoint | `true` | -| authStyle | Optionally specifies how the endpoint wants the client ID & client secret sent. See the table of possible values below | `0` | - -### Possible values for `authStyle` - -| Value | Meaning | -|-------|---------| -| `1` | Sends the "client_id" and "client_secret" in the POST body as application/x-www-form-urlencoded parameters. | -| `2` | Sends the "client_id" and "client_secret" using HTTP Basic Authorization. This is an optional style described in the [OAuth2 RFC 6749 section 2.3.1](https://tools.ietf.org/html/rfc6749#section-2.3.1). | -| `0` | Means to auto-detect which authentication style the provider wants by trying both ways and caching the successful way for the future. | - -## Dapr configuration - -To be applied, the middleware must be referenced in a [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). - -```yaml -apiVersion: dapr.io/v1alpha1 -kind: Configuration -metadata: - name: appconfig -spec: - httpPipeline: - handlers: - - name: oauth2clientcredentials - type: middleware.http.oauth2clientcredentials -``` - -## Related links -- [Middleware concept]({{< ref middleware-concept.md >}}) -- [Configuration concept]({{< ref configuration-concept.md >}}) -- [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/operations/configuration/api-allowlist.md b/daprdocs/content/en/operations/configuration/api-allowlist.md index e87a9b37ab3..8499e0222cd 100644 --- a/daprdocs/content/en/operations/configuration/api-allowlist.md +++ b/daprdocs/content/en/operations/configuration/api-allowlist.md @@ -8,7 +8,7 @@ description: "Choose which Dapr sidecar APIs are available to the app" In certain scenarios such as zero trust networks or when exposing the Dapr sidecar to external traffic through a frontend, it's recommended to only enable the Dapr sidecar APIs that are being used by the app. Doing so reduces the attack surface and helps keep the Dapr APIs scoped to the actual needs of the application. -Dapr allows developers to control which APIs are accessible to the application by setting an API allow list using a [Dapr Configuration](({{}})). +Dapr allows developers to control which APIs are accessible to the application by setting an API allow list using a [Dapr Configuration]({{}}). ### Default behavior diff --git a/daprdocs/content/en/operations/configuration/configuration-overview.md b/daprdocs/content/en/operations/configuration/configuration-overview.md index 055ebdc8f65..e027eda255e 100644 --- a/daprdocs/content/en/operations/configuration/configuration-overview.md +++ b/daprdocs/content/en/operations/configuration/configuration-overview.md @@ -115,7 +115,7 @@ The following table lists the properties for HTTP handlers: | name | string | Name of the middleware component | type | string | Type of middleware component -See [Middleware pipelines]({{< ref "middleware-concept.md" >}}) for more information +See [Middleware pipelines]({{< ref "middleware.md" >}}) for more information #### Scope secret store access See the [Scoping secrets]({{< ref "secret-scope.md" >}}) guide for information and examples on how to scope secrets to an application. diff --git a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md index 533007f4beb..9077cc9ee3d 100644 --- a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md +++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md @@ -25,3 +25,8 @@ The `dapr-placement` service is responsible for managing the actor distribution You can use the [`dapr run` CLI command]({{< ref dapr-run.md >}}) to a Dapr sidecar process along with your application. +## Name resolution + +Dapr uses a [name resolution component]({{< ref supported-name-resolution >}}) for service discovery within the [service invocation]({{< ref service-invocation >}}) building block. By default Dapr uses mDNS when in self-hosted mode. + +If you are running Dapr on virtual machines or where mDNS is not available, then you can use the [HashiCorp Consul]({{< ref setup-nr-consul.md >}}) component for name resolution. diff --git a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md index 9abe5a26512..b69b48ac0ab 100644 --- a/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md +++ b/daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md @@ -149,6 +149,10 @@ To further learn how to run Dapr with Docker Compose, see the [Docker-Compose Sa If your deployment target is Kubernetes please use Dapr's first-class integration. Refer to the [Dapr on Kubernetes docs]({{< ref "kubernetes-overview.md" >}}). +## Name resolution + +Dapr by default uses mDNS as the name resolution component in self-hosted mode for service invocation. If you are running Dapr on virtual machines or where mDNS is not available, then you can use the [HashiCorp Consul]({{< ref setup-nr-consul.md >}}) component for name resolution. + ## Docker images Dapr provides a number of prebuilt Docker images for different components, you should select the relevant image for your desired binary, architecture, and tag/version. diff --git a/daprdocs/content/en/operations/security/oauth.md b/daprdocs/content/en/operations/security/oauth.md index 4f8be5fcdf4..637fa1eac0d 100644 --- a/daprdocs/content/en/operations/security/oauth.md +++ b/daprdocs/content/en/operations/security/oauth.md @@ -6,7 +6,7 @@ weight: 2000 description: "Enable OAUTH authorization on Dapr endpoints for your web APIs" --- -Dapr OAuth 2.0 [middleware]({{< ref "middleware-concept.md" >}}) allows you to enable [OAuth](https://oauth.net/2/) authorization on Dapr endpoints for your web APIs using the [Authorization Code Grant flow](https://tools.ietf.org/html/rfc6749#section-4.1). +Dapr OAuth 2.0 [middleware]({{< ref "middleware.md" >}}) allows you to enable [OAuth](https://oauth.net/2/) authorization on Dapr endpoints for your web APIs using the [Authorization Code Grant flow](https://tools.ietf.org/html/rfc6749#section-4.1). You can also inject authorization tokens into your APIs which can be used for authorization towards external APIs called by your APIs using the [Client Credentials Grant flow](https://tools.ietf.org/html/rfc6749#section-4.4). When the middleware is enabled any method invocation through Dapr needs to be authorized before getting passed to the user code. @@ -81,7 +81,7 @@ spec: ### Define a custom pipeline for an Authorization Code Grant -To use the OAuth middleware (Authorization Code), you should create a [custom pipeline]({{< ref "middleware-concept.md" >}}) +To use the OAuth middleware (Authorization Code), you should create a [custom pipeline]({{< ref "middleware.md" >}}) using [Dapr configuration]({{< ref "configuration-overview" >}}), as shown in the following sample: ```yaml @@ -139,7 +139,7 @@ spec: ### Define a custom pipeline for a Client Credentials Grant -To use the OAuth middleware (Client Credentials), you should create a [custom pipeline]({{< ref "middleware-concept.md" >}}) +To use the OAuth middleware (Client Credentials), you should create a [custom pipeline]({{< ref "middleware.md" >}}) using [Dapr configuration]({{< ref "configuration-overview.md" >}}), as shown in the following sample: ```yaml diff --git a/daprdocs/content/en/reference/api/actors_api.md b/daprdocs/content/en/reference/api/actors_api.md index 522f65b3bc0..03b8080d227 100644 --- a/daprdocs/content/en/reference/api/actors_api.md +++ b/daprdocs/content/en/reference/api/actors_api.md @@ -311,8 +311,8 @@ name | The name of the reminder to delete. #### Examples ```shell -curl http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ - -X "Content-Type: application/json" +curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/reminders/checkRebels \ + -H "Content-Type: application/json" ``` ### Create actor timer @@ -404,8 +404,8 @@ name | The name of the timer to delete. > Note, all URL parameters are case-sensitive. ```shell -curl http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \ - -X "Content-Type: application/json" +curl -X DELETE http://localhost:3500/v1.0/actors/stormtrooper/50/timers/checkRebels \ + -H "Content-Type: application/json" ``` ## Dapr calling to user service code diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/cron.md b/daprdocs/content/en/reference/components-reference/supported-bindings/cron.md index 34a069192cc..70d6d959932 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/cron.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/cron.md @@ -50,7 +50,7 @@ For example: * `30 * * * * *` - every 30 seconds * `0 15 * * * *` - every 15 minutes * `0 30 3-6,20-23 * * *` - every hour on the half hour in the range 3-6am, 8-11pm -* `CRON_TZ=America/New_York 0 0 30 04 * * *` - every day at 4:30am New York time +* `CRON_TZ=America/New_York 0 30 04 * * *` - every day at 4:30am New York time > You can learn more about cron and the supported formats [here](https://en.wikipedia.org/wiki/Cron) diff --git a/daprdocs/content/en/reference/components-reference/supported-bindings/gcppubsub.md b/daprdocs/content/en/reference/components-reference/supported-bindings/gcppubsub.md index af1e78d0a48..c7e49edf79a 100644 --- a/daprdocs/content/en/reference/components-reference/supported-bindings/gcppubsub.md +++ b/daprdocs/content/en/reference/components-reference/supported-bindings/gcppubsub.md @@ -56,17 +56,17 @@ The above example uses secrets as plain strings. It is recommended to use a secr | Field | Required | Binding support | Details | Example | |--------------------|:--------:|-----------| -----|---------| | topic | Y | Output | GCP Pub/Sub topic name | `"topic1"` | -| subscription | Y | GCP Pub/Sub subscription name | `"name1"` | +| subscription | N | GCP Pub/Sub subscription name | `"name1"` | | type | Y | Output | GCP credentials type | `service_account` | project_id | Y | Output | GCP project id| `projectId` -| private_key_id | Y | Output | GCP private key id | `"privateKeyId"` +| private_key_id | N | Output | GCP private key id | `"privateKeyId"` | private_key | Y | Output | GCP credentials private key. Replace with x509 cert | `12345-12345` | client_email | Y | Output | GCP client email | `"client@email.com"` -| client_id | Y | Output | GCP client id | `0123456789-0123456789` -| auth_uri | Y | Output | Google account OAuth endpoint | `https://accounts.google.com/o/oauth2/auth` -| token_uri | Y | Output | Google account token uri | `https://oauth2.googleapis.com/token` -| auth_provider_x509_cert_url | Y | Output |GCP credentials cert url | `https://www.googleapis.com/oauth2/v1/certs` -| client_x509_cert_url | Y | Output | GCP credentials project x509 cert url | `https://www.googleapis.com/robot/v1/metadata/x509/.iam.gserviceaccount.com` +| client_id | N | Output | GCP client id | `0123456789-0123456789` +| auth_uri | N | Output | Google account OAuth endpoint | `https://accounts.google.com/o/oauth2/auth` +| token_uri | N | Output | Google account token uri | `https://oauth2.googleapis.com/token` +| auth_provider_x509_cert_url | N | Output |GCP credentials cert url | `https://www.googleapis.com/oauth2/v1/certs` +| client_x509_cert_url | N | Output | GCP credentials project x509 cert url | `https://www.googleapis.com/robot/v1/metadata/x509/.iam.gserviceaccount.com` ## Binding support diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/_index.md b/daprdocs/content/en/reference/components-reference/supported-middleware/_index.md similarity index 92% rename from daprdocs/content/en/developing-applications/middleware/supported-middleware/_index.md rename to daprdocs/content/en/reference/components-reference/supported-middleware/_index.md index dc343472d48..039ec971e34 100644 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/_index.md @@ -1,10 +1,12 @@ --- type: docs -title: "Supported middleware" -linkTitle: "Supported middleware" -weight: 30000 +title: "Middleware component specs" +linkTitle: "Middleware" +weight: 6000 description: List of all the supported middleware components that can be injected in Dapr's processing pipeline. no_list: true +aliases: +- /developing-applications/middleware/supported-middleware/ --- ### HTTP diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-bearer.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-bearer.md new file mode 100644 index 00000000000..bf637194e89 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-bearer.md @@ -0,0 +1,56 @@ +--- +type: docs +title: "Bearer" +linkTitle: "Bearer" +description: "Use bearer middleware to secure HTTP endpoints by verifying bearer tokens" +type: docs +aliases: +- /developing-applications/middleware/supported-middleware/middleware-bearer/ +--- + +The bearer [HTTP middleware]({{< ref middleware.md >}}) verifies a [Bearer Token](https://tools.ietf.org/html/rfc6750) using [OpenID Connect](https://openid.net/connect/) on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code. + +## Component format + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: bearer-token +spec: + type: middleware.http.bearer + version: v1 + metadata: + - name: clientId + value: "" + - name: issuerURL + value: "https://accounts.google.com" +``` +## Spec metadata fields + +| Field | Details | Example | +|-------|---------|---------| +| clientId | The client ID of your application that is created as part of a credential hosted by a OpenID Connect platform +| issuerURL | URL identifier for the service. | `"https://accounts.google.com"`, `"https://login.salesforce.com"` + +## Dapr configuration + +To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md">}}). + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + httpPipeline: + handlers: + - name: bearer-token + type: middleware.http.bearer +``` + +## Related links + +- [Middleware]({{< ref middleware.md >}}) +- [Configuration concept]({{< ref configuration-concept.md >}}) +- [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md new file mode 100644 index 00000000000..7097835a1a0 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md @@ -0,0 +1,80 @@ +--- +type: docs +title: "OAuth2" +linkTitle: "OAuth2" +description: "Use OAuth2 middleware to secure HTTP endpoints" +aliases: +- /developing-applications/middleware/supported-middleware/middleware-oauth2/ +--- + +The OAuth2 [HTTP middleware]({{< ref middleware.md >}}) enables the [OAuth2 Authorization Code flow](https://tools.ietf.org/html/rfc6749#section-4.1) on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code. + +## Component format + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: oauth2 +spec: + type: middleware.http.oauth2 + version: v1 + metadata: + - name: clientId + value: "" + - name: clientSecret + value: "" + - name: scopes + value: "https://www.googleapis.com/auth/userinfo.email" + - name: authURL + value: "https://accounts.google.com/o/oauth2/v2/auth" + - name: tokenURL + value: "https://accounts.google.com/o/oauth2/token" + - name: redirectURL + value: "http://dummy.com" + - name: authHeaderName + value: "authorization" + - name: forceHTTPS + value: "false" +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Details | Example | +|-------|---------|---------| +| clientId | The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform +| clientSecret | The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform +| scopes | A list of space-delimited, case-sensitive strings of [scopes](https://tools.ietf.org/html/rfc6749#section-3.3) which are typically used for authorization in the application | `"https://www.googleapis.com/auth/userinfo.email"` +| authURL | The endpoint of the OAuth2 authorization server | `"https://accounts.google.com/o/oauth2/v2/auth"` +| tokenURL | The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token | `"https://accounts.google.com/o/oauth2/token"` +| redirectURL | The URL of your web application that the authorization server should redirect to once the user has authenticated | `"https://myapp.com"` +| authHeaderName | The authorization header name to forward to your application | `"authorization"` +| forceHTTPS | If true, enforces the use of TLS/SSL | `"true"`,`"false"` | + +## Dapr configuration + +To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md#customize-processing-pipeline">}}). + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + httpPipeline: + handlers: + - name: oauth2 + type: middleware.http.oauth2 +``` + +## Related links + +- [Configure API authorization with OAuth]({{< ref oauth >}}) +- [Middleware OAuth quickstart](https://github.com/dapr/quickstarts/tree/master/middleware) +- [Middleware]({{< ref middleware.md >}}) +- [Configuration concept]({{< ref configuration-concept.md >}}) +- [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md new file mode 100644 index 00000000000..ceba912ef68 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md @@ -0,0 +1,78 @@ +--- +type: docs +title: "OAuth2 client credentials" +linkTitle: "OAuth2 client credentials" +description: "Use OAuth2 client credentials middleware to secure HTTP endpoints" +aliases: +- /developing-applications/middleware/supported-middleware/middleware-oauth2clientcredentials/ +--- + +The OAuth2 client credentials [HTTP middleware]({{< ref middleware.md >}}) enables the [OAuth2 Client Credentials flow](https://tools.ietf.org/html/rfc6749#section-4.4) on a Web API without modifying the application. This design separates authentication/authorization concerns from the application, so that application operators can adopt and configure authentication/authorization providers without impacting the application code. + +## Component format + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Component +metadata: + name: oauth2clientcredentials +spec: + type: middleware.http.oauth2clientcredentials + version: v1 + metadata: + - name: clientId + value: "" + - name: clientSecret + value: "" + - name: scopes + value: "https://www.googleapis.com/auth/userinfo.email" + - name: tokenURL + value: "https://accounts.google.com/o/oauth2/token" + - name: headerName + value: "authorization" +``` + +{{% alert title="Warning" color="warning" %}} +The above example uses secrets as plain strings. It is recommended to use a secret store for the secrets as described [here]({{< ref component-secrets.md >}}). +{{% /alert %}} + +## Spec metadata fields + +| Field | Details | Example | +|------------|---------|---------| +| clientId | The client ID of your application that is created as part of a credential hosted by a OAuth-enabled platform +| clientSecret | The client secret of your application that is created as part of a credential hosted by a OAuth-enabled platform +| scopes | A list of space-delimited, case-sensitive strings of [scopes](https://tools.ietf.org/html/rfc6749#section-3.3) which are typically used for authorization in the application | `"https://www.googleapis.com/auth/userinfo.email"` +| tokenURL | The endpoint is used by the client to obtain an access token by presenting its authorization grant or refresh token | `"https://accounts.google.com/o/oauth2/token"` +| headerName | The authorization header name to forward to your application | `"authorization"` +| endpointParamsQuery | Specifies additional parameters for requests to the token endpoint | `true` +| authStyle | Optionally specifies how the endpoint wants the client ID & client secret sent. See the table of possible values below | `0` + +### Possible values for `authStyle` + +| Value | Meaning | +|-------|---------| +| `1` | Sends the "client_id" and "client_secret" in the POST body as application/x-www-form-urlencoded parameters. | +| `2` | Sends the "client_id" and "client_secret" using HTTP Basic Authorization. This is an optional style described in the [OAuth2 RFC 6749 section 2.3.1](https://tools.ietf.org/html/rfc6749#section-2.3.1). | +| `0` | Means to auto-detect which authentication style the provider wants by trying both ways and caching the successful way for the future. | + +## Dapr configuration + +To be applied, the middleware must be referenced in a [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md#customize-processing-pipeline">}}). + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: appconfig +spec: + httpPipeline: + handlers: + - name: oauth2clientcredentials + type: middleware.http.oauth2clientcredentials +``` + +## Related links +- [Middleware]({{< ref middleware.md >}}) +- [Configuration concept]({{< ref configuration-concept.md >}}) +- [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-opa.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-opa.md similarity index 80% rename from daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-opa.md rename to daprdocs/content/en/reference/components-reference/supported-middleware/middleware-opa.md index 36870c59a65..1c10e602638 100644 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-opa.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-opa.md @@ -2,11 +2,12 @@ type: docs title: "Apply Open Policy Agent (OPA) policies" linkTitle: "Open Policy Agent (OPA)" -weight: 6000 description: "Use middleware to apply Open Policy Agent (OPA) policies on incoming requests" +aliases: +- /developing-applications/middleware/supported-middleware/middleware-opa/ --- -The Open Policy Agent (OPA) [HTTP middleware]({{< ref middleware-concept.md >}}) applys [OPA Policies](https://www.openpolicyagent.org/) to incoming Dapr HTTP requests. This can be used to apply reusable authorization policies to app endpoints. +The Open Policy Agent (OPA) [HTTP middleware]({{< ref middleware.md >}}) applys [OPA Policies](https://www.openpolicyagent.org/) to incoming Dapr HTTP requests. This can be used to apply reusable authorization policies to app endpoints. ## Component format @@ -70,15 +71,15 @@ You can prototype and experiment with policies using the [official opa playgroun ## Spec metadata fields -| Field | Details | Example | -|-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------| -| rego | The Rego policy language | See above | -| defaultStatus | The status code to return for denied responses | `"https://accounts.google.com"`, `"https://login.salesforce.com"` | -| includedHeaders | A comma-separated set of case-insensitive headers to include in the request input. Request headers are not passed to the policy by default. Include to receive incoming request headers in the input | `"x-my-custom-header, x-jwt-header"` | +| Field | Details | Example | +|--------|---------|---------| +| rego | The Rego policy language | See above | +| defaultStatus | The status code to return for denied responses | `"https://accounts.google.com"`, `"https://login.salesforce.com"` +| includedHeaders | A comma-separated set of case-insensitive headers to include in the request input. Request headers are not passed to the policy by default. Include to receive incoming request headers in the input | `"x-my-custom-header, x-jwt-header"` ## Dapr configuration -To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). +To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md#customize-processing-pipeline">}}). ```yaml apiVersion: dapr.io/v1alpha1 @@ -208,6 +209,6 @@ type Result struct { - [Open Policy Agent](https://www.openpolicyagent.org) - [HTTP API example](https://www.openpolicyagent.org/docs/latest/http-api-authorization/) -- [Middleware concept]({{< ref middleware-concept.md >}}) +- [Middleware]({{< ref middleware.md >}}) - [Configuration concept]({{< ref configuration-concept.md >}}) - [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-rate-limit.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-rate-limit.md similarity index 61% rename from daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-rate-limit.md rename to daprdocs/content/en/reference/components-reference/supported-middleware/middleware-rate-limit.md index a2796b74eea..d154871529d 100644 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-rate-limit.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-rate-limit.md @@ -2,11 +2,12 @@ type: docs title: "Rate limiting" linkTitle: "Rate limiting" -weight: 1000 description: "Use rate limit middleware to limit requests per second" +aliases: +- /developing-applications/middleware/supported-middleware/middleware-rate-limit/ --- -The rate limit [HTTP middleware]({{< ref middleware-concept.md >}}) allows restricting the maximum number of allowed HTTP requests per second. Rate limiting can protect your application from denial of service (DOS) attacks. DOS attacks can be initiated by malicious 3rd parties but also by bugs in your software (a.k.a. a "friendly fire" DOS attack). +The rate limit [HTTP middleware]({{< ref middleware.md >}}) allows restricting the maximum number of allowed HTTP requests per second. Rate limiting can protect your application from denial of service (DOS) attacks. DOS attacks can be initiated by malicious 3rd parties but also by bugs in your software (a.k.a. a "friendly fire" DOS attack). ## Component format @@ -26,9 +27,9 @@ spec: ## Spec metadata fields -| Field | Details | Example | -|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| -| maxRequestsPerSecond | The maximum requests per second by remote IP and path. Something to consider is that **the limit is enforced independently in each Dapr sidecar and not cluster wide** | `10` | +| Field | Details | Example | +|-------|---------|---------| +| maxRequestsPerSecond | The maximum requests per second by remote IP and path. Something to consider is that **the limit is enforced independently in each Dapr sidecar and not cluster wide** | `10` Once the limit is reached, the request will return *HTTP Status code 429: Too Many Requests*. @@ -36,7 +37,7 @@ Alternatively, the [max concurrency setting]({{< ref control-concurrency.md >}}) ## Dapr configuration -To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). +To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md#customize-processing-pipeline">}}). ```yaml apiVersion: dapr.io/v1alpha1 @@ -53,6 +54,6 @@ spec: ## Related links - [Control max concurrently]({{< ref control-concurrency.md >}}) -- [Middleware concept]({{< ref middleware-concept.md >}}) +- [Middleware]({{< ref middleware.md >}}) - [Dapr configuration]({{< ref configuration-concept.md >}}) - [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-sentinel.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-sentinel.md similarity index 70% rename from daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-sentinel.md rename to daprdocs/content/en/reference/components-reference/supported-middleware/middleware-sentinel.md index 72dcac73e35..e93fd9c7381 100644 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-sentinel.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-sentinel.md @@ -2,13 +2,14 @@ type: docs title: "Sentinel fault-tolerance middleware component" linkTitle: "Sentinel" -weight: 7000 description: "Use Sentinel middleware to guarantee the reliability and resiliency of your application" +aliases: +- /developing-applications/middleware/supported-middleware/middleware-sentinel/ --- [Sentinel](https://github.com/alibaba/sentinel-golang) is a powerful fault-tolerance component that takes "flow" as the breakthrough point and covers multiple fields including flow control, traffic shaping, concurrency limiting, circuit breaking, and adaptive system protection to guarantee the reliability and resiliency of microservices. -The Sentinel [HTTP middleware]({{< ref middleware-concept.md >}}) enables Dapr to facilitate Sentinel's powerful abilities to protect your application. You can refer to [Sentinel Wiki](https://github.com/alibaba/sentinel-golang/wiki) for more details on Sentinel. +The Sentinel [HTTP middleware]({{< ref middleware.md >}}) enables Dapr to facilitate Sentinel's powerful abilities to protect your application. You can refer to [Sentinel Wiki](https://github.com/alibaba/sentinel-golang/wiki) for more details on Sentinel. ## Component format @@ -41,15 +42,15 @@ spec: ## Spec metadata fields -| Field | Details | Example | -|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------| -| appName | the name of current running service | `nodeapp` | -| logDir | the log directory path | `/var/tmp/sentinel` | -| flowRules | json array of sentinel flow control rules | [flow control rule](https://github.com/alibaba/sentinel-golang/blob/master/core/flow/rule.go) | -| circuitBreakerRules | json array of sentinel circuit breaker rules | [circuit breaker rule](https://github.com/alibaba/sentinel-golang/blob/master/core/circuitbreaker/rule.go) | -| hotSpotParamRules | json array of sentinel hotspot parameter flow control rules | [hotspot rule](https://github.com/alibaba/sentinel-golang/blob/master/core/hotspot/rule.go) | -| isolationRules | json array of sentinel isolation rules | [isolation rule](https://github.com/alibaba/sentinel-golang/blob/master/core/isolation/rule.go) | -| systemRules | json array of sentinel system rules | [system rule](https://github.com/alibaba/sentinel-golang/blob/master/core/system/rule.go) | +| Field | Details | Example | +|-------|---------|---------| +| appName | the name of current running service | `nodeapp` +| logDir | the log directory path | `/var/tmp/sentinel` +| flowRules | json array of sentinel flow control rules | [flow control rule](https://github.com/alibaba/sentinel-golang/blob/master/core/flow/rule.go) +| circuitBreakerRules | json array of sentinel circuit breaker rules | [circuit breaker rule](https://github.com/alibaba/sentinel-golang/blob/master/core/circuitbreaker/rule.go) +| hotSpotParamRules | json array of sentinel hotspot parameter flow control rules | [hotspot rule](https://github.com/alibaba/sentinel-golang/blob/master/core/hotspot/rule.go) +| isolationRules | json array of sentinel isolation rules | [isolation rule](https://github.com/alibaba/sentinel-golang/blob/master/core/isolation/rule.go) +| systemRules | json array of sentinel system rules | [system rule](https://github.com/alibaba/sentinel-golang/blob/master/core/system/rule.go) Once the limit is reached, the request will return *HTTP Status code 429: Too Many Requests*. @@ -63,7 +64,7 @@ All concrete HTTP API information can be found from [Dapr API Reference]{{< ref ## Dapr configuration -To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). +To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md#customize-processing-pipeline">}}). ```yaml apiVersion: dapr.io/v1alpha1 @@ -80,6 +81,6 @@ spec: ## Related links - [Sentinel Github](https://github.com/alibaba/sentinel-golang) -- [Middleware concept]({{< ref middleware-concept.md >}}) +- [Middleware]({{< ref middleware.md >}}) - [Dapr configuration]({{< ref configuration-concept.md >}}) - [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-uppercase.md b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-uppercase.md similarity index 69% rename from daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-uppercase.md rename to daprdocs/content/en/reference/components-reference/supported-middleware/middleware-uppercase.md index b0fac0eaff9..a2b38433e27 100644 --- a/daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-uppercase.md +++ b/daprdocs/content/en/reference/components-reference/supported-middleware/middleware-uppercase.md @@ -2,11 +2,12 @@ type: docs title: "Uppercase request body" linkTitle: "Uppercase" -weight: 9999 description: "Test your HTTP pipeline is functioning with the uppercase middleware" +aliases: +- /developing-applications/middleware/supported-middleware/middleware-uppercase/ --- -The uppercase [HTTP middleware]({{< ref middleware-concept.md >}}) converts the body of the request to uppercase letters and is used for testing that the pipeline is functioning. It should only be used for local development. +The uppercase [HTTP middleware]({{< ref middleware.md >}}) converts the body of the request to uppercase letters and is used for testing that the pipeline is functioning. It should only be used for local development. ## Component format @@ -26,7 +27,7 @@ This component has no `metadata` to configure. ## Dapr configuration -To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware-concept.md#customize-processing-pipeline">}}). +To be applied, the middleware must be referenced in [configuration]({{< ref configuration-concept.md >}}). See [middleware pipelines]({{< ref "middleware.md#customize-processing-pipeline">}}). ```yaml apiVersion: dapr.io/v1alpha1 @@ -42,6 +43,6 @@ spec: ## Related links -- [Middleware concept]({{< ref middleware-concept.md >}}) +- [Middleware]({{< ref middleware.md >}}) - [Configuration concept]({{< ref configuration-concept.md >}}) - [Configuration overview]({{< ref configuration-overview.md >}}) diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/_index.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/_index.md index bfa170ed5ce..c0c66b074c5 100644 --- a/daprdocs/content/en/reference/components-reference/supported-name-resolution/_index.md +++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/_index.md @@ -1,6 +1,6 @@ --- type: docs -title: "Name resolution component specs" +title: "Name resolution provider component specs" linkTitle: "Name resolution" weight: 5000 description: The supported name resolution providers that interface with Dapr service invocation @@ -21,14 +21,13 @@ The following components provide name resolution for the service invocation buil | Name | Status | Component version | Since | |------|:------:|:-----------------:|:-----:| -| mDNS | GA | v1 | 1.0 | +| [mDNS]({{< ref nr-mdns.md >}}) | GA | v1 | 1.0 | ### Kubernetes | Name | Status | Component version | Since | |------------|:------:|:-----------------:|:-----:| -| Kubernetes | GA | v1 | 1.0 | - +| [Kubernetes]({{< ref nr-kubernetes.md >}}) | GA | v1 | 1.0 | ## Definitions diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md new file mode 100644 index 00000000000..15f22643ff2 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md @@ -0,0 +1,23 @@ +--- +type: docs +title: "Kubernetes DNS name resolution provider spec" +linkTitle: "Kubernetes DNS" +description: Detailed information on the Kubernetes DNS name resolution component +--- + +## Configuration format + +Kubernetes DNS name resolution is configured automatically in [Kubernetes mode]({{< ref kubernetes >}}) by Dapr. There is no configuration needed to use Kubernetes DNS as your name resolution provider. + +## Behaviour + +The component resolves target apps by using the Kubernetes cluster's DNS provider. You can learn more in the [Kubernetes docs](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/). + +## Spec configuration fields + +Not applicable, as Kubernetes DNS is configured by Dapr when running in Kubernetes mode. + +## Related links + +- [Service invocation building block]({{< ref service-invocation >}}) +- [Kubernetes DNS docs](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-mdns.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-mdns.md new file mode 100644 index 00000000000..2c9d0ea6484 --- /dev/null +++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-mdns.md @@ -0,0 +1,29 @@ +--- +type: docs +title: "mDNS name resolution provider spec" +linkTitle: "mDNS" +description: Detailed information on the mDNS name resolution component +--- + +## Configuration format + +Multicast DNS (mDNS) is configured automatically in [self-hosted mode]({{< ref self-hosted >}}) by Dapr. There is no configuration needed to use mDNS as your name resolution provider. + +## Behaviour + +The component resolves target apps by using the host system's mDNS service. You can learn more about mDNS [here](https://en.wikipedia.org/wiki/Multicast_DNS). + +### Troubleshooting + +In some cloud provider virtual networks, such as Microsoft Azure, mDNS is not available. Use an alternate provider such as [HashiCorp Consul]({{< ref setup-nr-consul.md >}}) instead. + +On some enterprise-managed systems, mDNS may be disabled on macOS if a network filter/proxy is configured. Check with your IT department if mDNS is disabled and you are unable to use service invocation locally. + +## Spec configuration fields + +Not applicable, as mDNS is configured by Dapr when running in self-hosted mode. + +## Related links + +- [Service invocation building block]({{< ref service-invocation >}}) +- [mDNS reference](https://en.wikipedia.org/wiki/Multicast_DNS) \ No newline at end of file diff --git a/daprdocs/content/en/reference/components-reference/supported-name-resolution/setup-nr-consul.md b/daprdocs/content/en/reference/components-reference/supported-name-resolution/setup-nr-consul.md index ab5b44a84f4..1959ab71365 100644 --- a/daprdocs/content/en/reference/components-reference/supported-name-resolution/setup-nr-consul.md +++ b/daprdocs/content/en/reference/components-reference/supported-name-resolution/setup-nr-consul.md @@ -1,9 +1,9 @@ --- type: docs -title: "HashiCorp Consul" +title: "HashiCorp Consul name resolution provider spec" linkTitle: "HashiCorp Consul" description: Detailed information on the HashiCorp Consul name resolution component ---- +--- ## Configuration format @@ -29,14 +29,14 @@ If Consul service registration is managed externally from Dapr you need to ensur ## Behaviour -On init the Consul component will either validate the connection to the configured (or default) agent or register the service if configured to do so. The name resolution interface does not cater for an "on shutdown" pattern so please consider this if using Dapr to register services to Consul as it will not deregister services. +On `init` the Consul component either validates the connection to the configured (or default) agent or registers the service if configured to do so. The name resolution interface does not cater for an "on shutdown" pattern so consider this when using Dapr to register services to Consul as it does not deregister services. The component resolves target apps by filtering healthy services and looks for a `DAPR_PORT` in the metadata (key is configurable) in order to retrieve the Dapr sidecar port. Consul `service.meta` is used over `service.port` so as to not interfere with existing Consul estates. ## Spec configuration fields -As of writing the configuration spec is fixed to v1.3.0 of the Consul api +The configuration spec is fixed to v1.3.0 of the Consul API | Field | Required | Type | Details | Examples | |--------------|:--------:|-----:|:---------|----------| @@ -105,7 +105,7 @@ spec: ### Advanced registration -Configuring the advanced registration gives you full control over all the properties possible when registering. +Configuring the advanced registration gives you full control over setting all the Consul properties possible when registering. ```yaml apiVersion: dapr.io/v1alpha1 @@ -142,11 +142,11 @@ spec: {{< tabs "Self-Hosted" "Kubernetes" >}} {{% codetab %}} -HashiCorp offer in depth guides on how to setup Consul for different hosting models. Please check out the [self-hosted guide here](https://learn.hashicorp.com/collections/consul/getting-started) +HashiCorp offer in depth guides on how to setup Consul for different hosting models. Check out the [self-hosted guide here](https://learn.hashicorp.com/collections/consul/getting-started) {{% /codetab %}} {{% codetab %}} -HashiCorp offer in depth guides on how to setup Consul for different hosting models. Please check out the [Kubernetes guide here](https://learn.hashicorp.com/collections/consul/gs-consul-service-mesh) +HashiCorp offer in depth guides on how to setup Consul for different hosting models. Check out the [Kubernetes guide here](https://learn.hashicorp.com/collections/consul/gs-consul-service-mesh) {{% /codetab %}} {{< /tabs >}} diff --git a/daprdocs/static/images/middleware.png b/daprdocs/static/images/middleware.png index 92c3380754f..1642493ad21 100644 Binary files a/daprdocs/static/images/middleware.png and b/daprdocs/static/images/middleware.png differ diff --git a/daprdocs/static/images/service-invocation-overview.png b/daprdocs/static/images/service-invocation-overview.png index f9af4d25c2a..c5b2fe55400 100644 Binary files a/daprdocs/static/images/service-invocation-overview.png and b/daprdocs/static/images/service-invocation-overview.png differ