From 85bd965c567b2e89e3e2f8946f8d58456be851a3 Mon Sep 17 00:00:00 2001 From: Frank Budinsky Date: Fri, 28 Apr 2017 15:12:12 -0400 Subject: [PATCH] traffic management doc improvements (#80) * request timeout task * traffic management docs improvements * address review comments --- .../traffic-management/fault-injection.md | 2 + .../traffic-management/handling-failures.md | 13 +- _docs/concepts/traffic-management/overview.md | 2 +- .../{service-model.md => request-routing.md} | 2 +- .../traffic-management/rules-configuration.md | 120 ++++++++++++++++- _docs/tasks/request-timeouts.md | 125 ++++++++++++++++++ .../timeouts-retries-circuit-breakers.md | 37 ------ 7 files changed, 254 insertions(+), 47 deletions(-) rename _docs/concepts/traffic-management/{service-model.md => request-routing.md} (99%) create mode 100644 _docs/tasks/request-timeouts.md delete mode 100644 _docs/tasks/timeouts-retries-circuit-breakers.md diff --git a/_docs/concepts/traffic-management/fault-injection.md b/_docs/concepts/traffic-management/fault-injection.md index 7b8434b38a..031f681cf5 100644 --- a/_docs/concepts/traffic-management/fault-injection.md +++ b/_docs/concepts/traffic-management/fault-injection.md @@ -33,3 +33,5 @@ injected: delays and aborts. Delays are timing failures, mimicking increased network latency, or an overloaded upstream service. Aborts are crash failures that mimick failures in upstream services. Aborts usually manifest in the form of HTTP error codes, or TCP connection failures. + +Refer to [Istio's traffic management rules](./rules-configuration.html) for more details. \ No newline at end of file diff --git a/_docs/concepts/traffic-management/handling-failures.md b/_docs/concepts/traffic-management/handling-failures.md index 8f325a6989..fb54751f4a 100644 --- a/_docs/concepts/traffic-management/handling-failures.md +++ b/_docs/concepts/traffic-management/handling-failures.md @@ -21,7 +21,7 @@ include: instance in the load balancing pool These features can be dynamically configured at runtime through -[Istio's traffic management rules](../tasks/timeouts-retries-circuit-breakers.html). +[Istio's traffic management rules](./rules-configuration.html). The jitter between retries minimizes the impact of retries on an overloaded upstream service, while timeout budgets ensure that the calling service @@ -41,9 +41,14 @@ and prevent localized failures from cascading instability to other nodes. Istio's traffic management rules allow operators to set global defaults for failure recovery per -service/version. However, consumers of a service can override these -defaults by providing -[request-level overrides through special HTTP headers](../tasks/timeouts-retries-circuit-breakers.html). +service/version. However, consumers of a service can also override +[timeout](/docs/reference/api/proxy-config.html#istio.proxy.v1alpha.config.HTTPTimeout.SimpleTimeoutPolicy) +and +[retry](/docs/reference/api/proxy-config.html#istio.proxy.v1alpha.config.HTTPRetry.SimpleRetryPolicy) +defaults by providing request-level overrides through special HTTP headers. +With the Envoy proxy implmentation, the headers are "x-envoy-upstream-rq-timeout-ms" and +"x-envoy-max-retries", respectively. + ## FAQ diff --git a/_docs/concepts/traffic-management/overview.md b/_docs/concepts/traffic-management/overview.md index 625b58983b..2c6c06c22d 100644 --- a/_docs/concepts/traffic-management/overview.md +++ b/_docs/concepts/traffic-management/overview.md @@ -33,7 +33,7 @@ before beginning a canary deployment. Decoupling traffic flow from infrastructure scaling allows Istio to provide a variety of traffic management features that reside outside the application code. Features include dynamic -[request routing](../tasks/request-routing.html) for A/B testing, canary releases, +[request routing](./request-routing.html) for A/B testing, canary releases, gradual rollouts, etc., [failure recovery](./handling-failures.html) using timeouts, retries, circuit breakers, and finally [fault injection](./fault-injection.html) to test compatibility of diff --git a/_docs/concepts/traffic-management/service-model.md b/_docs/concepts/traffic-management/request-routing.md similarity index 99% rename from _docs/concepts/traffic-management/service-model.md rename to _docs/concepts/traffic-management/request-routing.md index 5139f45535..2962ed015a 100644 --- a/_docs/concepts/traffic-management/service-model.md +++ b/_docs/concepts/traffic-management/request-routing.md @@ -1,5 +1,5 @@ --- -title: Service Model +title: Request Routing overview: Describes how services are modeled within the Istio mesh, the notion of multiple versions of a service, and the communication model between services. order: 20 diff --git a/_docs/concepts/traffic-management/rules-configuration.md b/_docs/concepts/traffic-management/rules-configuration.md index eaa6a4d56f..2993258a10 100644 --- a/_docs/concepts/traffic-management/rules-configuration.md +++ b/_docs/concepts/traffic-management/rules-configuration.md @@ -16,7 +16,7 @@ services in the application deployment. The DSL allows the operator to configure service-level properties such as circuit breakers, timeouts, retries, as well as set up common continuous deployment tasks such as canary rollouts, A/B testing, staged rollouts with %-based traffic splits, -etc. See routing rules reference for detailed information. _link TBD_ +etc. See [routing rules reference](/docs/reference/api/proxy-config.html) for detailed information. For example, a simple rule to send 100% of incoming traffic for a "reviews" service to version "v1" can be described using the Rules DSL as @@ -35,9 +35,9 @@ routed. In a Kubernetes deployment of Istio, the route *tag* "version: v1" corresponds to a Kubernetes *label* "version: v1". The rule ensures that only Kubernetes pods containing the label "version: v1" will receive traffic. Rules can be configured using the -[istioctl CLI](../reference/istioctl.html). See -[configuring request routing](../tasks/request-routing.html) section for -more information and examples. +[istioctl CLI](/docs/reference/istioctl.html). See the +[configuring request routing task](/docs/tasks/request-routing.html) for +examples. There are two types of rules in Istio, **Routes** and **Destination Policies** (these are not the same as Mixer policies). Both types of rules @@ -148,6 +148,99 @@ route: weight: 75 ``` +### Timeouts and Retries + +By default, the timeout for http requests is 15 seconds, +but this can be overridden in a route rule as follows: + +```yaml +destination: "ratings.default.svc.cluster.local" +route: +- tags: + version: v1 +httpReqTimeout: + simpleTimeout: + timeoutSeconds: 10 +``` + +The number of retries for a given http request can also be specified in a route rule. +The maximum number of attempts, or as many as possible within the default or overriden timeout period, +can be set as follows: + +```yaml +destination: "ratings.default.svc.cluster.local" +route: +- tags: + version: v1 +httpReqRetries: + simpleRetry: + attempts: 3 +``` + +Note that request timeouts and retries can also be +[overridden on a per-request basis](https://istio.io/docs/concepts/traffic-management/handling-failures.html#fine-tuning). + +See the [request timeouts task](/docs/tasks/request-timeouts.html) for a demonstration of timeout control. + +### Injecting faults in the request path + +A route rule can specify one or more faults to inject +while forwarding http requests to the rule's corresponding request destination. +The faults can be either delays or aborts. + +The following example will introduce a 5 second delay in 10% of the requests to the "v1" version of the "reviews" microservice. + +```yaml +destination: reviews.default.svc.cluster.local +route: +- tags: + version: v1 +httpFault: + delay: + percent: 10 + fixedDelaySeconds: 5 +``` + +The other kind of fault, abort, can be used to prematurely terminate a request, +for example, to simulate a failure. + +The following example will return an HTTP 400 error code for 10% +of the requests to the "ratings" service "v1". + +```yaml +destination: "ratings.default.svc.cluster.local" +route: +- tags: + version: v1 +httpFault: + abort: + percent: 10 + httpStatus: 400 +``` + +Sometimes delays and abort faults are used together. For example, the following rule will delay +by 5 seconds all requests from the "reviews" service "v2" to the "ratings" service "v1" and +then abort 10 percent of them: + +```yaml +destination: ratings.default.svc.cluster.local +match: + source: reviews.default.svc.cluster.local + sourceTags: + version: v2 +route: +- tags: + version: v1 +httpFault: + delay: + fixedDelaySeconds: 5 + abort: + percent: 10 + httpStatus: 400 +``` + +To see fault injection in action, see the [fault injection task](/docs/tasks/fault-injection.html). + ### Rules have precedence Multiple route rules could be applied to the same destination. The order of @@ -232,6 +325,25 @@ tags: loadBalancing: RANDOM ``` +### Circuit Breakers + +A simple circuit breaker can be set based on a number of criteria such as connection and request limits. + +For example, the following destination policy +sets a limit of 100 connections to "reviews" service version "v1" backends. + +```yaml +destination: reviews.default.svc.cluster.local +tags: + version: v1 +circuitBreaker: + simpleCb: + maxConnections: 100 +``` + +The complete set of simple circuit breaker fields can be found +[here](/docs/reference/api/proxy-config.html#istio.proxy.v1alpha.config.CircuitBreaker.SimpleCircuitBreakerPolicy). + ### Destination Policy evaluation Similar to route rules, destination policies are associated with a diff --git a/_docs/tasks/request-timeouts.md b/_docs/tasks/request-timeouts.md new file mode 100644 index 0000000000..ee9b3aa8bd --- /dev/null +++ b/_docs/tasks/request-timeouts.md @@ -0,0 +1,125 @@ +--- +title: Request Timeouts +overview: This task shows you how to setup request timeouts in Envoy using Istio. + +order: 40 + +bodyclass: docs +layout: docs +type: markdown +--- + +This task shows you how to setup request timeouts in Envoy using Istio. + + +## Before you begin + +* Setup Istio by following the instructions in the + [Installation guide](/docs/tasks/installing-istio.html). + +* Deploy the [bookinfo](/docs/samples/bookinfo.html) sample application. + +* Initialize the application version routing by running the following command: + + ```bash + $ istioctl create -f route-rule-all-v1.yaml + ``` + +## Request timeouts + +A timeout for http requests can be specified using the *httpReqTimeout* field of a routing rule. +By default, the timeout is 15 seconds, but in this task we'll override the `reviews` service +timeout to 1 second. +To see its effect, however, we'll also introduce an artificial 2 second delay in calls +to the `ratings` service. + +1. Route requests to v2 of the `reviews` service, i.e., a version that calls the `ratings` service + + ```bash + $ cat <