Skip to main content

Joining Consul Clients

TST, Hong Kong

When a new Consul agent starts, it doesn't know about other agents; it is essentially a datacenter with one member. Agents learn about each other in two ways. To add a new agent to an existing datacenter you give it the IP address of any other agent in the datacenter (either a client or a server), which causes the new agent to join the datacenter. Once the agent is a member of the new datacenter, it automatically learns about the other agents via gossip.

In this tutorial, we will configure the Consul agent to run in server mode instead of the dev mode we used earlier. This is done via the following command line flags:

(In production you would provide these settings to consul in a configuration file.)

  • server - Providing this flag specifies that you want the agent to start in server mode.
  • -bootstrap-expect - This tells the Consul server how many servers the datacenter should have in total. All the servers will wait for this number to join before bootstrapping the replicated log, which keeps data consistent across all the servers. Because you are setting up a one-server datacenter, you'll set this value to 1.
  • -node - Each node in a datacenter must have a unique name. By default, Consul uses the hostname of the machine, but you'll manually override it, and set it to consul-server.
  • -bind - This is the address that this agent will listen on for communication from other Consul members. It must be accessible by all other nodes in the datacenter. If you don't set a bind address Consul will try to listen on all IPv4 interfaces and will fail to start if it finds multiple private IPs. Since production servers often have multiple interfaces, you should always provide a bind address. In my case this is 192.168.2.110 for the server and 192.168.2.111 for the client.
  • data-dir - This flag tells Consul agents where they should store their state, which can include sensitive data like ACL tokens for both servers and clients. In production deployments you should be careful about the permissions for this directory. I will create a directory /tmp/consul-test.
  • config-dir - This flag tells consul where to look for its configuration. You will set it to a standard location: /etc/consul.d.

Start the Agents​

Start your first Consul agent by running the following command. Consul will start up in the foreground of your terminal window:

Server

consul agent \
  -server \
  -bootstrap-expect=1 \
  -node=consul-server \
  -bind=192.168.2.110 \
  -data-dir=/tmp/consul-test \
  -config-dir=/etc/consul.d

Client

And on your client server - in my case IP 192.168.2.111 - execute the Consul service with:

consul agent \
  -node=consul-client1 \
  -bind=192.168.2.111 \
  -enable-script-checks=true \
  -data-dir=/tmp/consul-test \
  -config-dir=/etc/consul.d

Now you have two Consul agents running: one server and one client. The two agents still don't know about each other and each comprise their own single-node datacenters:

consul members

Node           Address             Status  Type    Build  Protocol  DC   Segment
consul-server  192.168.2.110:8301  alive   server  1.8.3  2         dc1  <all>
consul members
              
Node       Address             Status  Type    Build  Protocol  DC   Segment
agent-two  192.168.2.111:8301  alive   client  1.8.3  2         dc1  <default>

Join the Agents​

Run the consul join command on the Consul server, giving it the bind address of the Consul client:

consul join 192.168.2.111

Successfully joined cluster by contacting 1 nodes.

You can verify that the client was added by typing:

Server

consul members

Node           Address             Status  Type    Build  Protocol  DC   Segment
consul-server  192.168.2.110:8301  alive   server  1.8.3  2         dc1  <all>
agent-two      192.168.2.111:8301  alive   client  1.8.3  2         dc1  <default>

Client

consul members
              
Node           Address             Status  Type    Build  Protocol  DC   Segment
consul-server  192.168.2.110:8301  alive   server  1.8.3  2         dc1  <all>
agent-two      192.168.2.111:8301  alive   client  1.8.3  2         dc1  <default>

In production, new Consul agents should automatically join the datacenter without human intervention. You can provide hard-coded addresses of known Consul agents to new agents using the -join flag or start_join setting.