istio
/
istio.io
mirror of https://github.com/istio/istio.io.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
istio.io/_docs/reference/api/traffic-rules/routing-rules.md

18 KiB
Raw Blame History

title overview order layout type
Routing Rules Generated documentation for Istio's traffic routing rules 20 docs markdown

Index

RouteRule

Route rule provides a custom routing policy based on the source and destination service versions and connection/request metadata. The rule must provide a set of conditions for each protocol (TCP, UDP, HTTP) that the destination service exposes on its ports.

The rule applies only to the ports on the destination service for which it provides protocol-specific match condition, e.g. if the rule does not specify TCP condition, the rule does not apply to TCP traffic towards the destination service.

For example, a simple rule to send 100% of incoming traffic for a "reviews" service to version "v1" can be specified as follows:

destination: reviews.default.svc.cluster.local
route:
- tags:
    version: v1
  weight: 100
Field Type Description
destination string REQUIRED: Destination uniquely identifies the destination associated with this routing rule. This field is applicable for hostname-based resolution for HTTP traffic as well as IP-based resolution for TCP/UDP traffic. The value MUST BE a fully-qualified domain name, e.g. "my-service.default.svc.cluster.local".
precedence int32 RECOMMENDED. Precedence is used to disambiguate the order of application of rules for the same destination service. A higher number takes priority. If not specified, the value is assumed to be 0. The order of application for rules with the same precedence is unspecified.
match MatchCondition Match condtions to be satisfied for the route rule to be activated. If match is omitted, the route rule applies only to HTTP traffic.
route[] repeated DestinationWeight REQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The forwarding target can be one of several versions of a service (see glossary in beginning of document). Weights associated with the service version determine the proportion of traffic it receives.
redirect HTTPRedirect REQUIRED (route|redirect). A routing rule can either redirect traffic or forward traffic. The redirect primitive can be used to send a HTTP 302 redirect to a different URI or Authority.
rewrite HTTPRewrite Rewrite HTTP URIs and Authority headers. Rewrite cannot be used with Redirect primitive. Rewrite will be performed before forwarding.
httpReqTimeout HTTPTimeout Timeout policy for HTTP requests.
httpReqRetries HTTPRetry Retry policy for HTTP requests.
httpFault HTTPFaultInjection Fault injection policy to apply on HTTP traffic

MatchCondition

Match condition specifies a set of criterion to be met in order for the route rule to be applied to the connection or HTTP request. The condition provides distinct set of conditions for each protocol with the intention that conditions apply only to the service ports that match the protocol. For example, the following route rule restricts the rule to match only requests originating from "reviews:v2", accessing ratings service where the URL path starts with /ratings/v2/ and the request contains a "cookie" with value "user=jason",

destination: ratings.default.svc.cluster.local
match:
  source: reviews.default.svc.cluster.local
  sourceTags:
    version: v2
  httpHeaders:
    cookie:
      regex: "^(.*?;)?(user=jason)(;.*)?$"
    uri:
      prefix: "/ratings/v2/"

MatchCondition CANNOT BE empty. Atleast one of source, sourceTags or httpHeaders must be specified.

Field Type Description
source string Identifies the service initiating a connection or a request by its name. If specified, name MUST BE a fully qualified domain name such as foo.bar.com
sourceTags repeated map<string, string> One or more tags that uniquely identify the source service version. In Kubernetes, tags correspond to the labels associated with pods.
httpHeaders repeated map<string, StringMatch>

Set of HTTP match conditions based on HTTP/1.1, HTTP/2, GRPC request metadata, such as uri, scheme, authority. The header keys must be lowercase and use hyphen as the separator, e.g. x-request-id.

Note 1: The keys uri, scheme, method, and authority correspond to URI, protocol scheme (e.g., HTTP, HTTPS), HTTP method (e.g., GET, POST), and the HTTP Host header respectively.

Note 2: uri can be used to perform URL matches. For URL matches (Uri_), only prefix and exact (see StringMatch) matches are supported. For other HTTP headers, exact, prefix and ECMA style regular expression matches are supported.

StringMatch

Describes how to match a given string in HTTP headers. Match is case-sensitive.

Field Type Description
exact string (oneof ) exact string match
prefix string (oneof ) prefix-based match
regex string (oneof ) ECMAscript style regex-based match

DestinationWeight

Each routing rule is associated with one or more service versions (see glossary in beginning of document). Weights associated with the version determine the proportion of traffic it receives. For example, the following rule will route 25% of traffic for the "reviews" service to instances with the "v2" tag and the remaining traffic (i.e., 75%) to "v1".

destination: reviews.default.svc.cluster.local
route:
- tags:
    version: v2
  weight: 25
- tags:
    version: v1
  weight: 75
Field Type Description
destination string Destination uniquely identifies the destination service. If not specified, the value is inherited from the parent route rule. Value must be in fully qualified domain name format (e.g., "my-service.default.svc.cluster.local").
tags repeated map<string, string> Service version identifier for the destination service.
weight int32 REQUIRED. The proportion of traffic to be forwarded to the service version. (0-100). Sum of weights across destinations SHOULD BE == 100. If there is only destination in a rule, the weight value is assumed to be 100.

