Merge pull request #2910 from hashicorp/jbs-2867

Docs: update bootstrapping and config, fixes #2867

website/source/docs/agent/options.html.markdown

@@ -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
+~> **Notice:** The hosted version of Consul Enterprise was deprecated on
-  March 7th, 2017. For details, see https://atlas.hashicorp.com/help/consul/alternatives
+  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.

website/source/docs/guides/bootstrapping.html.markdown

@@ -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
+Choose the method which best suits your environment and specific use case.
-$ consul agent -server -data-dir="/tmp/consul" -bootstrap-expect 3 \
-   -atlas=ATLAS_USERNAME/infrastructure \
-   -atlas-join \
-   -atlas-token="YOUR_ATLAS_TOKEN"
-```
 
-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