Define policies for the Terraform policy framework

Terraform policy is HashiCorp's native HCL-based policy framework that integrates directly with Terraform providers. This page describes how to use Terraform policy with HCP Terraform.

Overview

Terraform policy uses HCL, the same language as Terraform, to define policies and integrates with Terraform and Terraform providers. This makes it familiar to Terraform users and allows for integration with Terraform workflows. When you implement Terraform policy in your organization, author your policies, test them, and then commit them to your version control system (VCS). Then, configure policy sets in HCP Terraform and apply them to specific projects and workspaces or to your entire organization.

Why use Terraform policy?

Terraform policy provides the following features and benefits for Terraform practitioners:

• HCL familiarity: Uses the same configuration language as Terraform, reducing the learning curve for Terraform practitioners
• Native Terraform integration: Directly integrates with Terraform providers and resources
• Built-in testing: Includes a testing framework to allow you to verify your policies work as expected before you enforce them in HCP Terraform
• Multiple evaluation stages: Supports pre-plan, plan-time, and apply-time evaluation

Implement Terraform policy

In order to implement Terraform policy for your organization, you will:

1. Write policies for resources defined in any Terraform provider using Terraform policy's configuration language based on HCL.
2. Test your policies locally with the tfpolicy CLI to ensure each policy targets the correct resources and behaves as expected.
3. Commit your policies to a version control system (VCS) repository and connect it to HCP Terraform.
4. Organize policies into policy sets on HCP Terraform and target projects, workspaces, or your entire organization for evaluation.

After you have configured a policy set, HCP Terraform automatically enforces your policies whenever you trigger a run on a target workspace and reports the results of the policy evaluation to end users during the run.

Write policies

First, write your policies in .policy.hcl files in Terraform policy's HCL-based configuration language.

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

To learn how to write your policies, refer to Terraform policy - Write policies.

Test policies

When you write your polices, we recommend you also write tests to verify that each policy works as expected. Policy tests also use HCL, and we recommend that you store them in your VCS repository alongside the policies they test. Policy tests work by defining mock providers, resources, data sources, and modules that you will configure with attributes to either pass or fail policy enforcement. Policy test files end in .policytest.hcl.

When you test the following example policy with the tfpolicy CLI, it reports that both tests pass because the second mocked resource is configured with expect_failure = true.

resource "aws_instance" "pass" {
  attrs = {
    instance_type = "t3.micro"
  }
}

resource "aws_instance" "fail_wrong_type" {
  expect_failure = true
  
  attrs = {
    instance_type = "t3.large"
  }
}

Terraform policy reports the results of your policy tests.

$ tfpolicy test --policies=policies/ --tests=tests/
 # tests/example.policytest.hcl... running
   # resource.aws_instance.pass... running
   # resource.aws_instance.pass... pass
   # resource.aws_instance.fail_wrong_type... running
   # resource.aws_instance.fail_wrong_type... pass

To learn how to test your policies, refer to Test policies.

Commit policies to VCS

Commit sets of policies and their tests into a VCS repository so that you can create a policy set in HCP Terraform.

To learn how to organize your policies into a VCS repository, refer to VCS setup for Terraform policy.

Configure a policy set

After you have committed your policies to a VCS repository, you can configure a policy set within HCP Terraform to begin enforcing your policies. Refer to Policy set configuration in HCP Terraform for more information.