open-consul/website/source/docs/agent/basics.html.markdown

142 lines
7.2 KiB
Markdown
Raw Normal View History

2014-02-08 00:41:03 +00:00
---
layout: "docs"
page_title: "Agent"
sidebar_current: "docs-agent-running"
description: |-
2015-01-30 19:48:20 +00:00
The Consul agent is the core process of Consul. The agent maintains membership information, registers services, runs checks, responds to queries, and more. The agent must run on every node that is part of a Consul cluster.
2014-02-08 00:41:03 +00:00
---
2014-02-18 23:30:07 +00:00
# Consul Agent
2014-02-08 00:41:03 +00:00
2014-02-18 23:30:07 +00:00
The Consul agent is the core process of Consul. The agent maintains membership
2015-01-30 19:48:20 +00:00
information, registers services, runs checks, responds to queries,
2014-02-18 23:30:07 +00:00
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](/docs/internals/consensus.html).
2015-01-30 19:48:20 +00:00
These nodes take part in Raft and provide strong consistency and availability in
2014-02-18 23:30:07 +00:00
the case of failure. The higher burden on the server nodes means that usually they
2015-01-30 19:48:20 +00:00
should be run on dedicated instances -- they are more resource intensive than a client
2014-02-18 23:30:07 +00:00
node. Client nodes make up the majority of the cluster, and they are very lightweight
2015-01-30 19:48:20 +00:00
as they interface with the server nodes for most operations and maintain very little state
of their own.
2014-02-08 00:41:03 +00:00
## Running an Agent
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
2015-01-30 19:48:20 +00:00
of configuration options, but most have sane defaults.
When running [`consul agent`](/docs/commands/agent.html), you should see output similar to this:
2014-02-08 00:41:03 +00:00
```text
2014-04-17 18:31:25 +00:00
$ consul agent -data-dir=/tmp/consul
2014-02-18 23:30:07 +00:00
==> Starting Consul agent...
==> Starting Consul agent RPC...
==> Consul agent running!
2014-04-11 23:23:16 +00:00
Node name: 'Armons-MacBook-Air'
Datacenter: 'dc1'
Server: false (bootstrap: false)
Client Addr: 127.0.0.1 (HTTP: 8500, DNS: 8600, RPC: 8400)
Cluster Addr: 192.168.1.43 (LAN: 8301, WAN: 8302)
2015-02-07 00:34:07 +00:00
Atlas: (Infrastructure: 'hashicorp/test' Join: true)
2014-02-08 00:41:03 +00:00
==> Log data will now stream in as it occurs:
2014-04-11 23:23:16 +00:00
[INFO] serf: EventMemberJoin: Armons-MacBook-Air.local 192.168.1.43
2014-02-08 00:41:03 +00:00
...
```
There are several important messages that [`consul agent`](/docs/commands/agent.html) outputs:
2014-02-08 00:41:03 +00:00
2015-01-30 19:48:20 +00:00
* **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`](/docs/agent/options.html#_node) flag.
2014-02-08 00:41:03 +00:00
2015-01-30 19:48:20 +00:00
* **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,
each node must be configured to report its datacenter. The [`-dc`](/docs/agent/options.html#_dc) flag
2014-02-18 23:30:07 +00:00
can be used to set the datacenter. For single-DC configurations, the agent
will default to "dc1".
2015-01-30 19:48:20 +00:00
* **Server**: This indicates whether the agent is running in server or client mode.
2014-02-18 23:30:07 +00:00
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"](/docs/agent/options.html#_bootstrap_expect) mode. Multiple servers
cannot be in bootstrap mode as that would put the cluster in an inconsistent state.
2014-02-08 00:41:03 +00:00
* **Client Addr**: This is the address used for client interfaces to the agent.
2014-04-11 23:23:16 +00:00
This includes the ports for the HTTP, DNS, and RPC interfaces. The RPC
address is used by other `consul` commands (such as
[`consul members`](/docs/commands/members.html), [`consul join`](/docs/commands/join.html),
2015-01-30 19:48:20 +00:00
etc) which query and control a running agent. By default, this binds only to localhost. If you
change this address or port, you'll have to specify a `-rpc-addr` whenever you run
commands such as [`consul members`](/docs/commands/members.html) to indicate how to
reach the agent. Other applications can also use the RPC address and port
[to control Consul](/docs/agent/rpc.html).
2014-04-11 23:23:16 +00:00
2015-01-30 19:48:20 +00:00
* **Cluster Addr**: This is the address and set of ports used for communication between
2014-11-26 13:15:41 +00:00
Consul agents in a cluster. Not all Consul agents in a cluster have to
2014-04-11 23:23:16 +00:00
use the same port, but this address **MUST** be reachable by all other nodes.
2015-02-07 00:34:07 +00:00
* **Atlas**: This shows the [Atlas infrastructure](https://atlas.hashicorp.com)
with which the node is registered. It also indicates if auto-join is enabled.
The Atlas infrastructure is set using [`-atlas`](/docs/agent/options.html#_atlas)
and auto-join is enabled by setting [`-atlas-join`](/docs/agent/options.html#_atlas_join).
2015-02-07 00:34:07 +00:00
2014-02-08 00:41:03 +00:00
## Stopping an Agent
An agent can be stopped in two ways: gracefully or forcefully. To gracefully
2015-01-30 19:48:20 +00:00
halt an agent, send the process an interrupt signal (usually
2015-04-07 08:15:48 +00:00
`Ctrl-C` from a terminal or running `kill -INT consul_pid` ). When gracefully exiting, the agent first notifies
2014-02-08 00:41:03 +00:00
the cluster it intends to leave the cluster. This way, other cluster members
notify the cluster that the node has _left_.
Alternatively, you can force kill the agent by sending it a kill signal.
When force killed, the agent ends immediately. The rest of the cluster will
2015-01-30 19:48:20 +00:00
eventually (usually within seconds) detect that the node has died and
2014-02-08 00:41:03 +00:00
notify the cluster that the node has _failed_.
2015-01-30 19:48:20 +00:00
It is especially important that a server node be allowed to leave gracefully
so that there will be a minimal impact on availability as the server leaves
2014-02-18 23:30:07 +00:00
the consensus quorum.
For client agents, the difference between a node _failing_ and a node _leaving_
may not be important for your use case. For example, for a web server and load
2015-01-30 19:48:20 +00:00
balancer setup, both result in the same outcome: the web node is removed
from the load balancer pool.
## Lifecycle
Every agent in the Consul cluster goes through a lifecycle. Understanding
2015-01-30 19:48:20 +00:00
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`](/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
begin replicating to the new node.
In the case of a network failure, some nodes may be unreachable by other nodes.
In this case, unreachable nodes are marked as _failed_. It is impossible to distinguish
between a network failure and an agent crash, so both cases are handled the same.
Once a node is marked as failed, this information is updated in the service catalog.
2015-01-30 19:48:20 +00:00
Mote: there is some nuance here since this update is only possible if the servers can
still [form a quorum](/docs/internals/consensus.html). Once the network recovers
or a crashed agent restarts the cluster will repair itself and unmark
2014-11-26 13:15:41 +00:00
a node as failed. The health check in the catalog will also be updated to reflect
this.
2015-01-30 19:48:20 +00:00
When a node _leaves_, it specifies its intent to do so, and the cluster
marks that node as having _left_. Unlike the _failed_ case, all of the
services provided by a node are immediately deregistered. If the agent was
a server, replication to it will stop. To prevent an accumulation
of dead nodes, Consul will automatically reap _failed_ nodes out of the
2014-11-26 13:15:41 +00:00
catalog as well. This is currently done on a non-configurable interval of
72 hours. Reaping is similar to leaving, causing all associated services
to be deregistered.