VCS setup for Terraform policy

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

Prerequisites

Terraform policy requires Terraform 1.17.0 beta-1 or later. To enable pre-GA builds of Terraform:

1. Navigate to your organization's Settings page.
2. Select General from the left navigation.
3. Enable the Show Terraform pre-releases setting.

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. You should adhere to the following file and folder 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.

Repository structure

We recommend grouping sets of policies that you intend to enforce together into a VCS repository and creating a policy set to enforce them in Terraform Enterprise.

In addition to the policy files, we recommend storing 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. Refer to Terraform policy plugins for more information.

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 your policies with custom functions. In order for Terraform Enterprise workers or agents to execute your plugin, you must include a compiled binary in your policy VCS repository that is compatible with the Terraform Enterprise execution environment.

Because Terraform policy only supports a single binary per plugin, if you use agent pools with mixed architectures, you must configure workspaces and Stacks that evaluate your Terraform policies to use agent pools that run the same architecture as the one you built your policy plugin for. When Terraform Enterprise attempts to evaluate a policy that uses a plugin on an agent with an incompatible architecture, it responds with a plugin connection error. You can determine the architecture of your worker agents by running the uname -m command on an agent. Refer to Manage agent pools to learn how to configure agent pools.

The following is an example of a plugin connection error due to incompatible architectures:

Plugin connection error: Error connecting to plugin "example": failed to create client: fork/exec /home/tfc-agent/.tfc-agent/component/terraform/runs/run-abc123def456/config/tfpolicy-init/plugin-arch-error-test-v4/plugins/bin/example: exec format error.

For more information about writing and compiling Terraform policy plugins, refer to Terraform policy - Policy plugins.

Policy set configuration in Terraform Enterprise

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

Create a policy set

1. Sign in to Terraform Enterprise 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 set 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.16.0"
  }
}

Refer to policy block reference for more information.