Route Rules Alpha 1

Circuit breaker configuration for Envoy. The circuit breaker implementation is fine-grained in that it tracks the success/failure rates of individual hosts in the load balancing pool. Hosts that continually return errors for API calls are ejected from the pool for a pre-defined period of time. See Envoy’s circuit breaker and outlier detection for more details.

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.

metadata:
  name: reviews-cb-policy
  namespace: default
spec:
  destination:
    name: reviews
    labels:
      version: v1
  circuitBreaker:
    simpleCb:
      maxConnections: 100

The following destination policy sets a limit of 100 connections and 1000 concurrent requests, with no more than 10 req/connection to “reviews” service version “v1” backends. In addition, it configures hosts to be scanned every 5 mins, such that any host that fails 7 consecutive times with 5XX error code will be ejected for 15 minutes.

metadata:
  name: reviews-cb-policy
  namespace: default
spec:
  destination:
    name: reviews
    labels:
      version: v1
  circuitBreaker:
    simpleCb:
      maxConnections: 100
      httpMaxRequests: 1000
      httpMaxRequestsPerConnection: 10
      httpConsecutiveErrors: 7
      sleepWindow: 15m
      httpDetectionInterval: 5m

Describes the Cross-Origin Resource Sharing (CORS) policy, for a given service. Refer to https://developer.mozilla.org/en-US/docs/Web/HTTP/AccesscontrolCORS for further details about cross origin resource sharing. For example, the following rule restricts cross origin requests to those originating from example.com domain using HTTP POST/GET, and sets the Access-Control-Allow-Credentials header to false. In addition, it only exposes X-Foo-bar header and sets an expiry period of 1 day.

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: ratings
  route:
  - labels:
      version: v1
  corsPolicy:
    allowOrigin:
    - example.com
    allowMethods:
    - POST
    - GET
    allowCredentials: false
    allowHeaders:
    - X-Foo-Bar
    maxAge: "1d"

DestinationPolicy defines client/caller-side policies that determine how to handle traffic bound to a particular destination service. The policy specifies configuration for load balancing and circuit breakers. For example, a simple load balancing policy for the ratings service would look as follows:

metadata:
  name: ratings-lb-policy
  namespace: default # optional (default is "default")
spec:
  destination:
    name: ratings
  loadBalancing:
    name: ROUND_ROBIN

The FQDN of the destination service is composed from the destination name and meta namespace fields, along with a platform-specific domain suffix (e.g. on Kubernetes, “reviews” + “default” + “svc.cluster.local” -> “reviews.default.svc.cluster.local”).

A destination policy can be restricted to a particular version of a service or applied to all versions. It can also be restricted to calls from a particular source. For example, the following load balancing policy applies to version v1 of the ratings service running in the prod environment but only when called from version v2 of the reviews service:

metadata:
  name: ratings-lb-policy
  namespace: default
spec:
  source:
    name: reviews
    labels:
      version: v2
  destination:
    name: ratings
    labels:
      env: prod
      version: v1
  loadBalancing:
    name: ROUND_ROBIN

Note: Destination policies will be applied only if the corresponding tagged instances are explicitly routed to. In other words, for every destination policy defined, at least one route rule must refer to the service version indicated in the destination policy.

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

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: reviews
  route:
  - labels:
      version: v2
    weight: 25
  - labels:
      version: v1
    weight: 75

Egress rules describe the properties of a service outside Istio. When transparent proxying is used, egress rules signify a white listed set of external services that microserves in the mesh are allowed to access. A subset of routing rules and all destination policies can be applied on the service targeted by an egress rule. TCP services and HTTP-based services can be expressed by an egress rule. The destination of an egress rule for HTTP-based services must be an IP or a domain name, optionally with a wildcard prefix (e.g., *.foo.com). For TCP based services, the destination of an egress rule must be an IP or a block of IPs in CIDR notation.

