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

upmerge/06-24 (#1588) 

* Supported Release Info and Upgrade Path for v1.2 (#1494)

* Supported Release Info and Upgrade Path for v1.2

* Update support-release-policy.md

* Update daprdocs/content/en/operations/support/support-release-policy.md

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Adding K8s versions table (#1521)

* Adding table of kubernetes versions

* Updating intro

* Fix incorrect postgresql connection string example (#1524)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Update docs on using Codespaces with Dapr repos (#1522)

* Update docs on using Codespaces with Dapr repos

* Move codespaces.md under the Contributing topic

* Update daprdocs/content/en/contributing/codespaces.md

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Fix two typos (#1526)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Update chinese content (#1527)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Updated to fix deprecated helm chart location (#1528)

The `https://kubernetes-charts.storage.googleapis.com/` location is no longer used, so this change updates this, the command to install, and the missing update step that will cause the install to fail if an update was never done after adding the location.

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* nr_consul_typo fixed malformed yaml (#1532)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Fix typo in azure-keyvault-managed-identity.md (#1541)

* Fix custom middleware sample code interface implementation error (#1539)

Fix custom middleware sample code interface implementation error, interface function declare error.

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Fix the file name of secrets json (#1546)

* Tech writing touch-ups (#1555)

* Tech writing touch-ups (#1556)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Tech writing touch-ups (#1557)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Tech writing touch-ups (#1558)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Tech writing touch-ups (#1560)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Tech writing touch-ups (#1559)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Ignore intellij link that isn't resolvable (#1564)

* Update issue templates (#1563)

* Update issue templates

* Add needs-triage

* Updating PubSub documentation to remove slave wording (#1565)

* Updating PubSub documentation to remove slave

Bitnami has updated their Redis Helm chart to change redis-slave to redis-replicas. I am updating the documentation for PubSub to reflect this change and avoid confusion for any readers.

* Removing more instances of Redis slave naming

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Actor Runtime Configuration Docs (#1495)

* Actor Runtime Configuration Docs

Addresses #1470

* Update daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Update daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* add configuration examples

* configuration examples

* Fix syntax

* Add dotnet sample

* Update daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Fixed GCP Pub/Sub Binding required fields (#1578)

* aacrawfi/middlware (#1567)

* Move and update middleware components

* Update middleware docs structure

* Combine middleware pages

* Update middleware references

* Update middleware image

* Fix incorrect curl syntax in Actors API examples (#1577)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Fix link at api-allowlist.md (#1574)

Fix link at api-allowlist.md to Dapr Configuration overview

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* Add language that only a single state store component can be used for actors state mangement (#1579)

Co-authored-by: Aaron Crawfis <Aaron.Crawfis@microsoft.com>

* fix: cron format (#1581)

* Updated name resolution docs (#1576)

* Add consul references

* Fix typo

Add a missing word

* Clarify state management examples

* Added table to show Kubernetes options

When I read this doc it was unclear that the cert could be provided as a secret. The only table on the original version showed `spnCertificateFile` as a required option. I added a second table to make it clear that in Kubernetes there is a `spnCertificate` option that does not require a file on disk.

* incorporating feedback

* Update daprdocs/content/en/reference/components-reference/supported-secret-stores/azure-keyvault.md

* Update daprdocs/content/en/reference/components-reference/supported-secret-stores/azure-keyvault.md

* Fix self-hosted docs

* Remove name-resolution reference

* Add other name resolution providers

* Update service invocation docs

* Remove whitespace

* Update service-invocation-overview.md

Fixed typo and added a sentence on Consul

* Update setup-nr-consul.md

Minor updates

* Address comments

* Fix code formatting

Co-authored-by: Esteban Luchsinger <eluchsingerm@hotmail.com>
Co-authored-by: Donovan Brown <dbrown@microsoft.com>
Co-authored-by: Mark Fussell <mfussell@microsoft.com>

Co-authored-by: Bernd Verst <berndverst@users.noreply.github.com>
Co-authored-by: Mark Fussell <mfussell@microsoft.com>
Co-authored-by: Zonciu Liang <zonciu@zonciu.com>
Co-authored-by: Simon Leet <31784195+CodeMonkeyLeet@users.noreply.github.com>
Co-authored-by: Maarten Mulders <mthmulders@users.noreply.github.com>
Co-authored-by: Newbe36524 <newbe36524@qq.com>
Co-authored-by: Steven Jenkins De Haro <20492442+StevenJDH@users.noreply.github.com>
Co-authored-by: Abdulaziz Elsheikh <abdulaziz.elsheikh@gmail.com>
Co-authored-by: Antonio Fiumanò <antoniofiumano@outlook.com>
Co-authored-by: li1234yun <li1234yun@163.com>
Co-authored-by: greenie-msft <56556602+greenie-msft@users.noreply.github.com>
Co-authored-by: voipengineer <voipengineer@users.noreply.github.com>
Co-authored-by: Evan Simkowitz <esimkowitz@users.noreply.github.com>
Co-authored-by: Ricardo Niepel <RicardoNiepel@users.noreply.github.com>
Co-authored-by: Abhith Rajan <Abhith@users.noreply.github.com>
Co-authored-by: Esteban Luchsinger <eluchsingerm@hotmail.com>
Co-authored-by: Donovan Brown <dbrown@microsoft.com>
This commit is contained in:
Aaron Crawfis 2021-06-24 17:50:12 -07:00 committed by GitHub
parent cb0335f549
commit 55d9123cfe
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
32 changed files with 401 additions and 382 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
daprdocs/content/en/concepts/components-concept.md
View File

@ -29,7 +29,7 @@ Service discovery components are used with the [service invocation]({{<ref "serv
## Middleware
Dapr allows custom [middleware]({{<ref "middleware-concept.md">}}) 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]({{<ref "service-invocation-overview.md">}}) building block.
Dapr allows custom [middleware]({{<ref "middleware.md">}}) 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]({{<ref "service-invocation-overview.md">}}) building block.
- [Middleware implementations](https://github.com/dapr/components-contrib/tree/master/middleware)

39
daprdocs/content/en/concepts/middleware-concept.md
View File

@ -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.
<img src="/images/middleware.png" width=400>
## 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 >}})

3
daprdocs/content/en/developing-applications/building-blocks/actors/howto-actors.md
View File

@ -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

67
daprdocs/content/en/developing-applications/building-blocks/service-invocation/service-invocation-overview.md
View File

@ -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.
<img src="/images/service-invocation-overview.png" width=800 alt="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
```
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. Watch this video for a demo on how to use namespaces with service invocation.
<iframe width="560" height="315" src="https://www.youtube.com/embed/LYYV_jouEuA?start=497" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
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.
<img src="/images/service-invocation-security.png" width=800>
### 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. .
<img src="/images/service-invocation-mdns-round-robin.png" width=800 alt="Diagram showing the steps of service invocation">
<img src="/images/service-invocation-mdns-round-robin.png" width=600 alt="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:
<img src="/images/service-invocation-overview-example.png" width=800>
<img src="/images/service-invocation-overview-example.png" width=800 />
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

2
daprdocs/content/en/developing-applications/building-blocks/state-management/state-management-overview.md
View File

@ -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

56
daprdocs/content/en/developing-applications/middleware/middleware-overview.md → daprdocs/content/en/developing-applications/middleware.md
View File

@ -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:
<img src="/images/middleware.png" width=800>
```yaml
apiVersion: dapr.io/v1alpha1
kind: Component
metadata:
name: <COMPONENT NAME>
namespace: <NAMESPACE>
spec:
type: middleware.http.<MIDDLEWARE TYPE>
version: v1
metadata:
- name: <KEY>
value: <VALUE>
- name: <KEY>
value: <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
Next, a Dapr [configuration]({{< ref configuration-overview.md >}}) defines the pipeline of middleware components for your application.
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.
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: <COMPONENT NAME>
type: middleware.http.<MIDDLEWARE TYPE>
- name: <COMPONENT NAME>
type: middleware.http.<MIDDLEWARE TYPE>
- 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)

7
daprdocs/content/en/developing-applications/middleware/_index.md
View File

@ -1,7 +0,0 @@
---
type: docs
title: "Middleware"
linkTitle: "Middleware"
weight: 50
description: "Customize processing pipelines by adding middleware components"
---

55
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-bearer.md
View File

@ -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: "<your client ID>"
- 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 >}})

72
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2.md
View File

@ -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: "<your client ID>"
- name: clientSecret
value: "<your client secret>"
- 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 >}})

72
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-oauth2clientcredentials.md
View File

@ -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: "<your client ID>"
- name: clientSecret
value: "<your client secret>"
- 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 >}})

2
daprdocs/content/en/operations/configuration/api-allowlist.md
View File

@ -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](({{<ref "configuration-overview.md">}})).
Dapr allows developers to control which APIs are accessible to the application by setting an API allow list using a [Dapr Configuration]({{<ref "configuration-overview.md">}}).
### Default behavior

2
daprdocs/content/en/operations/configuration/configuration-overview.md
View File

@ -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.

5
daprdocs/content/en/operations/hosting/self-hosted/self-hosted-overview.md
View File

@ -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.

4
daprdocs/content/en/operations/hosting/self-hosted/self-hosted-with-docker.md
View File

@ -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.

6
daprdocs/content/en/operations/security/oauth.md
View File

@ -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

8
daprdocs/content/en/reference/api/actors_api.md
View File

@ -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

2
daprdocs/content/en/reference/components-reference/supported-bindings/cron.md
View File

@ -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)

14
daprdocs/content/en/reference/components-reference/supported-bindings/gcppubsub.md
View File

@ -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/<PROJECT_NAME>.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/<PROJECT_NAME>.iam.gserviceaccount.com`
## Binding support

8
daprdocs/content/en/developing-applications/middleware/supported-middleware/_index.md → daprdocs/content/en/reference/components-reference/supported-middleware/_index.md
View File

@ -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

56
daprdocs/content/en/reference/components-reference/supported-middleware/middleware-bearer.md Normal file
View File

@ -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: "<your client ID>"
- 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 >}})

80
daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2.md Normal file
View File

@ -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: "<your client ID>"
- name: clientSecret
value: "<your client secret>"
- 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 >}})

78
daprdocs/content/en/reference/components-reference/supported-middleware/middleware-oauth2clientcredentials.md Normal file
View File

@ -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: "<your client ID>"
- name: clientSecret
value: "<your client secret>"
- 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 >}})

19
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-opa.md → daprdocs/content/en/reference/components-reference/supported-middleware/middleware-opa.md
View File

@ -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 >}})

15
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-rate-limit.md → daprdocs/content/en/reference/components-reference/supported-middleware/middleware-rate-limit.md
View File

@ -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 >}})

27
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-sentinel.md → daprdocs/content/en/reference/components-reference/supported-middleware/middleware-sentinel.md
View File

@ -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 >}})

9
daprdocs/content/en/developing-applications/middleware/supported-middleware/middleware-uppercase.md → daprdocs/content/en/reference/components-reference/supported-middleware/middleware-uppercase.md
View File

@ -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 >}})

7
daprdocs/content/en/reference/components-reference/supported-name-resolution/_index.md
View File

@ -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

23
daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-kubernetes.md Normal file
View File

@ -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/)

29
daprdocs/content/en/reference/components-reference/supported-name-resolution/nr-mdns.md Normal file
View File

@ -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)

14
daprdocs/content/en/reference/components-reference/supported-name-resolution/setup-nr-consul.md
View File

@ -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 >}}

BIN
daprdocs/static/images/middleware.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 24 KiB

After

Width:  |  Height:  |  Size: 44 KiB

BIN
daprdocs/static/images/service-invocation-overview.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 92 KiB

After

Width:  |  Height:  |  Size: 85 KiB