mirror of https://github.com/status-im/consul.git
[docs] Bootstrapping Guide -> Install docs (#5473)
* moved the bootstrapping guide to the docs. * More edits for consistency. * Added arch link
This commit is contained in:
kaitlincarter-hc
GitHub
parent
a7528db560
commit
1333bfe324
|
|
@ -1,99 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Bootstrapping"
|
||||
sidebar_current: "docs-guides-bootstrapping"
|
||||
description: |-
|
||||
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
|
||||
|
||||
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 initial server nodes into a cluster.
|
||||
|
||||
The recommended way to bootstrap is to use the [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
|
||||
configuration option. 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`](/docs/agent/options.html#_bootstrap_expect)
|
||||
or specify no value at all. Only servers that specify a value will attempt to bootstrap the cluster.
|
||||
|
||||
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#deployment-table) for more detail.
|
||||
|
||||
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. To prevent a split-brain
|
||||
scenario, the servers will not elect themselves leader.
|
||||
|
||||
## Creating the cluster
|
||||
|
||||
To trigger leader election, we must join these machines together and create a cluster. There are multiple options for joining the machines:
|
||||
|
||||
- Manually specified list of machines with
|
||||
[-join](/docs/agent/options.html#_join) and
|
||||
[start_join](https://www.consul.io/docs/agent/options.html#start_join)
|
||||
options
|
||||
- Manually specified list of machines with [-retry-join](https://www.consul.io/docs/agent/options.html#_retry_join) option
|
||||
- Automatic joining by tag for supported cloud environments with the [-retry-join](https://www.consul.io/docs/agent/options.html#_retry_join) option
|
||||
|
||||
Choose the method which best suits your environment and specific use case.
|
||||
|
||||
### Manually Creating a Cluster
|
||||
|
||||
To manually create a cluster, access one of the machines and run the following:
|
||||
|
||||
```
|
||||
$ consul join <Node A Address> <Node B Address> <Node C Address>
|
||||
Successfully joined cluster by contacting 3 nodes.
|
||||
```
|
||||
|
||||
Since a join operation is symmetric, it does not matter which node initiates it. Once the join is successful, one of the nodes will output something like:
|
||||
|
||||
```
|
||||
[INFO] consul: adding server foo (Addr: 127.0.0.2:8300) (DC: dc1)
|
||||
[INFO] consul: adding server bar (Addr: 127.0.0.1:8300) (DC: dc1)
|
||||
[INFO] consul: Attempting bootstrap with nodes: [127.0.0.3:8300 127.0.0.2:8300 127.0.0.1:8300]
|
||||
...
|
||||
[INFO] consul: cluster leadership acquired
|
||||
```
|
||||
|
||||
## Verifying the Cluster
|
||||
|
||||
As a sanity check, the [`consul info`](/docs/commands/info.html) 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`](/docs/commands/info.html) on the followers, you
|
||||
should see `raft.last_log_index` 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
|
||||
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.
|
||||
|
||||
-> **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 prior to 0.4, bootstrapping was a more manual process. For details on
|
||||
using the [`-bootstrap`](/docs/agent/options.html#_bootstrap) flag directly, see the
|
||||
[manual bootstrapping guide](/docs/guides/manual-bootstrap.html).
|
||||
|
||||
Manual bootstrapping is not recommended as it is more error-prone than automatic bootstrapping
|
||||
with [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect).
|
||||
|
|
@ -22,8 +22,6 @@ The following guides are available:
|
|||
|
||||
* [Autopilot](https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/autopilot) - This guide covers Autopilot, which provides automatic operator-friendly management of Consul servers.
|
||||
|
||||
* [Bootstrapping](/docs/guides/bootstrapping.html) - This guide covers bootstrapping a new datacenter. This covers safely adding the initial Consul servers.
|
||||
|
||||
* [Connect in Production](/docs/guides/connect-production.html) - This guide describes critical aspects of operating Consul Connect in Production.
|
||||
|
||||
* [Connect with Envoy](/docs/guides/connect-envoy.html) - This guide will describe how to setup a development-mode Consul server and two Envoy proxies on a single machine using Docker.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Bootstrapping a Datacenter"
|
||||
sidebar_current: "docs-install-bootstrapping"
|
||||
description: |-
|
||||
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
|
||||
|
||||
An agent can run in either client or 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. Bootstrapping is the process
|
||||
of joining these initial server nodes into a cluster. Read the
|
||||
[architecture documentation](/docs/internals/architecture.html) to learn more about
|
||||
the internals of Consul.
|
||||
|
||||
It is recommended to have three or five 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#deployment-table) for more detail.
|
||||
|
||||
~> **Note**: In versions of Consul prior to 0.4, bootstrapping was a manual process. For details on using the `-bootstrap` flag directly, see the
|
||||
[manual bootstrapping guide](/docs/install/manual-bootstrap.html).
|
||||
Manual bootstrapping with `-bootstrap` is not recommended in
|
||||
newer versions of Consul (0.5 and newer) as it is more error-prone.
|
||||
Instead you should use automatic bootstrapping
|
||||
with [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect).
|
||||
|
||||
## Bootstrapping the Servers
|
||||
|
||||
The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
|
||||
configuration option. 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 (clusters where multiple servers consider
|
||||
themselves leader) situations, you should either specify the same value for
|
||||
[`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
|
||||
or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster.
|
||||
|
||||
Suppose we are starting a three 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 warning message in the service output.
|
||||
|
||||
```text
|
||||
[WARN] raft: EnableSingleNode disabled, and no known peers. Aborting election.
|
||||
```
|
||||
|
||||
The warning indicates that the nodes are expecting 2 peers but none are known yet. Below you will learn how to connect the servers so that one can be
|
||||
elected leader.
|
||||
|
||||
## Creating the Cluster
|
||||
|
||||
You can trigger leader election by joining the servers together, to create a cluster. You can either configure the nodes to join automatically or manually.
|
||||
|
||||
### Automatically Join the Servers
|
||||
|
||||
There are multiple options for joining the servers. Choose the method which best suits your environment and specific use case.
|
||||
|
||||
- Specify a list of servers with
|
||||
[-join](/docs/agent/options.html#_join) and
|
||||
[start_join](https://www.consul.io/docs/agent/options.html#start_join)
|
||||
options.
|
||||
- Specify a list of servers with [-retry-join](https://www.consul.io/docs/agent/options.html#_retry_join) option.
|
||||
- Use automatic joining by tag for supported cloud environments with the [-retry-join](https://www.consul.io/docs/agent/options.html#_retry_join) option.
|
||||
|
||||
All three methods can be set in the agent configuration file or
|
||||
the command line flag.
|
||||
|
||||
### Manually Join the Servers
|
||||
|
||||
To manually create a cluster, you should connect to one of the servers
|
||||
and run the `consul join` command.
|
||||
|
||||
```
|
||||
$ consul join <Node A Address> <Node B Address> <Node C Address>
|
||||
Successfully joined cluster by contacting 3 nodes.
|
||||
```
|
||||
|
||||
Since a join operation is symmetric, it does not matter which node initiates it. Once the join is successful, one of the nodes will output something like:
|
||||
|
||||
```
|
||||
[INFO] consul: adding server foo (Addr: 127.0.0.2:8300) (DC: dc1)
|
||||
[INFO] consul: adding server bar (Addr: 127.0.0.1:8300) (DC: dc1)
|
||||
[INFO] consul: Attempting bootstrap with nodes: [127.0.0.3:8300 127.0.0.2:8300 127.0.0.1:8300]
|
||||
...
|
||||
[INFO] consul: cluster leadership acquired
|
||||
```
|
||||
|
||||
### Verifying the Cluster and Connect the Clients
|
||||
|
||||
As a sanity check, the [`consul info`](/docs/commands/info.html) command
|
||||
is a useful tool. It can be used to verify the `raft.num_peers`
|
||||
and to view the latest log index under `raft.last_log_index`. When
|
||||
running [`consul info`](/docs/commands/info.html) on the followers, you
|
||||
should see `raft.last_log_index` 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, you can
|
||||
join the clients with the same join method you used for the servers.
|
||||
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.
|
||||
|
||||
-> **Note:** It is not strictly necessary to start the server nodes before the clients; however, most operations will fail until the servers are available.
|
||||
|
||||
|
||||
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Manual Bootstrapping"
|
||||
sidebar_current: "docs-guides-bootstrapping"
|
||||
sidebar_current: "docs-install-bootstrapping"
|
||||
description: |-
|
||||
When deploying Consul to a datacenter for the first time, there is an initial bootstrapping that must be done. As of Consul 0.4, an automatic bootstrapping is available and is the recommended approach. However, older versions only support a manual bootstrap that is documented here.
|
||||
---
|
||||
|
|
@ -7,6 +7,9 @@
|
|||
<li<%= sidebar_current("docs-install-ports") %>>
|
||||
<a href="/docs/install/ports.html">Required Ports</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-install-bootstrapping") %>>
|
||||
<a href="/docs/install/bootstrapping.html">Bootstrapping a Datacenter</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
|
|
@ -411,9 +414,6 @@
|
|||
<li<%= sidebar_current("docs-guides-autopilot") %>>
|
||||
<a href="https://learn.hashicorp.com/consul/day-2-operations/advanced-operations/autopilot">Autopilot</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-guides-bootstrapping") %>>
|
||||
<a href="/docs/guides/bootstrapping.html">Bootstrapping</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-guides-connect-production") %>>
|
||||
<a href="/docs/guides/connect-production.html">Connect in Production</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue