Running the Consul Agent

Starting the Agent

Consul can be startet in development mode where it does not persist any state:

consul agent -dev

the log shows that the agent is running in server mode and is leader of the cluster.

Cluster Members

consul members

Shows the members of the consul cluster. The output is based on the gossip protocol and eventually consistent.

For a strongly consistent view HTTP is used, which is forwarded to the server:

curl localhost:8500/v1/catalog/nodes

Additionaly DNS can be used to query:

dig @127.0.0.1 -p 8600 my-hostname.node.consul

Stopping the Agent

The agent can be gracefully stopped with ctrl-c (the interrupt signal).

So cluster members are informed that the node left

If one would forcibly kill the agent, it would ne detected as failed.

This would lead to reconnect attempts.

Registering Services

Defining a Service

A service can be registered by providing a definition in the config directory or using the HTTP API.

We write a service definition configuration file:

echo '{"service": {"name": "web", "tags": ["rails"], "port": 80}}' > /etc/consul.d/web.json

Then restart the agent providing the config dir:

consul agent -dev -config-dir=./consul.d

Querying a Service

Can be done via DNS or HTTP API

DNS

The DNS Name for a service is NAME.service.consul.

dig @127.0.0.1 -p 8600 web.service.consul

Will return an A-Record for the service.

The whole address / port combination can be queried as a SRV record:

dig @127.0.0.1 -p 8600 web.service.consul SRV

Services can be filtered by tag in the format TAG.NAME.service.consul :

dig @127.0.0.1 -p 8600 rails.web.service.consul

HTTP API

Additionaly the HTTP API can be used to query services:

curl http://localhost:8500/v1/catalog/service/web

The catalog API gives all nodes of service but sometimes one may want just healthy instances. This can be queried too:

curl 'http://localhost:8500/v1/health/service/web?passing'

Updating Services

You can change service configuration files and send a SIGHUP to the agent.

Alternatively the HTTP API can be used to add, remove and modify services.

Consul cluster with Vagrant

The vagrant file can be found here

Change “debian/stretch64” to “generic/debian9”

Boot the machines with vagrant up and ssh with vagrant ssh n1

consul agent -server -bootstrap-expect=1 \
    -data-dir=/tmp/consul -node=agent-one -bind=172.20.20.10 \
    -enable-script-checks=true -config-dir=/etc/consul.d

Each node in a cluster must have a unique name. By default, Consul uses the hostname of the machine, but we’ll manually override it using the -node

Now connect to the second node vagrant ssh n2

And run a consul agent like this:

consul agent -data-dir=/tmp/consul -node=agent-two \
    -bind=172.20.20.11 -enable-script-checks=true -config-dir=/etc/consul.d

But the two agents don’t know each other yet, which can be seen with consul members

In order to join open another shell with vagrant ssh n1 and do:

consul join 172.20.20.11
consul members

or use a JSON config for agent-two:

{
  "start_join": ["172.20.20.10"]
}

KV Data

Consul provides an easy to use KV store:

consul kv put redis/config/minconns 1
consul kv put redis/config/maxconns 25

consul kv get -recurse

consul kv delete -recurse redis

Web UI

Consul comes with a Web UI that can be enabled:

consul agent -dev -ui

It can be reached here: http://localhost:8500/ui