From 788726afc47c20563b63f4e0b8aa1f72bd8078e8 Mon Sep 17 00:00:00 2001 From: Nick Greenfield Date: Wed, 6 Apr 2022 12:51:17 -0700 Subject: [PATCH] Address PR Feedback Signed-off-by: Nick Greenfield --- .../en/operations/resiliency/policies.md | 24 +++++++++++---- .../resiliency/resiliency-overview.md | 27 ++++++++++++----- .../en/operations/resiliency/targets.md | 29 ++++++++++++++----- 3 files changed, 59 insertions(+), 21 deletions(-) diff --git a/daprdocs/content/en/operations/resiliency/policies.md b/daprdocs/content/en/operations/resiliency/policies.md index 1fc31266b..800ab859c 100644 --- a/daprdocs/content/en/operations/resiliency/policies.md +++ b/daprdocs/content/en/operations/resiliency/policies.md @@ -6,7 +6,20 @@ weight: 4500 description: "Configure resiliency policies for timeouts, retries/backoffs and circuit breakers" --- -> Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first enable the resiliency preview feature. +Resiliency is currently a preview feature. Before you can utilize a resiliency spec, you must first [enable the resiliency preview feature]({{< ref preview-features >}}). + +#### Enablethe resiliency: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: featureconfig +spec: + features: + - name: Resiliency + enabled: true +``` ### Policies @@ -19,8 +32,9 @@ Timeouts can be used to early-terminate long-running operations. If you've excee - The operation in progress will be terminated (if possible). - An error is returned. -Valid values are of the form `15s`, `2m`, `1h30m`, etc. For example: +Valid values are of the form `15s`, `2m`, `1h30m`, etc. +Example: ```yaml spec: policies: @@ -51,8 +65,7 @@ if BackOffDuration > maxInterval { } ``` -Example definitions: - +Example: ```yaml spec: policies: @@ -79,9 +92,10 @@ Circuit breakers (CBs) policies are used when other applications/services/compon | `interval` | The cyclical period of time used by the CB to clear its internal counts. If set to 0 seconds, this will never clear. Defaults to `0s`. | | `timeout` | The period of the open state (directly after failure) until the CB switches to half-open. Defaults to `60s`. | | `trip` | A Common Expression Language (CEL) statement that is evaluated by the CB. When the statement evaluates to true, the CB trips and becomes open. Default is `consecutiveFailures > 5`. | +| `circuitBreakerScope` | Specify whether circuit breaking state should be scoped to an individual actor ID, all actors across the actor type, or both. Possible values include `id`, `type`, or `both`| +| `circuitBreakerCacheSize` | Specify a cache size for the number of circuit breakers to keep in memory. Prvovide an integer value, for example `5000`. | Example: - ```yaml spec: policies: diff --git a/daprdocs/content/en/operations/resiliency/resiliency-overview.md b/daprdocs/content/en/operations/resiliency/resiliency-overview.md index 3a015971f..0bab55b26 100644 --- a/daprdocs/content/en/operations/resiliency/resiliency-overview.md +++ b/daprdocs/content/en/operations/resiliency/resiliency-overview.md @@ -6,7 +6,20 @@ weight: 4500 description: "Configure Dapr retries, timeouts, and circuit breakers" --- -> Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first [enable the resiliency preview feature]({{< ref preview-features >}}). +Resiliency is currently a preview feature. Before you can utilize a resiliency spec, you must first [enable the resiliency preview feature]({{< ref preview-features >}}). + +#### Enable resiliency: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: featureconfig +spec: + features: + - name: Resiliency + enabled: true +``` ## Introduction @@ -14,13 +27,13 @@ Distributed applications are commonly comprised of many moving pieces, with doze ## Overview -Dapr provides a mechanism for defining and applying fault tolerance/resiliency policies via a [resiliency spec]({{< ref "resiliency-overview.md#complete-example-policy" >}}). The resiliency spec is defined in the same location as components and is applied when the Dapr sidecar starts. The sidecar determines when and how to apply resiliency policies to your Dapr API calls. Within the resiliency spec, you can define policies for popular resiliency patterns, such as: +Dapr provides a mechanism for defining and applying fault tolerance/resiliency policies via a [resiliency spec]({{< ref "resiliency-overview.md#complete-example-policy" >}}). The resiliency spec is defined in the same location as components and is applied when the Dapr sidecar starts. The sidecar determines when and how to apply resiliency policies to your Dapr API calls. In self-hosted mode, the resiliency spec must be named `resiliency.yaml`. In Kubernetes Dapr scans all resiliency specs. Within the resiliency spec, you can define policies for popular resiliency patterns, such as: - [Timeouts]({{< ref "policies.md#timeouts" >}}) - [Retries/back-offs]({{< ref "policies.md#retries" >}}) - [Circuit breakers]({{< ref "policies.md#circuit-breakers" >}}) -Policies can then be applied consistently to [targets]({{< ref "targets.md" >}}), which include: +Policies can then be applied to [targets]({{< ref "targets.md" >}}), which include: - [Apps]({{< ref "targets.md#apps" >}}) via service invocation - [Components]({{< ref "targets.md#components" >}}) @@ -34,7 +47,7 @@ Below is the general structure of a resiliency policy: apiVersion: dapr.io/v1alpha1 kind: Resiliency metadata: - name: resiliency + name: myresiliency scopes: # optionally scope the policy to specific apps spec: @@ -59,15 +72,13 @@ spec: # components and their applied policies here ``` -> Note: In self-hosted mode, the resiliency policy must be named `resiliency.yaml` and reside in the components folder provided to the sidecar. In Kubernetes, resiliency policies are global and a named policy if loaded by the applications's sidecar . - ### Complete Example Policy ```yaml apiVersion: dapr.io/v1alpha1 kind: Resiliency metadata: - name: resiliency + name: myresiliency # simialrly to Subscriptions and Configurations specs, scopes lists the Dapr App IDs that this # configuration applies to. scopes: @@ -140,7 +151,7 @@ spec: # circuit breakers for actors are scoped by type, id, or both. # when a breaker is tripped, that type or id is removed from the placement table for the configured `timeout` duration. circuitBreaker: simpleCB - circuitBreakerScope: both + circuitBreakerScope: both ## circuitBreakerCacheSize: 5000 components: diff --git a/daprdocs/content/en/operations/resiliency/targets.md b/daprdocs/content/en/operations/resiliency/targets.md index ec45f5934..fa98d08c6 100644 --- a/daprdocs/content/en/operations/resiliency/targets.md +++ b/daprdocs/content/en/operations/resiliency/targets.md @@ -3,10 +3,23 @@ type: docs title: "Targets" linkTitle: "Targets" weight: 4500 -description: "Apply resiliency policies for apps, components and actors" +description: "Apply resiliency policies to apps, components and actors" --- -> Resiliency is currently a preview feature. Before you can utilize resiliency policies, you must first enable the resiliency preview feature. +Resiliency is currently a preview feature. Before you can utilize a resiliency spec, you must first [enable the resiliency preview feature]({{< ref preview-features >}}). + +#### Enablethe resiliency: + +```yaml +apiVersion: dapr.io/v1alpha1 +kind: Configuration +metadata: + name: featureconfig +spec: + features: + - name: Resiliency + enabled: true +``` ### Targets Named policies are applied to targets. Dapr supports 3 target types that cover all Dapr building blocks, except observability: @@ -14,13 +27,13 @@ Named policies are applied to targets. Dapr supports 3 target types that cover a - `components` - `actors` -Resilient behaviors might differ between target types, as some targets may already include resilient capabilities; for example, service invocation with built-in retries. +Fault tolerance behaviors might differ between target types, as some targets may already include resilient capabilities; for example, [service invocation with built-in retries]({{< ref "service-invocation-overview.md#retries" >}}). #### Apps -Diagram showing service invocation resiliency +With the `apps` target, you can apply `retry`, `timeout`, and `circuitBreaker` policies to service invocation calls between Dapr apps. Under `targets/apps`, policies are applied to each target service's `app-id`. The policies are invoked when a network failure occurs in communication between sidecars (as pictured in the diagram above). -With the `apps` target, you can apply `retry`, `timeout`, and `circuitBreaker` policies to service invocation calls between Dapr apps. Under `targets/apps`, policies are applied to each key or target service's `app-id` listed when network failure occurs between sidecar communication (as pictured in the diagram above). +Diagram showing service invocation resiliency Example of policies to a target app with the `app-id` "appB": @@ -38,7 +51,7 @@ specs: #### Components -With the `components` target, you can apply `retry`, `timeout` and `circuitBreaker` policies to components operations. Policy assignments are optional. +With the `components` target, you can apply `retry`, `timeout` and `circuitBreaker` policies to component operations. Policies can be applied for `outbound` operations (calls to the Dapr sidecar) and/or `inbound` (the sidecar calling your app). At this time, *inbound* only applies to PubSub and InputBinding components. @@ -52,7 +65,7 @@ Policies can be applied for `outbound` operations (calls to the Dapr sidecar) an Diagram showing service invocation resiliency -Some components have built-in `retry` capabilities and are configured on a per-component basis. +Some components have built-in `retry` capabilities and are configured on a per-component basis. ```yaml spec: @@ -68,7 +81,7 @@ spec: `inbound` operations are calls from the sidecar to your application, such as: -- Subscribing to a topic. +- Subscriptions when delivering a message. - Inbound bindings. Diagram showing service invocation resiliency