If TLS origination from the sidecar is desired, the protocol associated with the service port must be marked as HTTPS, and the service is expected to be accessed over HTTP (e.g., http://gmail.com:443). The sidecar will automatically upgrade the connection to TLS when initiating a connection with the external service.

For example, the following egress rule describes the set of services hosted under the *.foo.com domain

kind: EgressRule
metadata:
  name: foo-egress-rule
spec:
  destination:
    service: *.foo.com
  ports:
    - port: 80
      protocol: http
    - port: 443
      protocol: https

The following egress rule describes the set of services accessed by a block of IPs

kind: EgressRule
metadata:
  name: bar-egress-rule
spec:
  destination:
    service: 92.198.174.192/27
  ports:
    - port: 111
      protocol: tcp

Port describes the properties of a specific TCP port of an external service.

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.

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

metadata:
  name: my-rule
spec:
  destination:
    name: reviews
  route:
  - labels:
      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.

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.

metadata:
  name: my-rule
spec:
  destination:
    name: reviews
  route:
  - labels:
      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.

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.

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: ratings
  match:
    request:
      headers:
        uri: /v1/getProductRatings
  redirect:
    uri: /v1/bookRatings
    authority: bookratings.default.svc.cluster.local

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.

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: ratings
  route:
  - labels:
      version: v1
  httpReqRetries:
    simpleRetry:
      attempts: 3
      perTryTimeout: 2s

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.

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: ratings
  match:
    request:
      headers:
        uri:
          prefix: /ratings
  rewrite:
    uri: /v1/bookRatings
  route:
  - labels:
      version: v1

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

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: ratings
  route:
  - labels:
      version: v1
  httpReqTimeout:
    simpleTimeout:
      timeout: 10s

Ingress rules are routing rules applied to the ingress proxy pool. The ingress proxes serve as the receiving edge proxy for the entire mesh, but can also be addressed from inside the mesh. Each ingress rule defines a destination service and port. Rules that do not resolve to a service or a port in the mesh should be ignored.

The routing rules for the destination service are applied at the ingress proxy. That means the routing rule match conditions are composed and its actions are enforced. The traffic splitting for the destination service is also effective.

WARNING: This API is experimental and under active development

IstioService identifies a service and optionally service version. The FQDN of the service is composed from the name, namespace, and implementation-specific domain suffix (e.g. on Kubernetes, “reviews” + “default” + “svc.cluster.local” -> “reviews.default.svc.cluster.local”).

(– Faults can be injected into the connections from downstream by the Envoy, for testing the failure recovery capabilities of downstream services. Faults include aborting the connection from downstream service, delaying proxying of connection to the destination service, and throttling the bandwidth of the connection (either end). Bandwidth throttling for failure testing should not be confused with the rate limiting policy enforcement provided by the Mixer component. L4 fault injection is not supported at the moment. –)

Abruptly reset (terminate) the Tcp connection after it has been established, emulating remote server crash or link failure.

Bandwidth throttling for Tcp and Udp connections

(– L4 connection match attributes. Note that L4 connection matching support is incomplete. –)

Load balancing policy to use when forwarding traffic. These policies directly correlate to load balancer types supported by Envoy. Example,

metadata:
  name: reviews-lb-policy
  namespace: default
spec:
  destination:
    name: reviews
  loadBalancing:
    name: RANDOM

Load balancing algorithms supported by Envoy.

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”,

metadata:
  name: my-rule
  namespace: default
spec:
  destination:
    name: ratings
  match:
    source:
      name: reviews
      labels:
        version: v2
    request:
      headers:
        cookie:
          regex: "^(.*?;)?(user=jason)(;.*)?"
        uri:
          prefix: "/ratings/v2/"

MatchCondition CANNOT be empty. At least one source or request header must be specified.

MatchRequest specifies the attributes of an HTTP request to be used for matching a request.

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:

metadata:
  name: my-rule
  namespace: default # optional (default is "default")
spec:
  destination:
    name: reviews
    namespace: my-namespace # optional (default is metadata namespace field)
  route:
  - labels:
      version: v1
    weight: 100

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