Consul on FreeBSD

Consul on FreeBSD

This tutorial will walk you through the steps to install and configure a Consul Cluster running on FreeBSD 12.1. Consul is a distributed highly available solution used for service discovery and health checking, configuration management, and service mesh. Consul has a robust ecosystem with integrations into many other tools. FreeBSD is a Unix like operating system with many advanced features. I expect you already knew what Consul and FreeBSD are or you wouldn’t be reading this.

Please take a look at https://www.consul.io as they have great documentation on the use and design of Consul. Getting it running on FreeBSD is missing however.

Consul Architecture

Each host will need at minimum the following bind ports accessible

+------------------------+--------------+
|          Use           | Default Port |
+------------------------+--------------+
| DNS (TCP and UDP)      |         8600 |
| HTTP (TCP)             |         8500 |
| LAN Serf (TCP and UDP) |         8301 |
| WAN Serf (TCP and UDP) |         8302 |
| Server (TCP)           |         8300 |
+------------------------+--------------+

Consul uses a consensus protocol, based on Raft, to elect a leader for the cluster. It is recommended that you have three or five total servers per datacenter. Having an odd number helps the cluster form a consensus.

For this tutorial we will have three servers

+-----------+--------------+
| Hostname  |      IP      |
+-----------+--------------+
| consul-01 | 192.168.1.11 |
| consul-02 | 192.168.1.12 |
| consul-03 | 192.168.1.13 |
+-----------+--------------+

Step 1: Install Consul

This couldn’t be any easier

pkg install consul

You can verify the install by

# consul -v
Consul v1.7.2

Step 2: Configure rc.conf and config.json

Edit /etc/rc.conf to enable Consul at startup. Add the following line

consul_enable="YES"

Optional rc.conf settings include

consul_configtest (string): Set to yes to enable Consul config validation
Set to NO by default
consul_datadir (dir): Set dir to run consul in.
Default is "/var/db/consul"
consul_syslog_output_enable (bool): Set to YES to enable syslog output
Default is "NO". See daemon(8).
consul_syslog_output_tag (str): Set syslog tag if syslog enabled.
Default is "consul".
consul_syslog_output_priority (str): Set syslog priority if syslog enabled.
Default is "info".
consul_syslog_output_facility (str): Set to YES to enable syslog output

Now we need to make the directory where the Consul configuration file will live. On FreeBSD the Consul daemon expects the find the configuration file in /usr/local/etc/consul.d and the file to be named config.json

# mkdir /usr/local/etc/consul.d

Now create an encryption key for the cluster. Run consul keygen and save the output. We will use this in config.json as the value for the encrypt key.

Now edit /usr/local/etc/consul.d/config.json

On consul-01 my config file looks like

{
  "bind_addr":"192.168.1.11",
  "datacenter":"dc1",
  "bootstrap_expect":3,
  "client_addr":"0.0.0.0",
  "domain":"consul",
  "enable_script_checks":true,
  "dns_config": {
    "enable_truncate": true,
    "only_passing": true
  },
  "encrypt": "<mykey>",
  "data_dir":"/var/db/consul",
  "leave_on_terminate": true,
  "log_level":"INFO",
  "rejoin_after_leave": true,
  "node_name":"consul-01",
  "server": true,
  "ui": true,
  "start_join": ["192.168.1.11", "192.168.1.12", "192.168.1.13]
}

Save the file and run `consul validate /usr/local/etc/consul.d/config.json` to make sure everything looks good

Repeat this process on consul-02 and consul-03. Copy the config.json file makeing sure to edit the bind_addr and node_name for each server.

Step 3: Startup and Test

Time to start the server. Run the following on each server

service consul start

If all when well you can run

# service consul status
consul is running as pid 4324.

You can check the status of all members by running

# consul members
Node       Address              Status  Type    Build  Protocol  DC   Segment
consul-01  192.168.1.11:8301    alive   server  1.7.2  2         dc1  <all>
consul-02  192.168.1.12:8301  alive   server  1.7.2  2         dc1  <all>
consul-03  192.168.1.13:8301  alive   server  1.7.2  2         dc1  <all>

You can also go to any of your servers via web browser and get to the Consul UI http://192.168.1.11:8500

That’s it for this tutorial. I just wanted to show how to get things up and running. There are a number of other tutorial out there on how to use Consul.

Thanks for reading