Consul Example

This repo demonstrates the uses of Hashicorp's Consul.

1. Service Registry
2. Health Checks
3. Key-Value (K/V) store

Table of Contents

• Intro
  • Starting Consul Agent
  • Querying Consul Agents (Members)
• Configuration Directory
• Services
• HealthChecks
• Consul Connect
  • Intentions
• Cluster
  • Start the Server & Client
  • Joining Cluster
  • Query the Nodes
  • Leave Cluster
• Key/Value (K/V) Store
• UI Web Console

Intro

Starting the Consul agent:

consul agent

Starting in "Dev" mode:

consul agent -dev

Querying Agents (Members)

From CLI:

consul members --detailed

via HTTP API:

curl localhost:8500/v1/catalog/nodes

default port of 8500 applies

or via DNS interface:

e.g.

dig @127.0.0.1 -p 8600 ip-192-168-20-127.eu-west-1.compute.internal

"Note that you have to make sure to point your DNS lookups to the Consul agent's DNS server which runs on port 8600 by default."

Configuration Directory

A 'config' directory for Consul. The directory stores:

1. Service definition files
2. HealthChecks definitions
3. Sidecar Proxy definitions

This config directory is commonly stored under /etc/conf.d

Create the folder before starting up Consul.

e.g.

sudo mkdir /etc/conf.d

Services

You define 'services' in a "Service Definition" file which is of JSON format. See this repo for samples.

You store the definition files in the Configuration Directory.

If Consul is already started up after you placed the 'new' Definition files in the Configuration Directory then issue either a Consul reload or SIGNUP

e.g.

consul reload

Queries e.g.

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

or via DNS:

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

HealthChecks

curl http://localhost:8500/v1/health/state/critical

or via DNS:

dig @127.0.0.1 -p 8600 web.service.consul

Consul Connect

[TBC]

consul connect proxy -sidecar-for socat
consul connect proxy -service web -upstream socat:9191
consul connect proxy -sidecar-for web

Controlling access with Intentions

Interactions in Consul are a way to specify whether a service can or cannot communicate with another service.

Deny

consul intention create -deny web socat

Allow it again

consul intention delete web socat

Cluster

Assumming you're running more than one node and therefore have multiple nodes forming a cluster.

Start the Server & Client agents on the nodes

One agent acts as the 'Server' so you start up the agent as the Server.

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

Another 'member' comes along to this cluster as the 'Client'

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

Joining a cluster

To join a cluster, run as the agent of any node and connect to one of the nodes already on the cluster by specifying that nodes' IP address.

e.g.

consul join 172.20.20.11

Query the nodes

Agent from one node querying another Agent from a second node.

e.g.

dig @127.0.0.1 -p 8600 agent-two.node.consul

Leave a cluster

consul leave

K/V Store

The Key/Value store.

Put

consul kv put redis/config/minconns 1
consul kv put redis/config/maxconns 25
consul kv put -flags=42 redis/config/users/admin abcd1234

Get one

consul kv get redis/config/minconns
consul kv get -detailed redis/config/minconns

Get All

consul kv get -recurse

Delete

consul kv delete redis/config/minconns
consul kv delete -recurse redis

Update

consul kv put foo bar
consul kv put foo zip

Atomic Update

consul kv put -cas -modify-index=123 foo bar

Ui Web Console

via the -ui flag on the CLI

consul agent -ui -config-dir=/etc/consul.d

and then you can visit the /ui path on the HTTP port of 8500

e.g.

http://localhost:8500/ui/

The official Demo Consul UI is located here: https://demo.consul.io/ui