Vault on Amazon Web Services with Terraform represents a production pattern where secret management, infrastructure provisioning, and dynamic credential issuance converge. The reference material covers three distinct but interlocking surfaces: the HashiCorp Validated Design module for Vault Enterprise on AWS EC2, the now-deprecated community Terraform AWS Vault modules, and the integration of Vault dynamic provider credentials with HCP Terraform for AWS access. These surfaces are tied together by the common requirement for AWS pre-existing resources, KMS-backed auto-unseal, TLS material handling, and short-lived AWS credentials issued by Vault’s AWS Secrets Engine.
The operational reality for teams adopting this stack is that Vault itself must be placed securely before it can be used to issue credentials. That placement requires a VPC, a dedicated KMS Key to support auto-unseal, TLS certificates with intermediate chain, private key and CA certificate for privately signed certs, Secrets Manager access for initial secrets such as product license and TLS material, and optionally a Route53 Hosted Zone if createroute53vaultdnsrecord is used. AWS API credentials for Terraform must be available to create the supporting AWS control plane resources: Autoscaling Group, Launch Template and Placement Group, IAM Roles and Instance Profile, Load Balancer, Listener and Target Group, Security Group and Security Group Rules.
Once Vault is running, the next layer is how Terraform consumes Vault. HCP Terraform can authenticate to AWS via Vault-generated credentials during plan and apply. The authentication is only valid for the length of the plan or apply phase. The setup requires configuring Vault Dynamic Provider Credentials with a trust configuration between Vault and HCP Terraform, Vault roles and policies for workspaces, and environment variables in those workspaces. The Vault AWS Secrets Engine must be set up in the Vault instance. HCP Terraform workspaces need additional environment variables. Terraform providers must be configured to work with Vault-backed dynamic credentials.
In practice, the Vault AWS Secrets Engine mounts at a path such as dynamic-aws-creds-vault-admin-path with type aws. A vaultawsaccesscredentials.creds data block retrieves dynamic short-lived AWS credentials from Vault. Those credentials are fed to the AWS provider. The provider is initialized with short-lived credentials retrieved by vaultawsaccesscredentials.creds. The provider configuration is scoped to a region such as us-east-1 as defined by the region variable. An awsami.ubuntu data block retrieves the most recent Ubuntu image. An awsinstance.main resource block creates a t2.micro EC2 instance.
The lifecycle of a dynamic credential is visible in IAM. Searching for the username prefix vault-token-terraform-dynamic-aws-creds-vault-admin shows nothing before plan or apply. A user with this prefix appears on terraform plan or terraform apply. After terraform apply, a IAM user is created. The IAM user was generated by Vault with the appropriate IAM policy configured by the Vault Admin workspace. Because the defaultleasettl_seconds is set to 120 seconds, Vault will revoke those IAM credentials and they will be removed from the AWS IAM console after 120 seconds. Every Terraform run uses its own unique set of AWS IAM credentials scoped to whatever the Vault Admin has defined. The Terraform Operator does not have to manage long-lived AWS credentials locally.
HashiCorp Validated Design for Vault Enterprise on AWS with EC2
The Terraform module aligned with HashiCorp Validated Designs deploys Vault Enterprise on Amazon Web Services using EC2 instances. This module deploys Vault Enterprise with integrated storage. The module assumes a pre-built AWS foundation.
The module requires the following to already be in place in AWS:
- A VPC with the following:
- A dedicated KMS Key to support auto-unseal
- TLS certificate with intermediate certs, certificate private key and CA certificate required for privately signed cert
- Access to Secrets Manager for initial secrets such as product license and TLS certificate material
- Optional A Route53 Hosted Zone if using createroute53vaultdnsrecord
- AWS API credentials for Terraform to deploy:
- AWS Autoscaling Group, Launch Template and Placement Group
- AWS IAM Roles and Instance Profile
- AWS Load Balancer, Listener and Target Group
- AWS Security Group and Security Group Rules
The impact of these prerequisites is that the module is not a greenfield deploy. Teams must first provision networking, key management, and certificate material before the Vault Enterprise cluster can be created. The dedicated KMS Key to support auto-unseal means Vault can recover automatically after restarts or reboots without manual intervention. The requirement for TLS certificate with intermediate certs, certificate private key and CA certificate ensures privately signed certs can be used for inter-node and client TLS. Access to Secrets Manager for initial secrets such as product license and TLS certificate material centralizes sensitive bootstrap data outside Terraform state.
The module supports Linux distributions via the ec2osdistro variable.
| Distribution | Value | AMI source |
|---|---|---|
| Ubuntu 22.04 LTS | ubuntu (default) | Canonical |
| RHEL 9 | rhel | Red Hat |
| Amazon Linux 2023 | al2023 | Amazon |
| CentOS | centos | Custom AMI required |
Note: For CentOS deployments, you must provide a custom AMI ID via vmimageid.
The module supports both x86_64 amd64 and ARM64 aarch64 instances.
The choice of distro affects AMI selection, package manager behavior, and instance metadata. Ubuntu 22.04 LTS as default aligns with Canonical support and HashiCorp testing. RHEL 9 provides Red Hat lifecycle policies. Amazon Linux 2023 is optimized for AWS services. CentOS requires a custom AMI ID via vmimageid, shifting AMI ownership to the operator.
Deprecated Community Terraform AWS Vault Modules
This repository is no longer supported, please consider using this repository for the latest and most supported version for Vault. Moving forward in the future this repository will be no longer supported and eventually lead to deprecation. Please use our latest versions of our products moving forward or alternatively you may fork the repository to continue use and development for your personal/business use.
The repo contains a set of modules in the modules folder for deploying a Vault cluster on AWS using Terraform. Vault is an open source tool for managing secrets. By default, this Module uses Consul as a storage backend. You can optionally add an S3 backend for durability.
The Module includes:
- private-tls-cert: Generate a private TLS certificate for use with a private Vault cluster.
- update-certificate-store: Add a trusted, CA public key to an OS's certificate store. This allows you to establish TLS connections to services that use this TLS certs signed by this CA without getting x509 certificate errors.
This repo has the following structure:
- modules: This folder contains several standalone, reusable, production-grade modules that you can use to deploy Vault.
- examples: This folder shows examples of different ways to combine the modules in the modules folder to deploy Vault.
- test: Automated tests for the modules and examples.
- root folder: The root folder is an example of how to use the vault-cluster module module to deploy a Vault cluster in AWS
The deprecation notice means operators should not start new production workloads on this repo. The private-tls-cert module addresses the TLS material requirement seen in the HVD module. The update-certificate-store module addresses x509 errors when connecting to services using CA-signed certs.
Vault-Backed Dynamic Provider Credentials for HCP Terraform
Configuring the integration requires the following steps:
- Configure Vault Dynamic Provider Credentials: Set up a trust configuration between Vault and HCP Terraform, create Vault roles and policies for your HCP Terraform workspaces, and add environment variables to those workspaces.
- Configure the Vault AWS Secrets Engine: Set up the AWS secrets engine in your Vault instance.
- Configure HCP Terraform: Add additional environment variables to the HCP Terraform workspaces where you want to use Vault-Backed Dynamic Credentials.
- Configure Terraform Providers: Configure your Terraform providers to work with Vault-backed dynamic credentials.
If you are configuring a Stack, refer to Authenticate a Stack to learn about the workflow of authenticating your Stack deployments with dynamic credentials.
Once setup is complete, HCP Terraform automatically authenticates with AWS via Vault-generated credentials during the plan and apply phase of each run. The AWS provider's authentication is only valid for the length of the plan or apply phase.
You must first set up Vault dynamic provider credentials before you can use Vault-backed dynamic credentials. This includes setting up the JWT auth backend in Vault, configuring trust between HCP Terraform and Vault, and populating the required environment variables in your HCP Terraform workspace.
Follow the instructions in the Vault documentation for setting up the AWS secrets engine in your Vault instance.
The impact is elimination of long-lived AWS access keys in Terraform workspaces. Credentials are short-lived and scoped to the run. The contextual connection is that this pattern relies on the Vault cluster already being deployed and healthy via the HVD or community modules.
AWS KMS Auto-Unseal and Secrets Management with Terraform and Ansible
Because AWS KMS enables vault auto-unsealing, allowing vault to recover automatically after restarts/reboots without manual intervention.
Conclusion from the reference material: Integrating HashiCorp Vault with AWS KMS, Terraform, and Ansible enables secure, automated, and resilient secrets management. Vault centrally stores secrets, AWS KMS ensures auto-unsealing after reboots, Terraform manages secrets dynamically, and Ansible consumes them securely at runtime, making the solution ideal for real-world production and disaster recovery scenarios.
The auto-unseal capability removes the operational burden of manual unseal keys. Terraform manages secrets dynamically via the Vault provider and AWS provider. Ansible consumes them securely at runtime, closing the loop from secret storage to configuration management.
Terraform Operator Workspace Pattern with Vault AWS Secrets Engine
The tutorial flow for getting started includes:
- Terraform installed locally
- Vault installed locally
- an AWS account and AWS Access Credentials
If you don't have AWS Access Credentials, create your AWS Access Key ID and Secret Access Key by navigating to your service credentials in the IAM service on AWS. Click Create access key here to view your AWSACCESSKEYID and AWSSECRETACCESSKEY. You will need these values later.
Start a Vault server in development mode with education as the root token. Leave this process running in your terminal window.
vault server -dev -dev-root-token-id="education"
The server output includes:
Api Address: http://127.0.0.1:8200
Cgo: disabled
Cluster Address: https://127.0.0.1:8201
Go Version: go1.14.4
Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", maxrequestduration: "1m30s", maxrequestsize: "33554432", tls: "disabled")
Log Level: info
Mlock: supported: false, enabled: false
Recovery Mode: false
Storage: inmem
Version: Vault v1.4.3
Version Sha: 491533b63ec9c1343eac3a24d8a7558185a0acb7+CHANGES
Your Vault server should now be up. Navigate to localhost:8200 and login into the instance using your root token: education.
In your terminal, clone the Inject Secrets repository and navigate into the directory.
Mounting the AWS Secrets Engine is confirmed by log:
[INFO] core: successful mount: namespace= path=dynamic-aws-creds-vault-admin-path/ type=aws
Now that you have successfully configured Vault's AWS Secrets Engine, you can retrieve dynamic short lived AWS token to provision an EC2 instance.
Navigate to the Terraform Operator workspace.
cd ../operator-workspace
In the main.tf file, you should find the following data and resource blocks:
the terraformremotestate.admin data block retrieves the Terraform state file generated from your Vault Admin workspace
the vaultawsaccess_credentials.creds data block retrieves the dynamic, short-lived AWS credentials from your Vault instance. Notice that this uses the Vault Admin workspace's output variables: backend and role
the aws provider is initialized with the short-lived credentials retrieved by vaultawsaccess_credentials.creds. The provider is configured to the us-east-1 region, as defined by the region variable
the aws_ami.ubuntu data block retrieves the most recent Ubuntu image
the aws_instance.main resource block creates an t2.micro EC2 instance
Initialize the Terraform Operator workspace.
terraform init
Navigate to the IAM Users page in AWS Console. Search for the username prefix vault-token-terraform-dynamic-aws-creds-vault-admin. Nothing should show up on your initial search
Apply the Terraform configuration, remember to confirm the run with a yes. Terraform will provision the EC2 instance using the dynamic credentials generated from Vault.
terraform apply
Refresh the IAM Users and search for the vault-token-terraform-dynamic-aws-creds-vault-admin prefix. You should see a IAM user.
This IAM user was generated by Vault with the appropriate IAM policy configured by the Vault Admin workspace. Because the defaultleasettl_seconds is set to 120 seconds, Vault will revoke those IAM credentials and they will be removed from the AWS IAM console after 120 seconds.
Navigate to the EC2 page and search for dynamic-aws-creds-operator. You should see an instance provisioned by the Terraform Operator workspace using the short-lived AWS credentials.
Every Terraform run with this configuration will use its own unique set of AWS IAM credentials that are scoped to whatever the Vault Admin has defined.
The Terraform Operator doesn't have to manage long-lived AWS credentials locally.
The pattern demonstrates separation of concerns: a Vault Admin workspace configures the secrets engine, roles and policies, and outputs backend and role names. An Operator workspace consumes those outputs via remote state and Vault data sources.