# shared\_rules

## Summary

A `shared_rule` defines a re-usable mapping of traffic between [clusters](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/cluster) and [routes](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/route). This can be very simple, or very complex, depending on the need and the stage of deployment. In it's 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/route) object. When defined inline, they cannot be shared between proxies.

### Features

* Retry Policies
* Traffic Splitting
* Traffic Tap/Shadow

### Example Object

```javascript
{
  "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](https://www.envoyproxy.io/docs/envoy/v1.15.0/configuration/http/http_conn_man/traffic_splitting)
* [Weighted Routing](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/route/v3/route_components.proto#config-route-v3-weightedcluster)
* [Retry Policy](https://www.envoyproxy.io/docs/envoy/v1.15.0/intro/arch_overview/http/http_routing#arch-overview-http-routing-retry)

### 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_rules) 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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_rules).

```javascript
"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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/shared_rules) See [response data](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/route/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](https://greymatter.gitbook.io/grey-matter-documentation/1.3/reference/api/fabric-api/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.