diff --git a/website/source/intro/getting-started/agent.html.markdown b/website/source/intro/getting-started/agent.html.markdown index 27dced736..78a44ef85 100644 --- a/website/source/intro/getting-started/agent.html.markdown +++ b/website/source/intro/getting-started/agent.html.markdown @@ -12,10 +12,11 @@ After Consul is installed, the agent must be run. The agent can run either in server or client mode. Each datacenter must have at least one server, although 3 or 5 is recommended. A single server deployment is _**highly**_ discouraged as data loss is inevitable in a failure scenario. [This guide](/docs/guides/bootstrapping.html) -covers bootstrapping a new datacenter. All other agents run in client mode, which -is a very lightweight process that registers services, runs health checks, -and forwards queries to servers. The agent must be run for every node that -will be part of the cluster. +covers bootstrapping a new datacenter. + +All other agents run in client mode, a very lightweight +process that registers services, runs health checks, and forwards queries to +servers. The agent must be run on every node that is part of the cluster. ## Starting the Agent @@ -51,7 +52,7 @@ $ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul ``` As you can see, the Consul agent has started and has output some log -data. From the log data, you can see that our agent is running in server mode, +data. From the log data, you can see that our agent is running in server mode and has claimed leadership of the cluster. Additionally, the local member has been marked as a healthy member of the cluster. @@ -63,24 +64,25 @@ the name of your node with the `-node` flag. ## Cluster Members If you run `consul members` in another terminal, you can see the members of -the Consul cluster. You should only see one member (yourself). We'll cover -joining clusters in the next section. +the Consul cluster. We'll cover joining clusters in the next section, but for now, +you should only see one member (yourself): ```text $ consul members Node Address Status Type Build Protocol -Armons-MacBook-Air 10.1.10.38:8301 alive server 0.3.0 2 +Armons-MacBook-Air 10.1.10.38:8301 alive server 0.5.1 2 ``` The output shows our own node, the address it is running on, its -health state, its role in the cluster, as well as some versioning information. +health state, its role in the cluster, and some version information. Additional metadata can be viewed by providing the `-detailed` flag. -The output from the `members` command is generated based on the +The output of the `members` command is based on the [gossip protocol](/docs/internals/gossip.html) and is eventually consistent. -For a strongly consistent view of the world, use the -[HTTP API](/docs/agent/http.html), which forwards the request to the -Consul servers: +That is, at any point in time, the view of the world as seen by your local +agent may not exactly match the state on the servers. For a strongly consistent +view of the world, use the [HTTP API](/docs/agent/http.html) as it forwards the +request to the Consul servers: ```text $ curl localhost:8500/v1/catalog/nodes @@ -90,8 +92,9 @@ $ curl localhost:8500/v1/catalog/nodes In addition to the HTTP API, the [DNS interface](/docs/agent/dns.html) can be used to query the node. Note that you have to make sure to point your DNS lookups to the Consul agent's -DNS server, which runs on port 8600 by default. The format of the DNS -entries (such as "Armons-MacBook-Air.node.consul") will be covered later. +DNS server which runs on port 8600 by default. The format of the DNS +entries (such as "Armons-MacBook-Air.node.consul") will be covered in more +detail later. ```text $ dig @127.0.0.1 -p 8600 Armons-MacBook-Air.node.consul @@ -107,7 +110,7 @@ Armons-MacBook-Air.node.consul. 0 IN A 10.1.10.38 ## Stopping the Agent You can use `Ctrl-C` (the interrupt signal) to gracefully halt the agent. -After interrupting the agent, you should see it leave the cluster gracefully +After interrupting the agent, you should see it leave the cluster and shut down. By gracefully leaving, Consul notifies other cluster members that the @@ -115,10 +118,10 @@ node _left_. If you had forcibly killed the agent process, other members of the cluster would have detected that the node _failed_. When a member leaves, its services and checks are removed from the catalog. When a member fails, its health is simply marked as critical, but it is not removed from the catalog. -Consul will automatically try to reconnect to _failed_ nodes, which allows it +Consul will automatically try to reconnect to _failed_ nodes, allowing it to recover from certain network conditions, while _left_ nodes are no longer contacted. Additionally, if an agent is operating as a server, a graceful leave is important to avoid causing a potential availability outage affecting the [consensus protocol](/docs/internals/consensus.html). -See the [guides section](/docs/guides/index.html) for how to safely add +See the [guides section](/docs/guides/index.html) for details on how to safely add and remove servers.