Terraform: Integration Guide for Vault (Beta)

Introduction

HashiCorp Vault offers an identity-based management system for secrets and encryption, ensuring secure access through authentication and authorization. By integrating Terraform with Vault, organizations can enhance their infrastructure and security lifecycle management by enabling secure provisioning, dynamic secret management, and automated secret rotation, thus bolstering their overall security framework.

In this guide we will cover the following key use cases for integrating Terraform with Vault:

1. Vault Authentication.
2. Dynamic Provider Credentials (Dynamic Credentials for Terraform Providers including AWS, Azure & GCP).
3. Reading/Writing Secrets (Interacting with Vault within Terraform run).
4. Terraform Secrets Engine (Generating dynamic secrets for Terraform runs using Vault).

Target Audience

• Platform Teams responsible for managing HCP Terraform.
• Security Teams responsible for managing HCP Vault Dedicated.

Prerequisites and limitations

Before starting on this guide, we recommend that you have reviewed the following:

• Access to HCP Terraform & Vault.
• Reviewed and implemented Vault Enterprise(opens in new tab) and Terraform Enterprise(opens in new tab) Solution Design Guide (for self-hosted customers).
• Reviewed Terraform Operating Guide - Adopting(opens in new tab).
• Reviewed Vault Operating Guide - Adopting(opens in new tab).
• Terraform and Vault training(opens in new tab).

Access requirements

• HCP Vault:
  • Admin rights to configure Vault namespaces, policies, authentication methods and secret engines.
• HCP Terraform:
  • Workspace administrator rights to configure workspaces, set up VCS integrations, and manage environment variables.
• Version control system (VCS):
  • Access to repositories storing Terraform configurations and potentially Packer templates, including rights to commit changes and manage branches.

Integration architecture

Terraform can connect to Vault either directly (a) or via the Terraform Cloud Agent (b). For HCP Terraform customers we recommend that Terraform Cloud agents are used to connect to Vault (b). This will ensure that Vault DNS is not exposed to the public internet and improves the security posture of the integration.

For Terraform Enterprise customers, since both Terraform and Vault will be on a private network either method will provide the same level of security.

If you are using HCP Terraform or Terraform Enterprise with HCP Vault Dedicated, we again recommend using Terraform Cloud agent. The Terraform Cloud agent should be able to use use private (non-public) networking leveraging HVN Hashicorp Virtual Network(opens in new tab).

In this example below we show how to connect Terraform to Vault using the Terraform Cloud agent when Terraform and Vault are on different networks. While this example shows HCP Terraform and HCP Vault Dedicated, the same pattern can be used for Terraform Enterprise and Vault Enterprise in different networks.

Prescriptive guidance

People & Process

We have already discussed recommended People & Process patterns in our operating guides. We recommend that the platform team admin is responsible for the following:

1. Ensure that the integration between HCP Terraform and HCP Vault is established.
2. Establish an appropriate mapping between the Terraform projects, workspaces and Vault namespaces keeping RBAC and scalability as priorities.
3. Ensure that the appropriate Terraform workspaces are assigned the correct variable sets with Vault static secrets or/and integrated with the appropriate Vault namespaces and secret engines for dynamic credentials.
4. Ensure documentation is in a centralized location for the application team regarding this integration.
5. Set up periodic collaboration meetings with the cross-functional teams to ensure that the integration’s objectives are being met.

Object planning

We recommend careful planning to ensure that objects in both HCP Terraform (Projects/Workspaces) and Vault (Namespaces/Secret Engines) are mapped correctly. This will ensure that the integration is scalable and secure.

Both the Terraform and Vault Operating guides provide recommendations on how an organization should structure their Terraform projects and Vault namespaces. This guide that those recommendations to the next step from an integration perspective.

While there is no one correct answer to how to map Terraform projects to Vault namespaces, we recommend that whatever the pattern is, it should be consistent across the organization. This will ensure that the integration is scalable and secure.

In the example we demonstrate how workspaces/projects in Terraform can be mapped to namespaces in Vault.

1. In the HCP Terraform organization, projects are created based on two factors(opens in new tab), the line of business they belong to and the application for which the infrastructure will be provisioned. Similarly, Vault namespaces are created for each line of business.
2. Each application would be deployed into multiple environments. Additionally, the infrastructure is divided into different tiers like compute, storage and databases, each having its own workspace according to the workspace design best practices].
3. An HCP Terraform organization would map logically to the Vault root namespace. Similarly, all projects created for a particular line of business(LOB) would map logically to a single namespace in Vault dedicated to storing all secrets of that particular LOB.
4. A dedicated secrets engine mount will be created for each environment within the LOB namespace. For example, dynamic credentials for AWS accounts will be mounted on aws-dev, aws-uat, aws-prod mounts respectively. Mounts that allow a folder structure like K/V can have a path structure like kv/dev, kv/uat etc with RBAC policies in place

Additional recommendations on Vault namespace design are listed here(opens in new tab)