status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Website: Cleanup for docs/guides/bootstrapping

This commit is contained in:
Ryan Breen 2015-02-22 23:19:11 -05:00
parent bc331fb0c6
commit d89a44d71d
1 changed files with 35 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
website/source/docs/guides/bootstrapping.html.markdown
View File

@ -3,38 +3,44 @@ layout: "docs"
page_title: "Bootstrapping"
sidebar_current: "docs-guides-bootstrapping"
description: |-
Before a Consul cluster can begin to service requests, it is necessary for a server node to be elected leader. For this reason, the first nodes that are started are generally the server nodes. Remember that an agent can run in both client and server mode. Server nodes are responsible for running the consensus protocol, and storing the cluster state. The client nodes are mostly stateless and rely on the server nodes, so they can be started easily.
An agent can run in both client and server mode. Server nodes are responsible for running the consensus protocol and storing the cluster state. Before a Consul cluster can begin to service requests, a server node must be elected leader. Thus, the first nodes that are started are generally the server nodes. Bootstrapping is the process of joining these server nodes into a cluster.
---
# Bootstrapping a Datacenter
Before a Consul cluster can begin to service requests, it is necessary for a server node to
be elected leader. For this reason, the first nodes that are started are generally the server nodes.
Remember that an agent can run in both client and server mode. Server nodes are responsible for running
the [consensus protocol](/docs/internals/consensus.html), and storing the cluster state.
The client nodes are mostly stateless and rely on the server nodes, so they can be started easily.
An agent can run in both client and server mode. Server nodes are responsible for running the
[consensus protocol](/docs/internals/consensus.html) and storing the cluster state.
The client nodes are mostly stateless and rely heavily on the server nodes.
Before a Consul cluster can begin to service requests, a server node must be elected leader.
Thus, the first nodes that are started are generally the server nodes. Bootstrapping is the process
of joining these server nodes into a cluster.
The recommended way to bootstrap is to use the `-bootstrap-expect` [configuration
option](/docs/agent/options.html). This options informs Consul of the expected number of
server nodes, and automatically bootstraps when that many servers are available. To prevent
inconsistencies and split-brain situations, all servers should specify the same value for `-bootstrap-expect`
or specify no value at all. Any server that does not specify a value will not attempt to
bootstrap the cluster.
option](/docs/agent/options.html). This option informs Consul of the expected number of
server nodes and automatically bootstraps when that many servers are available. To prevent
inconsistencies and split-brain situations (that is, clusters where multiple servers consider
themselves leader), all servers should either specify the same value for `-bootstrap-expect`
or specify no value at all. Only servers that specify a value will attempt to bootstrap the cluster.
There is a [deployment table](/docs/internals/consensus.html#toc_4) that covers various options,
but it is recommended to have 3 or 5 total servers per datacenter. A single server deployment is _**highly**_
discouraged as data loss is inevitable in a failure scenario.
We recommend 3 or 5 total servers per datacenter. A single server deployment is _**highly**_ discouraged
as data loss is inevitable in a failure scenario. Please refer to the
[deployment table](/docs/internals/consensus.html#toc_4) for more detail.
Suppose we are starting a 3 server cluster, we can start `Node A`, `Node B` and `Node C` providing
the `-bootstrap-expect 3` flag. Once the nodes are started, you should see a message to the effect of:
Suppose we are starting a 3 server cluster. We can start `Node A`, `Node B`, and `Node C` with each
providing the `-bootstrap-expect 3` flag. Once the nodes are started, you should see a message like:
```text
[WARN] raft: EnableSingleNode disabled, and no known peers. Aborting election.
```
This indicates that the nodes are expecting 2 peers, but none are known yet. The servers will not elect
themselves leader to prevent a split-brain. We can now join these machines together. Since a join operation
is symmetric it does not matter which node initiates it. From any node you can do the following:
This indicates that the nodes are expecting 2 peers but none are known yet. To provent a split-brain
scenario, the servers will not elect themselves leader.
To trigger leader election, we must join these machines together. Since a join operation is symmetric,
it does not matter which node initiates it.
From any node, you can do the following:
```text
$ consul join <Node A Address> <Node B Address> <Node C Address>
@ -54,21 +60,21 @@ Once the join is successful, one of the nodes will output something like:
As a sanity check, the `consul info` command is a useful tool. It can be used to
verify `raft.num_peers` is now 2, and you can view the latest log index under `raft.last_log_index`.
When running `consul info` on the followers, you should see `raft.last_log_index`
converge to the same value as the leader begins replication. That value represents the last
converge to the same value once the leader begins replication. That value represents the last
log entry that has been stored on disk.
Now that the servers are all started and replicating to each other, all the remaining
clients can be joined. Clients are much easier, as they can be started and perform
a `join` against any existing node. All nodes participate in a gossip protocol to
perform basic discovery, so clients will automatically find the servers and register
themselves.
clients can be joined. Clients are much easier as they can join against any existing node.
All nodes participate in a gossip protocol to perform basic discovery, so once joined to any
member of the cluster, new clients will automatically find the servers and register themselves.
It should be noted that it is not strictly necessary to start the server nodes
before the clients, however most operations will fail until the servers are available.
Note: it is not strictly necessary to start the server nodes before the clients; however, most
operations will fail until the servers are available.
## Manual Bootstrapping
In versions of Consul previous to 0.4, bootstrapping was a more manual process.
For a guide on using the `-bootstrap` flag directly, see the [manual bootstrapping guide](/docs/guides/manual-bootstrap.html).
In versions of Consul prior to 0.4, bootstrapping was a more manual process. For details on
using the `-bootstrap` flag directly, see the [manual bootstrapping guide](/docs/guides/manual-bootstrap.html).
This is not recommended, as it is more error prone than automatic bootstrapping.
Manual bootstrapping is not recommended as it is more error-prone than automatic bootstrapping
with `-bootstrap-expect`.