Codify management of Vault using Terraform
Personas
The scenario described in this tutorial introduces the following personas:
admin
is the organization-level administratorstudent
is a user allowed to write data to a path in vault
Challenge
A manual system administration can become a challenge as the scale of infrastructure increases. Often, an organization must manage multiple Vault environments (development, testing, staging, production, etc.). Keeping up with the increasing management demand soon becomes a challenge without some sort of automation.
Solution
One of the pillars behind the Tao of Hashicorp is automation through codification.
HashiCorp Terraform is an infrastructure as code which enables the operation team to codify the Vault configuration tasks such as the creation of policies. Automation through codification allows operators to increase their productivity, move quicker, promote repeatable processes, and reduce human error.
This tutorial demonstrates techniques for creating Vault policies and configurations using Terraform Vault Provider.
Prerequisites
- Terraform installed
- A Vault environment to connect
Note
If you are running Vault Enterprise, see the Codify Management of Vault Enterprise Using Terraform tutorial.
Launch Terminal
This tutorial includes a free interactive command-line lab that lets you follow along on actual cloud infrastructure.
Scenario introduction
Vault administrators must manage multiple Vault environments. The test servers get destroyed at the end of each test cycle and a new set of servers must be provisioned for the next test cycle. To automate the Vault server configuration, you are going to use Terraform to provision the following Vault resources.
Type | Name | Description |
---|---|---|
ACL Policy | admins | Sets policies for the admin team |
ACL Policy | eaas-client | Sets policies for clients to encrypt/decrypt data through transit secrets engine |
auth method | userpass | Enable and create a user, "student" with admins and fpe-client policies |
secrets engine | kv-v2 | Enable kv-v2 secrets engine at kv-v2 |
secrets engine | transit | Enable transit secrets engine at transit |
encryption key | payment | Encryption key to encrypt/decrypt data |
The following steps are demonstrated:
Examine the Terraform files
Clone or download the demo assets from the hashicorp/learn-vault-codify GitHub repository to perform the steps described in this tutorial.
This repository contains supporting content for all of the Vault learn guides. The content specific to this tutorial can be found within a sub-directory.
Change the working directory to
learn-vault-codify/community
.The directory contains Terraform files to configure Vault.
Open the
main.tf
file in your preferred text editor to examine its content.main.tf123456789
Within the file is a
vault
provider block. You can provide the server connection details inside this block (Vault server address, client tokens, etc.); however, it is strongly recommended to configure those target server specific information using environment variables. And that's what you are going to do in this tutorial.Open the
policies.tf
file and examine thevault_policy
resources.policies.tf1 2 3 4 5 6 7 8 9 1011
Open the
auth.tf
file and note that it enablesuserpass
auth method and creates a user, "student" withadmins
andeaas-client
policies attached. The password is set to "changeme".auth.tf1 2 3 4 5 6 7 8 9 1011121314151617
Open the
secrets.tf
file which enableskv-v2
secrets engine (line 2-5).secrets.tf1 2 3 4 5 6 7 8 9 10111213141516171819
It enables transit secrets engine at
transit
(line 8-10), and create an encryption key named, "payment" (line 14-19).
Run Terraform to configure Vault
Optional: Start a Vault server in development mode with
root
as the root token if you don't have one running already.Set the client token in the
VAULT_TOKEN
environment variable.If the token is different, be sure to set it to the correct token value that has permissions to create policies, enable secrets engines, and enable auth methods.
Set the target Vault server address in the
VAULT_ADDR
environment variable if it's not done so already.If you are connecting to a remote Vault server, be sure to set the
VAULT_ADDR
value to the correct target Vault API address.Initialize Terraform to pull Vault provider plugin.
This will download the Vault plugin.
Execute the
apply
command to configure Vault.This will display the actions to be performed by Terraform.
When prompted, enter
yes
to accept the plan and proceed with Vault configuration.Once completed, the output similar to the following displays.
Verify the configuration
List existing policies to make sure that
admins
andeaas-client
policies were created.List enabled secrets engines to verify that kv-v2 and transit secrets engines are enabled.
List transit keys to make sure that
payment
key exists.Unset the
VAULT_TOKEN
environment variable which you used to run Terraform.Now, verify that you can log in with userpass auth method using the username, "student".
Enter
changeme
when prompted to enter the password.Example output:
The generated token has
eaas-client
policy attached.Review the
eaas-client
policy.Make sure that student can encrypt and decrypt data using the
payment
key.Example output:
Now, decrypt the returned ciphertext.
Example output:
The returned value is base64-encoded and must be decoded to reveal the original input value.
Note
The details about how transit secrets engine works are out of scope for this tutorial. If you are not familiar with transit secrets engine, read the Encryption as a Service: Transit Secrets Engine tutorial.
Clean up
When you are done exploring, you can undo the configuration made by Terraform.
Before running Terraform, make sure that VAULT_TOKEN
and VAULT_ADDR
environment variables exist and their values are set as you have done so in the
Run Terraform to configure Vault section.
Make sure that
VAULT_TOKEN
andVAULT_ADDR
environment variables are set.Destroy the Vault resources created by Terraform.
Remove the terraform state files.
Unset the
VAULT_TOKEN
andVAULT_ADDR
environment variables.
Note
To learn more about Terraform, visit Learn Terraform.
Next steps
Treat your Terraform files like any other code and manage them through a version control system such as GitHub. You may integrate it with your favorite CI/CD tool (Jenkins, Travis CI, Circle CI, etc.), always review and test the configuration.
Travis CI example:
You can test your Terraform files against a development server that runs locally, or use a Docker image of Vault.
Summary
In this guide you learned a technique for creating Vault policies and configurations using the Terraform Vault Provider. For more information, see the help and reference section.
Help and Reference
- Terraform Vault Provider documentation page
- Terraform Provider GitHub repository
- Learn Terraform
Tip
Terraform users can leverage the Vault's dynamic secrets engine to generate short-live cloud credentials when provisioning cloud resources. Inject secrets into Terraform using the Vault provider tutorial demonstrates the use of AWS secrets engine to manage AWS IAM credentials used by Terraform.