Merge pull request #2910 from hashicorp/jbs-2867

Docs: update bootstrapping and config, fixes #2867
This commit is contained in:
James Phillips 2017-04-13 12:26:27 -07:00 committed by GitHub
commit ef6a42ade2
2 changed files with 29 additions and 16 deletions

View File

@ -59,8 +59,8 @@ The options below are all specified on the command-line.
address when being accessed from a remote datacenter if the remote datacenter is configured
with <a href="#translate_wan_addrs">`translate_wan_addrs`</a>.
~> **Notice:** The hosted version of Consul Enterprise will be deprecated on
March 7th, 2017. For details, see https://atlas.hashicorp.com/help/consul/alternatives
~> **Notice:** The hosted version of Consul Enterprise was deprecated on
March 7th, 2017. For details, see https://atlas.hashicorp.com/help/consul/alternatives.
* <a name="_atlas"></a><a href="#_atlas">`-atlas`</a> - This flag
enables [Atlas](https://atlas.hashicorp.com) integration.
@ -198,6 +198,10 @@ will exit with an error at startup.
specified multiple times to specify multiple agents to join. If Consul is
unable to join with any of the specified addresses, agent startup will
fail. By default, the agent won't join any nodes when it starts up.
Note that using
<a href="#retry_join">`retry_join`</a> could be more appropriate to help
mitigate node startup race conditions when automating a Consul cluster
deployment.\
* <a name="_retry_join"></a><a href="#_retry_join">`-retry-join`</a> - Similar
to [`-join`](#_join) but allows retrying a join if the first
@ -924,7 +928,10 @@ Consul will not enable TLS for the HTTP API unless the `https` port has been ass
quorum, and Ctrl-C on a client will gracefully leave).
* <a name="start_join"></a><a href="#start_join">`start_join`</a> An array of strings specifying addresses
of nodes to [`-join`](#_join) upon startup.
of nodes to [`-join`](#_join) upon startup. Note that using
<a href="#retry_join">`retry_join`</a> could be more appropriate to help
mitigate node startup race conditions when automating a Consul cluster
deployment.
* <a name="start_join_wan"></a><a href="#start_join_wan">`start_join_wan`</a> An array of strings specifying
addresses of WAN nodes to [`-join-wan`](#_join_wan) upon startup.

View File

@ -38,31 +38,35 @@ providing the `-bootstrap-expect 3` flag. Once the nodes are started, you should
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 a cluster
## Creating the cluster
To trigger leader election, we must join these machines together and create a cluster. There are two options for joining; you can use [Atlas by HashiCorp](https://atlas.hashicorp.com?utm_source=oss&utm_medium=guide-bootstrapping&utm_campaign=consul) to auto-join or you can access the machine and manually run the join.
To trigger leader election, we must join these machines together and create a cluster. There are multiple options for joining the machines:
For auto-join using Atlas, you must set three configurations — the name of your Atlas infrastructure with the [`-atlas` flag](/docs/agent/options.html#_atlas), your Atlas token with the [`-atlas-token` CLI flag](/docs/agent/options.html#_atlas_token), and the [`-atlas-join` flag](/docs/agent/options.html#_atlas_join). Below is an example configuration:
- 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 AWS EC2 instance joining with the [-retry-join-ec2-*](https://www.consul.io/docs/agent/options.html#_retry_join_ec2_tag_key) options
- Automatic GCE instance joining with the [-retry-join-gce-*](https://www.consul.io/docs/agent/options.html#_retry_join_gce_tag_value) options
```text
$ consul agent -server -data-dir="/tmp/consul" -bootstrap-expect 3 \
-atlas=ATLAS_USERNAME/infrastructure \
-atlas-join \
-atlas-token="YOUR_ATLAS_TOKEN"
```
Choose the method which best suits your environment and specific use case.
To get an Atlas username and token, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=guide-bootstrapping&utm_campaign=consul) and replace the respective values in your Consul configuration with your credentials.
~> **Notice:** The hosted version of Consul Enterprise was deprecated on
March 7th, 2017 and the Atlas `auto-join` feature is no longer available. For details, see https://atlas.hashicorp.com/help/consul/alternatives.
### Manually Creating a Cluster
To manually create a cluster, access one of the machines and run the following:
```text
```
$ 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:
```text
```
[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]
@ -70,6 +74,8 @@ Since a join operation is symmetric, it does not matter which node initiates it.
[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