# Consul Discovery

## HashiCorp Consul

### Description

Grey Matter Control discovers service instances from a Consul service registry using service tags.

### Usage

To use consul discovery, set the following environment variables:

```bash
# required
GM_CONTROL_CMD=consul
GM_CONTROL_CONSUL_DC={}
GM_CONTROL_CONSUL_HOSTPORT={}
# optional
GM_CONTROL_CONSUL_ACLTOKEN={}
GM_CONTROL_CONSUL_USE_SSL={}
GM_CONTROL_CONSUL_CLUSTER_TAG={}
GM_CONTROL_CONSUL_TAG_DELIMITER={}
GM_CONTROL_CONSUL_LOG_LEVEL={}
```

| Environment Variable              | Description                                                           | Type      | Default          | Required |
| --------------------------------- | --------------------------------------------------------------------- | --------- | ---------------- | -------- |
| `GM_CONTROL_CONSUL_DC`            | Consul datacenter to collect services from                            | `string`  | `dc`             | `false`  |
| `GM_CONTROL_CONSUL_HOSTPORT`      | host:port address to connect to Consul API                            | `string`  | `localhost:8500` | `false`  |
| `GM_CONTROL_CONSUL_ACLTOKEN`      | ACL token to use to connect to Consul servers                         | `string`  |                  | `false`  |
| `GM_CONTROL_CONSUL_USE_SSL`       | If true, connect to Consul API with SSL                               | `boolean` | `false`          | `false`  |
| `GM_CONTROL_CONSUL_CLUSTER_TAG`   | Service tag to indicate which Consul services are discovered          | `string`  | `gm-cluster`     | `false`  |
| `GM_CONTROL_CONSUL_TAG_DELIMITER` | Delimiter used to split key/value pairs stored in Consul service tags | `string`  |                  | `false`  |
| `GM_CONTROL_CONSUL_LOG_LEVEL`     | log level used for consul discovery plugin                            | `string`  | `info`           | `false`  |

#### Consul Service Specifications

Grey Matter Control will discover services in the Consul datacenter specified with `GM_CONTROL_CONSUL_DC` with a tag with key equal to the value of `GM_CONTROL_CONSUL_CLUSTER_TAG`.

If the consul server configuration you are registering with uses an [ACL token configuration](https://www.consul.io/api-docs/acl/tokens), set the environment variable `GM_CONTROL_CONSUL_ACLTOKEN`. In an ACL bootstrapped consul setup, this will be required to register services.

See the [consul usage docs](https://greymatter.gitbook.io/grey-matter-documentation/1.3/usage/discovery/consul) for more information on HashiCorp Consul.

#### Command Line

To use the command line, run gm-control with `gm-control consul <global-flags>`.

**Help**

For help or to list available options for consul discovery using the cli, run `gm-control consul --help`.