Maintenance cheatsheet

This is a cheatsheet. Please refer to the documentation for step-by-step guides.

The setup and maintenance are orchestrated via a Makefile. It shall be used for as much tasks as possible since it automates scripts and environment variables.

Environment variables can be exported via a .env file at the top-level directory of HashiBox.

Once HashiBox has been initialized, we assume the following required environment variables are set on your machine:

export VAULT_UNSEAL_KEY=<key>
export VAULT_TOKEN=<token>
export CONSUL_HTTP_TOKEN=<token>
export NOMAD_TOKEN=<token>

Optional environment variables for tweaking Vagrant:

export UBUNTU_VERSION=23.04-arm64
export VAGRANT_PROVIDER=parallels
export VAGRANT_CLIENT_RAM=2048
export VAGRANT_CLIENT_CPUS=1
export VAGRANT_SERVER_RAM=1024
export VAGRANT_SERVER_CPUS=1

Optional environment variables to install HashiCorp Enterprise products using license keys, used on make init and make update:

export CONSUL_LICENSE=<key>
export NOMAD_LICENSE=<key>
export VAULT_LICENSE=<key>

To start the Vagrant environment, run:

$ make up

This assumes your environment has already been initialized. Otherwise, an error will be prompted.

The most useful command when working / collaborating on HashiBox is probably this one:

$ make sync

This:

1. uploads the config files from your local machine to your virtual machines for server and client nodes;
2. updates the environment variables of your virtual machines using the ones from the local .env file;
3. restarts the Consul, Nomad, and Vault services on every nodes;
4. unseals Vault on server nodes.

To completely restart the Vagrant environment, run:

$ make restart

To update the services to the latest version, run:

$ make update

To stop the Vagrant environment, run:

$ make halt

To stop and destroy the Vagrant environment, run:

$ make destroy

If you need your virtual machines to connect to private Git repos, you will most likely need to sync SSH keys from your local machine to your virtual machines.

First, you must ensure that the Nomad user's known hosts file is populated with GitHub and Bitbucket hosts.

We provide a shortcut to achieve this:

$ make ssh

Then you will need to upload your SSH key. This can be done with:

$ bolt file upload <path_to_key>/id_rsa /home/vagrant/.ssh/id_rsa \
  --targets=us --run-as root

$ bolt file upload <path_to_key>/id_rsa.pub /home/vagrant/.ssh/id_rsa.pub \
  --targets=us --run-as root

$ bolt command run "cat /home/vagrant/.ssh/id_rsa.pub >> /home/vagrant/.ssh/authorized_keys" \
  --targets=us --run-as root