Define Vault policies with HCP Terraform

16min
|
Vault

Author: Carlos Villegas

This guide provides a comprehensive overview of using Terraform to manage HashiCorp Vault policies. By automating policy management, you can ensure consistency, improve security, and enhance operational efficiency.

This guide is designed for platform teams responsible for managing Vault policies who want to streamline their processes using Terraform.

Managing Vault policies with Terraform offers several benefits:

Automation: Streamline the process of managing Vault policies through Terraform.
Consistency: Ensure uniform policy application across environments. Policy modules and repositories become a single source of truth for definitions.
Security: Manage policies as code to enable version control and auditability. Easily implement least-privilege access for secrets.
Scalability: Scale policy management as your infrastructure grows.
Efficiency: Reduce manual intervention and errors when managing policies.

Prerequisites

To follow this validated pattern, you need:

A basic understanding of Terraform, Vault, and HCL.
Access to HCP Terraform and a Vault server with appropriate permissions. You must have permissions to manage Vault policies.
Familiarity with Git and version control concepts.
Review the Vault Solution Design Guide and the Vault Operating Guide for Adoption.
A GitHub, BitBucket, or other HCP Terraform-supported repository to store your Terraform configuration.

In addition, after you use Terraform to manage Vault, we recommend all Vault policy changes be implemented exclusively through Terraform. This ensures there are no state drifts between the Terraform configuration and the actual Vault policies.

Validated architecture

This validated architecture involves using Terraform to define and manage Vault policies. Policies are stored in a version control system, applied through Terraform, and enforced by the Vault server. This approach ensures automation, consistency, and security.

This document references the following roles:

Platform operator: Someone who manages your organization's plaform. This may include infrastructure, security, and operations teams. This is an all-encompassing role that may include the responsibilities of the Vault administrator and producer.
Vault administrator: Someone who has access to configure Vault secret engines.
Vault producer: Someone who has access to create and update Vault secrets.
Vault consumer: Someone who has access to read Vault secrets.

Architecture model workflow

The diagram shows the following steps:

Platform operators publish Terraform modules with standardized Vault policies to HCP Terraform private module registry. These modules are customized to your environment and let Vault administrators deploy standard policies quickly, consistently, and safely to all required namespaces.
Vault producers use these Terraform modules to manage Vault policies. They store the Terraform configurations in a version control system (VCS) repository.
The repositories containing Terraform configuration use a branching strategy to apply the policy changes to test environments before applying the same policies to the production environment.

Background and best practices

This section contains best practices for managing Vault policies using Terraform. You will need to understand these concepts and best practices to manage Vault with Terraform successfully.

When managing Vault namespaces:

Use separate workspaces for the root namespace (Vault Enterprise only).
Set up at least two workspaces per namespace (one for testing and one for production). You should deploy each workspace to a different Vault cluster.
Use a development cluster for testing with HCP Vault Dedicated and a production cluster for production environments.
If you have multiple clusters in a replicated set, you only need one workspace to connect to the primary cluster. Vault replication will propagate the policies to all clusters.

This validated pattern assumes that you have a new Vault installation, and guides you through the necessary steps to install the policies provided by the Terraform module.

Obtain the root token for your test and production clusters.
Grant root namespace access to the Vault administrators (Vault Enterprise only).
Follow the principle of least privilege when assigning permissions.
Pre-create the organization admin and child namespaces. You can also define them in your Terraform configuration.

If you are starting from an existing Vault environment, you will need to adjust the steps accordingly.

Configure dynamic credentials for Vault in HCP Terraform instead of using the root token. The JWT role you use must have enough permissions to manage policies. Refer to Dynamic Credentials with the Vault Provider to learn how to configure dynamic credentials for Vault in HCP Terraform.
The Terraform module in this document installs multiple policies. Review your environment to ensure the policy names do not conflict with your existing policies.
If there are any conflicts, either rename the policies in the Terraform module or your existing policies.
Ensure that all root tokens are revoked.

People and process considerations

Clear roles and defined processes are essential:

Roles and responsibilities: Define clear roles for policy authors, reviewers, and approvers. Platform sub-teams responsible for Vault should author and review policies. The reviewer must be a separate person than the author. Senior team members should conduct reviews, and final approvals should fall under the security sub-team.
Collaboration: Use version control systems to collaborate on policy definitions.
Review process: Implement a review process for policy changes to ensure security and compliance. The review of changes should be done via version control mechanisms, such as merge requests. Testing should be done via deployment to a sandbox installation of Vault, which is not used by other teams, but just serves to test important changes to the Vault platform, allowing validation of impact of policy changes, patching and other changes to be implemented.
Ongoing management: Ensure all policy updates follow the version control process. You should not manage Vault policies using a different method or process since it may cause state drift in Terraform.

