mirror of https://github.com/hashicorp/consul
91 lines
3.6 KiB
Markdown
91 lines
3.6 KiB
Markdown
---
|
|
layout: "intro"
|
|
page_title: "Join a Cluster"
|
|
sidebar_current: "gettingstarted-join"
|
|
---
|
|
|
|
# Join a Cluster
|
|
|
|
In the previous page, we started our first agent. While it showed how easy
|
|
it is to run Consul, it wasn't very exciting since we simply made a cluster of
|
|
one member. In this page, we'll create a real cluster with multiple members.
|
|
|
|
When starting a Consul agent, it begins without knowledge of any other node, and is
|
|
an isolated cluster of one. To learn about other cluster members, the agent must
|
|
_join_ an existing cluster. To join an existing cluster, only needs to know
|
|
about a _single_ existing member. After it joins, the agent will gossip with this
|
|
member and quickly discover the other members in the cluster.
|
|
|
|
## Starting the Agents
|
|
|
|
To simulate a more realistic cluster, we are using a two node cluster in
|
|
Vagrant. The Vagrantfile can be found in the demo section of the repo
|
|
[here](https://github.com/hashicorp/consul/tree/master/demo/vagrant-cluster).
|
|
|
|
We start the first agent on our first node and also specify a node name.
|
|
The node name must be unique and is how a machine is uniquely identified.
|
|
By default it is the hostname of the machine, but we'll manually override it.
|
|
We are also providing a bind address. This is the address that Consul listens on,
|
|
and it *must* be accessible by all other nodes in the cluster. The first node
|
|
will act as our server in this cluster.
|
|
|
|
```
|
|
$ consul agent -server -bootstrap -data-dir /tmp/consul -node=agent-one -serf-bind=172.20.20.10 -server-addr=172.20.20.10:8300 -advertise=172.20.20.10
|
|
...
|
|
```
|
|
|
|
Then, in another terminal, start the second agent on the new node.
|
|
This time, we set the bind address to match the IP of the second node
|
|
as specified in the Vagrantfile. In production, you will generally want
|
|
to provide a bind address or interface as well.
|
|
|
|
```
|
|
$ consul agent -data-dir /tmp/consul -node=agent-two -serf-bind=172.20.20.11 -server-addr=172.20.20.11:8300 -advertise=172.20.20.11
|
|
...
|
|
```
|
|
|
|
At this point, you have two Consul agents running, one server and one client.
|
|
The two Consul agents still don't know anything about each other, and are each part of their own
|
|
clusters (of one member). You can verify this by running `consul members`
|
|
against each agent and noting that only one member is a part of each.
|
|
|
|
## Joining a Cluster
|
|
|
|
Now, let's tell the first agent to join the second agent by running
|
|
the following command in a new terminal:
|
|
|
|
```
|
|
$ consul join 172.20.20.11
|
|
Successfully joined cluster by contacting 1 nodes.
|
|
```
|
|
|
|
You should see some log output in each of the agent logs. If you read
|
|
carefully, you'll see that they received join information. If you
|
|
run `consul members` against each agent, you'll see that both agents now
|
|
know about each other:
|
|
|
|
```
|
|
$ consul members
|
|
agent-one 172.20.20.10:8301 alive role=consul,dc=dc1,vsn=1,vsn_min=1,vsn_max=1,port=8300,bootstrap=1
|
|
agent-two 172.20.20.11:8301 alive role=node,dc=dc1,vsn=1,vsn_min=1,vsn_max=1
|
|
```
|
|
|
|
<div class="alert alert-block alert-info">
|
|
<p><strong>Remember:</strong> To join a cluster, a Consul agent needs to only
|
|
learn about <em>one existing member</em>. After joining the cluster, the
|
|
agents gossip with each other to propagate full membership information.
|
|
</p>
|
|
</div>
|
|
|
|
In addition to using `consul join` you can use the `-join` flag on
|
|
`consul agent` to join a cluster as part of starting up the agent.
|
|
|
|
## Leaving a Cluster
|
|
|
|
To leave the cluster, you can either gracefully quit an agent (using
|
|
`Ctrl-C`) or force kill one of the agents. Gracefully leaving allows
|
|
the node to transition into the _left_ state, otherwise other nodes
|
|
will detect it as having _failed_. The difference is covered
|
|
in more detail [here](/intro/getting-started/agent.html#toc_3).
|
|
|