Skip to main content
In this guide, you’ll learn how to add and remove Consul agents—both servers and clients—in your cluster. We’ll cover three primary join methods, how to gracefully remove agents, and how to list all cluster members.

​
Overview of Agent Membership

Consul agents use the Gossip Protocol to share membership updates. When a new agent joins, it contacts an existing member; the protocol then propagates that change across the entire cluster. You can even merge two independent clusters by having an agent in one contact a node in the other.

​
1. Joining via the CLI

You can manually join an agent to the cluster by specifying any existing member’s hostname or IP:
Replace consul-node-a.example.com with an IP address if preferred. CLI joins are best suited for testing or small labs—automated config is recommended in production.

​
2. Joining via Configuration

Add join settings directly to your agent’s JSON or HCL config. There are two options: Example (config.json):
This instructs the agent to keep retrying until it joins one of the specified IPs.
Use retry_join for environments where agents start in an unpredictable order.
If you need a single attempt only, use the join option instead.

​
3. Cloud Auto-Join

Cloud auto-join uses provider metadata (tags or labels) to discover peers automatically. Supported providers include AWS, Azure, GCP, Kubernetes, and more. You must grant the agent appropriate API permissions (for example, via an AWS IAM role).
The image is a slide titled "Adding Servers," detailing methods for an agent to join a cluster using a configuration file and cloud auto-join, listing various cloud services like AWS, Azure, and Kubernetes. It also mentions the requirement of credentials for authentication.
Example AWS auto-join config:
Each agent queries AWS EC2 for instances tagged consul=true and attempts to join them.
Ensure your cloud credentials or IAM roles only grant enough permissions to list instances—avoid overly broad access.

​
Removing Agents from the Cluster

To gracefully remove an agent and inform the cluster:
A graceful leave updates the Raft peer set (for servers) and ensures nodes treat the departure as intentional rather than a failure.

​
Listing Cluster Members

Use the members command to see all servers and clients:
In production, clusters can scale to hundreds or thousands of nodes across multiple datacenters.

Watch Video