Vaultini

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).

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).

The name Vaultini hints at the tininess of the project when compared to Vaultron.

Spinning up a useful Vault cluster in Docker for development, educating, or testing is the main goal for Vaultini.

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
• TLS enabled

To make a Vault cluster with Vaultini, you need the following:

• Linux or macOS

• 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 install the latter with your OS package manager.

• Docker (opens in a new tab)

• Terraform CLI (opens in a new tab)

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

1. Clone the repository.

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

2. Change into the vaultini directory.

   cd vaultini

3. 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. Documentation includes instructions for popular operating systems. This is the macOS example. The OS prompts 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

4. Make a Vault cluster.

   make

After about 30 seconds, Vaultini presents 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

To inform the Vault client how to connect to the cluster, export the VAULT_ADDR environment variable with the cluster URL plus port.

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

You now have a Vault cluster ready for use.

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

Cleanup

When you finish 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

Note: Vaultini doesn't remove its own log, vaultini.log in any case to assist with troubleshooting, but the log gets overwritten on each run.

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

Next steps

New to Vault and unsure what to do next?

Dive 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!