Terraform policy

Terraform policy is a policy-as-code framework that integrates directly with Terraform providers. You can write policies for the framework using HashiCorp Configuration Language (HCL) syntax, which lets you reference any resource defined in a Terraform provider. At runtime, HCP Terraform can evaluate and enforce them across your organization as part of your normal infrastructure workflows.

Workflow

To implement Terraform policy for your organization, you will:

1. Write policies for resources, providers, and modules.
2. Test your policies locally with the tfpolicy CLI to ensure each policy behaves as you expect.
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 tags for evaluation.
5. Start a workspace run to trigger policy evaluations and report the results in HCP Terraform.

Policy-as-code

Policy-as-code is the practice of writing code in a high-level language to define, test, and automate policy enforcement. By representing policies as code in text files, you can apply software development best practices to your policy enforcement, such as version control, testing, and automated deployments.

Evaluation and enforcement

HCP Terraform uses Terraform policy to evaluate your policies during Terraform runs. HCP Terraform evaluates each policy when the data the policy references is available. You can also configure an enforcement level with each policy, which determines when a policy violation halts a run or continues a run with a warning message.

Evaluation stages

You can use Terraform policy to enforce policy at multiple points during a workspace run. Not all infrastructure data is available at the start of a run, so Terraform policy supports policy evaluation at three distinct stages of each Terraform run:

• Pre-plan: HCP Terraform executes provider and module policies that evaluate pre-plan arguments, such as their source and version, during workspace initialization and before Terraform installs the providers or modules. A policy violation prevents Terraform from downloading the providers or modules.

• Plan time: If all of the referenced attributes are available during the plan operation, Terraform policy evaluates policies against the Terraform plan before Terraform changes any infrastructure. These policies are ideal for catching configuration errors before Terraform makes changes to your infrastructure.

• Apply time: Some attribute values are unknown until Terraform applies your changes. Terraform marks these attributes as "(known after apply)" when it creates a plan. During the apply operation, policies run after Terraform makes changes to your infrastructure and determines these attribute values. Because Terraform must apply the changes before determining if there is a policy violation, HCP Terraform notifies teams of any non-complaint infrastructure after the Terraform apply is complete. A team member must manually resolve the policy violation and redeploy the infrastructure.

Enforcement levels

The enforcement model for Terraform policy allows you to designate an enforcement level for each policy. The enforcement level determines whether the deployment continues with a warning or whether Terraform blocks the deployment. Users with the correct permissions can override some policy enforcement violations and allow the deployment to continue. Refer to Policy enforcement levels in the HCP Terraform documentation for more information.

Benefits

Terraform policy provides the following benefits. For information about the differences between Terraform policy and other supported policy-as-code frameworks, refer to Compare policy frameworks.

Native HCL syntax

Terraform policy implements HCL syntax. As a result, policy blocks, locals, and enforce blocks follow familiar Terraform patterns, eliminating the need to learn a new language. This reduces the learning curve and enables faster policy development for teams already using Terraform.

Deep Terraform integration

Terraform policy is tightly integrated with Terraform's execution model, enabling capabilities that external policy frameworks cannot provide:

• Early validation: Terraform evaluates provider and module policies are during the terraform init operation before any downloads occur.
• Post-apply evaluation: Policies can validate provider-computed values, such as ARNs, IDs, and ports, that are only known after Terraform provisions resources.
• Resource relationship queries: Use built-in functions, such as core::getresources(), to validate relationships between resources.
• Data source lookups: Policies can query data source results directly using core::getdatasource() to enforce dynamic requirements.

Flexible enforcement levels

Terraform policy supports enforcement levels for customizing how to proceed when Terraform detects a violation. Refer to Policy enforcement levels for details.

Guidance

Refer to the following topics for next steps on implementing policies authored for the Terraform policy framework:

• Install the Terraform policy CLI on your local machine.
• Write policies. Refer to Write policies for more information.
• Learn how to write policies and tests for Terraform policy. Refer to Write Terraform policies.
• For complete examples, including tests, refer to Terraform policy examples.
• Commit your policies and tests to a VCS. Refer to VCS setup for Terraform policy for more information.
• Enforce your policies in HCP Terraform. Refer to HCP Terraform policy enforcement overview for more information.
• You can write custom plugins to extend Terraform policy.