Introduction

In this blog post, I will introduce you to a new tool, hashi-up, I created to install a HashiCorp Nomad cluster in a matter of minutes.

This project is heavily inspired on the work of Alex Ellis who created k3sup, a tool to to get from zero to KUBECONFIG with k3s

What is hashi-up?

hashi-up is a lightweight utility to install HashiCorp Consul and Nomad on any remote Linux host. All you need is ssh access and the binary hashi-up to build a Consul or a Nomad cluster.

The tool is written in Go and is cross-compiled for Linux, Windows, macOS and even on Raspberry Pi.

How does it work?

This tool uses ssh to install HashiCorp Consul or Nomad to a remote Linux host. You can also use it to join existing Linux hosts into a Consul or Nomad cluster. First, Consul or Nomad is installed using a utility script, along with a minimal configuration to run the agent as a server or a client.

hashi-up was developed to automate what can be a very manual and confusing process for many developers, who are already short on time. Once you’ve provisioned a VM with your favourite tooling, hashi-up means you are only 60 seconds away from running nomad status on your computer.

Usage

The hashi-up tool is a client application which you can run on your computer. It uses SSH to connect to remote servers when installing HashiCorp Consul or Nomad. Binaries are available for macOS, Windows, and Linux (including ARM).

Setup a single Nomad server

Provision a new VM with a compatible operating system such as Ubuntu, Debian, Raspbian, or something else. Make sure that you opt-in to copy your registered SSH keys over to the new VM or host automatically.

Note: You can copy ssh keys to a remote VM with ssh-copy-id user@IP.

Imagine the IP was 192.168.0.100 and the username was ubuntu, then you would run this:

export IP=192.168.0.100
hashi-up nomad install --ssh-target-addr $IP --ssh-target-user ubuntu --server

When the command finishes, try to access Nomad using the UI at http://192.168.100:4646 or with the CLI:

nomad agent-info -address=http://192.168.0.100:4646

Join some agents to your Nomad server

Let’s say you have a Nomad server up and running; now you can join one or more client agents to the cluster:

export SERVER_IP=192.168.0.100
export AGENT_1_IP=192.168.0.105
export AGENT_2_IP=192.168.0.106

hashi-up nomad install --ssh-target-addr $AGENT_1_IP --ssh-target-user ubuntu --client --retry-join $SERVER_IP
hashi-up nomad install --ssh-target-addr $AGENT_2_IP --ssh-target-user ubuntu --client --retry-join $SERVER_IP

Create a multi-server (HA) setup

Prepare, for example, three nodes and let’s say they have the following IP addresses:

192.168.0.100
192.168.0.101
192.168.0.102

With hashi-up it is quite easy to install 3 Nomad servers which will form a cluster:

export SERVER_1_IP=192.168.0.100
export SERVER_2_IP=192.168.0.101
export SERVER_3_IP=192.168.0.102

hashi-up nomad install --ssh-target-addr $SERVER_1_IP --ssh-target-user ubuntu --server --bootstrap-expect 3 --retry-join $SERVER_1_IP --retry-join $SERVER_2_IP --retry-join $SERVER_3_IP
hashi-up nomad install --ssh-target-addr $SERVER_2_IP --ssh-target-user ubuntu --server --bootstrap-expect 3 --retry-join $SERVER_1_IP --retry-join $SERVER_2_IP --retry-join $SERVER_3_IP
hashi-up nomad install --ssh-target-addr $SERVER_3_IP --ssh-target-user ubuntu --server --bootstrap-expect 3 --retry-join $SERVER_1_IP --retry-join $SERVER_2_IP --retry-join $SERVER_3_IP

And of course, joining client agents is the same as above:

export SERVER_1_IP=192.168.0.100
export SERVER_2_IP=192.168.0.101
export SERVER_3_IP=192.168.0.102
export AGENT_1_IP=192.168.0.105
export AGENT_2_IP=192.168.0.106

hashi-up nomad install --ssh-target-addr $AGENT_1_IP --ssh-target-user ubuntu --client --retry-join $SERVER_1_IP --retry-join $SERVER_2_IP --retry-join $SERVER_3_IP
hashi-up nomad install --ssh-target-addr $AGENT_2_IP --ssh-target-user ubuntu --client --retry-join $SERVER_1_IP --retry-join $SERVER_2_IP --retry-join $SERVER_3_IP

Create a multi-server (HA) setup with Consul

If a Consul agent is already available on the Nomad nodes, Nomad can use Consul the automatically bootstrap the cluster. So after installing a Consul cluster on all nodes, with hashi-up the cluster, as explained above, can be installed with the following commands:

export SERVER_1_IP=192.168.0.100
export SERVER_2_IP=192.168.0.101
export SERVER_3_IP=192.168.0.102
export AGENT_1_IP=192.168.0.105
export AGENT_2_IP=192.168.0.106

hashi-up nomad install --ssh-target-addr $SERVER_1_IP --ssh-target-user ubuntu --server --bootstrap-expect 3 
hashi-up nomad install --ssh-target-addr $SERVER_2_IP --ssh-target-user ubuntu --server --bootstrap-expect 3 
hashi-up nomad install --ssh-target-addr $SERVER_3_IP --ssh-target-user ubuntu --server --bootstrap-expect 3 
hashi-up nomad install --ssh-target-addr $AGENT_1_IP --ssh-target-user ubuntu --client
hashi-up nomad install --ssh-target-addr $AGENT_2_IP --ssh-target-user ubuntu --client

Demo

In this demo, I install a Nomad cluster onto eight separate DigitalOcean droplets. I takes only five minutes to get three Nomad servers and 5 Nomad clients up and running.

Note: in the demo, the Nomad agents will join with the Cloud Auto-join option, instead of using IP addresses

Next steps

So what’s next? Well, this project is very young and does require some improvements. At the time of writing, you can spin up a Consul or Nomad cluster with some basic configuration. Still, some additional flags and feature will be useful to build a production-ready cluster with hashi-up. For instance, the tool does not have support to enable Gossip Communication encryption, Agent Communication TLS encryption and ACLs.

So stay tuned!

update 2020-12-06

Meanwhile, the hashi-up project progressed a little bit, and additional features like encryption and ACLs are available now. With the latest release, you could even install HashiCorp Vault using hashi-up.

See also:

References:

Deploying a highly-available Nomad cluster with hashi-up!