Demo Adding and Removing Consul Agents

The image is mostly black with a small, dark purple rectangle in the bottom right corner.

In this tutorial, you'll learn how to view your current Consul cluster, add a new client agent, and remove an agent—either gracefully or forcefully. This ensures your service mesh remains healthy and up to date.

Viewing the Current Cluster

On your server node (consul-node-a), verify the existing members and Raft peers:

# List all cluster members
consul members

# Check Raft peer status
consul operator raft list-peers

Example output:

Node            Address             Status  Type    Build       Protocol  DC         Segment
consul-node-a   10.0.101.110:8301   alive   server  1.9.3+ent   2         us-east-1  <all>
consul-node-b   10.0.101.248:8301   alive   server  1.9.3+ent   2         us-east-1  <all>

Node            ID                                   Address              State     Voter  RaftProtocol
consul-node-a   9655caa5-8d6d-bb5b-b087-df7acc277d60  10.0.101.110:8300    leader    true   3
consul-node-b   7d69d582-7308-b1e8-ff51-8c4899f2df43  10.0.101.248:8300    follower  true   3

Note

consul-node-a is the Raft leader, while consul-node-b is a follower. Maintaining at least three servers is recommended for high availability.

Cluster Members Overview

Node	Address	Status	Type	DC	Segment
consul-node-a	10.0.101.110:8301	alive	server	us-east-1	<all>
consul-node-b	10.0.101.248:8301	alive	server	us-east-1	<all>

Adding a New Client Agent

Prepare the client config
On your new machine (web-server-01), create /etc/consul.d/config.hcl:
```
node_name  = "web-server-01"
server     = false
datacenter = "us-east-1"
```
Start the Consul agent
```
sudo systemctl start consul
```

Verify local membership

consul members

Expected:

Node            Address             Status  Type    Build       Protocol  DC         Segment
web-server-01   10.0.101.177:8301   alive   client  1.9.3+ent   2         us-east-1  <default>

Join the cluster

consul join 10.0.101.110

Successfully joined cluster by contacting 10.0.101.110

Confirm membership across the cluster

consul members

All nodes:

Node            Address             Status  Type    Build       Protocol  DC         Segment
consul-node-a   10.0.101.110:8301   alive   server  1.9.3+ent   2         us-east-1  <all>
consul-node-b   10.0.101.248:8301   alive   server  1.9.3+ent   2         us-east-1  <all>
web-server-01   10.0.101.177:8301   alive   client  1.9.3+ent   2         us-east-1  <default>

Note

For automatic retries, add a retry_join block in your client config. You can also leverage cloud auto-join or gossip keys—see Consul auto-join for details.

Removing a Client Agent

Graceful Leave

On the client (web-server-01), run:

consul leave

==> Graceful leave complete, shutting down agent...

On any server, you’ll see the client marked as left:

consul members

Node            Address             Status  Type    Build       Protocol  DC         Segment
consul-node-a   10.0.101.110:8301   alive   server  1.9.3+ent   2         us-east-1  <all>
consul-node-b   10.0.101.248:8301   alive   server  1.9.3+ent   2         us-east-1  <all>
web-server-01   10.0.101.177:8301   left    client  1.9.3+ent   2         us-east-1  <default>

Forceful Removal

If a client is unresponsive or destroyed, use force-leave with pruning:

consul force-leave --prune web-server-01

consul members

Node            Address             Status  Type    Build       Protocol  DC         Segment
consul-node-a   10.0.101.110:8301   alive   server  1.9.3+ent   2         us-east-1  <all>
consul-node-b   10.0.101.248:8301   alive   server  1.9.3+ent   2         us-east-1  <all>

Warning

force-leave is destructive and should only be used when an agent cannot leave gracefully. It immediately prunes the node from the membership list.