From cb1568b8b884fc53d23b5226fb4cef14b5fb286d Mon Sep 17 00:00:00 2001 From: Mitchell Hashimoto Date: Mon, 14 Apr 2014 12:47:55 -0700 Subject: [PATCH] website: creating a cluster --- .../intro/getting-started/join.html.markdown | 48 +++++++++++++++---- website/source/layouts/intro.erb | 2 +- 2 files changed, 41 insertions(+), 9 deletions(-) diff --git a/website/source/intro/getting-started/join.html.markdown b/website/source/intro/getting-started/join.html.markdown index 70904be6c4..a27f186eda 100644 --- a/website/source/intro/getting-started/join.html.markdown +++ b/website/source/intro/getting-started/join.html.markdown @@ -1,20 +1,23 @@ --- layout: "intro" -page_title: "Join a Cluster" +page_title: "Consul Cluster" sidebar_current: "gettingstarted-join" --- -# Join a Cluster +# Consul Cluster -In the previous page, we started our first agent. While it showed how easy -it is to run Consul, it wasn't very exciting since we simply made a cluster of -one member. In this page, we'll create a real cluster with multiple members. +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. When starting a Consul agent, it begins without knowledge of any other node, and is an isolated cluster of one. To learn about other cluster members, the agent must _join_ an existing cluster. To join an existing cluster, 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. +member and quickly discover the other members in the cluster. A Consul +agent can join any other agent, it doesn't have be an agent in server mode. ## Starting the Agents @@ -27,10 +30,12 @@ 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. +will act as our server in this cluster. We're still not making a cluster +of servers. ``` -$ consul agent -server -bootstrap -data-dir /tmp/consul -node=agent-one -bind=172.20.20.10 +$ consul agent -server -bootstrap -data-dir /tmp/consul \ + -node=agent-one -bind=172.20.20.10 ... ``` @@ -80,6 +85,33 @@ agents gossip with each other to propagate full membership information. In addition to using `consul join` you can use the `-join` flag on `consul agent` to join a cluster as part of starting up the agent. +## Querying Nodes + +Just like querying services, Consul has an API for querying the +nodes themselves. You can do this via the DNS or HTTP API. + +For the DNS API, the structure of the names is `NAME.node.consul` or +`NAME.DATACENTER.node.consul`. If the datacenter is omitted, Consul +will only search the local datacenter. + +From "agent-one", query "agent-two": + +``` +$ dig @127.0.0.1 -p 8600 agent-two.node.consul +... + +;; QUESTION SECTION: +;agent-two.node.consul. IN A + +;; ANSWER SECTION: +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. + ## Leaving a Cluster To leave the cluster, you can either gracefully quit an agent (using diff --git a/website/source/layouts/intro.erb b/website/source/layouts/intro.erb index 1bb6baa6ab..1a607fae11 100644 --- a/website/source/layouts/intro.erb +++ b/website/source/layouts/intro.erb @@ -55,7 +55,7 @@ > - Join a Cluster + Consul Cluster >