# 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 the [Grey Matter CLI](https://github.com/greymatter-io/cli/blob/release-1.2/docs/create.md) or [hitting the API endpoint](https://github.com/greymatter-io/gm-control-api/blob/release-1.2/docs/swagger.yaml).

The `zone` must be the first Grey Matter object created in series, followed by [`domain`](/grey-matter-documentation/usage/fabric/api/domain.md), [`cluster`](/grey-matter-documentation/usage/fabric/api/cluster.md), [`listener`](/grey-matter-documentation/usage/fabric/api/listener.md), [`proxy`](/grey-matter-documentation/usage/fabric/api/proxy.md), [`shared_rules`](/grey-matter-documentation/usage/fabric/api/shared_rules.md), and [`route`](/grey-matter-documentation/usage/fabric/api/route.md) (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 it's 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.13.0/api-v2/api/v2/core/base.proto.html?highlight=locality#core-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.13.0/api-v2/api/v2/core/base.proto.html?highlight=locality#core-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.13.0/api-v3/service/discovery/v3/discovery.proto.html#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 it's 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](/grey-matter-documentation/usage/fabric/api/zone.md#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

![](/files/-M3fy6reEmYVx--r--xy)

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api/zone.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.