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

website: add docs for dev mode

This commit is contained in:
Ryan Uber 2015-12-27 09:45:59 -06:00
parent 689698eefa
commit 579a08ec20
4 changed files with 73 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -124,6 +124,12 @@ The options below are all specified on the command-line.
the use of filesystem locking, meaning some types of mounted folders (e.g. VirtualBox
shared folders) may not be suitable.
* <a name="_dev"></a><a href="#_dev">`-dev`</a> - Enable development server
mode. This is useful for quickly starting a Consul agent with all persistence
options turned off, enabling an in-memory server which can be used for rapid
prototyping or developing against the API. This mode is **not** intended for
production use as it does not write any data to disk.
* <a name="_dc"></a><a href="#_dc">`-dc`</a> - This flag controls the datacenter in
which the agent is running. If not provided,
it defaults to "dc1". Consul has first-class support for multiple datacenters, but

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

@ -2,8 +2,11 @@
layout: "intro"
page_title: "Run the Agent"
sidebar_current: "gettingstarted-agent"
description: |-
After Consul is installed, the agent must be run. The agent can either run in server or client mode. Each datacenter must have at least one server, though a cluster of 3 or 5 servers is recommended. A single server deployment is highly discouraged as data loss is inevitable in a failure scenario.
description: >
The Consul agent can run in either server or client mode. Each datacenter
must have at least one server, though a cluster of 3 or 5 servers is
recommended. A single server deployment is highly discouraged in production
as data loss is inevitable in a failure scenario.
---
# Run the Consul Agent
@ -22,34 +25,44 @@ For more detail on bootstrapping a datacenter, see
## Starting the Agent
For simplicity, we'll run a single Consul agent in server mode:
For simplicity, we'll start the Consul agent in development mode for now. This
mode is useful for bringing up a single-node Consul environment quickly and
easily. It is **not** intended to be used in production as it does not persist
any state.
```text
$ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul
==> WARNING: BootstrapExpect Mode is specified as 1; this is the same as Bootstrap mode.
==> WARNING: Bootstrap mode enabled! Do not enable unless necessary
==> Starting Consul agent...
==> Starting Consul agent RPC...
==> Consul agent running!
Node name: 'Armons-MacBook-Air'
Datacenter: 'dc1'
Server: true (bootstrap: true)
Client Addr: 127.0.0.1 (HTTP: 8500, DNS: 8600, RPC: 8400)
Cluster Addr: 10.1.10.38 (LAN: 8301, WAN: 8302)
Node name: 'Armons-MacBook-Air'
Datacenter: 'dc1'
Server: true (bootstrap: false)
Client Addr: 127.0.0.1 (HTTP: 8500, HTTPS: -1, DNS: 8600, RPC: 8400)
Cluster Addr: 172.20.20.11 (LAN: 8301, WAN: 8302)
Gossip encrypt: false, RPC-TLS: false, TLS-Incoming: false
Atlas: <disabled>
==> Log data will now stream in as it occurs:
[INFO] serf: EventMemberJoin: Armons-MacBook-Air.local 10.1.10.38
[INFO] raft: Node at 10.1.10.38:8300 [Follower] entering Follower state
[INFO] consul: adding server for datacenter: dc1, addr: 10.1.10.38:8300
[ERR] agent: failed to sync remote state: rpc error: No cluster leader
[INFO] raft: Node at 172.20.20.11:8300 [Follower] entering Follower state
[INFO] serf: EventMemberJoin: Armons-MacBook-Air 172.20.20.11
[INFO] consul: adding LAN server Armons-MacBook-Air (Addr: 172.20.20.11:8300) (DC: dc1)
[INFO] serf: EventMemberJoin: Armons-MacBook-Air.dc1 172.20.20.11
[INFO] consul: adding WAN server Armons-MacBook-Air.dc1 (Addr: 172.20.20.11:8300) (DC: dc1)
[ERR] agent: failed to sync remote state: No cluster leader
[WARN] raft: Heartbeat timeout reached, starting election
[INFO] raft: Node at 10.1.10.38:8300 [Candidate] entering Candidate state
[INFO] raft: Node at 172.20.20.11:8300 [Candidate] entering Candidate state
[DEBUG] raft: Votes needed: 1
[DEBUG] raft: Vote granted. Tally: 1
[INFO] raft: Election won. Tally: 1
[INFO] raft: Node at 10.1.10.38:8300 [Leader] entering Leader state
[INFO] raft: Node at 172.20.20.11:8300 [Leader] entering Leader state
[INFO] raft: Disabling EnableSingleNode (bootstrap)
[INFO] consul: cluster leadership acquired
[DEBUG] raft: Node 172.20.20.11:8300 updated peer set (2): [172.20.20.11:8300]
[DEBUG] consul: reset tombstone GC to index 2
[INFO] consul: New leader elected: Armons-MacBook-Air
[INFO] consul: member 'Armons-MacBook-Air' joined, marking health alive
[INFO] agent: Synced service 'consul'
```
As you can see, the Consul agent has started and has output some log
@ -70,8 +83,8 @@ 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.5.1 2
Node Address Status Type Build Protocol DC
Armons-MacBook-Air 172.20.20.11:8301 alive server 0.6.1dev 2 dc1
```
The output shows our own node, the address it is running on, its
@ -87,7 +100,7 @@ request to the Consul servers:
```text
$ curl localhost:8500/v1/catalog/nodes
[{"Node":"Armons-MacBook-Air","Address":"10.1.10.38"}]
[{"Node":"Armons-MacBook-Air","Address":"172.20.20.11","CreateIndex":3,"ModifyIndex":4}]
```
In addition to the HTTP API, the [DNS interface](/docs/agent/dns.html) can
@ -104,7 +117,7 @@ $ dig @127.0.0.1 -p 8600 Armons-MacBook-Air.node.consul
;Armons-MacBook-Air.node.consul. IN A
;; ANSWER SECTION:
Armons-MacBook-Air.node.consul. 0 IN A 10.1.10.38
Armons-MacBook-Air.node.consul. 0 IN A 172.20.20.11
```
## <a name="stopping"></a>Stopping the Agent

