Codify Management of Vault Using Terraform

»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

  To test and learn the use of Vault provider, you can use a Vault server running in development mode since you are going to perform Vault admin tasks in this tutorial.

Online tutorial: An interactive tutorial is also available if you do not wish to install a Vault HA cluster locally. Click the Show Terminal button to start.

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

»Examine the Terraform files

1. Clone the demo assets from the hashicorp/vault-guides GitHub repository to perform the steps described in this tutorial.

   $ git clone https://github.com/hashicorp/vault-guides.git
   

   $ git clone https://github.com/hashicorp/vault-guides.git

   Copy

   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.

2. Change the working directory to /operations/codify-mgmt/oss.

   $ cd vault-guides/operations/codify-mgmt/oss
   

   $ cd vault-guides/operations/codify-mgmt/oss

   Copy

   The directory contains Terraform files to configure Vault.

   $ tree
   .
   ├── auth.tf
   ├── main.tf
   ├── policies
   │   ├── admin-policy.hcl
   │   └── eaas-client-policy.hcl
   ├── policies.tf
   └── secrets.tf
   

   $ tree.├── auth.tf├── main.tf├── policies│   ├── admin-policy.hcl│   └── eaas-client-policy.hcl├── policies.tf└── secrets.tf

   Copy

3. Open the main.tf file in your preferred text editor to examine its content.

   provider "vault" {
     # It is strongly recommended to configure this provider through the
     # environment variables:
     #    - VAULT_ADDR
     #    - VAULT_TOKEN
     #    - VAULT_CACERT
     #    - VAULT_CAPATH
     #    - etc.
   }
   

   main.tf

   Copy

   123456789provider "vault" {  # It is strongly recommended to configure this provider through the  # environment variables:  #    - VAULT_ADDR  #    - VAULT_TOKEN  #    - VAULT_CACERT  #    - VAULT_CAPATH  #    - etc.}

   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.

4. Open the policies.tf file and examine the vault_policy resources.

   # Create admin policy in the root namespace
   resource "vault_policy" "admin_policy" {
     name   = "admins"
     policy = file("policies/admin-policy.hcl")
   }
   
   # Create 'training' policy
   resource "vault_policy" "eaas-client" {
     name   = "eaas-client"
     policy = file("policies/eaas-client-policy.hcl")
   }
   

   policies.tf

   Copy

   1 2 3 4 5 6 7 8 9 1011# Create admin policy in the root namespaceresource "vault_policy" "admin_policy" {  name   = "admins"  policy = file("policies/admin-policy.hcl")}
   # Create 'training' policyresource "vault_policy" "eaas-client" {  name   = "eaas-client"  policy = file("policies/eaas-client-policy.hcl")}

5. Open the auth.tf file and note that it enables userpass auth method and creates a user, "student" with admins and eaas-client policies attached. The password is set to "changeme".

   resource "vault_auth_backend" "userpass" {
     type = "userpass"
   }
   
   # Create a user, 'student'
   resource "vault_generic_endpoint" "student" {
     depends_on           = [vault_auth_backend.userpass]
     path                 = "auth/userpass/users/student"
     ignore_absent_fields = true
   
     data_json = <<EOT
   {
     "policies": ["admins", "eaas-client"],
     "password": "changeme"
   }
   EOT
   }
   

   auth.tf

   Copy

   1 2 3 4 5 6 7 8 9 1011121314151617resource "vault_auth_backend" "userpass" {  type = "userpass"}
   # Create a user, 'student'resource "vault_generic_endpoint" "student" {  depends_on           = [vault_auth_backend.userpass]  path                 = "auth/userpass/users/student"  ignore_absent_fields = true
     data_json = <<EOT{  "policies": ["admins", "eaas-client"],  "password": "changeme"}EOT}

