luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity

Merge pull request #713 from ryanbreen/agent 

Website: cleanup for getting-started/agent
This commit is contained in:
Ryan Breen 2015-02-19 17:40:25 -05:00
parent fe150743eb 0730e0dfe4
commit bdd694fcdf
1 changed files with 21 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
website/source/intro/getting-started/agent.html.markdown
View File

@ -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.