Deploy HCP Vault with Terraform

HashiCorp Cloud Platform (HCP) features a web user interface to deploy and manage resources, including HCP Vault deployments in AWS. If you prefer to automate HCP Vault deployment however, one recommended approach is to use HashiCorp Terraform with the HCP provider.

You can use Terraform CLI and the HCP provider with your HCP account credentials from a terminal session to successfully deploy a HCP Vault cluster. This enables you to leverage HCP to rapidly and reliably deploy Vault clusters in AWS, while offloading the operations burden to SRE experts at HashiCorp.

»Prerequisites

To complete the steps listed in this tutorial, you need:

• The Terraform CLI (version 0.14.+) installed on your computer. Follow the Install Terraform tutorial if you need to learn how to install it.

• A HCP account.

• A git clone of the vault-guides repository; you will be instructed on how to clone and use the repository in later steps.

The tutorial example scenario also automatically deploys an AWS VPC, and peers it with your HashiCorp Virtual Network (HVN).

To successfully follow example, you need the following AWS related items.

• An AWS account.

• Your AWS credentials configured locally.

You can export the AWS credentials as environment variables to meet the second requirement.

Export the access key value.

$ export AWS_ACCESS_KEY_ID=<your AWS access key ID>

Export the secret access key value.

$export AWS_SECRET_ACCESS_KEY=<your AWS secret access key>

Export the session token value.

$export AWS_SESSION_TOKEN=<your AWS session token>

»Create service principal and key

Begin in the HCP portal to create a Service Principal and associated key that you will use with Terraform to deploy the HCP Vault cluster.

1. From the navigation menu within the Settings section, select Access Control (IAM).

2. In the Access Control (IAM) page, select the Service principals tab, and then click Create a service principal.

3. Enter the name you prefer in the Name field.

   For example, learn-hcp-vault for this tutorial.

4. Choose Contributor from the Role select field.

   

5. Click Create.

6. Click Create.

   The Service principal is created and the view returns to the index.

7. Click on the service principal name.

8. From the detail page, click on the Create service principal key link.

   A dialog like the following example appears:

   

9. Copy the Client ID.

10. In a terminal, export the variable HCP_CLIENT_ID to the Client ID.

    $ export HCP_CLIENT_ID=<client id value previously copied>
    

    Copy

    Terraform authenticate with HCP with this ID.

11. Copy the Client secret.

12. In a terminal, export the variable HCP_CLIENT_SECRET to the Client secret.

    $ export HCP_CLIENT_SECRET=<client secret value previously copied>
    

    Copy

    Terraform authenticate with HCP with this secret.

»Clone vault-guides repository

Clone the vault-guides repository to get the necessary Terraform configuration for the example scenarios.

Ensure that you are in a directory that you wish to work through this tutorial in, and clone the repository.

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

Change into the directory containing the base example scenario Terraform configuration.

$ cd vault-guides/cloud/terraform-hcp-vault/hcp-vault-vpc

Verify that you are in the correct directory before proceeding.

$ ls -1
variables.tf
vault.tf
vpc-peering.tf

The configuration in hcp-vault-vpc is the minimum configuration necessary to deploy HCP Vault using the Terraform HCP provider with peered VPC, as an example for this tutorial. You will need to significantly expand on this example to build a more advanced configurations for actual use cases.

»Define variables

You should first examine the file variables.tf and determine what you might need to update to match your own AWS setup.

$ cat variables.tf

The output contains all Terraform variables for the project expressed in HashiCorp Configuration Language (HCL).

variable "hvn_id" {
  description = "The ID of the HCP HVN."
  type        = string
  default     = "learn-hcp-vault-hvn"
}

variable "cluster_id" {
  description = "The ID of the HCP Vault cluster."
  type        = string
  default     = "learn-hcp-vault-cluster"
}

variable "region" {
  description = "The region of the HCP HVN and Vault cluster."
  type        = string
  default     = "us-west-2"
}

variable "cloud_provider" {
  description = "The cloud provider of the HCP HVN and Vault cluster."
  type        = string
  default     = "aws"
}

Note the description values to understand each variable.

If you need to make changes for your environment, edit variable.tf and save your changes before proceeding.

»Define HVN

Before you can deploy the HCP Vault cluster, you need to first configure an HVN. HVNs enable you to deploy HashiCorp Cloud products without the need to manage networking details.

You can define an HVN using the hcp_hvn resource. Examine the file vault.tf to learn about the resource configured for the example.

$ sed -n 9,13p vault.tf
resource "hcp_hvn" "learn_hcp_vault_hvn" {
  hvn_id         = var.hvn_id
  cloud_provider = var.cloud_provider
  region         = var.region
}

The configuration specifies an HVN resource named learn_hcp_vault_hvn that uses the variable values from the variables.tf to declare the HVN ID, the cloud provider name, and cloud provider region.

»Define HCP Vault cluster

For this tutorial you will deploy a single Vault cluster.

You can define an HCP Vault cluster using the hcp_vault_cluster resource. Examine the file vault.tf to learn about the resource configured for the example.

$ sed -n 15,18p vault.tf
resource "hcp_vault_cluster" "learn_hcp_vault" {
  hvn_id     = hcp_hvn.learn_hcp_vault_hvn.hvn_id
  cluster_id = var.cluster_id
}

The configuration specifies an HCP Vault cluster resource named learn_hcp_vault that uses the variable value from variables.tf to declare the HVN ID, and set the cluster ID to learn-hcp-vault-cluster.

»Define VPC peering

The HVN to VPC peering is defined in the vpc-peering.tf file.

$ cat vpc-peering.tf
provider "aws" {
  region = var.region
}

resource "aws_vpc" "peer" {
  cidr_block = "172.31.0.0/16"
}

data "aws_arn" "peer" {
  arn = aws_vpc.peer.arn
}

resource "hcp_aws_network_peering" "peer" {
  hvn_id              = hcp_hvn.learn_hcp_vault_hvn.hvn_id
  peer_vpc_id         = aws_vpc.peer.id
  peer_account_id     = aws_vpc.peer.owner_id
  peer_vpc_region     = data.aws_arn.peer.region
  peer_vpc_cidr_block = aws_vpc.peer.cidr_block
}

resource "aws_vpc_peering_connection_accepter" "peer" {
  vpc_peering_connection_id = hcp_aws_network_peering.peer.provider_peering_id
  auto_accept               = true
}

After making any necessary changes to vpc-peering.tf, proceed to deploy the infrastructure.

»Deploy infrastructure

After you have cloned the repository and defined the environment variables for HCP (and optionally AWS) in the example you wish to try, you are ready to deploy infrastructure.

First, initialize terraform; this downloads the necessary providers and initializes the backend.

$ terraform init

Initializing the backend...

Initializing provider plugins...
...snip...

Terraform has been successfully initialized!

After Terraform is initialized, you can verify that the resources will be created using terraform plan.

$ terraform plan

An execution plan has been generated and is shown below.
Resource actions are indicated with the following symbols:
...snip...

Plan: 5 to add, 0 to change, 0 to destroy.

You should note resources listed in the output, and at the end a summary that lists 5 resources to add.

Finally, you can deploy the resources with terraform apply.

$ terraform apply

...snip...
Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value:

Confirm the run by entering yes.

Once you confirm, it will take a few minutes to complete the deploy. If the deploy was successful, you should observe output at the end resembling this example.

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

»Access Vault

Return to the HCP portal to inspect the newly created Vault cluster.

1. From the navigation menu within the Resources section, select Vault.

   

2. Click learn-hcp-vault to access cluster details.

   

   The HCP Vault cluster overview is shown and the State is Running. You can interact with the cluster from this overview to perform a range of operational tasks.

3. To confirm the HVN to VPC peering status, select HashiCorp Virtual Network from the navigation menu.

   

4. Click learn-hcp-vault-hvn to access the HVN details.

   

5. In the HVN details page, select the Peering connections tab.

   

The details for the VPC peering connection you deployed are shown. The HVN and VPC are peered and ready to use.

»Clean up

Use terraform destroy to clean up all of the resources that you created.

$ terraform destroy

Terraform will prompt you for confirmation.

Do you really want to destroy all resources?
  Terraform will destroy all your managed infrastructure, as shown above.
  There is no undo. Only 'yes' will be accepted to confirm.

  Enter a value:

Confirm by entering yes.

Once you confirm, it will take a few minutes to complete the the destroy. When successful, you should observe output resembling the following example.

Destroy complete! Resources: 5 destroyed.

In this tutorial you learned how to automate the deployment of an HCP Vault cluster using the Terraform HCP provider. You also learned about some of the resources available with the provider.

You can find the full documentation for the HashiCorp Cloud Platform Terraform provider in the Terraform registry documentation.

»Next steps

From here you can learn more about HCP Vault including Vault Operation Tasks specific to HCP Vault.

With Vault in your HVN, and your HVN peered to an AWS VPC, you can deploy further AWS resources into the same VPC and access Vault with them through the Vault HTTP API or CLI.

»Help and Reference

• HashiCorp Cloud Platform

• HCP Vault

• Terraform HCP provider

• Terraform HCP provider documentation