# consul Grey Matter Control supports service discovery from [HashiCorp Consul](https://www.consul.io/docs/index.html). For a working example, see [examples/consul](https://github.com/DecipherNow/gm-gitbook-sync/tree/e291b7c6efe71715000ac2f5742a714439ecf33d/usage/examples/consul/README.md). ## Consul and Service Configuration To discover services using Consul, there are three specifications that must be met in the Consul configuration and specified in the configuration of `gm-control`. ### Consul Agent Each service must be registered with a [Consul Agent](https://www.consul.io/docs/agent/basics.html). The Consul Agents should be running in the same cluster. For `gm-control` to recognize instance information such as node and/or service health, services should be registered with their own client node (agent). More information on running a Consul Agent can be found [here](https://www.consul.io/docs/agent/options.html). The cluster should be running at a known address to be specified in the `gm-control` configuration. ### Datacenter Consul services are collected by `gm-control` from a single specified datacenter, thus all services to be discovered by Consul must be registered in this datacenter. The datacenter is a also a part of the [Consul Agent](/grey-matter-documentation/usage/fabric/discovery/consul.md#consul-agent) configuration. > **NOTE** The datacenter **must** be explicitly set using the command line flag `--dc` or environment variable `GM_CONTROL_CONSUL_DC` when running `gm-control`. ### Service Tags Services in Consul are discovered by `gm-control` using tags. All services to be discovered by `gm-control` must contain a matching service tag. Tags are specified in the [service definition](https://www.consul.io/docs/agent/services.html) in the form of `"tags": ["{chosen-tag}"]`. Without this tag, services will be ignored by the control plane. > **NOTE** By default, this tag must be `"gm-cluster"` or can be otherwise specified to `gm-control` on the command line with the flag `--cluster-tag`. ## Configure Grey Matter Control The following three environment variables must be set in `gm-control` to discover services from Consul: ```yaml GM_CONTROL_CMD=consul GM_CONTROL_CONSUL_DC={your-consul-datacenter} GM_CONTROL_CONSUL_HOSTPORT={your-consul-host}:{your-consul-port} ``` `GM_CONTROL_CONSUL_HOSTPORT` must specify the address of your Consul cluster. As noted above, the datacenter can be specified here or with the command line flag `--dc`. There is an optional environment variable, `GM_CONTROL_XDS_RESOLVE_DNS`, which should be set to `true` in order to resolve service DNS before passing the instance IPs to Envoy (as service instances will normally be registered as IP addresses). If you plan to use Envoy to route to hostname, make sure to set this flag. --- # 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/discovery/consul.md?ask= ``` 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.