Set up repositories

You will create two repositories and workspaces — one for your Vault root namespace and one for your Vault admin namespace. You may also create an optional repository and workspace for each child namespace.

Platform team members responsible for managing Vault policies should fork the repository into your own GitHub organization. If your organization does not use GitHub, clone the repository and push it to your organization's VCS.

$ git clone https://github.com/hashicorp-validated-designs/terraform-vault-policies

Apply a git tag in SemVer format to the repository and push it to your VCS. In the next step, you will upload this repository to your HCP Terraform private module registry (PMR).

Set up repository for root workspace

Create a new repository then clone it. Update the URL to point to your repository. This document will reference your cloned repository as root_namespace_setup and will create a set of standard policies in the Vault root namespace.

$ git clone YOUR_ROOT_POLICIES_REPOSITORY

Copy the Terraform configuration in examples/root_namespace_setup directory from the example repository into your repository.

Finally, protect the branch you will use for production. This is often the main branch. This ensures that changes to production must be reviewed and approved by the appropriate stakeholders.

Set up repository for admin workspace

Create a new repository then clone it. Update the URL to point to your repository. This document will reference your cloned repository as admin_namespace_setup and will create a set of standard policies in the Vault admin namespace.

$ git clone YOUR_ADMIN_POLICIES_REPOSITORY

Copy the Terraform configuration in examples/admin_namespace_setup directory from the example repository into your repository.

Finally, protect the branch you will use for production. This is often the main branch. This ensures that changes to production must be reviewed and approved by the appropriate stakeholders.

(Optional) Set up repository for child workspace

This is an optional step specifically for Vault producers — teams and people responsible for managing Vault but not necessarily other infrastructure.

Create a new repository then clone it. Update the URL to point to your repository. This document will reference your cloned repository as child_namespace_setup.

$ git clone YOUR_CHILD_NS_POLICIES_REPOSITORY

Copy the Terraform configuration in examples/simple directory from the example repository into your repository.

Modify the module source and version to match your PMR configuration In addition, modify the example code to match your needs.

Finally, protect the branch you will use for production. This is often the main branch. This ensures that changes to production must be reviewed and approved by the appropriate stakeholders.

Import the Vault policies module into your own module registry

Import the terraform-vault-policies repository into the HCP Terraform private module registry (PMR). Reference the SemVer tag you created when importing the repository.

Image showing the module imported into the Private Module Registry

Set up workspaces to manage policies at the root namespace (Vault Enterprise only)

Vault administrators should create a workspace for their sandbox Vault environment. This will be used to push new policies to a sandbox environment for initial validation of policies and the impact of their changes. This document will refer to this workspace as the root_namespace_setup-sandbox workspace.

When initially configuring workspaces, you need to authenticate with either root token (for Vault Enterprise) or an administration token (for HCP Vault Dedicated). For simplicity, this document refers to both types as the "root token", but the steps apply to either token type.

The examples in the terraform-vault-policies repo are configured for dynamic credentials, if you're starting from a root token as mentioned above, you'll need to:

Create a new branch in your repository for this environment (for example sandbox). All remaining changes in this step will be done on this branch.
Remove the dynamic credentials code from your root_namespace_setup repository (by removing the file called provider.tf) while you use the root token.
At this point, make sure to update your repository to use the correct source and version for the module from your PMR configuration.
(Optional) Modify the example code to match your needs. You can review the code in the other examples in the policies repository for inspiration., and then put it back in place to enable the use of dynamic credentials. The example code will automatically create several Vault policies in the root namespace that can be of use.
Configure the new workspace to run for the sandbox branch.
Configure the workspace variables for connectivity to Vault using the root token.
Push your sandbox branch to the VCS.
Run the workspace and review the plan and proceed with the apply or discard the run if needed.

After the Terraform run completes with the root token, you'll have a few policies available in the admin namespace that you can grant to the HCP Terraform role in use to be able to complete the rest of this document (which only covers policy management). The minimal set of permissions you require will be granted by the namespace-consumer and policy-admin policies. You can add additional permissions if you intend to manage more than just policies from this workspace.

You can use them to configure the JWT role for HCP Terraform authentication. Once those are in place, you need to reconfigure your workspaces to use Dynamic credentials instead of the root token. Once access is verified, you can revoke the root token. For details on this configuration refer to Dynamic Credentials with the Vault Provider.

Update your repository (by adding back the file called provider.tf from the example).
Remove the variables for root token authentication from the workspace and instead add the variables for dynamic credentials.
Revoke the root token.

You can now create new workspaces pointed to the same root_namespace_setup repository but configured to run with different branches, one branch per environment where you have separate Vault clusters. Name these additional workspaces with either the environment or branch name, for example root_namespace_setup-prod. And make sure to configure the variables for each workspace to match the target Vault cluster.

