Routing Rules

RouteRule

Glossary & concepts

Service is a unit of an application with a unique name that other services use to refer to the functionality being called. Service instances are pods/VMs/containers that implement the service.

Service versions - In a continuous deployment scenario, for a given service, there can be multiple sets of instances running potentially different variants of the application binary. These variants are not necessarily different API versions. They could be iterative changes to the same service, deployed in different environments (prod, staging, dev, etc.). Common scenarios where this occurs include A/B testing, canary rollouts, etc. The choice of a particular version can be decided based on various criterion (headers, url, etc.) and/or by weights assigned to each version. Each service has a default version consisting of all its instances.

Source - downstream client (browser or another service) calling the Envoy proxy/sidecar (typically to reach another service).

Destination - The remote upstream service to which the Envoy proxy/sidecar is talking to, on behalf of the source service. There can be one or more service versions for a given service (see the discussion on versions above). Envoy would choose the version based on various routing rules.

Access model - Applications address only the destination service without knowledge of individual service versions. The actual choice of the version is determined by Envoy, enabling the application code to decouple itself from the evolution of dependent services.

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:

apiVersion: config.istio.io/v1alpha2
kind: RouteRule
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

IstioService

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

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

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

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

StringMatch

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

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

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

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.

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

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.

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

HTTPTimeout

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

SimpleTimeoutPolicy

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.

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

SimpleRetryPolicy

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.

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

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

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.