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

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

API Configuration

Zones can be created using the Grey Matter CLI or hitting the API endpoint.

The zone must be the first Grey Matter object created in series, followed by domain, cluster, listener, proxy, shared_rules, and 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 it's corresponding Grey Matter Control API objects.

Each Envoy proxy set up by the Grey Matter Sidecar has a Node specification that identifies it as a specific Envoy instance. A part of this identification is a Node's 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 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, 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

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.