Vaultini

Brian Shumate,Wed Oct 04 2023•CLI Docker HashiCorp security Terraform Vault

Since I work daily with Vault (opens in a new tab), Terraform (opens in a new tab), and Docker (opens in a new tab) I inevitably combined these 3 technologies into 1 rocking good time.

I originally set out to do that back in 2017 (opens in a new tab) with Vaultron (opens in a new tab).

Vaultron diagram

Alas, Vaultron grew to be mighty, complicated, and tremendously bloated. Since its formation also predated integrated storage in Vault, I felt that the support for it which I bolted on just further increased its bloat.

I decided to start anew with Vaultini (opens in a new tab).

Vaultini diagram

Although the name is something reminiscent of an adult beverage, it's really a nod to the tininess of the project when compared to Vaultron. The goal with Vaultini is to quickly spin up a fairly useful Vault cluster in Docker for development, educating, or testing.

Vaultini accomplishes this goal with Terraform, the Terraform Docker Provider, and a Makefile to make a cluster with these default properties:

Latest available official Vault community edition Docker image version
5 nodes with deterministic hostnames and IP addresses
Shamir's seal with a single key share for convenience
Uses only integrated storage (sorry, Consul and others)
TLS enabled

To make a Vault cluster with Vaultini, you need these things installed and working (i.e. CLI tool binaries in your system PATH).

Linux or macOS (Vaultini is not yet tested on Windows)
git (opens in a new tab)
BSD make or gnumake (opens in a new tab); the Vaultini user interface is a Makefile. The former is typically preinstalled, while you usually install the former with your OS package manager.
Docker (opens in a new tab)
Terraform CLI (opens in a new tab)

Provided your computer meets all above requirements, you can make a Vault cluster in 4 steps.

Clone the repository.

git clone https://github.com/brianshumate/vaultini.git

Change into the vaultini directory.
```
cd vaultini
```
Add the Vaultini Certificate Authority certificate to your operating system trust store. This helps clients securely communicate with the cluster, and enables you to access the web UI without errors. There are instructions for popular operating systems. This example is for macOS. You'll be prompted for your user password at least one time during this step.
```
sudo security add-trusted-cert -d -r trustAsRoot \
    -k /Library/Keychains/System.keychain \
    ./containers/vaultini1/certs/vaultini-ca.pem
```
Make a Vault cluster.
```
make
```

After about 30 seconds, you're presented with some helpful output to get started with your new Vault cluster.

[vaultini] Initializing Terraform workspace ...Done.
[vaultini] Applying Terraform configuration ...Done.
[vaultini] Checking Vault active node status ...Done.
[vaultini] Checking Vault initialization status ...Done.
[vaultini] Unsealing cluster nodes .....vaultini2. vaultini3. vaultini4. vaultini5. Done.
[vaultini] Enable audit device ...Done.
[vaultini] Export VAULT_ADDR for the active node: export VAULT_ADDR=https://127.0.0.1:8200
[vaultini] Login to Vault with initial root token: vault login hvs.jBsc0ff33HG4xZziwrrij3kP

Export the VAULT_ADDR environment variable

export VAULT_ADDR=https://127.0.0.1:8200

Check Vault status.

vault status

Example output:

Key                     Value
---                     -----
Seal Type               shamir
Initialized             true
Sealed                  false
Total Shares            1
Threshold               1
Version                 1.15.2
Build Date              2023-11-06T11:33:28Z
Storage Type            raft
Cluster Name            vault-cluster-55e1fd16
Cluster ID              9534f489-914c-d4db-5b44-e6489d88d7eb
HA Enabled              true
HA Cluster              https://10.1.42.101:8201
HA Mode                 active
Active Since            2023-11-10T19:59:31.56255684Z
Raft Committed Index    71
Raft Applied Index      71

That's it! Your Vault cluster is ready for use.

You can also access Vault with a browser and the web UI: https://localhost:8200 (opens in a new tab).

Cleanup

When you're finished using Vaultini, you have two options to clean up its artifacts.

To clean up Docker containers and all generated artifacts, including audit device log files:

make clean

To clean up everything including Terraform runtime configuration and state:

make cleanest

Check out the README.md (opens in a new tab) for more details.

Next steps

If you're new to Vault and unsure what to do next, consider diving into some of the available tutorials (opens in a new tab) on the HashiCorp Developer site.

The CLI quick start (opens in a new tab) is good to get familiar from the beginning, but you can actually start with Your first secret (opens in a new tab) and use Vaultini as your dev mode Vault server right now.

Enjoy!