Summary

A shared_rule defines a re-usable mapping of traffic between clusters and routes. This can be very simple, or very complex, depending on the need and the stage of deployment. In its most simple setup, any given request is just sent to a single cluster. However, traffic can also be fractionally diverted and/or simultaneously shadowed to alternate clusters.

NOTE Some features of the shared_rules object can also be defined in the route object. When defined inline, they cannot be shared between proxies.

Features

• Retry Policies

• Traffic Splitting

• Traffic Tap/Shadow

Example Object

{
  "shared_rules_key": "edge-catalog-shared-rules",
  "name": "catalog",
  "zone_key": "default",
  "default": {
    "light": [
      {
        "constraint_key": "",
        "cluster_key": "catalog-cluster",
        "metadata": null,
        "properties": null,
        "response_data": {},
        "weight": 1
      }
    ]
  },
  "rules": null,
  "response_data": {},
  "cohort_seed": null,
  "properties": null,
  "retry_policy": null
}

Envoy Reference

• ​Traffic Splitting​

• ​Weighted Routing​

• ​Retry Policy​

Fields

shared_rules_key

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

name

The name of the shared rules object. This will become the value of a header with key "shared_rules_key" on all routes linked to this shared rule.

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.

default

The default field defines cluster_constraint arrays that map requests to clusters. Currently, the only implemented field is the light field which is used to determine the Instance to which the live request will be sent and from which the response will be sent to the caller.

Currently, the default field must set a light field that contains an array of cluster_constraints.

"constraints" : {
  "light": [
    {
      "cluster_key": "example-service-1.0",
      "weight": 10
    },
    {
      "cluster_key": "example-service-1.1",
      "weight": 1
    }
  ]
}

NOTE: default also contains a dark and a light field which currently have no effect. dark array will be used in future versions to support traffic shadowing to Instances. Similarly the tap array will determine an Instance to send a copy of the request to, comparing the response to the light response.

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 See response data.

cohort_seed

This field has no effect.

properties

This field has no effect.

retry_policy

Specifies the default retry policy and timeout for any route referencing this shared rule object. Any retry policy set on the route will take precedence over one configured here.

checksum

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