27
website/source/intro/getting-started/join.html.markdown
View File

@ -2,8 +2,11 @@
layout: "intro"
page_title: "Consul Cluster"
sidebar_current: "gettingstarted-join"
description: |-
We've started our first agent and registered and queried a service on that agent. This showed how easy it is to use Consul but didn't show how this could be extended to a scalable, production-grade service discovery infrastructure. In this step, we'll create our first real cluster with multiple members.
description: >
When a Consul agent is started, it begins as an isolated cluster of its own.
To learn about other cluster members, the agent just join one or more other
nodes using a provided join address. In this step, we will set up a two-node
cluster and join the nodes together.
---
# Consul Cluster
@ -40,6 +43,12 @@ of our cluster. We start by logging in to the first node:
$ vagrant ssh n1
```
In our previous examples, we used the [`-dev`
flag](/docs/agent/options.html#_dev) to quickly set up a development server.
However, this is not sufficient for use in a clustered environment. We will
omit the `-dev` flag from here on, and instead specify our clustering flags as
outlined below.
Each node in a cluster must have a unique name. By default, Consul uses the
hostname of the machine, but we'll manually override it using the [`-node`
command-line option](/docs/agent/options.html#_node).
@ -53,9 +62,17 @@ multiple interfaces, so specifying a `bind` address assures that you will
never bind Consul to the wrong interface.
The first node will act as our sole server in this cluster, and we indicate
this with the [`server` switch](/docs/agent/options.html#_server). Finally, we
add the [`config-dir` flag](/docs/agent/options.html#_config_dir), marking
where service and check definitions can be found.
this with the [`server` switch](/docs/agent/options.html#_server).
The [`-bootstrap-expect` flag](/docs/agent/options.html#_bootstrap_expect)
hints to the Consul server the number of additional server nodes we are
expecting to join. The purpose of this flag is to delay the bootstrapping of
the replicated log until the expected number of servers has successfully joined.
You can read more about this in the [bootstrapping
guide](/docs/guides/bootstrapping.html).
Finally, we add the [`config-dir` flag](/docs/agent/options.html#_config_dir),
marking where service and check definitions can be found.
All together, these settings yield a
[`consul agent`](/docs/commands/agent.html) command like this:

19
website/source/intro/getting-started/services.html.markdown
View File

@ -2,8 +2,11 @@
layout: "intro"
page_title: "Registering Services"
sidebar_current: "gettingstarted-services"
description: |-
In the previous step, we ran our first agent, saw the cluster members (well, our cluster member), and queried that node. Now, we'll register our first service and query that service.
description: >
A service can be registered either by providing a service definition or by
making the appropriate calls to the HTTP API. A configuration file is the
most common, so we will use this approach to register a service, and then
query that service using the REST API and DNS interfaces.
---
# Registering Services
@ -44,8 +47,7 @@ $ echo '{"service": {"name": "web", "tags": ["rails"], "port": 80}}' \
Now, restart the agent, providing the configuration directory:
```text
$ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul \
-config-dir /etc/consul.d
$ consul agent -dev -config-dir /etc/consul.d
==> Starting Consul agent...
...
[INFO] agent: Synced service 'web'
@ -53,7 +55,8 @@ $ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul \
```
You'll notice in the output that it "synced" the web service. This means
that it loaded the information from the configuration.
that the agent loaded the service definition from the configuration file,
and has successfully registered it in the service catalog.
If you wanted to register multiple services, you could create multiple
service definition files in the Consul configuration directory.
@ -97,13 +100,13 @@ $ dig @127.0.0.1 -p 8600 web.service.consul SRV
...
;; QUESTION SECTION:
;web.service.consul. IN SRV
;web.service.consul. IN SRV
;; ANSWER SECTION:
web.service.consul. 0 IN SRV 1 1 80 agent-one.node.dc1.consul.
web.service.consul. 0 IN SRV 1 1 80 Armons-MacBook-Air.node.dc1.consul.
;; ADDITIONAL SECTION:
agent-one.node.dc1.consul. 0 IN A 172.20.20.11
Armons-MacBook-Air.node.dc1.consul. 0 IN A 172.20.20.11
```
The `SRV` record says that the web service is running on port 80 and exists on