diff --git a/website/source/docs/agent/basics.html.markdown b/website/source/docs/agent/basics.html.markdown index 31e39b803c..106e610f5f 100644 --- a/website/source/docs/agent/basics.html.markdown +++ b/website/source/docs/agent/basics.html.markdown @@ -13,7 +13,7 @@ information, registers services, runs checks, responds to queries, and more. The agent must run on every node that is part of a Consul cluster. Any agent may run in one of two modes: client or server. A server -node takes on the additional responsibility of being part of the [consensus quorum](#). +node takes on the additional responsibility of being part of the [consensus quorum](/docs/internals/consensus.html). These nodes take part in Raft and provide strong consistency and availability in the case of failure. The higher burden on the server nodes means that usually they should be run on dedicated instances -- they are more resource intensive than a client @@ -23,11 +23,11 @@ of their own. ## Running an Agent -The agent is started with the `consul agent` command. This command blocks, -running forever or until told to quit. The agent command takes a variety +The agent is started with the [`consul agent`](/docs/commands/agent.html) command. This +command blocks, running forever or until told to quit. The agent command takes a variety of configuration options, but most have sane defaults. -When running `consul agent`, you should see output similar to this: +When running [`consul agent`](/docs/commands/agent.html), you should see output similar to this: ```text $ consul agent -data-dir=/tmp/consul @@ -47,10 +47,11 @@ $ consul agent -data-dir=/tmp/consul ... ``` -There are several important messages that `consul agent` outputs: +There are several important messages that [`consul agent`](/docs/commands/agent.html) outputs: * **Node name**: This is a unique name for the agent. By default, this - is the hostname of the machine, but you may customize it using the `-node` flag. + is the hostname of the machine, but you may customize it using the + [`-node`](/docs/agent/options.html#_node) flag. * **Datacenter**: This is the datacenter in which the agent is configured to run. Consul has first-class support for multiple datacenters; however, to work efficiently, @@ -61,8 +62,8 @@ There are several important messages that `consul agent` outputs: * **Server**: This indicates whether the agent is running in server or client mode. Server nodes have the extra burden of participating in the consensus quorum, storing cluster state, and handling queries. Additionally, a server may be - in "bootstrap" mode. Multiple servers cannot be in bootstrap mode as that would - put the cluster in an inconsistent state. + in ["bootstrap"](/docs/agent/options.html#_bootstrap_expect) mode. Multiple servers + cannot be in bootstrap mode as that would put the cluster in an inconsistent state. * **Client Addr**: This is the address used for client interfaces to the agent. This includes the ports for the HTTP, DNS, and RPC interfaces. The RPC @@ -112,7 +113,8 @@ this lifecycle is useful for building a mental model of an agent's interactions with a cluster and how the cluster treats a node. When an agent is first started, it does not know about any other node in the cluster. -To discover its peers, it must _join_ the cluster. This is done with the `join` +To discover its peers, it must _join_ the cluster. This is done with the +[`join`](/docs/commands/join.html) command or by providing the proper configuration to auto-join on start. Once a node joins, this information is gossiped to the entire cluster, meaning all nodes will eventually be aware of each other. If the agent is a server, existing servers will diff --git a/website/source/docs/agent/options.html.markdown b/website/source/docs/agent/options.html.markdown index 16fa37a44c..d0e3b950e2 100644 --- a/website/source/docs/agent/options.html.markdown +++ b/website/source/docs/agent/options.html.markdown @@ -67,7 +67,7 @@ The options below are all specified on the command-line. Either this value should not be provided or the value must agree with other servers in the cluster. When provided, Consul waits until the specified number of servers are available and then bootstraps the cluster. This allows an initial leader to be elected - automatically. This cannot be used in conjunction with the [`-bootstrap`](#_bootstrap) flag. + automatically. This cannot be used in conjunction with the legacy [`-bootstrap`](#_bootstrap) flag. * `-bind` - The address that should be bound to for internal cluster communications. diff --git a/website/source/docs/guides/bootstrapping.html.markdown b/website/source/docs/guides/bootstrapping.html.markdown index d346d967b2..009234d29a 100644 --- a/website/source/docs/guides/bootstrapping.html.markdown +++ b/website/source/docs/guides/bootstrapping.html.markdown @@ -16,11 +16,12 @@ Before a Consul cluster can begin to service requests, a server node must be ele 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 option informs Consul of the expected number of +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` +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 @@ -57,9 +58,9 @@ Once the join is successful, one of the nodes will output something like: [INFO] consul: cluster leadership acquired ``` -As a sanity check, the `consul info` command is a useful tool. It can be used to +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` on the followers, you should see `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. @@ -74,7 +75,8 @@ 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` flag directly, see the [manual bootstrapping guide](/docs/guides/manual-bootstrap.html). +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`. +with [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect).