Deploying Vault using Terraform

HashiCorp provides a set of official Terraform(opens in new tab) modules to make it easier to deploy a Vault Enterprise environment that adheres to the requirements and standards laid out in this HashiCorp Validated Design.

Platform-specific guidance

Select the tab below for your cloud for further guidance.

Using this module, you will be able to use Terraform to deploy a complete, end-to-end Vault Enterprise deployment inside of your own cloud account.

While we have made efforts throughout this document to provide prescriptive best practices, we recognize that each organization has their own unique requirements and constraints when it comes to deploying infrastructure. Wherever possible, we have attempted to represent the different considerations you will need to make when deploying Vault in your cloud environment within the context of this Terraform module. The module contains additional capabilities that you may wish to review if the variables from this module do not suit your specific needs.

Deployment sequence overview

1. Create the certificate files.
2. Obtain the license file.
3. Download the Vault CLI.
4. Download the Terraform CLI.
5. Deploy your prerequisite resources.
6. Obtain the HashiCorp Validated Design Terraform module for deploying Vault Enterprise.
7. Configure your cloud credentials.
8. Initialize your Terraform workspace.
9. Input your variables, including the values from your prerequisite deployment, in the module for deployment.
10. Create a Terraform plan.
11. Apply the plan.
12. Validate the cluster was created and is reachable.
13. Initialize the Vault cluster.

Preparation

Create the certificate files

Create a standard X.509 certificate that will be installed on the Vault servers. Refer to your organization's process on creating a new certificate that matches the DNS record you intend to direct users to when accessing Vault.

A total of three files will be needed as follows.

1. The certificate (vault-public.pub).
2. The certificate's private key (vault-private.key).
3. The bundle file from the certificate authority used to vend the certificate (ca.pub).

Keep these files to hand as you will need them later in the installation process.

Obtain the Vault Enterprise license file

Obtain the Vault Enterprise license file from your HashiCorp account team. This file contains a license key unique to your environment. The file will be named something like vault.hclic.

Keep this file handy, as you will need it later in the installation process.

Download and Install the Vault CLI

• Download the appropriate package for your operating system from the HashiCorp Releases(opens in new tab) site.
• Unzip the package.
• Move the vault binary (vault.exe for Windows) to a directory in your system's PATH.

Download and install the Terraform CLI

• Download the appropriate package for your operating system from the HashiCorp Releases(opens in new tab) site.
• Unzip the package.
• Move the terraform binary (terraform.exe for Windows) to a directory in your system's PATH.

Download the Terraform module

For the purpose of an automated deployment, HashiCorp and HashiCorp partners provide private Terraform modules to customize and support your deployment.

Once you have downloaded the module, navigate to the examples/default/ directory. Use this as the base working directory during the installation process.

Installation

Initialize Terraform

Run terraform init to initialize your Terraform workspace. Inspect the output to ensure that all providers and modules are successfully downloaded, and that there are no outstanding errors before continuing.

Configure variables for deployment

Review the terraform.tfvars.example file HashiCorp maintains in the examples/default/ directory for explanations of each relevant variable. There is a terraform.tfvars.example file in the respective module for each public cloud provider. Copy this file to a file called terraform.tfvars, and then fill in the values for each declared variable with the applicable values for your environment.

Create and apply Terraform plan

From the examples/default/ directory, generate a Terraform plan with the following command:

terraform plan -out plan.out

Review the plan output to see the changes that will be applied, then apply the changes with this command:

terraform apply plan

Confirm the changes by typing yes when prompted.

Validate installation

Run the following command:

terraform output

Using the terraform output that references the load balancer name or ip address, create a new DNS entry that matches your TLS certificate and points to the load balancer for the Vault cluster. Set the following environment variables:

$ export VAULT_ADDR="https://vault.example.com:8200/"

Test that the Vault cluster is running and reachable by running:

vault status

Initialize

Create GPG public keys

For each individual who will be receiving a key share, create their own unique GPG public key:

$ cat > alice_key.conf << EOF
%echo Generating a basic OpenPGP key for Alice
Key-Type: 1
Key-Length: 4096
Subkey-Type: 1
Subkey-Length: 4096
Name-Real: Alice
Name-Comment: Alice is a Vault PGP user
Name-Email: alice@example.com
Expire-Date: 1
Passphrase: recede-yard-unwilling-shrouded
%commit
%echo done
EOF
 
 
$ gpg --full-gen-key --batch alice_key.conf
…
$ gpg --output alice_key.pub --export alice@example.com

Initialize Vault

Pass in the GPG public key from each participating individual to initialize Vault with the API, CLI, or UI. Once Vault initializes, it returns the key shares, each one encrypted with the GPG public keys which you passed in at initialization time.

$ vault operator init \
  -pgp-keys “alice_key.pub,bob_key.pub,carol_key.pub,dan_key.pub,frank_key.pub" \
  -root-token-pgp-key "alice_key.pub"
 
 
Recovery Key 1: Fr6OZBDRG…KsgqC
Recovery Key 2: X6/RDBpC…rZfUM
Recovery Key 3: XCAmAgbr…J0+P3
Recovery Key 4: JwoPoWtl…QXhyV
Recovery Key 5: 8Rdk5D+7…0tgWJ
 
 
Initial Root Token: hvs.NpBT…cbbXZ
 
 
Success! Vault is initialized
 
 
Recovery key initialized with 5 key shares and a key threshold of 3. Please
securely distribute the key shares printed above.

Record the root_token from the output, so you can authenticate to Vault and begin configuration of user authentication.

Each individual should now record their unique recovery key and store it safely. This is their key share, which is now encrypted and base64-encoded.

This concludes the key ceremony.

You should now have a running cluster. Log into Vault:

$ VAULT_ADDR=$(terraform output vault_addr) VAULT_TOKEN="hvs-TOKEN-value-from-key-ceremony" vault login