2014-02-08 00:41:03 +00:00
|
|
|
---
|
2020-09-01 15:14:13 +00:00
|
|
|
layout: commands
|
2020-04-07 18:55:19 +00:00
|
|
|
page_title: 'Commands: Join'
|
2020-03-16 21:54:45 +00:00
|
|
|
description: >-
|
2020-04-07 18:55:19 +00:00
|
|
|
The `join` command tells a Consul agent to join an existing cluster. A new
|
|
|
|
|
Consul agent may join any node in the existing cluster. After joining with one
|
|
|
|
|
member, the gossip communication will propagate the updated membership state
|
|
|
|
|
across the cluster.
|
2014-02-08 00:41:03 +00:00
|
|
|
---
|
|
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
# Consul Join
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
Command: `consul join`
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2022-01-11 13:26:58 +00:00
|
|
|
Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/join/:address](/api-docs/agent#join-agent)
|
2022-01-10 17:40:11 +00:00
|
|
|
|
2014-10-19 23:40:10 +00:00
|
|
|
The `join` command tells a Consul agent to join an existing cluster.
|
2020-03-16 21:54:45 +00:00
|
|
|
A new Consul agent may join any node in the existing cluster. After joining
|
|
|
|
|
with one member, the gossip communication will propagate the updated membership
|
|
|
|
|
state across the cluster.
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2020-03-16 21:54:45 +00:00
|
|
|
An agent which is already part of a cluster may join an agent in a different
|
|
|
|
|
cluster, causing the two clusters to be merged into a single cluster.
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2022-10-18 19:49:07 +00:00
|
|
|
The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of
|
2022-03-30 21:16:26 +00:00
|
|
|
[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching)
|
2022-01-10 21:44:56 +00:00
|
|
|
are not supported from commands, but may be from the corresponding HTTP endpoint.
|
|
|
|
|
|
|
|
|
|
| ACL Required |
|
|
|
|
|
| ------------- |
|
|
|
|
|
| `agent:write` |
|
|
|
|
|
|
2014-02-08 00:41:03 +00:00
|
|
|
## Usage
|
|
|
|
|
|
2014-02-19 01:32:13 +00:00
|
|
|
Usage: `consul join [options] address ...`
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2022-01-26 21:01:57 +00:00
|
|
|
You may call `join` with multiple addresses if you want attempt to join the cluster
|
|
|
|
|
through multiple nodes. Consul will attempt to join all addresses. The join
|
|
|
|
|
command will fail only if Consul was unable to join any of the specified addresses.
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2017-02-08 22:14:02 +00:00
|
|
|
#### Command Options
|
2014-02-08 00:41:03 +00:00
|
|
|
|
2020-04-07 18:55:19 +00:00
|
|
|
- `-wan` - For agents running in server mode, the agent will attempt to join
|
2014-02-19 01:32:13 +00:00
|
|
|
other servers gossiping in a WAN cluster. This is used to form a bridge between
|
|
|
|
|
multiple datacenters.
|
2022-07-27 06:17:11 +00:00
|
|
|
|
|
|
|
|
#### API Options
|
|
|
|
|
|
|
|
|
|
@include 'http_api_options_client.mdx'
|
