route

Summary

Routes match the URI portion of the incoming request and route traffic to different shared_rules. This allows requests to routes like /api/v1 and /api/v2 to end up at entirely different hosts if desired. The routes objects support matching, prefix rewriting, and redirection of requests.

Example Object

{
  "zone_key": "default",
  "domain_key": "fibonacci",
  "route_key": "fibonacci-route",
  "path": "/",
  "prefix_rewrite": null,
  "redirects": null,
  "shared_rules_key": "",
  "rules": [
    {
      "rule_key": "default",
      "constraints": {
        "light": [
          {
            "constraint_key": "",
            "cluster_key": "fibonacci-service",
            "metadata": null,
            "properties": null,
            "response_data": {},
            "weight": 1
          }
        ],
        "dark": null,
        "tap": null
      }
    }
  ],
  "response_data": {},
  "cohort_seed": null,
  "retry_policy": {
    "num_retries": 3
  },
  "request_headers_to_add" : [],
  "request_headers_to_remove" : [],
  "response_headers_to_add" : [],
  "response_headers_to_remove" : []
}

Features

• Path matching

• Prefix Rewriting

• Redirect

• Routing Rules

• Retry Policies

See the routing documentation for an explanation of all of the routing features and how to set them.

Envoy Reference

• Envoy Route Reference

Fields

route_key

A unique key to identify this route configuration in the Fabric API.

domain_key

String domain key to specify which domain object this route should attach to.

zone_key

The zone in which this object will live. It will only be able to be referenced by objects or sent to Sidecars that live in the same zone.

path

DEPRECATION: This field has been deprecated and will be removed in the next major version release. Use route_match instead.

Explicit path string to match on. E.g. "/services/catalog/" or "/apps/ui/".

route_match

Route match to match against incoming requests.

prefix_rewrite

When a match is found using the values configured in route_match, the value of the :path header on the request will be replaced with this value for forwarding.

redirects

This field can be used to configure redirect routes for the domain. See Redirect for details.

Fields:

• name

  • the name of the redirect

• from

  • regex value that the incoming request :path will be regex matched to

• to

  • the new URL that an incoming request matching from will route to

  • if set to "$host", will redirect to the name of the domain

• redirect_type

  • determines the response code of the redirect

  • must be one of: "permanent" (for a 301 code), "temporary" (for a 307 code)

• header_constraints

  • a list of header constraint objects

  • each header constraint has the following fields:

    • name

      • the header key to be compared to the incoming requests headers

      • will be compared without case sensitivity

    • value

      • must be a valid regex

      • the value to be compared to the value of the incoming request header with matching name

    • case_sensitive

      • boolean indicating whether the value will be compared to the value of the header with matching name with case sensitivity

    • invert

      • boolean value

shared_rules_key

Indicates the key of the shared_rules object to use for specifying a default cluster to forward to.

This field may be omitted if rules are defined directly.

rules

A list of rules to specify various more complex route matching and forwarding specifications.

response_data

A collection of annotations that should be applied to responses when handling a request. Configuration

cohort_seed

This field has no effect.

retry_policy

A retry_policy that controls how this route will handle automatic retries to upstream clusters and govern timeouts.

high_priority

Defaults to false, which indicates this is normal traffic. If set to true, routes are considered high priority which allows different handling of the request.

filter_metadata

A map from string to metadata that can be used to provide virtual host-specific configurations for filters. See the per route filter configuration guide for info on setting this up.

request_headers_to_add

Specifies a set of headers that will be added to requests matching this route.

E.g.

"request_headers_to_add" : [
  {
    "key": "x-forwarded-proto",
    "value": "https"
  }
]

request_headers_to_remove

Specifies a list of HTTP headers that should be removed from each request matching this route.

E.g.

"request_headers_to_remove" : [
  "request-header1",
  "request-header2",
]

response_headers_to_add

Specifies a set of headers that will be added to responses matching this route.

E.g.

"response_headers_to_add" : [
  {
    "key": "x-forwarded-proto",
    "value": "https"
  }
]

response_headers_to_remove

Specifies a list of HTTP headers that should be removed from each response matching this route.

E.g.

"response_headers_to_remove" : [
  "response-header1",
  "response-header2",
]

checksum

An API calculated checksum. Can be used to verify that the API contains the expected object before performing a write.