Light Dark Auto

Consul

HashiCorp Consul service discovery

greymatter.io Fabric supports service discovery from HashiCorp Consul. See the greymatter.io Control Consul discovery setup documentation for how to configure this with greymatter.io Control.

Overview

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 greymatter.io Control server will discover service instances based on those registered 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)
  • services are registered with a particular service tag (see the Service Definition documentation)
  • if the Consul cluster uses an ACL setup, there is a known token value for greymatter.io Control to connect to the Consul cluster

The above specifications will be passed to the greymatter.io Control server as environment variables, see the greymatter.io Control Consul discovery setup documentation for information on how to configure the greymatter.io Control Plane for Consul service discovery.

ACL Tokens

For a secure production implementation, your Consul cluster should be using an ACL token configuration. greymatter.io Control will then need to be provided an ACL token to connect to the Consul cluster, which should be passed through the environment.

Service Registry

One way to register services with the Consul catalog automatically is to use a Consul Agent. 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.

There are other options for registering services, including the Kubernetes Consul Sync Catalog and manual registration. The greymatter.io Control Plane will discover any services for its configured cluster and datacenter as long as they contain the specified tag.

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

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 in the form of "tags": ["{chosen-tag}"]. Without this tag, services will be ignored by the control plane.

Configure greymatter.io Control

The following three environment variables must be set in gm-control to discover s ervices from Consul:

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.

{% hint style="danger" %} 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. {% end %}