Manage Vault policies using Terraform

Purpose of this guide

This guide aims to provide a comprehensive overview of how to use Terraform to manage HashiCorp Vault policies. By leveraging Terraform, users can automate and streamline the process of policy management in Vault, ensuring consistency, security, and ease of use.

Other guides provide details on managing other Vault resources through Terraform.

Target audience

This guide is intended for Platform Teams who are responsible for managing Vault policies and are looking to automate this process using Terraform.

Benefits

Benefits of this solution:

• Automation: Streamline the process of managing Vault policies through Terraform.
• Consistency: Ensure consistent policy application across different environments, enhancing your ability to understand the environment at large scale. Your repository and policy modules become a single source of truth for policy definitions.
• Security: Enhance security by managing policies as code, enabling version control and auditability. In addition, you can more easily manage policies that assign least privilege to each secret.
• Scalability: Easily scale policy management as your infrastructure grows.
• Efficiency: Reduce manual intervention and potential errors in policy management.

Prerequisites and limitations

Prerequisites

• Basic understanding of Terraform and Vault
• HCP Terraform and Vault available for use
• Access to a Vault server with appropriate permissions to manage policies
• Familiarity with HCL (HashiCorp Configuration Language)
• Familiarity with Git and version control concepts
• Familiarity with the Vault Solution Design Guide(opens in new tab) & the Vault Operating Guide for Adoption(opens in new tab)
• A GitHub, BitBucket, or other HCP Terraform-supported repository that will hold Terraform configuration files

Limitations

• A constraint on the Vault operations team needs to be implemented: all Vault policy changes should be executed through Terraform

Integration architecture

Summary of the architecture

The diagram shows the following workflow:

1. A Terraform module with standardized Vault policies is published to the private module registry for consumption.
2. Vault management repositories are created that consume the module. The module provides standard policies to allow deploying these standard policies quickly, consistently and safely to all the required namespaces.
3. The Vault management repositories use a branching strategy to apply the policy changes to test environments before applying the same policies to the production environment, enhancing security, stability and reliability.

Best practices - prescriptive guidance

The integration architecture involves using Terraform to define and manage Vault policies. Terraform configurations are written in HCL and stored in a supported version control system. These configurations are then applied to the Vault server, which enforces the defined policies. The architecture ensures that policy management is automated, consistent, and secure.

People and process considerations

Some important process considerations:

• Roles and responsibilities: Define clear roles for policy authors, reviewers, and approvers. Usually, the “platform team” is composed of multiple sub-teams with separate areas of responsibility. The sub-team responsible for operating Vault should be in charge of authoring and reviewing policies. The reviewer must be a separate person than the originator of the change. If possible, the subset of the most senior members should be reviewing the changes. Ultimate approval for policy changes 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: All further updates to Vault policies must be done through this process (change in version control, review, approve, and deploy using HCP Terraform). No policy changes should be allowed to be done directly on the Vault servers.

The policies provided split permissions for common access patterns. The following patterns are used throughout the provided access policies:

• Consumer: Someone who has access to read (consume) secrets from Vault.
• Producer: Someone who has access to create and update (produce) secrets in Vault.
• Administrator: Someone who has access to manage the configuration of the secret engines in Vault.

Object planning considerations

• You need to use a separate set of workspaces for the root namespace (Vault Enterprise only).
• You need to have at least two workspaces per namespace (one for testing and one for production, each deploying to different Vault clusters).
• If using HCP Vault Dedicated you can use a development cluster for your testing needs and a production level cluster for your production usage.
• If you have multiple clusters in a replicated set, you only need to have a workspace connecting to the primary cluster. Vault replication will ensure that the new policies are present on all clusters in the set.

Checklist

