• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Vault
  • Install
  • Tutorials
  • Documentation
  • API
  • Integrations
  • Try Cloud(opens in new tab)
  • Sign up
Terraform for HCP Vault

Skip to main content
5 tutorials
  • Deploy HCP Vault with Terraform
  • Codify Management of HCP Vault
  • Deploy HCP Vault Performance Replication with Terraform
  • Apply Codified OSS Vault Configuration to HCP Vault with Terraform
  • Manage Codified Vault on HCP Vault with Terraform

  • Resources

  • Tutorial Library
  • Certifications
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Vault
  3. Tutorials
  4. Terraform for HCP Vault
  5. Deploy HCP Vault with Terraform

Deploy HCP Vault with Terraform

  • 14min

  • HCPHCP
  • TerraformTerraform
  • VaultVault

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

Note: This tutorial provisions resources that qualify under the AWS free-tier. If your account doesn't qualify under the AWS free-tier, HashiCorp is not responsible for any charges that you may incur.

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

  • An AWS account.

  • Your AWS credentials configured locally. To do this with IAM user authentication, set your AWS access key ID as an environment variable.

    $ export AWS_ACCESS_KEY_ID="<YOUR_AWS_ACCESS_KEY_ID>"
    

    Now set your secret key.

    $ export AWS_SECRET_ACCESS_KEY="<YOUR_AWS_SECRET_ACCESS_KEY>"
    

Tip: If you don't have access to IAM user credentials, use another authentication method described in the AWS provider documentation.

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, select Access control (IAM).

  2. Select Service principals, and then click Create 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.

    Create Service Principal

  5. Click Save. The Service principal is created and displays the overview page.

  6. Click Create service principal key.

    A dialog like the following example appears:

    Create Service Principal Key

  7. Copy the Client ID.

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

    $ export HCP_CLIENT_ID=<client id value previously copied>
    

    Terraform authenticate with HCP with this ID.

  9. Copy the Client secret.

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

    $ export HCP_CLIENT_SECRET=<client secret value previously copied>
    

    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.

Tip: The commands you use for the rest of the example should all be executed from within this directory.

Define variables

Examine the file variables.tf and determine what you might need to update to match your own AWS setup. The file defines all Terraform variables for the project expressed in HashiCorp Configuration Language (HCL).

variables.tf
1 2 3 4 5 6 7 8 9 1011121314151617181920212223242526272829303132333435363738394041variable "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 "peering_id" {
  description = "The ID of the HCP peering connection."
  type        = string
  default     = "learn-peering"
}

variable "route_id" {
  description = "The ID of the HCP HVN route."
  type        = string
  default     = "learn-hvn-route"
}

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"
}

variable "tier" {
  description = "Tier of the HCP Vault cluster. Valid options for tiers."
  type        = string
  default     = "dev"
}

Note the description values to understand each variable.

Line 37 through 41 defines the values for HCP Vault cluster tier. This is an optional parameter and the default value is dev; therefore, you can omit this parameter. However, if you wish to create a cluster other than a Dev cluster, overwrite this value by creating a terraform.tfvars file.

Example:

$ tee terraform.tfvars -<<EOF
tier = "starter_small"
EOF

The same for other variables. Make necessary changes before proceeding.

Note: Currently, AWS is the only supported cloud_provider type for the HCP provider, and values other than "aws" are not recognized.

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 vault.tf file line 1 through 5 to learn about the resource configured for the example.

vault.tf
1 2 3 4 5 6 7 8 9 101112resource "hcp_hvn" "learn_hcp_vault_hvn" {
  hvn_id         = var.hvn_id
  cloud_provider = var.cloud_provider
  region         = var.region
}

resource "hcp_vault_cluster" "learn_hcp_vault" {
  hvn_id     = hcp_hvn.learn_hcp_vault_hvn.hvn_id
  cluster_id = var.cluster_id
  tier       = var.tier
  #public_endpoint = true
}

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 vault.tf file line 7 through 12 to learn about the resource configured for the example.

