# Grey Matter Control Plane

**Grey Matter Control** performs service discovery and distribution of configuration in the Grey Matter service mesh. Control provides policy and configuration for all running sidecars within the Grey Matter platform.

The Control server works in conjunction with the [Grey Matter Control API](https://greymatter.gitbook.io/grey-matter-documentation/usage/fabric/api) to manage, maintain, operate, and govern the Grey Matter hybrid mesh platform.

## xDS

The Control server performs service discovery in the mesh and acts as an xDS server to which all proxies connect.

**xDS** is the generic name for the following:

* Endpoints (EDS)
* Clusters (CDS)
* Routes (RDS)
* Listeners (LDS)
* Access Logging (ALS)
* Aggregate (ADS)

{% hint style="info" %}
Each discovery service allows proxies (and other services that speak the xDS protocol) to request streams for particular resources (Listeners, Routes, Clusters, etc) from the control plane.
{% endhint %}

## Service Discovery

Service Discovery is the way Grey Matter dynamically adds and removes instances of each microservice. Discovery adds the initial instances that come online, and modifies the mesh to react to any scaling actions that happen. To keep flexibility in the Grey Matter platform, the Control server supports a number of different service discovery options and platforms.

* [Kubernetes](https://github.com/greymatter-io/gm-control/blob/release-1.1/docs/discovery/kubernetes.md)
* [Consul](https://github.com/greymatter-io/gm-control/blob/release-1.1/docs/discovery/consul.md)
* [AWS/EC2](https://github.com/greymatter-io/gm-control/blob/release-1.1/docs/discovery/ec2.md)
* [AWS/ECS](https://github.com/greymatter-io/gm-control/blob/release-1.1/docs/discovery/ecs.md)
* [File](https://github.com/greymatter-io/gm-control/blob/release-1.1/docs/discovery/file.md)
* Envoy v1 CDS/SDS (beta)
* Envoy v2 CDS/EDS (beta)

{% hint style="success" %}
One key benefit to a service mesh is the dynamic handling of ephemeral service nodes. These nodes have neither consistent IP addresses nor consistent numbers of instances as services are spun up and down. The `gm-control-api` server, in conjunction with Grey Matter Control, can handle these ephemeral services automatically.‌
{% endhint %}

The ability to automatically populate instances of a particular microservice comes from the `cluster`object. In particular, the `name` field in the `cluster` object determines which nodes will be pulled out of the mesh and populated in the `instances` array. In the example below, the name is `catalog`. This means that all services that announce as catalog in service discovery, will be found and populated into the instances array after creation.‌

Create the following object:

```
{    "zone_key": "default-zone",    "cluster_key": "catalog-proxy",    "name": "catalog",    "instances": [],    "circuit_breakers": {      "max_connections": 500,      "max_requests": 500    },    "outlier_detection": null,    "health_checks": []}
```

‌

Will be populated in the mesh as:

```
{  "cluster_key": "catalog-proxy",  "zone_key": "default-zone",  "name": "catalog",  "secret": {    "secret_key": "",    "secret_name": "",    "secret_validation_name": "",    "subject_names": null,    "ecdh_curves": null,    "set_current_client_cert_details": {      "uri": false    },    "checksum": ""  },  "instances": [    {      "host": "10.128.2.183",      "port": 9080,      "metadata": [        {          "key": "pod-template-hash",          "value": "2000163809"        },        {          "key": "gm_k8s_host_ip",          "value": "10.0.2.132"        },        {          "key": "gm_k8s_node_name",          "value": "ip-10-0-2-132.ec2.internal"        }      ]    },    {      "host": "10.128.2.140",      "port": 9080,      "metadata": [        {          "key": "pod-template-hash",          "value": "475497808"        },        {          "key": "gm_k8s_host_ip",          "value": "10.0.2.82"        },        {          "key": "gm_k8s_node_name",          "value": "ip-10-0-2-82.ec2.internal"        }      ]    }  ],  "circuit_breakers": {    "max_connections": 500,    "max_pending_requests": null,    "max_retries": null,    "max_requests": 500  },  "outlier_detection": null,  "health_checks": [],  "checksum": "2b6d2a8a6886eb30574f16480b0f99b90e11484d9ddb10fb7970c3ce37d945ab"}
```

‌

Even though the object was created with no `instances`, they were discovered from the mesh and populated. Now any service that needs to talk to `catalog`, can link to this `cluster` and address all live instance.‌

## Configuration Discovery

Each proxy in the mesh is connected to the control plane through a gRPC stream to the Grey Matter Control server. Though `gm-control-api` houses all the configuration for the mesh, it's ultimately `gm-control` that turns these configs into full Envoy configuration objects and sends them to the proxies.‌

The configuration in the Control API is mapped to physical proxies by the `name` field in the `proxy` API object. It's very important that this field exactly match the `service-cluster` identifier that the intended target proxy used when registering with `gm-control.`

In the example below, the `proxy` object, and all other objects linked by their appropriate keys, will be turned into a full Envoy configuration and sent to any proxies that announce as a cluster `catalog`.‌

Services that announce as:

```
XDS_CLUSTER=catalogXDS_REGION=default-zone
```

‌Will receive the config form the object below, because `XDS_CLUSTER`==`name`, and they're both in the same zone.

```
{    "proxy_key": "catalog-proxy",    "zone_key": "default-zone",    "name": "catalog",    "domain_keys": [        "catalog"    ],    "listener_keys": [        "catalog-listener"    ],    "listeners": null,    "active_proxy_filters": [        "gm.metrics"    ],    "proxy_filters": {        "gm_impersonation": {},        "gm_observables": {},        "gm_oauth": {},        "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"        }    }}
```

## Questions?

{% hint style="success" %}
Have a question about the Grey Matter Control Plane? Reach out to us at <info@greymatter.io> to [learn more ](https://app.gitbook.com/@deciphernow/s/scratchpad/red-content/10-25-19/gm-control-api-docs-1/mesh/configuration/routing/multi-mesh)
{% endhint %}


---

# 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/introduction/internals/service-discovery.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.