# proxy

## Summary

Each `proxy` is the sum total of all configurations that will be sent to each Grey Matter Proxy. This includes the [`listeners`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener), [`domains`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/domain), [`routes`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/route), [`shared_rules`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/shared_rules), and [`clusters`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/cluster). Each `proxy` object may be mapped to 0 or more physical instances; each of which will share the exact same configurations.

> **NOTE** The `name` field in the object dictates which cluster in the mesh it gets applied to, see the [discovery docs](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/usage/discovery) for more information.

### Features

* Configure active filters
* Set virtual domains
* Directly set listeners

### Multiple Listeners

Multiple listeners can be configured for each Proxy object, either inline or through the `listener_keys` field. Each one defines a new network interface to handle different traffic patterns and protocols, like the example diagram below.

![](https://3431003532-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-LsNFVozLgvw3NDMzxBg-1847203797%2Fuploads%2Fgit-blob-4165d3d0a963b3c59ac6a26d1a07a18077026eea%2Fmulti-listener.jpg?alt=media)

How each Sidecar is configured to listen on the network comes from both both the [domains](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/domain) and [listeners](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener). These objects are linked to a specific proxy using the [`domain_keys`](#domain_keys), [`listener_keys`](#listener_keys), and [`listeners`](#listeners) fields below.

A listener is created for the sidecar on the [`port`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/domain#port) of every [domain](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/domain) specified in [`domain_keys`](#domain_keys). If there are no referenced [listeners](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener) on the same [`port`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/listener#port), a default `listener` object is used with [IP](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/listener#ip) `0.0.0.0`. Otherwise, every domain/listener on the same port combine to configure the sidecar's listener at that port and the IP of the listener.

> NOTE: In a SPIFFE/SPIRE installation, to enable ingress traffic to the sidecar, a [listener object](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener) **must** be configured for the proxy on the ingress port. The only way to configure SSL for a listener with SPIRE is using the [`secret`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener/secret).

### Example Object

```javascript
{
  "proxy_key": "catalog",
  "zone_key": "default",
  "name": "catalog",
  "domain_keys": [
    "catalog-domain"
  ],
  "listener_keys": [
    "catalog-listener"
  ],
  "listeners": null,
  "upgrades": "",
  "active_proxy_filters": [
    "gm.metrics",
    "gm.observables"
  ],
  "proxy_filters": {
    "envoy_rbac": null,
    "gm_impersonation": {},
    "gm_inheaders": {},
    "gm_listauth": {},
    "gm_metrics": {
      "metrics_port": 8081,
      "metrics_host": "0.0.0.0",
      "metrics_dashboard_uri_path": "/metrics",
      "metrics_prometheus_uri_path": "/prometheus",
      "prometheus_system_metrics_interval_seconds": 15,
      "metrics_ring_buffer_size": 4096,
      "metrics_key_function": "depth",
      "metrics_key_depth": "1"
    },
    "gm_oauth": {},
    "gm_observables": {
      "useKafka": true,
      "topic": "production-catalog-1.0",
      "eventTopic": "events",
      "kafkaServerConnection": "kafka-observables.observables.svc:9092"
    }
  },
  "checksum": "9830e988dd93d560426e3ddff6758ca2976565b9e064e68f99661a39b3b17239"
}
```

### Envoy Reference

* [Envoy Filters Reference](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/filter/http/http)

### Fields

#### `proxy_key`

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

#### `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.

#### `name`

The name of the service that this proxy configuration (and all linked objects) will be sent to. This name must exactly match the [service announcement](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/usage/discovery) information when a sidecar registers in the mesh.

#### `domain_keys`

Array of [domain keys](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/domain) to specify which domain objects should be included in this configuration.

#### `listener_keys`

Array of [listener keys](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener) to specify which which objects should be included in this configuration. Listeners can also be specified in-line with the [listeners](#listeners) field.

#### `listeners`

Array of [listener](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener) definitions to create for this Sidecar.

> NOTE: See [Multiple Listeners](#multiple-listeners) for information on how the referenced domains and listeners are used to configure listeners for the sidecar.

#### `upgrades`

String value to specify connection upgrades to all listeners on this Sidecar. The only currently supported option is `"websocket"`.

#### `active_filters`

> DEPRECATION: This field has been deprecated and will be removed in the next major version release. Use [listener.active\_http\_filters](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/listener#active_http_filters) instead.

Array of [http filters](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/filters/http) that should be active on this listener's filter chain. This list acts as a simple mechanism for turning specific filters on/off without needing to completely remove their configuration from the [http\_filter](#httpfilters) section.

> NOTE: The order of filters in this array dictates the evaluation order of the filters in the chain.

#### `filters`

> DEPRECATION: This field has been deprecated and will be removed in the next major version release. Use [listener.http\_filters](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/listener#httpfilters) instead.

Array of filter configurations to be used when a filter is [enabled](#activehttpfilters).

#### `checksum`

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