open-consul/website/content/commands/join.mdx

50 lines
1.7 KiB
Plaintext
Raw Normal View History

2014-02-08 00:41:03 +00:00
---
layout: commands
2020-04-07 18:55:19 +00:00
page_title: 'Commands: Join'
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
---
# Consul Join
2014-02-08 00:41:03 +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)
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
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
The table below shows this command's [required ACLs](/api#authentication). Configuration of
[blocking queries](/api/features/blocking) and [agent caching](/api/features/caching)
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
Usage: `consul join [options] address ...`
2014-02-08 00:41:03 +00:00
You may call join with multiple addresses if you want to try to join
multiple clusters. Consul will attempt to join all addresses, and the join
command will fail only if Consul was unable to join with any.
2014-02-08 00:41:03 +00:00
#### API Options
2020-04-07 18:55:19 +00:00
@include 'http_api_options_client.mdx'
#### 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
other servers gossiping in a WAN cluster. This is used to form a bridge between
multiple datacenters.