status-im/consul
2
0
Fork 0
mirror of https://github.com/status-im/consul.git synced 2025-01-11 14:24:39 +00:00
Code Issues Projects Releases Wiki Activity

Website: Add links to options and commands referenced in docs/agent/basics.html and docs/guide/bootstrapping.html.

Browse Source
This commit is contained in:
Ryan Breen 2015-02-24 14:11:11 -05:00
parent f41dce97fd
commit b9e72887e9
3 changed files with 21 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
website/source/docs/agent/basics.html.markdown
View File

@ -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. 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 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 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 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 should be run on dedicated instances -- they are more resource intensive than a client
@ -23,11 +23,11 @@ of their own.
## Running an Agent ## Running an Agent
The agent is started with the `consul agent` command. This command blocks, The agent is started with the [`consul agent`](/docs/commands/agent.html) command. This
running forever or until told to quit. The agent command takes a variety command blocks, running forever or until told to quit. The agent command takes a variety
of configuration options, but most have sane defaults. 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 ```text
$ consul agent -data-dir=/tmp/consul $ 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 * **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. * **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, 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**: This indicates whether the agent is running in server or client mode.
Server nodes have the extra burden of participating in the consensus quorum, Server nodes have the extra burden of participating in the consensus quorum,
storing cluster state, and handling queries. Additionally, a server may be storing cluster state, and handling queries. Additionally, a server may be
in "bootstrap" mode. Multiple servers cannot be in bootstrap mode as that would in ["bootstrap"](/docs/agent/options.html#_bootstrap_expect) mode. Multiple servers
put the cluster in an inconsistent state. 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. * **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 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. 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. 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 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 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 eventually be aware of each other. If the agent is a server, existing servers will

2
website/source/docs/agent/options.html.markdown
View File

@ -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 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 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 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.
* <a name="_bind"></a><a href="#_bind">`-bind`</a> - The address that should be bound to * <a name="_bind"></a><a href="#_bind">`-bind`</a> - The address that should be bound to
for internal cluster communications. for internal cluster communications.

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

@ -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 Thus, the first nodes that are started are generally the server nodes. Bootstrapping is the process
of joining these server nodes into a cluster. of joining these server nodes into a cluster.
The recommended way to bootstrap is to use the `-bootstrap-expect` [configuration The recommended way to bootstrap is to use the [`-bootstrap-expect`](/docs/agent/options.html#_bootstrap_expect)
option](/docs/agent/options.html). This option informs Consul of the expected number of configuration option. This option informs Consul of the expected number of
server nodes and automatically bootstraps when that many servers are available. To prevent 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 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. 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 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 [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`. 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 converge to the same value once the leader begins replication. That value represents the last
log entry that has been stored on disk. log entry that has been stored on disk.
@ -74,7 +75,8 @@ operations will fail until the servers are available.
## Manual Bootstrapping ## Manual Bootstrapping
In versions of Consul prior to 0.4, bootstrapping was a more manual process. For details on 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 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).