HTTPRedirect

HTTPRedirect can be used to send a 302 redirect response to the caller, where the Authority/Host and the URI in the response can be swapped with the specified values. For example, the following route rule redirects requests for /v1/getProductRatings API on the ratings service to /v1/bookRatings provided by the bookratings service.

destination: ratings.default.svc.cluster.local
match:
  httpHeaders:
    uri:
     exact: /v1/getProductRatings
redirect:
  uri: /v1/bookRatings
  authority: bookratings.default.svc.cluster.local
Field Type Description
uri string On a redirect, overwrite the Path portion of the URL with this value. Note that the entire path will be replaced, irrespective of the request URI being matched as an exact path or prefix.
authority string On a redirect, overwrite the Authority/Host portion of the URL with this value

HTTPRewrite

HTTPRewrite can be used to rewrite specific parts of a HTTP request before forwarding the request to the destination. Rewrite primitive can be used only with the DestinationWeights. The following example demonstrates how to rewrite the URL prefix for api call (/ratings) to ratings service before making the actual API call.

destination: ratings.default.svc.cluster.local
match:
  httpHeaders:
    uri:
     prefix: /ratings
rewrite:
  uri: /v1/bookRatings
route:
  - tags:
      version: v1
Field Type Description
uri string rewrite the Path (or the prefix) portion of the URI with this value. If the original URI was matched based on prefix, the value provided in this field will replace the corresponding matched prefix.
authority string rewrite the Authority/Host header with this value.

HTTPTimeout

Describes HTTP request timeout. For example, the following rule sets a 10 second timeout for calls to the ratings:v1 service

destination: ratings.default.svc.cluster.local
route:
- tags:
    version: v1
  httpReqTimeout:
    simpleTimeout:
      timeout: 10s
Field Type Description
simpleTimeout SimpleTimeoutPolicy

SimpleTimeoutPolicy

Field Type Description
timeout Duration REQUIRED. Timeout for a HTTP request. Includes retries as well. Default 15s. format: 1h/1m/1s/1ms. MUST BE >=1ms. It is possible to control timeout per request by supplying the timeout value via x-envoy-upstream-rq-timeout-ms HTTP header.

HTTPRetry

Describes the retry policy to use when a HTTP request fails. For example, the following rule sets the maximum number of retries to 3 when calling ratings:v1 service, with a 2s timeout per retry attempt.

destination: ratings.default.svc.cluster.local
route:
- tags:
    version: v1
  httpReqRetries:
    simpleRetry:
      attempts: 3
      perTryTimeout: 2s
Field Type Description
simpleRetry SimpleRetryPolicy

SimpleRetryPolicy

Field Type Description
attempts int32 REQUIRED. Number of retries for a given request. The interval between retries will be determined automatically (25ms+). Actual number of retries attempted depends on the httpReqTimeout.
perTryTimeout Duration Timeout per retry attempt for a given request. format: 1h/1m/1s/1ms. MUST BE >=1ms.

HTTPFaultInjection

HTTPFaultInjection can be used to specify one or more faults to inject while forwarding http requests to the destination specified in the route rule. Fault specification is part of a route rule. Faults include aborting the Http request from downstream service, and/or delaying proxying of requests. A fault rule MUST HAVE delay or abort or both.

Note: Delay and abort faults are independent of one another, even if both are specified simultaneously.

Field Type Description
delay Delay Delay requests before forwarding, emulating various failures such as network issues, overloaded upstream service, etc.
abort Abort Abort Http request attempts and return error codes back to downstream service, giving the impression that the upstream service is faulty.

Abort

Abort specification is used to prematurely abort a request with a pre-specified error code. The following example will return an HTTP 400 error code for 10% of the requests to the "ratings" service "v1".

destination: ratings.default.svc.cluster.local
route:
- tags:
    version: v1
httpFault:
  abort:
    percent: 10
    httpStatus: 400

The HttpStatus_ field is used to indicate the HTTP status code to return to the caller. The optional Percent_ field, a value between 0 and 100, is used to only abort a certain percentage of requests. If not specified, all requests are aborted.

Field Type Description
percent float percentage of requests to be aborted with the error code provided (0-100).
httpStatus int32 REQUIRED. HTTP status code to use to abort the Http request.

Delay

Delay specification is used to inject latency into the request forwarding path. The following example will introduce a 5 second delay in 10% of the requests to the "v1" version of the "reviews" service.

destination: reviews.default.svc.cluster.local
route:
- tags:
    version: v1
httpFault:
  delay:
    percent: 10
    fixedDelay: 5s

The FixedDelay_ field is used to indicate the amount of delay in seconds. An optional Percent_ field, a value between 0 and 100, can be used to only delay a certain percentage of requests. If left unspecified, all request will be delayed.

Field Type Description
percent float percentage of requests on which the delay will be injected (0-100)
fixedDelay Duration REQUIRED. Add a fixed delay before forwarding the request. Format: 1h/1m/1s/1ms. MUST be >=1ms.