VCS setup for Terraform policy

This page describes how to integrate your version control system (VCS) with HCP Terraform so that it can evaluate policies written for Terraform policy.

VCS repository setup

Terraform policy supports VCS-backed policy sets containing one or more policy files with the .policy.hcl extension. You can create as many policy sets as you wish.

Repository structure requirements

We recommend that you group sets of policies that you intend to enforce together into a VCS repository and create a policy set to enforce them in HCP Terraform. In addition to the policy files, we recommend that you include tests for your policies in the same VCS repository. If you use policy plugins to implement custom functions for your policies to use, you must also commit the plugin binary to your VCS repository.

For example, your Terraform policy VCS repositories could follow this standard structure:

./
├── policies/
│   ├── resource-tagging.policy.hcl
│   ├── security-rules.policy.hcl
│   └── naming-conventions.policy.hcl
├── tests/
│   ├── resource-tagging.policytest.hcl
│   ├── security-rules.policytest.hcl
│   └── naming-conventions.policytest.hcl
├── plugins/
│   ├── src/
│   │   └── example/
│   │       ├── main.go
│   │       ├── go.mod
│   │       └── go.sum
│   └── bin/
│       └── example
└── README.md

Terraform policy plugins

Terraform policy supports plugins that allow you to extend Terraform policy with additional functions that you can use to simplify your policy authoring experience. In order for HCP Terraform agents to execute your custom plugins, you must include a compatible binary plugin in your policy VCS repository. Refer to Terraform policy - Policy plugins for more information.

File naming conventions

• Policy files must have a .policy.hcl extension.
• Test files must have a .policytest.hcl extension.
• Use descriptive names that indicate the policy's purpose
• Keep related policies and their tests in the same VCS repository

Policy set configuration in HCP Terraform

To enforce your policies in HCP Terraform, write your policies and tests, test your policies locally, and check them into your VCS repository. Then, organize the policies into sets in HCP Terraform and configure which workspaces to them to run them against.

Create a policy set

1. Sign in to HCP Terraform and navigate to your organization
2. Go to Settings > Policy Sets
3. Click Create a new policy set
4. Choose VCS as the source
5. Select Terraform policy as the policy framework
6. Connect to your VCS repository
7. Configure the policy set settings:
   • Name: A unique name for the policy set
   • Description: Describe the policy set's purpose
   • Scope: Choose global, project-specific, or workspace-specific
   • VCS Branch: Select the branch to use, usually main
   • Policies Path: Specify the directory containing policy files, for example policies/.

Policy enforcement levels

Each policy in your policy set can set its enforcement level in the policy configuration:

resource_policy "aws_instance" "example" {
  enforcement_level = "mandatory" # or "advisory" or "mandatory_overridable"
  
  enforce {
    condition     = attrs.instance_type == "t3.micro"
    error_message = "Only t3.micro instances allowed"
  }
}

Refer to Enforcement levels for more information.

Workspace and project scope

You can enable the following settings to se the scope for your policy sets:

• Project: All workspaces in specific projects
• Workspace: Specific workspaces only
• Tags: Workspaces configured with the given tags

Pin the Terraform version

You can specify the required Terraform version in your policy files:

policy {
  terraform_config {
    required_version = ">= 1.15.0"
  }
}

Refer to policy block reference for more information.