terraci policy

Commands for managing and running OPA policy checks against Terraform plans.

Subcommands

terraci policy pull

Materialize policies from configured sources. This command is useful for local debugging or cache prewarming; generated CI jobs run terraci policy check directly.

terraci policy pull
terraci policy pull --cache-dir .terraci/policies

This command:

1. Reads policy sources from .terraci.yaml
2. Materializes policies to the cache directory when needed
3. Prepares policies for evaluation

Example output:

pulling policies
  source                                      path: policies
  source                                      git: https://github.com/org/policies.git@main
  pulled                                      sources: 2  dest: .terraci/policies

terraci policy check

Run policy checks against Terraform plan JSON files. The command materializes configured policy sources before evaluation.

terraci policy check [flags]

Flags:

Flag	Short	Description
--module	-m	Check specific module path
--format		Output format: text (default) or json

Examples:

# Check all modules with plan.json files
terraci policy check

# Check specific module
terraci policy check --module platform/prod/eu-central-1/vpc

# Output as JSON
terraci policy check --format json

Text output:

summary
  modules                                     total: 3
  passed                                      count: 2
  failed                                      count: 1

module result                                 module: platform/prod/eu-central-1/eks  status: fail
  failure                                     namespace: terraform.deny  message: EKS must use private endpoint

policy check FAILED

JSON output:

{
  "total_modules": 3,
  "passed_modules": 1,
  "warned_modules": 1,
  "failed_modules": 1,
  "total_failures": 1,
  "total_warnings": 1,
  "results": [
    {
      "module": "platform/prod/eu-central-1/vpc",
      "failures": [],
      "warnings": [],
      "successes": 5
    },
    {
      "module": "platform/prod/eu-central-1/ec2",
      "failures": [],
      "warnings": [
        {
          "msg": "Instance 'web' should have Environment tag",
          "namespace": "terraform"
        }
      ],
      "successes": 3
    },
    {
      "module": "platform/prod/eu-central-1/s3",
      "failures": [
        {
          "msg": "S3 bucket 'logs' must not be public",
          "namespace": "terraform"
        }
      ],
      "warnings": [],
      "successes": 2
    }
  ]
}

Exit Codes

Code	Description
0	All checks passed, or blocking findings were downgraded/ignored
1	Blocking policy findings found
2	Configuration or runtime error

Requirements

Policy checks require plan.json files in module directories. Generate them with:

terraform plan -out=plan.tfplan
terraform show -json plan.tfplan > plan.json

Or in GitLab CI:

plan-module:
  script:
    - terraform init
    - terraform plan -out=plan.tfplan
    - terraform show -json plan.tfplan > plan.json
  artifacts:
    paths:
      - "**/plan.json"

Configuration

See Policy Configuration for full configuration options.

Minimal example:

extensions:
  policy:
    enabled: true
    sources:
      - type: path
        path: policies
    namespaces:
      - terraform
    decisions:
      deny: block
      warn: warn

See Also

• Policy Configuration - Full configuration reference
• examples/policy-checks - Example policies