Set up your Terraform policy project

This section provides guidance on organizing your Terraform policy projects and writing policies, tests, and plugins.

Note

This functionality is in beta. Do not use beta features in production environments.

Policy files

Terraform policy evaluates policies in files with the .policy.hcl file extension. You can create policy files in any directory, passing your policy file path to tfpolicy when validating or testing policies. Unlike Terraform, Terraform policy evaluates each policy file in a given directory separately. Refer to Write policies to learn how to write policy files.

Version control

You can configure HCP Terraform to evaluate your policies when provisioning infrastructure. To do so, you must host your policy files in a version control system (VCS) repository connected to HCP Terraform. Refer to VCS Setup for Terraform policy for more information.

Directory structure

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

File naming conventions

Policy files must use .policy.hcl extension
Policy test files must use .policytest.hcl extension
Use descriptive names that indicate the policy's purpose
Keep related policies and tests in the same VCS repository

Next steps

To learn how to write policy files, refer to Write policies.
To learn how to test your policies, refer to Write and run policy tests.
To learn how to write custom functions for your policies, refer to Write policy plugins.
Refer to Examples to review example policies.