Master Consul Service Discovery: Principles, Docker Setup, and Health Checks

Why Use Service Discovery

Service discovery prevents hard‑coding, enables fault tolerance, horizontal scaling, and improves operational efficiency, especially in microservice architectures where many services need automated registration and lookup.

Consul Internal Principles

Consul operates across multiple data centers; each data center contains Server and Client agents. Servers store data, elect a Leader, and replicate via Raft. Clients perform health checks and forward requests. Nodes maintain membership via a gossip protocol using TCP/UDP ports 8301 (intra‑DC) and 8302 (inter‑DC). Reads and writes go through the Leader on port 8300.

Consul Service Discovery Flow

A healthy Consul cluster (e.g., three Server nodes with one Leader) registers services via the HTTP API (port 8500) or configuration files. Clients query the local Consul Agent, which forwards to the Server; the Server returns IPs and ports of service instances. DNS queries can also resolve service names like hello.service.dc1.consul.

Setting Up Consul with Docker

Install Docker Desktop for Windows, then pull the Consul image: docker pull consul Start a three‑node Server cluster and one Client:

# Server 1 (maps 8500→8900 and enables UI)
docker run -d --name=consul1 -p 8900:8500 -e CONSUL_BIND_INTERFACE=eth0 consul agent --server=true --bootstrap-expect=3 --client=0.0.0.0 -ui
# Server 2
docker run -d --name=consul2 -e CONSUL_BIND_INTERFACE=eth0 consul agent --server=true --client=0.0.0.0 --join 172.17.0.2
# Server 3
docker run -d --name=consul3 -e CONSUL_BIND_INTERFACE=eth0 consul agent --server=true --client=0.0.0.0 --join 172.17.0.2
# Client
docker run -d --name=consul4 -e CONSUL_BIND_INTERFACE=eth0 consul agent --server=false --client=0.0.0.0 --join 172.17.0.2

Copy a service definition (e.g., services.json) into /consul/config of a client container and reload the configuration with consul reload.

Registering a Service

Create a JSON file describing the service (name, id, address, port, health‑check URL) and place it in the Consul config directory. After reloading, the service becomes discoverable.

Discovering Services

Use the HTTP API:

curl http://127.0.0.1:8500/v1/health/service/hello?passing=false

or DNS:

dig @127.0.0.1 -p 8600 hello.service.dc1.consul ANY

Both methods return service instances; the HTTP API can filter by health status, while DNS provides only IPs.

Consul Template

Install Consul Template to render configuration files from service data:

curl -L https://releases.hashicorp.com/consul-template/0.19.5/consul-template_0.19.5_linux_amd64.tgz | tar -xzv -C /usr/local/bin

Create a template (e.g., in.tpl) that iterates over services and outputs server {{ .Name }} {{ .Address }}:{{ .Port }}. Run:

nohup consul-template -template "in.tpl:out.txt" &

The generated file updates automatically as services change.

Deregistering Nodes and Services

Use the HTTP API endpoints /catalog/deregister to remove any node or service, or /agent/service/deregister/:service_id to remove a specific service from the current node. Nodes that fail are marked as failed and removed after 72 hours unless manually forced to leave.

Health Checks

Consul supports Script, TCP, HTTP, and TTL health checks, executed by the agent that registered the service. Health status influences service visibility in both HTTP and DNS queries.

Comparison with ZooKeeper and etcd

ZooKeeper uses temporary nodes, etcd uses TTL keys; both provide strong consistency. Consul stores registration data on servers with strong consistency, but health status is maintained by agents, allowing failed agents to hide unhealthy services.

Alternative Deployment Architectures

One can centralize Consul Clients on dedicated machines and have services register to multiple Clients, using a load‑balanced front‑end to forward discovery requests. This isolates Consul from application servers and reduces per‑host installation, but adds complexity in load balancing and duplicate registration handling.

Can Consul Run with Only Servers?

While a small number of services (≈10) could run on a pure Server cluster, best practice is to include Clients to offload health checks and keep the cluster scalable.