vault.tf
1 2 3 4 5 6 7 8 9 101112resource "hcp_hvn" "learn_hcp_vault_hvn" {
  hvn_id         = var.hvn_id
  cloud_provider = var.cloud_provider
  region         = var.region
}

resource "hcp_vault_cluster" "learn_hcp_vault" {
  hvn_id     = hcp_hvn.learn_hcp_vault_hvn.hvn_id
  cluster_id = var.cluster_id
  tier       = var.tier
  #public_endpoint = true
}

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.

The public_endpoint parameter is commented out at line 11. See the Enable public cluster address section for more details about this optional parameter.

Tip: You can edit the variables.tf file to change some attributes for the Vault cluster. You can learn more about the available options in the Terraform HCP provider documentation.

Performance Replication: You can enable performance replication for HCP Vault by adding an additional hcp_hvn and hcp_vault_cluster block, then set the primary_link parameter. For more information please visit the Configure Vault performance replication - HCP Provider guide.

Define VPC peering

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

vpc-peering.tf
1 2 3 4 5 6 7 8 9 10111213141516171819202122232425262728293031provider "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
  peering_id          = var.peering_id
  peer_vpc_id         = aws_vpc.peer.id
  peer_account_id     = aws_vpc.peer.owner_id
  peer_vpc_region     = data.aws_arn.peer.region
}

resource "hcp_hvn_route" "peer_route" {
  hvn_link         = hcp_hvn.learn_hcp_vault_hvn.self_link
  hvn_route_id     = var.route_id
  destination_cidr = aws_vpc.peer.cidr_block
  target_link      = hcp_aws_network_peering.peer.self_link
}

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: 6 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: 6 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.

    HCP Vault cluster listing

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

    Vault cluster overview

    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, return to the main menu, and select HashiCorp Virtual Network.

    HVN listing

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

  5. Click Peering connections.

    HVN details

  6. Select the learn-peering link.

    HVN peering connection

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

Note: By default, the datacenter is not accessible from the internet. If you want to access the Vault API or UI, you will have to do it from a machine running inside your AWS VPC (recommended), or you need to configure your HCP Vault cluster to be publicly accessible.

VPC peering

Establish a VPC peering from your AWS VPC and HVN. By doing so, you can ensure that trusted clients (users, applications, containers, etc.) running inside the VPC connect to Vault and avoid systems outside of your selected network attempting to connect.

HCP Vault Architecture Diagram

Follow the Peering an AWS VPC with HashiCorp Cloud Platform (HCP) tutorial to create and establish a VPC peering. Vault clients running in the VPC can connect to learn-hcp-vault-cluster using the private cluster URL.

HCP Vault Private Address

Updating AWS security groups

Note: Configuring, managing, and securing access to your AWS workloads is a critical component of the shared responsibility model. Terraform changes the default AWS behavior of managing security groups. This section is provided to assist with understanding how you can manage access using Terraform. Refer to the Terraform AWS Provider documentation for a full list of available resources for AWS.

Once your AWS VPC is peered with the HVN, you will need to consider how to manage access from your AWS workloads to connect to HCP Vault.

When creating a new security group through the AWS console or AWS CLI, the default behavior is to create an egress or outbound rule that permits all traffic from the AWS workload to any destination, represented by the 0.0.0.0/0 CIDR notation.

However, if you manage your AWS security groups using Terraform, the default Terraform behavior is to remove the default egress rule. Once the default egress rule is removed, you need to explicitly add a rule to permit traffic from your AWS workloads to the desired destination.

How you utilize security groups in your organization will guide you on the best way to approach managing access to your HCP Vault cluster.

If you are already using Terraform to manage your AWS security groups, one option is to add an egress rule that will permit TCP traffic on port 8200 using the aws_security_group_rule resource to an existing security group.

Note: If you are already using the aws_security_group resource with in-line rules, you will need to update the existing Terraform configuration with a rule to allow port 8200. You cannot use both the aws_security_group and the aws_security_group_rule resources together.

12345678resource "aws_security_group_rule" "example" {
  type              = "egress"
  from_port         = 8200
  to_port           = 8200
  protocol          = "tcp"
  cidr_blocks       = ["172.25.16.0/20"]
  security_group_id = "sg-123456"
}
  • Line 2: The type parameter allows you to define whether the rule is for ingress (inbound) or egress (outbound).
  • Line 3-4: The from_port and to_port parameters allow you to define one or more port numbers. For Vault, clients will connect on port 8200.
  • Line 5: The protocol field specifies the type of traffic allowed.
  • Line 6: The cidr_blocks field contains the IP address the rule will permit access to, or from and should match the CIDR of your HVN.
  • Line 7: The security_group_id is the ID of the security group you want to update.

If you are already using Terraform to manage your AWS security groups, one option is to add a new security group with an egress rule that will permit TCP traffic on port 8200 using the aws_security_group resource with an in-line rule. This will create a new security group which will need to be attached to AWS workloads that connect to HCP Vault.

1 2 3 4 5 6 7 8 9 101112resource "aws_security_group" "allow_vault_egress" {
  name        = "allow_vault_egress"
  description = "Allow Vault outbound traffic"
  vpc_id      = aws_vpc.main.id

  egress {
    from_port        = 8200
    to_port          = 8200
    protocol         = "tcp"
    cidr_blocks      = ["172.25.16.0/20"]
  }
}
  • Line 2-3: Defines the name and description of the AWS security group.
  • Line 4: Specifies the AWS VPC ID.
  • Line 6: Defines whether this is an ingress (inbound) or egress (outbound) rule.
  • Line 7-8: The from_port and to_port parameters allow you to define one or more port numbers. For Vault, clients will connect on port 8200.
  • Line 9: The protocol field specifies the type of traffic allowed.
  • Line 10: The cidr_blocks field contains the IP address the rule will permit access to, or from and should match the CIDR of your HVN.

If you are not familiar with AWS security groups, refer to the AWS documentation on Control traffic to resources using security groups.

Enable public cluster address

If you want to enable the public cluster address, update the vault.tf file with public_endpoint set to true for the hcp_vault_cluster resource.

vault.tf
1 2 3 4 5 6 7 8 9 1011resource "hcp_hvn" "learn_hcp_vault_hvn" {
  hvn_id         = var.hvn_id
  cloud_provider = var.cloud_provider
  region         = var.region
}

resource "hcp_vault_cluster" "learn_hcp_vault" {
  hvn_id     = hcp_hvn.learn_hcp_vault_hvn.hvn_id
  cluster_id = var.cluster_id
  public_endpoint = true
}

Re-run the terraform apply command.

$ terraform apply

When prompted, enter yes to continue.

Plan: 0 to add, 1 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

When it completes, you can access your HCP Vault cluster using its public address.

HCP Vault Private Address

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: 6 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

 Back to Collection
 Next

This tutorial also appears in:

  •  
    13 tutorials
    HashiCorp Product Integrations
    Vault can manage secrets associated with other HashiCorp products.
    • Vault
  •  
    12 tutorials
    HCP Vault Operations
    Learn how to provision and connect to HCP Vault clusters.
    • Vault
  •  
    16 tutorials
    HashiCorp Products - Better Together
    Use Terraform with other Hashicorp products including Vault, Boundary, Consul, Packer, and Hashicorp Cloud Platform.
    • Terraform

On this page

  1. Deploy HCP Vault with Terraform
  2. Prerequisites
  3. Create service principal and key
  4. Clone vault-guides repository
  5. Deploy infrastructure
  6. Access Vault
  7. Clean up
  8. Next steps
  9. Help and Reference
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)