Set up workspaces to manage policies at the admin namespace

The Vault administrator should create a workspace for their sandbox Vault environment. This will be used to push new policies to a sandbox environment for initial validation of policies and the impact of their changes. This document will refer to this workspace as the admin_namespace_setup-sandbox workspace.

In a new setup, the workspaces will need to be initially configured to use the root token (for Vault Enterprise) or an administration token (for HCP Vault Dedicated), for simplicity, the rest of this document talks about the root token only, but it applies to both.

The examples in the terraform-vault-policies repo are configured for dynamic credentials, if you're starting from a root token as mentioned above, you will need to:

Create a new branch in your repository for this environment (for example sandbox). All remaining changes in this step will be done on this branch.
Remove the dynamic credentials code from your admin_namespace_setup repository (by removing the file called provider.tf) while you use the root token
At this point, make sure to update your repository to use the correct source and version for the module from your PMR configuration.
(Optional) Modify the example code to match your needs. You can review the code in the other examples in the policies repository for inspiration., and then put it back in place to enable the use of dynamic credentials. The example code will automatically create several Vault policies in the admin namespace that can be of use.
Configure the new workspace to run for the sandbox branch.
Configure the workspace variables for connectivity to Vault using the root token. Note: When configuring the workspace variables, ensure you add the namespace variable to the admin_namespace_setup workspaces. This namespace has to exist before you can run it successfully, you should create this namespace (for example admin) beforehand.
Push your sandbox branch to the VCS.
Run the workspace and review the plan and proceed with the apply or discard the run if needed.

Update your repository (by adding back the file called provider.tf from the example).
Remove the variables for root token authentication from the workspace and instead add the variables for dynamic credentials. Note: When configuring the workspace variables, ensure you add the namespace variable to the admin_namespace_setup workspaces. This namespace has to exist before you can run it successfully, you should create this namespace (for example admin) beforehand.
Revoke the root token.

(Optional) Set up workspaces to manage policies for the child namespaces

Platform consumers (those responsible for managing Vault policies in child namespaces) should create a workspace for their sandbox Vault environment. This guide will refer to this workspace as the child_namespace_setup-sandbox workspace. This will be used to push new policies to a sandbox environment for initial validation of policies and the impact of their changes.

Obtain a JWT role from your Vault administrator for each of your workspaces. This role should be attached to pre-existing policies that grant access to it to do your work. There are a few policies available in the admin namespace that you can grant to the HCP Terraform role in use to be able to complete the rest of this document (which only covers policy management). The minimal set of permissions you require will be granted by the namespace-consumer and policy-admin policies. You can add additional permissions if you intend to manage more than just policies from this workspaces.

Note: the examples in the terraform-vault-policies repo are configured for dynamic credentials, if you're starting from a root token as mentioned above, you'll need to:

Create a new branch in your repository for this environment (for example sandbox). All remaining changes in this step will be done on this branch.
At this point, make sure to update your repository to use the correct source and version for the module from your PMR configuration.
(Optional) Modify the example code to match your needs. You can review the code in the other examples in the policies repository for inspiration., and then put it back in place to enable the use of dynamic credentials. The example code will automatically create several Vault policies in the admin namespace and in your child namespace that can be of use for common access patterns on common secret engines.
Configure the new workspace to run for the sandbox branch.
Configure the workspace variables for connectivity to Vault using dynamic credentials. Note: When configuring the workspace variables, ensure you add the namespace variable to all of your child_namespace_setup workspaces. This namespace has to exist before you can run it successfully, you should create this namespace (for example example1) beforehand.
Push your sandbox branch to the VCS.
Run the workspace and review the plan and proceed with the apply or discard the run if needed.

After the Terraform run completes, you'll have a few policies available in the admin namespace that you can grant to the HCP Terraform users to access secrets in your child namespace. There will also be additional policies inside the child namespace that you can use to grant granular access to the applications for your configured secrets.

Verify the deployment

Platform team members responsible for managing Vault policies need verify the deployment of the policies.

Review the policies and create Vault tokens that use the policies to test different access scenarios.

(Optional) Clean up resources

Platform team members that are responsible for managing Vault policies should clean up the resources created in this guide.

Run a destroy on all the workspaces for policy management that need cleanup.
Delete all the workspaces.
Delete the policies module from your PMR (if needed).
Delete or archive the source code repositories in VCS (if needed).

Conclusion

In this guide, you have learned how to manage Vault policies with Terraform. You have also learned about the benefits of using Terraform for policy management and the key concepts and best practices for managing Vault policies with Terraform.

For more information on how to implement this pattern in your organization, refer to the following resources:

Migrate to Vault Integrated Storage

HCP Vault with CICD