6. Open the secrets.tf file which enables kv-v2 secrets engine (line 2-5).

   # Enable K/V v2 secrets engine at 'kv-v2'
   resource "vault_mount" "kv-v2" {
     path = "kv-v2"
     type = "kv-v2"
   }
   
   # Enable Transit secrets engine at 'transit'
   resource "vault_mount" "transit" {
     path = "transit"
     type = "transit"
   }
   
   # Creating an encryption key named 'payment'
   resource "vault_transit_secret_backend_key" "key" {
     depends_on = [vault_mount.transit]
     backend    = "transit"
     name       = "payment"
     deletion_allowed = true
   }
   

   secrets.tf

   Copy

   1 2 3 4 5 6 7 8 9 10111213141516171819# Enable K/V v2 secrets engine at 'kv-v2'resource "vault_mount" "kv-v2" {  path = "kv-v2"  type = "kv-v2"}
   # Enable Transit secrets engine at 'transit'resource "vault_mount" "transit" {  path = "transit"  type = "transit"}
   # Creating an encryption key named 'payment'resource "vault_transit_secret_backend_key" "key" {  depends_on = [vault_mount.transit]  backend    = "transit"  name       = "payment"  deletion_allowed = true}

   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

1. Set the client token in the VAULT_TOKEN environment variable. If not using the root token, be sure that this token has permissions to create policies, enable secrets engines, and enable auth methods.

   $ export VAULT_TOKEN="<token>"
   

   $ export VAULT_TOKEN="<token>"

   Copy

2. Set the target Vault server address as the value of the VAULT_ADDR environment variable; an example value is used here, but you should use the actual host and port values for your Vault server. if it's not done so already.

   $ export VAULT_ADDR="http://127.0.0.1:8200"
   

   $ export VAULT_ADDR="http://127.0.0.1:8200"

   Copy

3. Initialize Terraform to pull Vault provider plugin.

   $ terraform init
   
   Initializing the backend...
   ...snip...
   Terraform has been successfully initialized!
   

   $ terraform init
   Initializing the backend......snip...Terraform has been successfully initialized!

   Copy

   This will download the Vault plugin.

4. Execute the apply command to configure Vault.

   $ terraform apply
   

   $ terraform apply

   Copy

   This will display the actions to be performed by Terraform.

   When prompted, enter yes to accept the plan and proceed with Vault configuration.

   Plan: 7 to add, 0 to change, 0 to destroy.
   
   Do you want to perform these actions?
     Terraform will perform the actions described above.
     Only 'yes' will be accepted to approve.
   
     Enter a value: yes
   

   Plan: 7 to add, 0 to change, 0 to destroy.
   Do you want to perform these actions?  Terraform will perform the actions described above.  Only 'yes' will be accepted to approve.
     Enter a value: yes

   Once completed, the output similar to the following displays.

   Apply complete! Resources: 7 added, 0 changed, 0 destroyed.
   

   Apply complete! Resources: 7 added, 0 changed, 0 destroyed.

»Verify the configuration

»Clean up

When you are done exploring, you can undo the configuration made by Terraform.

1. Destroy the Vault resources created by Terraform.

   $ terraform destroy -auto-approve
   
   ...snip...
   
   Destroy complete! Resources: 7 destroyed.
   

   $ terraform destroy -auto-approve
   ...snip...
   Destroy complete! Resources: 7 destroyed.

   Copy

2. Remove the terraform state files.

   $ rm *.tfstate.*
   

   $ rm *.tfstate.*

   Copy

3. Unset the VAULT_TOKEN environment variable.

   $ unset VAULT_TOKEN 
   

   $ unset VAULT_TOKEN 

   Copy

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

sudo: false

env:
  - VAULT_ADDR=<target_vault_address>  VAULT_TOKEN=<token>

before_install:
  - scripts/install.sh

before_script:
  - vault server -dev -dev-root-token-id="$VAULT_TOKEN"

script:
  - terraform init
  - terraform apply -auto-approve

sudo: false
env:  - VAULT_ADDR=<target_vault_address>  VAULT_TOKEN=<token>
before_install:  - scripts/install.sh
before_script:  - vault server -dev -dev-root-token-id="$VAULT_TOKEN"
script:  - terraform init  - terraform apply -auto-approve

»Help and Reference

• Terraform Vault Provider documentation page
• Terraform Provider GitHub repository
• Learn Terraform