# zone

Zones are used to group API objects and segment the data plane. Sidecars and Control servers will all run and serve in only a single zone. This doesn't enforce any physical or network isolation, but logically segments the service mesh.

## Example Object

```javascript
{
  "zone_key": "default-zone",
  "zone_name": "zone"
}
```

## API Configuration

Zones can be created using [greymatter create](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/cli/create) or using the Grey Matter Control API directly.

The `zone` must be the first Grey Matter object created in series, followed by [`domain`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/domain), [`cluster`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/cluster), [`listener`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/listener), [`proxy`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/proxy), [`shared_rules`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/shared_rules), and [`route`](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/api/fabric-api/route) (in that order) as each Grey Matter object contains a `zone_key` field, which must reference an existing zone object.

## Bootstrap Configuration

To configure Grey Matter Control API to automatically create a zone on startup, set `GM_CONTROL_API_ZONE_KEY`, `GM_CONTROL_API_ZONE_NAME`, and, optionally, `GM_CONTROL_API_ORG_KEY` and a zone will be created using these values. This allows a bootstrap configuration to reference this `zone_key` immediately.

## Grey Matter Proxy

A Grey Matter Sidecar is run in a single zone, configured with environment variable `XDS_ZONE`. This value should be the name of the zone with the `zone_key` matching its corresponding Grey Matter Control API objects.

Each Envoy proxy set up by the Grey Matter Sidecar has a [Node](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/core/v3/base.proto#config-core-v3-node) specification that identifies it as a specific Envoy instance. A part of this identification is a Node's [locality](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/config/core/v3/base.proto#config-core-v3-locality), which gives the information on "where" the instance is running. This locality has a field `zone`, which is used to indicate this location.

The value of the Node locality's zone is set using this variable, `XDS_ZONE`. This value must also match the `GM_CONTROL_API_ZONE_NAME`, because Control will only retrieve Envoy instances with the locality containing this zone for configuration (see below).

## Grey Matter Control

Grey Matter Control is also run with a single configured zone. It has an environment variable `GM_CONTROL_API_ZONE_NAME`, which is used to indicate both the name of the Grey Matter API zone for requests and the Node locality's zone of its [Discovery Requests](https://www.envoyproxy.io/docs/envoy/v1.15.0/api-v3/service/discovery/v3/discovery.proto#service-discovery-v3-discoveryrequest) to Envoy.

Grey Matter Control will only make requests to Grey Matter Control API in this zone, and only Grey Matter clusters in the API with `zone_key` corresponding to this zone name will be populated with discovered instances.

If `GM_CONTROL_API_ZONE_NAME` does not match the name of the zone corresponding to the `zone_key` on any of the mesh objects, the objects will not be found by gm-control in its requests, thus objects in one `zone` cannot reference objects in a different `zone`.

When Grey Matter Control makes a discovery request to Envoy, it sets the `node.locality.zone` field on its request set to the value of this variable. This value must match `XDS_ZONE` on a service's sidecar, as only Envoy instances with this `zone` in their Node locality will be retrieved from Envoy and configured via Grey Matter Control.

## Example

For the [zone object example created above](#example-object), the proper configuration for a bootstrap setup is as follows:

Grey Matter Control:

* `GM_CONTROL_API_ZONE_NAME=zone`

Grey Matter Control API:

* `GM_CONTROL_API_ZONE_KEY=default-zone`
* `GM_CONTROL_API_ZONE_NAME=zone`

Grey Matter Sidecar:

* `XDS_ZONE=zone`

Grey Matter Objects:

* Must have `"zone_key": "default-zone"`

## Zone Architecture

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

## Fields

### `zone_key`

A unique key to identify this zone. All api objects will be created using an existing `zone_key`.

### `name`

A human readable name to give further descriptive information about this zone.