From ce7dbc345b3a9456d3785b3262960bf4565fe327 Mon Sep 17 00:00:00 2001 From: Ryan Breen Date: Sat, 14 Mar 2015 14:13:41 -0400 Subject: [PATCH] Website: substantial rewrite of intro/getting-started/join.html. --- .../intro/getting-started/agent.html.markdown | 4 +- .../intro/getting-started/join.html.markdown | 150 ++++++++++++------ 2 files changed, 104 insertions(+), 50 deletions(-) diff --git a/website/source/intro/getting-started/agent.html.markdown b/website/source/intro/getting-started/agent.html.markdown index 2a3cc186db..e745fd3790 100644 --- a/website/source/intro/getting-started/agent.html.markdown +++ b/website/source/intro/getting-started/agent.html.markdown @@ -108,7 +108,7 @@ $ dig @127.0.0.1 -p 8600 Armons-MacBook-Air.node.consul Armons-MacBook-Air.node.consul. 0 IN A 10.1.10.38 ``` -## Stopping the Agent +## 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 @@ -130,5 +130,5 @@ and remove servers. ## Next Steps -Your simple Consul cluster is up and running. Let's give it some +Your simple Consul cluster is up and running. Let's give it some [services](services.html)! diff --git a/website/source/intro/getting-started/join.html.markdown b/website/source/intro/getting-started/join.html.markdown index 594dcbe5d4..45f689e80c 100644 --- a/website/source/intro/getting-started/join.html.markdown +++ b/website/source/intro/getting-started/join.html.markdown @@ -3,19 +3,18 @@ layout: "intro" page_title: "Consul Cluster" sidebar_current: "gettingstarted-join" description: |- - By this point, we've started our first agent and registered and queried one or more services 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 service discovery infrastructure. On this page, we'll create our first real cluster with multiple members. + 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. --- # Consul Cluster -By this point, we've started our first agent and registered and queried -one or more services 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 -service discovery infrastructure. On this page, we'll create our first -real cluster with multiple members. +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. -When a Consul agent is started, it begins without knowledge of any other node, -and is an isolated cluster of one. To learn about other cluster members, the +When a Consul agent is started, it begins without knowledge of any other node: +it is an isolated cluster of one. To learn about other cluster members, the agent must _join_ an existing cluster. To join an existing cluster, it only needs to know about a _single_ existing member. After it joins, the agent will gossip with this member and quickly discover the other members in the cluster. @@ -23,59 +22,97 @@ A Consul agent can join any other agent, not just agents in server mode. ## Starting the Agents -To simulate a more realistic cluster, we are using a two node cluster in -Vagrant. The Vagrantfile can be found in the demo section of the repo -[here](https://github.com/hashicorp/consul/tree/master/demo/vagrant-cluster). +To simulate a more realistic cluster, we will start a two node cluster via +[Vagrant](https://www.vagrantup.com/). The Vagrantfile we will be using can +be found in the [demo section of the Consul repo] +(https://github.com/hashicorp/consul/tree/master/demo/vagrant-cluster). -We start the first agent on our first node and also specify a node name. -The node name must be unique and is how a machine is uniquely identified. -By default it is the hostname of the machine, but we'll manually override it. -We are also providing a bind address. This is the address that Consul listens on, -and it *must* be accessible by all other nodes in the cluster. The first node -will act as our server in this cluster. We're still not making a cluster -of servers. +We first boot our two nodes: ```text -$ consul agent -server -bootstrap-expect 1 -data-dir /tmp/consul \ - -node=agent-one -bind=172.20.20.10 +$ vagrant up +``` + +Once the systems are available, we can ssh into them to begin configuration +of our cluster. We start by logging in to the first node: + +```text +$ vagrant ssh n1 +``` + +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). + +We will also specify a [`bind` address](/docs/agent/options.html#_bind): +this is the address that Consul listens on, and it *must* be accessible by +all other nodes in the cluster. While a `bind` address is not strictly +necessary (Consul will by default listen on the first private IP on a +system), it's always best to provide one. Production servers often have +multiple interfaces, so specifying a `bind` address insures 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). + +All together, these settings yield a +[`consul agent`](/docs/commands/agent.html) command like this: + +```text +vagrant@n1:~$ consul agent -server -bootstrap-expect 1 \ + -data-dir /tmp/consul -node=agent-one -bind=172.20.20.10 ... ``` -Then, in another terminal, start the second agent on the new node. -This time, we set the bind address to match the IP of the second node -as specified in the Vagrantfile. In production, you will generally want -to provide a bind address or interface as well. +Now, in another terminal, we will connect to the second node: + +```text +$ vagrant ssh n2 +``` + +This time, we set the [`bind` address](/docs/agent/options.html#_bind) +address to match the IP of the second node as specified in the Vagrantfile +and the [`node` name](/docs/agent/options.html#_node) to be `agent-two`. +Since this node will not be a Consul server, we don't provide a +[`server` switch](/docs/agent/options.html#_server). + +All together, these settings yield a +[`consul agent`](/docs/commands/agent.html) command like this: ```text -$ consul agent -data-dir /tmp/consul -node=agent-two -bind=172.20.20.11 +vagrant@n2:~$ consul agent -data-dir /tmp/consul -node=agent-two \ + -bind=172.20.20.11 ... ``` -At this point, you have two Consul agents running, one server and one client. -The two Consul agents still don't know anything about each other, and are each part of their own -clusters (of one member). You can verify this by running `consul members` -against each agent and noting that only one member is a part of each. +At this point, you have two Consul agents running: one server and one client. +The two Consul agents still don't know anything about each other and are each +part of their own single-node clusters. You can verify this by running +[`consul members`](/docs/commands/members.html) against each agent and noting +that only one member is visible to each agent. ## Joining a Cluster -Now, let's tell the first agent to join the second agent by running -the following command in a new terminal: +Now, we'll tell the first agent to join the second agent by running +the following commands in a new terminal: ```text -$ consul join 172.20.20.11 +$ vagrant ssh n1 +... +vagrant@n1:~$ consul join 172.20.20.11 Successfully joined cluster by contacting 1 nodes. ``` You should see some log output in each of the agent logs. If you read carefully, you'll see that they received join information. If you -run `consul members` against each agent, you'll see that both agents now -know about each other: +run `consul members` against each agent, you'll see that both agents +now know about each other: ```text -$ consul members -detailed -Node Address Status Tags -agent-one 172.20.20.10:8301 alive role=consul,dc=dc1,vsn=2,vsn_min=1,vsn_max=2,port=8300,bootstrap=1 -agent-two 172.20.20.11:8301 alive role=node,dc=dc1,vsn=2,vsn_min=1,vsn_max=2 +vagrant@n2:~$ consul members +Node Address Status Type Build Protocol +agent-two 172.20.20.11:8301 alive client 0.5.0 2 +agent-one 172.20.20.10:8301 alive server 0.5.0 2 ``` -> **Remember:** To join a cluster, a Consul agent only needs to @@ -83,16 +120,27 @@ learn about one existing member. After joining the cluster, the agents gossip with each other to propagate full membership information. ## Auto-joining a Cluster on Start -Ideally whenever a new node is brought up in your datacenter, it should automatically join the Consul cluster without human intervention. To accomplish this, you can use [Atlas by HashiCorp](https://atlas.hashicorp.com?utm_source=oss&utm_medium=getting-started-join&utm_campaign=consul) and the [`-atlas-join` flag](/docs/agent/options.html#_atlas_join). An example configuration is shown below: +Ideally, whenever a new node is brought up in your datacenter, it should +automatically join the Consul cluster without human intervention. To +accomplish this, you can use +[Atlas by HashiCorp](https://atlas.hashicorp.com?utm_source=oss&utm_medium=getting-started-join&utm_campaign=consul) +and the [`-atlas-join` flag](/docs/agent/options.html#_atlas_join). +An example configuration is shown below: ```text $ consul agent -atlas-join \ -atlas=ATLAS_USERNAME/infrastructure \ -atlas-token="YOUR_ATLAS_TOKEN" ``` -To get an Atlas username and token, [create an account here](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started-join&utm_campaign=consul) and replace the respective values in your Consul configuration with your credentials. Now whenever a new node comes up with a Consul agent, it automatically joins your Consul cluster without any hardcoded configurations. - -Alternatively, you can use the [`-join` flag](http://www.consul.io/docs/agent/options.html#_join) +To get an Atlas username and token, +[create an account](https://atlas.hashicorp.com/account/new?utm_source=oss&utm_medium=getting-started-join&utm_campaign=consul) +and replace the respective values in your Consul configuration with your +credentials. Now, whenever a new node comes up with a Consul agent, it +will automatically join your Consul cluster without any hardcoded +configuration. + +Alternatively, you can use the +[`-join` flag](http://www.consul.io/docs/agent/options.html#_join) with a hardcoded address of a known Consul agent to join a cluster. ## Querying Nodes @@ -104,10 +152,11 @@ For the DNS API, the structure of the names is `NAME.node.consul` or `NAME.node.DATACENTER.consul`. If the datacenter is omitted, Consul will only search the local datacenter. -From "agent-one", query "agent-two": +For example, from "agent-one", we can query for the address of the +node "agent-two": ``` -$ dig @127.0.0.1 -p 8600 agent-two.node.consul +vagrant@n1:~$ dig @127.0.0.1 -p 8600 agent-two.node.consul ... ;; QUESTION SECTION: @@ -119,13 +168,18 @@ agent-two.node.consul. 0 IN A 172.20.20.11 The ability to look up nodes in addition to services is incredibly useful for system administration tasks. For example, knowing the address -of the node to SSH into is as easy as making it part of the Consul cluster -and querying it. +of the node to SSH into is as easy as making the node a part of the +Consul cluster and querying it. ## Leaving a Cluster To leave the cluster, you can either gracefully quit an agent (using `Ctrl-C`) or force kill one of the agents. Gracefully leaving allows -the node to transition into the _left_ state, otherwise other nodes +the node to transition into the _left_ state; otherwise, other nodes will detect it as having _failed_. The difference is covered -in more detail [here](/intro/getting-started/agent.html#toc_3). +in more detail [here](/intro/getting-started/agent.html#stopping). + +## Next Steps + +We now have a multi-node Consul cluster up and running. Let's make +our services more robust by giving them [health checks](checks.html)!