• If starting from scratch, obtain the root token for your sandbox and production clusters.
• Grant root namespace access to the Vault administrators, this is only applicable in Vault Enterprise.
• Follow the principle of least privilege and grant the minimum permissions required to perform a task.
• Pre-create the organization admin namespace and any child namespaces (or create them dynamically by adding code for those additional resources in your own repositories.

Workflows

The workflow described in this guide starts from a fresh installation of Vault, and guides you through all the necessary steps to install the policies provided by the Terraform module. If you're starting from an existing Vault environment, you will need to adjust the steps below as needed:

1. Instead of using a root token, you should instead configure dynamic credentials for Vault in HCP Terraform. For details on this configuration refer to Dynamic Credentials with the Vault Provider(opens in new tab). The JWT role that you use needs to have enough permissions to manage policies.
2. The Terraform module installs multiple policies, you must review your environment for existing policies with names clashing with the policies provided by the module. If there are any clashes, you'll need to decide on a path forward (for example rename your existing policies and update any existing policy assignments throughout your environment), there can be no policy name clashes with the policies defined by the module in your environment.
3. If you haven’t already, make sure to revoke all root tokens in use.

Steps

Step 1: Create the necessary repositories in your version control system

Task : Fork or clone the terraform-vault-policies repository into your own version control system (VCS). Persona : Platform Team members responsible for managing Vault policies Description: Bring the code for policies under your control:

1. If your organization is using GitHub, you can just fork the repository into your own GitHub organization.
2. If your organization is using a different VCS, then you can clone the repo from GitHub and push it to your organization’s VCS.
3. Apply a git tag in SemVer(opens in new tab) format to the repository and push it to your VCS.

Task: Create a new repository to manage the policies for the root namespace (Vault Enterprise only). Persona: Vault Administrator (Platform Team members responsible for managing Vault) Description:

1. Clone the new root namespace repository (update your URL as needed below)

   git clone YOUR_ROOT_POLICIES_REPOSITORY

2. Clone the policies repository

   git clone https://github.com/hashicorp-validated-designs/terraform-vault-policies.git(opens in new tab)

   1. Navigate to the examples directory of the cloned policies repository.
   2. Copy the code under the root_namespace_setup repository to your new repository.
   3. From now on in this document we will refer to this repository as the root_namespace_setup repository

3. Ensure that the main branch (or the branch you choose to use for the production environment) is configured to be a protected branch in your VCS, so that changes to it have to be peer reviewed and approved for this branch of the root_namespace_setup repository.

Task: Create a new repository to manage the policies for the organization admin namespace. Persona: Vault Administrator (Platform Team members responsible for managing the Vault admin namespace) Description:

1. Clone the new root namespace repository (update your URL as needed below)

   git clone YOUR_ADMIN_POLICIES_REPOSITORY

2. Clone the policies repository

   git clone https://github.com/hashicorp-validated-designs/terraform-vault-policies.git(opens in new tab)

   1. Navigate to the examples directory of the cloned policies repository.
   2. Copy the code under the admin_namespace_setup repository to your new repository.
   3. From now on in this document we will refer to this repository as the admin_namespace_setup repository.

3. Ensure that the main branch (or the branch you choose to use for the production environment) is configured to be a protected branch in your VCS, so that changes to it have to be peer reviewed and approved for this branch of the admin_namespace_setup repository.

Task: (Optional) Create one or more repositories to manage the access policies for the child namespaces. Persona: Platform Consumers (Delegated to be responsible for managing Vault policies in child namespaces). Description:

1. Clone the new root namespace repository (update your URL as needed below)

git clone YOUR_CHILD_NS_POLICIES_REPOSITORY

1. Clone the policies repository

   git clone https://github.com/hashicorp-validated-designs/terraform-vault-policies.git(opens in new tab)

   1. Navigate to the examples directory of the cloned policies repository.
   2. Copy the code under the simple repository to your new repository.
   3. Modify the module source and version to match your PMR configuration.
   4. Modify the example code to match your needs.

2. Ensure that the main branch (or the branch you choose to use for the production environment) is configured to be a protected branch in your VCS, so that changes to it have to be peer reviewed and approved for this branch of these additional repositories.

Step 2: Import the Vault policies module into your own module registry

Task : Add your copy of the terraform-vault-policies repo to the HCP Terraform private module registry (PMR). Persona : Platform Team members responsible for managing Vault policies Description: Ensure that the tag you created for versioning in step 1 is recognized.

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

Task : Create a workspace for your sandbox Vault environment. We will refer to this workspace as the root_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. Persona : Vault Administrator (Platform Team members responsible for managing Vault) Description: In a fresh 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.

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:

1. 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.
2. Remove the dynamic credentials code from your root_namespace_setup repository (by removing the file called provider.tf) while you use the root token.
3. At this point, make sure to update your repository to use the correct source and version for the module from your PMR configuration.
4. (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.
5. Configure the new workspace to run for the sandbox branch.
6. Configure the workspace variables for connectivity to Vault using the root token.
7. Push your sandbox branch to the VCS.
8. 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(opens in new tab).

1. Update your repository (by adding back the file called provider.tf from the example).
2. Remove the variables for root token authentication from the workspace and instead add the variables for dynamic credentials.
3. 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.

Step 4: Set up workspaces to manage policies at the admin namespace

Task : Create a workspace for your sandbox Vault environment. We will refer to this workspace as the admin_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. Persona : Vault Administrator (Platform Team members responsible for managing Vault) Description: In a fresh 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.

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:

1. 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.
2. Remove the dynamic credentials code from your admin_namespace_setup repository (by removing the file called provider.tf) while you use the root token
3. At this point, make sure to update your repository to use the correct source and version for the module from your PMR configuration.
4. (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.
5. Configure the new workspace to run for the sandbox branch.
6. 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.
7. Push your sandbox branch to the VCS.
8. 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 workspaces.

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(opens in new tab).

1. Update your repository (by adding back the file called provider.tf from the example).
2. 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.
3. Revoke the root token.

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

Task : Create a workspace for your sandbox Vault environment. We 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. Persona : Platform Consumers (Delegated to be responsible for managing Vault policies in child namespaces). Description:

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

1. 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.
2. At this point, make sure to update your repository to use the correct source and version for the module from your PMR configuration.
3. (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.
4. Configure the new workspace to run for the sandbox branch.
5. 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.
6. Push your sandbox branch to the VCS.
7. 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

Task : Verify Persona : Platform Team members responsible for managing Vault policies Description: Review the policies and create Vault tokens that use the policies to test different access scenarios.

Clean up infrastructure

Optional If needed Task : Clean Up Infrastructure Persona : Platform Team members responsible for managing Vault policies Description:

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

Related resources

Documentation & Tutorials

• Getting started with a Terraform product(opens in new tab)
• Terraform installation(opens in new tab)
• Codify management of Vault Enterprise using Terraform(opens in new tab)
• hashicorp/vault | Terraform Registry(opens in new tab)
• Manage Vault resources programmatically | Vault | HashiCorp Developer(opens in new tab)
• Programmatic best practices | Vault | HashiCorp Developer(opens in new tab)
• Policy Basics – HashiCorp Help Center(opens in new tab)
• Dynamic Credentials with the Vault Provider(opens in new tab)