Consul Service Discovery: Installation, Configuration, Java Client, and Cluster Setup Guide

Hello everyone, I'm Afan. Previously I introduced Nacos for service registration and configuration; now I will share another component, Consul, which offers similar functionality.

Background

Distributed system architectures are now common, making service registration and discovery essential. Various open‑source solutions exist, such as Zookeeper, Etcd, Eureka, Nacos, and the focus of this article, Consul.

Consul Overview

Developed in Go.

Provides built‑in service registration/discovery, consensus protocol, health checks, Key/Value store, multi‑datacenter support, DNS/HTTP APIs, and a web UI.

Distributed by HashiCorp as an open‑source tool.

Supports two registration methods: HTTP API or configuration file (the latter is recommended).

Consul Server Configuration Usage

Download and extract the binary, then copy it to /usr/local/consul . silence$ sudo mkdir /etc/consul.d silence$ echo '{"service":{"name":"web","tags":["rails"],"port":80}}' | sudo tee /etc/consul.d/web.json

Start the agent in development mode: silence$ /usr/local/consul/consul agent -dev -node consul_01 -config-dir=/etc/consul.d/ -ui -dev runs a local test instance; -node sets a custom node name; -config-dir points to the service definition directory; -ui enables the built‑in web UI.

Query cluster members: silence-pro:~ silence$ /usr/local/consul/consul members

Query service data via HTTP: silence-pro:~ silence$ curl http://127.0.0.1:8500/v1/catalog/service/web

Use the Consul Web UI to view service status, node health, ACLs, and KV store.

KV Store Import/Export

Import KV data:

silence-pro:consul$ ./consul kv import @temp.json

Export KV data:

silence-pro:consul$ ./consul kv export redis/

Example temp.json format:

[
    {
        "key": "redis/config/password",
        "flags": 0,
        "value": "MTIzNDU2"
    },
    {
        "key": "redis/config/username",
        "flags": 0,
        "value": "U2lsZW5jZQ=="
    }
]

Consul Java Client Usage

Add Maven dependency:

<dependency>
    <groupId>com.orbitz.consul</groupId>
    <artifactId>consul-client</artifactId>
    <version>0.12.3</version>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

Utility class example (ConsulUtil.java) provides methods for service registration, health checks, KV operations, and Raft status queries.

Consul Cluster Setup

Three virtual machines with IPs 192.168.231.145, .146, .147 are used.

Start two servers (n1 and n2) with -bootstrap-expect 2 and enable UI on n2. [root@centos145 consul]# ./consul agent -server -bootstrap-expect 2 -data-dir /tmp/consul -node=n1 -bind=192.168.231.145 -datacenter=dc1 -ui [root@centos146 consul]# ./consul agent -server -bootstrap-expect 2 -data-dir /tmp/consul -node=n2 -bind=192.168.231.146 -datacenter=dc1 -ui

Join n1 to n2: [silence@centos145 consul]$ ./consul join 192.168.231.146

Start a client node (n3): [root@centos147 consul]# ./consul agent -data-dir /tmp/consul -node=n3 -bind=192.168.231.147 -datacenter=dc1

Join the client to the cluster: [silence@centos147 consul]$ ./consul join 192.168.231.145

After these steps, the three‑node Consul cluster is operational, with n1 and n2 as server nodes and n3 as a client node.

The key difference between server and client modes is controlled by the -bootstrap-expect flag, which defines the expected number of server nodes and enables leader election among servers; client nodes can join and leave freely.

For more details, refer to the original article and the linked resources.