Defining OPA Policies

Policies are rules that Terraform Cloud enforces on runs. You use the Rego policy language to write policies for the Open Policy Agent (OPA) framework. After you define policies, you must add them to policy sets that Terraform Cloud can enforce on workspaces. OPA Policies are evaluated in Terraform Cloud Agents and requires Terraform Cloud Agent version 1.4.0 and higher.

Hands-on: Try the Detect Infrastructure Drift and Enforce OPA Policies tutorial.

Defining Policies

You can write Rego policies to check for any number of conditions. Common use cases include checking whether infrastructure configuration adheres to security standards or best practices. For example, you may want to write a policy to check whether Terraform plans to deploy production infrastructure to the correct region.

You can also use policies to enforce standards for your organization’s workflows. For example, you could write a policy to prevent new infrastructure deployments on Fridays, reducing the risk of production incidents outside of your team’s working hours.

Refer to How Do I Write Rego Policies? in the Rego documentation for more details. We also recommend using the Rego Policy Playground to iterate on new policies.

OPA Query

You must write a query to identify a specific policy rule within your Rego code. The query may evaluate code from multiple Rego files.

The result of each query must return an array, which Terraform Cloud uses to determine whether the policy has passed or failed. If the array is empty, Terraform Cloud reports that the policy has passed.

The query is typically a combination of the policy package name and rule name, such as data.terraform.deny.

OPA Input

Terraform Cloud combines the output from the Terraform run and plan into a single JSON file and passes that file to OPA as input. Refer to the OPA Overview documentation for more details about how OPA uses JSON input data.

The run data contains information like workspace details and the organization name. To access the properties from the Terraform plan data in your policies, use input.plan. To access properties from the Terraform run, use input.run.

The following example shows sample OPA input data.

{
"plan": {
 "format_version": "1.1",
 "output_changes": {
 },
 "planned_values": {
  },
  "resource_changes": [
 ],
 "terraform_version": "1.2.7"
},

"run": {
  "organization": {
  "name": "hashicorp"
  },
  "workspace": {
  }
}
}

Use the Retrieve JSON Execution Plan endpoint to retrieve Terraform plan output data for testing. Refer to Terraform Run Data for the properties included in Terraform run output data.

Example Policies

The following example policy parses a Terraform plan and checks whether it includes security group updates that allow ingress traffic from all CIDRs (0.0.0.0/0).

The OPA query for this example policy is data.terraform.policies.public_ingress.deny.

package terraform.policies.public_ingress

import input.plan as plan

deny[msg] {
  r := plan.resource_changes[_]
  r.type == "aws_security_group"
  r.change.after.ingress[_].cidr_blocks[_] == "0.0.0.0/0"
  msg := sprintf("%v has 0.0.0.0/0 as allowed ingress", [r.address])
}

The following example policy ensures that databases are no larger than 128 GB.

The OPA query for this policy is data.terraform.policies.fws.database.fws_db_001.rule.

package terraform.policies.fws.database.fws_db_001

import future.keywords.in
import input.plan as tfplan

actions := [
    ["no-op"],
    ["create"],
    ["update"],
]

db_size := 128

resources := [resource_changes |
    resource_changes := tfplan.resource_changes[_]
    resource_changes.type == "fakewebservices_database"
    resource_changes.mode == "managed"
    resource_changes.change.actions in actions
]

violations := [resource |
    resource := resources[_]
    not resource.change.after.size == db_size
]

violators[address] {
    address := violations[_].address
}

rule[msg] {
    count(violations) != 0
  msg := sprintf(
    "%d %q severity resource violation(s) have been detected.",
        [count(violations), rego.metadata.rule().custom.severity]
    )
}

Testing Policies

You can write tests for your policies by mocking the input data the policies use during Terraform runs.

The following example policy called policy1 checks whether a workspace has provider tags.

package terraform.policies.policy1

import input.plan as plan
import input.run as run

array_contains(arr, elem) {
  arr[_] = elem
}

get_basename(path) = basename{
    arr := split(path, "/")
    basename:= arr[count(arr) - 1]
}

deny[reason] {
    resource := plan.resource_changes[_]
    action := resource.change.actions[count(resource.change.actions) - 1]
    array_contains(["create", "update"], action)

    cloud_tag := get_basename(resource.provider_name)

    not run.workspace.tags[cloud_tag]

    reason := sprintf("Workspace must be marked with '%s' tag to create resources in %s cloud",
                      [cloud_tag, cloud_tag])
}

The following example shows mock JSON input data from Terraform that you could use to write tests for policy1.

{
   "mock":{
      "valid_tags":{
         "plan":{
            "resource_changes":[
               {
                  "address":"aws_instance.instance1",
                  "mode":"managed",
                  "type":"aws_instance",
                  "name":"instance1",
                  "provider_name":"registry.terraform.io/hashicorp/aws",
                  "change":{
                     "actions":[
                        "create",
                        "update"
                     ]
                  }
               },
               {
                  "address":"google_compute_instance.instance2",
                  "mode":"managed",
                  "type":"google_compute_instance",
                  "name":"instance2",
                  "provider_name":"registry.terraform.io/hashicorp/google",
                  "change":{
                     "actions":[
                        "create"
                     ]
                  }
               }
            ]
         },
         "run":{
            "workspace":{
               "tags":{
                  "aws":"",
                  "google":""
               }
            }
         }
      },
      "missing_tag":{
         "plan":{
            "resource_changes":[
               {
                  "address":"aws_instance.instance1",
                  "mode":"managed",
                  "type":"aws_instance",
                  "name":"instance1",
                  "provider_name":"registry.terraform.io/hashicorp/aws",
                  "change":{
                     "actions":[
                        "create",
                        "update"
                     ]
                  }
               },
               {
                  "address":"google_compute_instance.instance2",
                  "mode":"managed",
                  "type":"google_compute_instance",
                  "name":"instance2",
                  "provider_name":"registry.terraform.io/hashicorp/google",
                  "change":{
                     "actions":[
                        "create"
                     ]
                  }
               }
            ]
         },
         "run":{
            "workspace":{
               "tags":{
                  "google":""
               }
            }
         }
      }
   }
}

The following test validates policy1. The test checks for valid tags and missing tags in the workspace. You can run this test with the opa test CLI command. Refer to Policy Testing in the OPA documentation for more details.

package terraform.policies.policy1

test_workspace_tags_allowed {
    result = deny with input as data.mock.valid_tags
    count(result) == 0
}

test_workspace_tags_missing {
    result = deny with input as data.mock.missing_tag
    count(result) == 1
}

Terraform Run Data

Each Terraform run outputs data describing the run settings and the associated workspace.

Schema

The following code shows the schema for Terraform run data.

run
├── id (string)
├── created_at (string)
├── message (string)
├── commit_sha (string)
├── is_destroy (boolean)
├── refresh (boolean)
├── refresh_only (boolean)
├── replace_addrs (array of strings)
├── speculative (boolean)
├── target_addrs (array of strings)
├── variables (map of keys)
├── organization
│   └── name (string)
├── workspace
│   ├── id (string)
│   ├── name (string)
│   ├── created_at (string)
│   ├── description (string)
│   ├── auto_apply (bool)
│   ├── tags (array of strings)
│   ├── working_directory (string)
│   └── vcs_repo (map of keys)

Properties

The following sections contain details about each property in Terraform run data.

Run Namespace

The following table contains the attributes for the run namespace.

Organization Namespace

The organization namespace has one property called name. The name property is a string that specifies the name of the Terraform Cloud organization for the run.

Workspace Namespace

The following table contains the properties for the workspace namespace.