# consul

Grey Matter Fabric supports service discovery from [HashiCorp Consul](https://www.consul.io/docs/index.html). See the [Grey Matter Control Consul discovery setup documentation](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/setup/fabric-1/gm-control/gm-control-consul) for how to configure this with Grey Matter Control.

## Consul and Service Configuration

HashiCorp Consul is a service catalog with a full featured control plane with service discovery, configuration, and segmentation functionality.

When using `consul` service discovery, the Grey Matter Control server will discover service instances based on those [registered](https://www.consul.io/docs/discovery/services) with a Consul catalog that meet several specifications:

* the Consul cluster is reachable via a host:port address
* services are registered in a particular datacenter (see Consul's [architecture documentation](https://www.consul.io/docs/architecture#consul-architecture))
* services are registered with a particular service tag (see the [Service Definition documentation](https://www.consul.io/docs/discovery/services#service-definition))
* if the Consul cluster uses an [ACL setup](#acl-tokens), there is a known token value for Grey Matter Control to connect to the Consul cluster

The above specifications will be passed to the Grey Matter Control server as environment variables, see the [Grey Matter Control Consul discovery setup documentation](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/setup/fabric-1/gm-control/gm-control-consul) for information on how to configure the Grey Matter Control Plane for Consul service discovery.

### ACL Tokens

For a secure production implementation, your Consul cluster should be using an [ACL token configuration](https://www.consul.io/api-docs/acl/tokens). Grey Matter Control will then need to be provided an ACL token to connect to the Consul cluster, which should be passed [through the environment](https://greymatter.gitbook.io/grey-matter-documentation/1.7-beta/reference/setup/fabric-1/gm-control/gm-control-consul#consul-service-specifications).

### Service Registry

One way to register services with the Consul catalog automatically is to use a [Consul Agent](https://www.consul.io/docs/agent/basics.html). The Consul Agents should be running in the same cluster. For the Control server to recognize instance information such as node and/or service health, services should be registered with their own client node (agent). The datacenter will also be specified when running the Agent. More information on running a Consul Agent can be found [here](https://www.consul.io/docs/agent/options.html).

There are other options for registering services, including the [Kubernetes Consul Sync Catalog](https://www.consul.io/docs/k8s/service-sync) and manual registration. The Grey Matter Control Plane will discover any services for its configured cluster and datacenter as long as they contain the specified tag.