From def6d4d1063bf8dd0c58c1841ba1a5e646093b42 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Thu, 19 Feb 2015 17:12:56 -0500 Subject: [PATCH 1/3] Website: cleanup for getting-started/agent.html. --- .../intro/getting-started/agent.html.markdown | 45 ++++++++++--------- website/source/intro/index.html.markdown | 8 ++-- 2 files changed, 28 insertions(+), 25 deletions(-) diff --git a/website/source/intro/getting-started/agent.html.markdown b/website/source/intro/getting-started/agent.html.markdown index 27dced736..3d10e14f0 100644 --- a/website/source/intro/getting-started/agent.html.markdown +++ b/website/source/intro/getting-started/agent.html.markdown @@ -3,19 +3,20 @@ 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 a 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. + After Consul is installed, the agent must be run. The agent can either run in a server or client mode. Each data center 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. --- # Run the Consul Agent 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, +in server or client mode. Each data center 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. +as data loss is inevitable in a failure scenario. + +[This guide](/docs/guides/bootstrapping.html) covers bootstrapping a new +data center. 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) 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. diff --git a/website/source/intro/index.html.markdown b/website/source/intro/index.html.markdown index 40504803b..d7feff400 100644 --- a/website/source/intro/index.html.markdown +++ b/website/source/intro/index.html.markdown @@ -35,7 +35,7 @@ key features: store for any number of purposes, including dynamic configuration, feature flagging, coordination, leader election, and more. The simple HTTP API makes it easy to use. -* **Multi Datacenter**: Consul supports multiple datacenters out of the box. This +* **Multi Data Center**: Consul supports multiple data centers out of the box. This means users of Consul do not have to worry about building additional layers of abstraction to grow to multiple regions. @@ -58,15 +58,15 @@ The agents talk to one or more _Consul servers_. The Consul servers are where data is stored and replicated. The servers themselves elect a leader. While Consul can function with one server, 3 to 5 is recommended to avoid failure scenarios leading to data loss. A cluster of Consul servers is recommended -for each datacenter. +for each data center. Components of your infrastructure that need to discover other services or nodes can query any of the Consul servers _or_ any of the Consul agents. The agents forward queries to the servers automatically. -Each datacenter runs a cluster of Consul servers. When a cross-datacenter +Each data center runs a cluster of Consul servers. When a cross-data center service discovery or configuration request is made, the local Consul servers -forward the request to the remote datacenter and return the result. +forward the request to the remote data center and return the result. ## Next Steps From 61202c78ac9adc001b5bcdf2ab477d80da02b6bd Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Thu, 19 Feb 2015 17:18:58 -0500 Subject: [PATCH 2/3] Website: finalize cleanup for getting-started/agent.html. --- .../source/intro/getting-started/agent.html.markdown | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/website/source/intro/getting-started/agent.html.markdown b/website/source/intro/getting-started/agent.html.markdown index 3d10e14f0..98fd25cec 100644 --- a/website/source/intro/getting-started/agent.html.markdown +++ b/website/source/intro/getting-started/agent.html.markdown @@ -11,10 +11,10 @@ description: |- After Consul is installed, the agent must be run. The agent can run either in server or client mode. Each data center 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. +as data loss is inevitable in a failure scenario. [This guide](/docs/guides/bootstrapping.html) +covers bootstrapping a new data center. -[This guide](/docs/guides/bootstrapping.html) covers bootstrapping a new -data center. All other agents run in client mode, a very lightweight +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. @@ -65,7 +65,7 @@ the name of your node with the `-node` flag. If you run `consul members` in another terminal, you can see the members of the Consul cluster. We'll cover joining clusters in the next section, but for now, -you should only see one member (yourself). +you should only see one member (yourself): ```text $ consul members @@ -81,8 +81,8 @@ The output of the `members` command is based on the [gossip protocol](/docs/internals/gossip.html) and is eventually consistent. 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) forwards the request -to the Consul servers: +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 From 0730e0dfe4e241dbfd51de9fed2443ac3765bddb Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Thu, 19 Feb 2015 17:32:31 -0500 Subject: [PATCH 3/3] Website: revert changes to 'data center' from 'datacenter' --- website/source/intro/getting-started/agent.html.markdown | 6 +++--- website/source/intro/index.html.markdown | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/website/source/intro/getting-started/agent.html.markdown b/website/source/intro/getting-started/agent.html.markdown index 98fd25cec..78a44ef85 100644 --- a/website/source/intro/getting-started/agent.html.markdown +++ b/website/source/intro/getting-started/agent.html.markdown @@ -3,16 +3,16 @@ 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 a server or client mode. Each data center 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. + After Consul is installed, the agent must be run. The agent can either run in a 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. --- # Run the Consul Agent After Consul is installed, the agent must be run. The agent can run either -in server or client mode. Each data center must have at least one server, +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 data center. +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 diff --git a/website/source/intro/index.html.markdown b/website/source/intro/index.html.markdown index d7feff400..40504803b 100644 --- a/website/source/intro/index.html.markdown +++ b/website/source/intro/index.html.markdown @@ -35,7 +35,7 @@ key features: store for any number of purposes, including dynamic configuration, feature flagging, coordination, leader election, and more. The simple HTTP API makes it easy to use. -* **Multi Data Center**: Consul supports multiple data centers out of the box. This +* **Multi Datacenter**: Consul supports multiple datacenters out of the box. This means users of Consul do not have to worry about building additional layers of abstraction to grow to multiple regions. @@ -58,15 +58,15 @@ The agents talk to one or more _Consul servers_. The Consul servers are where data is stored and replicated. The servers themselves elect a leader. While Consul can function with one server, 3 to 5 is recommended to avoid failure scenarios leading to data loss. A cluster of Consul servers is recommended -for each data center. +for each datacenter. Components of your infrastructure that need to discover other services or nodes can query any of the Consul servers _or_ any of the Consul agents. The agents forward queries to the servers automatically. -Each data center runs a cluster of Consul servers. When a cross-data center +Each datacenter runs a cluster of Consul servers. When a cross-datacenter service discovery or configuration request is made, the local Consul servers -forward the request to the remote data center and return the result. +forward the request to the remote datacenter and return the result. ## Next Steps