Policy Configuration Reference

Terraform policy's syntax is based on HCL, and supports a number of block types that you can use when you write your policies. Unlike Terraform, Terraform policy evaluates each policy file in a given directory separately. We recommend that you include sets of policies that you want to enforce together in each policy file, and related policies in separate files in the same directory structure.

Policy block syntax

Terraform policy block syntax is based on HCL, and similar to Terraform's syntax.

<block_type> "<type>" ["<label>"] {
  <attribute_name> = <attribute_value>
  ...

  <block_name> {
    <block_attribute_name> = <block_attribute_value>
    ...
  }
}

Each policy file can include:

• An optional policy block to configure Terraform policy itself.
• One or more provider_policy, resource_policy, and module_policy blocks to define your policies.
• Any number of input blocks to define input variables.
• Any number of locals blocks to define local values.

Terraform policy will evaluate all policies in a policy file as a unit, as early in the Terraform run as possible, when all values that the given policy block refers to are available.

Policy blocks

Terraform policy supports three types of block that allow you to write policies for your Terraform providers, resources, and modules.

Each policy block requires two labels. The first label will match the target provider, resource, or module, and the second gives the policy a unique name within the same policy file. Optionally, you can use * for all or part the first label to match multiple providers, resources, or modules in your Terraform configuration.

By default, Terraform policy applies a given policy to all of the providers, resources, or modules that match the given label. You can filter the matching providers, resources, or modules with the filter meta-argument.

By default, Terraform policy treats your policies as mandatory. You can set the enforcement level with the optional enforcement_level meta-argument. The available enforcement levels are: "advisory", "mandatory_overridable", and "mandatory".

By default, Terraform policy evaluates resource policies during create and update operations. You can specify the lifecycle operations for a resource_policy with the optional operations argument.

Each policy block can contain one or more enforce {} blocks that define conditions that must evaluate to true for the policy to pass.

Policy block arguments and blocks

Terraform policy supports the following arguments within policy blocks:

The enforce {} block

The enforce {} block allows you to write conditions for Terraform policy to test against the underlying provider, resource, or module. Each enforce block includes the condition for Terraform policy to test, and an error message.

The enforce {} block is used within provider_policy, resource_policy, and module_policy blocks.

module_policy "git::github.com/org/terraform-aws-vpc" "example" {
  enforce {
    condition     = core::semverconstraint(meta.version, ">= 2.0.0")
    error_message = "The official VPC module must be at version 2.0.0 or higher."
    info_message  = "VPC module version ${meta.version}."
  }
}

You can include one or more enforce blocks in each policy block. If any of the enforce blocks' conditions fail during evaluation, then Terraform policy will fail the policy and return the corresponding error messages.

Enforce block arguments

Attributes and meta-arguments

Within a policy block, you have access to data about your configuration and infrastructure through attributes and metadata. The available values depend on the policy block type.

Attributes

Attributes correspond to the provider, resource, or module attributes defined in Terraform. When it evaluates your policies, Terraform policy assigns values to these attributes based on your configuration, plan, or state, depending on when those values are available. For provider attributes such as the provider's source and version, Terraform can compute them by reading your configuration at setup time, before initialization, so it does so. For resources and modules, the values of some attributes will be available at plan time. Other values depend on the successful completion of the apply step, and are marked as (known after apply) in Terraform plan output. Terraform will read the value from your state after applying the change.

Attribute values can be complex types such as maps and lists, which you can reference in your policies with dot notation. For example, use attrs.tags.environment to refer to the environment tag for a resource. Refer to provider, resource, or modules attributes with the attrs prefix to reference the target state of a provider, resource, or module. You can refer to the previous state in resource policies with the prior_attrs attribute.

Depending on the operation being evaluated, the value of the attrs and prior_attrs attributes will contain different values as described in the following table.

Each Terraform provider defines the attributes available for each resource it supports, and the provider itself. Refer to the provider documentation for a list of supported attributes.

Meta-arguments

Meta-arguments are fields provided by the Terraform policy engine. You can refer to meta-arguments in your policies, such as where a resource lives in the module tree or what version of a provider is being used. Provider and module meta-arguments such as "source" and "version" are available before the plan is complete, so Terraform policy will evaluate policies that refer to these meta-arguments at the setup stage. Refer to meta-arguments with the meta prefix.

Refer to the reference documentation for each policy block type to learn about the supported meta arguments.

Reference pages

• The policy block - Configure Terraform policy.
• The provider_policy block - Write provider policies.
• The resource_policy block - Write resource policies.
• The module_policy block - Write module policies.
• The input block - Define input variables.
• The locals block - Define local values.