Terraform Compliance

1.14.1 · active · verified Thu Apr 16

Terraform-compliance is a lightweight, security and compliance-focused BDD (Behavior Driven Development) test framework against Terraform. It enables negative testing capability for infrastructure-as-code, allowing teams to define and enforce policies against Terraform plans before deployment. It is an open-source tool that can be installed via pip or run via Docker. The library is currently at version 1.14.1 and sees frequent updates, often tied to supporting new Terraform CLI versions.

Common errors

```
Error: Failed to load plan file: <path-to-file>. Ensure it is a valid Terraform JSON plan output.
```
cause You provided a binary Terraform plan file (generated by `terraform plan -out=file.out`) instead of a JSON-formatted plan required by `terraform-compliance`.

fix After generating your binary plan (`terraform plan -out=myplan.out`), convert it to JSON using `terraform show -json myplan.out > myplan.json`. Then, pass the `myplan.json` file to `terraform-compliance` via the `-p` argument.
```
No features were found in the given directory or repository.
```
cause The path or URL provided to the `-f` (or `--features`) argument either does not exist, is inaccessible, or does not contain any Gherkin `.feature` files.

fix Verify the path to your feature files. Ensure the directory contains files ending with `.feature` and that the specified path is correct and accessible. If using a Git repository, ensure the URL is correct and includes a `git:` prefix.
```
ERROR: Terraform version is not supported.
```
cause The version of `terraform-compliance` you are using is not compatible with the version of the Terraform CLI that generated your plan file. `terraform-compliance` frequently adds support for new Terraform minor versions. [cite: Changelog]

fix Update `terraform-compliance` to its latest version using `pip install --upgrade terraform-compliance`. If the issue persists, consult the `terraform-compliance` GitHub releases or documentation for specific Terraform CLI version compatibility.

Warnings

breaking Terraform-compliance versions are often tied to specific Terraform CLI versions they support. Upgrading your Terraform CLI might require an upgrade of `terraform-compliance` to ensure plan parsing and feature execution work correctly. While Terraform 1.x itself offers strong backward compatibility, `terraform-compliance` updates are needed to integrate new parsing requirements for different Terraform versions.
Fix: Always check the `terraform-compliance` release notes for compatibility with your Terraform CLI version. Upgrade `terraform-compliance` to the latest version (`pip install --upgrade terraform-compliance`) when upgrading Terraform CLI.
gotcha The primary way to define compliance rules in `terraform-compliance` is through Gherkin `.feature` files. Users unfamiliar with Behavior Driven Development (BDD) or Gherkin syntax may find the learning curve steep.
Fix: Familiarize yourself with Gherkin syntax and BDD principles. Review the extensive examples provided in the `terraform-compliance` documentation and user-friendly-features repository for common patterns.
gotcha Older Python versions might encounter issues with specific dependencies like `orjson`. Version `1.3.52` specifically addressed a fix for `orjson` not supporting lower Python versions, indicating potential environment conflicts. [cite: Changelog]
Fix: Ensure your Python environment is up-to-date or explicitly manage dependencies if you are on an older Python version. Using a virtual environment is highly recommended to isolate `terraform-compliance` dependencies.

Install

pip install terraform-compliance Install with pip

Quickstart

This quickstart demonstrates how to use `terraform-compliance` by defining a simple Terraform resource, generating a plan, converting it to JSON, writing a BDD feature file for compliance, and then running the compliance checks. Ensure you have Terraform CLI installed and your feature files adhere to Gherkin syntax.

# 1. Create a Terraform configuration (e.g., main.tf)
# resource "aws_s3_bucket" "example" {
#   bucket = "my-unique-example-bucket-12345"
#   tags = {
#     Environment = "dev"
#     ManagedBy = "terraform-compliance-test"
#   }
# }

# 2. Initialize Terraform and generate a plan
# terraform init
# terraform plan -out=myplan.out

# 3. Convert the binary plan to JSON format
# terraform show -json myplan.out > myplan.json

# 4. Create a compliance feature file (e.g., features/s3_tags.feature)
# Feature: S3 Bucket Tagging
#   Scenario: S3 buckets must have 'Environment' and 'ManagedBy' tags
#     Given I have an S3 bucket
#     Then it must contain tags
#     And its 'Environment' tag must be defined
#     And its 'ManagedBy' tag must be defined

# 5. Run terraform-compliance against the plan and features
# terraform-compliance -p myplan.json -f features/

view raw JSON →