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 to manage, maintain, operate, and govern the Grey Matter hybrid mesh platform.


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)

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.

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.

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

The ability to automatically populate instances of a particular microservice comes from the clusterobject. 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": "", "port": 9080, "metadata": [ { "key": "pod-template-hash", "value": "2000163809" }, { "key": "gm_k8s_host_ip", "value": "" }, { "key": "gm_k8s_node_name", "value": "ip-10-0-2-132.ec2.internal" } ] }, { "host": "", "port": 9080, "metadata": [ { "key": "pod-template-hash", "value": "475497808" }, { "key": "gm_k8s_host_ip", "value": "" }, { "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:


‌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": "", "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" } }}


Have a question about the Grey Matter Control Plane? Reach out to us at to learn more