> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Demo Adding and Removing Consul Agents
> This tutorial covers viewing a Consul cluster, adding a client agent, and removing an agent to maintain a healthy service mesh.
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:
```bash theme={null}
# List all cluster members
consul members
# Check Raft peer status
consul operator raft list-peers
```
Example output:
```bash theme={null}
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
consul-node-b 10.0.101.248:8301 alive server 1.9.3+ent 2 us-east-1
```
```bash theme={null}
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
```
`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 | \ |
| consul-node-b | 10.0.101.248:8301 | alive | server | us-east-1 | \ |
## Adding a New Client Agent
1. **Prepare the client config**\
On your new machine (`web-server-01`), create `/etc/consul.d/config.hcl`:
```hcl theme={null}
node_name = "web-server-01"
server = false
datacenter = "us-east-1"
```
2. **Start the Consul agent**
```bash theme={null}
sudo systemctl start consul
```
3. **Verify local membership**
```bash theme={null}
consul members
```
Expected:
```bash theme={null}
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
```
4. **Join the cluster**
```bash theme={null}
consul join 10.0.101.110
```
```bash theme={null}
Successfully joined cluster by contacting 10.0.101.110
```
5. **Confirm membership across the cluster**
```bash theme={null}
consul members
```
All nodes:
```bash theme={null}
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
consul-node-b 10.0.101.248:8301 alive server 1.9.3+ent 2 us-east-1
web-server-01 10.0.101.177:8301 alive client 1.9.3+ent 2 us-east-1
```
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][consul-join] for details.
## Removing a Client Agent
### Graceful Leave
On the client (`web-server-01`), run:
```bash theme={null}
consul leave
```
```bash theme={null}
==> Graceful leave complete, shutting down agent...
```
On any server, you’ll see the client marked as `left`:
```bash theme={null}
consul members
```
```bash theme={null}
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
consul-node-b 10.0.101.248:8301 alive server 1.9.3+ent 2 us-east-1
web-server-01 10.0.101.177:8301 left client 1.9.3+ent 2 us-east-1
```
### Forceful Removal
If a client is unresponsive or destroyed, use `force-leave` with pruning:
```bash theme={null}
consul force-leave --prune web-server-01
```
```bash theme={null}
consul members
```
```bash theme={null}
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
consul-node-b 10.0.101.248:8301 alive server 1.9.3+ent 2 us-east-1
```
`force-leave` is destructive and should only be used when an agent cannot leave gracefully. It immediately prunes the node from the membership list.
## References
* [Consul Documentation][consul-docs]
* [consul members][consul-members]
* [consul join][consul-join]
* [consul force-leave][consul-force-leave]
[consul-docs]: https://www.consul.io/docs
[consul-members]: https://www.consul.io/docs/commands/members
[consul-join]: https://www.consul.io/docs/commands/join
[consul-force-leave]: https://www.consul.io/docs/commands/force-leave