Running HashiCorp Vault Locally: A Developer's Guide

HashiCorp Vault is a powerful tool for securely managing secrets and so much more. This guide will walk you through setting up a local Vault development environment, using the CLI, and performing basic secret operations.

Prerequisites

1. Open 2 terminal windows, one for the server and one for the Vault CLI.
2. Download Vault:
   • Visit the official HashiCorp website: https://developer.hashicorp.com/vault/install
   • Download the appropriate version for your operating system. I'm using version v1.18.0 at the time of writing and installed using brew.

brew tap hashicorp/tap
brew install hashicorp/tap/vault

Setting Up the Local Vault Environment

1. Start the development server:
   • Open your terminal and navigate to the directory where you downloaded Vault and run the following command:

vault server -dev -dev-root-token-id=root

2. Using the Vault CLI:
   • The development server automatically authenticates the local Vault CLI. You can verify this by running the following command in a second terminal window:

export VAULT_ADDR=http://localhost:8200
vault status

Working with Secrets

Create a Secret:

To create a secret named database with the value supersecurepassword, use the vault kv put command:

vault kv put -mount=secret database password=supersecurepassword

kv - The key-value secret storage engine. This engine is used when you need to store generic key-value (kv) secrets. The kv secrets engine enables users to store single values or multiple versions of a secret.

put - Writes data to the provided path in the key-value secret engine store. This translates to an HTTP POST API call to the Vault server.

mount - The kv engine mount point. By default Vault preconfigures the secret kv mount point. You can change this path or have multiple kv secret engines. By setting the -path command option when enabling the secret engine.

Reading a Secret:

To retrieve the secret, use the vault kv get command:

vault kv get -mount=secret database

To list all the secrets, use the vault kv list command:

vault kv list -mount=secret

or when your secret is under a path:

vault kv list -mount=secret dev/database/

Deleting a Secret:

When deleting secrets you have a few different options.

1. Delete a secret for a version and path in the key-value secret engine. This command would be used when you need to remove a specific version. Example, you accidentally overwrote a secret and need to remove the version, but you want to be able to recover the secret.

vault kv delete -versions=<version-number> -mount=secret database

2. Destroy a specific version and permanently remove the data from the key-value store. This operation would permanently delete the secret and not allow you to undo the delete.

vault kv destroy -mount=secret -versions=<version-number> database

Delete the metadata and all versions of a key. This is by far the most destructive operation. The entire history of the secret would be deleted along with any metadata held within Vault about the secret.

vault kv metadata delete -mount=secret database

Persisting Data Between Restarts

By default, the development server stores data in memory, which is lost upon restarts. Development can frequently span days or even multiple system reboots. In order to persist the data you need to launch the development server with a different configuration.

Create a Configuration File:

1. Create a file called config.hcl in the directory where you will launch the Vault server.
2. Paste the following configuration in the config.hcl file:

ui            = true
cluster_addr  = "http://127.0.0.1:8201"
api_addr      = "http://127.0.0.1:8200"
disable_mlock = true

storage "file" {
  path = "./vault"
}

listener "tcp" {
  address = "127.0.0.1:8200"
  tls_disable = true
}

Start the Server with the Configuration:

Run the following command:

vault server -config=config.hcl

Conclusion

Exploring HashiCorp Vault locally is a great way to learn and develop applications that use Vault. Operators can explore new features without the worry of disrupting operations and with a little work Terraform can be used to automate your Vault configurations.

Dive into the HashiCorp documentation for recommended patterns and integrations. Feeling adventurous take a look at HCP Vault Secrets and Vault dedicated and allow HashiCorp to manage your Vault.

• Vault Best Practices: https://developer.hashicorp.com/vault/docs/internals/recommended-patterns
• Vault Configurations: https://developer.hashicorp.com/vault/docs/configuration
• HashiCorp Cloud Platform: https://developer.hashicorp.com/hcp