diff --git a/daprdocs/content/en/operations/components/middleware.md b/daprdocs/content/en/operations/components/middleware.md index ca85f08a848..d6820166790 100644 --- a/daprdocs/content/en/operations/components/middleware.md +++ b/daprdocs/content/en/operations/components/middleware.md @@ -3,15 +3,21 @@ type: docs title: "Configure middleware components" linkTitle: "Configure middleware" weight: 2000 -description: "Customize processing pipelines by adding middleware components" +description: "Customize processing pipelines via the middleware components" --- -Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. There are two places that you can use a middleware pipeline: +{{% alert title="Note" color="primary" %}} +Configuring middleware components using the [configuration schema]({{< ref configuration-schema.md >}}) is **deprecated**. +{{% /alert %}} + +With Dapr, you can define custom processing pipelines by chaining a series of middleware components. There are two places that you can use a middleware pipeline: 1. Building block APIs - HTTP middleware components are executed when invoking any Dapr HTTP APIs. -2. Service-to-Service invocation - HTTP middleware components are applied to service-to-service invocation calls. +1. Service-to-Service invocation - HTTP middleware components are applied to service-to-service invocation calls. + +In this guide, you learn how to configure middleware using its component YAML. To learn how to create middleware components, see the [Author middleware components how-to guides.]({{< ref develop-middleware.md >}}) -## Configure API middleware pipelines +## Configure API middleware pipelines (sidecar to sidecar) When launched, a Dapr sidecar constructs a middleware processing pipeline for incoming HTTP calls. By default, the pipeline consists of the [tracing]({{< ref tracing-overview.md >}}) and CORS middlewares. Additional middlewares, 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, secrets, configuration, distributed lock, etc. @@ -19,30 +25,30 @@ A request goes through all the defined middleware components before it's routed Diagram showing the flow of a request and a response through the middlewares, as described in the paragraph above -HTTP middleware components are executed when invoking Dapr HTTP APIs using the `httpPipeline` configuration. +HTTP middleware components are executed when invoking Dapr HTTP APIs using the `httpPipeline` setting. -The following configuration example defines a custom pipeline that uses an [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. +The following example defines a custom pipeline that uses a [RouterChecker middleware]({{< ref middleware-routerchecker.md >}}). In this case, all requests are authorized against the `^[A-Za-z0-9/._-]+$`:regex before they are forwarded to user code. The `priority` field determines the order in which requests are executed once all handler components are collected. ```yaml apiVersion: dapr.io/v1alpha1 -kind: Configuration +kind: Component metadata: - name: pipeline - namespace: default + name: routerchecker1 spec: - httpPipeline: - handlers: - - name: oauth2 - type: middleware.http.oauth2 - - name: uppercase - type: middleware.http.uppercase + type: middleware.http.routerchecker + version: v1 + metadata: + - name: rule + value: "^[A-Za-z0-9/._-]+$" + - name: pipelineType + value: httpPipeline + - name: priority + value: 1 ``` -As with other components, middleware components can be found in the [supported Middleware reference]({{< ref supported-middleware >}}) and in the [`dapr/components-contrib` repo](https://github.com/dapr/components-contrib/tree/master/middleware/http). - -{{< button page="supported-middleware" text="See all middleware components">}} +As with other components, supported middleware components can be found in the [supported Middleware reference guide]({{< ref supported-middleware >}}) and in the [`dapr/components-contrib` repo](https://github.com/dapr/components-contrib/tree/master/middleware/http). -## Configure app middleware pipelines +## Configure app middleware (sidecar to app) You can also use any middleware component when making service-to-service invocation calls. For example, to add token validation in a zero-trust environment, to transform a request for a specific app endpoint, or to apply OAuth policies. @@ -50,24 +56,26 @@ Service-to-service invocation middleware components apply to all **outgoing** ca Diagram showing the flow of a service invocation request. Requests from the callee Dapr sidecar to the callee application go through the app middleware pipeline as described in the paragraph above. -Any middleware component that can be used as HTTP middleware can also be applied to service-to-service invocation calls as a middleware component using the `appHttpPipeline` configuration. The example below adds the `uppercase` middleware component for all outgoing calls from the Dapr sidecar (target of service invocation) to the application that this configuration is applied to. +Any middleware component that can be used as HTTP middleware can also be applied to service-to-service invocation calls as a middleware component using the `appHttpPipeline` configuration. The example below adds the `routerchecker` middleware component for all outgoing calls from the Dapr sidecar (target of service invocation) to the application that this configuration is applied to. ```yaml apiVersion: dapr.io/v1alpha1 -kind: Configuration +kind: Component metadata: - name: pipeline - namespace: default + name: routerchecker1 spec: - appHttpPipeline: - handlers: - - name: uppercase - type: middleware.http.uppercase + type: middleware.http.routerchecker + version: v1 + metadata: + - name: rule + value: "^[A-Za-z0-9/._-]+$" + - name: pipelineType + value: appHttpPipeline + - name: priority + value: 1 ``` ## Related links - [Learn how to author middleware components]({{< ref develop-middleware.md >}}) -- [Component schema]({{< ref component-schema.md >}}) -- [Configuration overview]({{< ref configuration-overview.md >}}) - [API middleware sample](https://github.com/dapr/samples/tree/master/middleware-oauth-google)