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).
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)
-
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.
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!
© Brian Shumate.RSS