tfbreak-core

tfbreak

A static analysis tool that compares two Terraform configurations and reports breaking changes to module interfaces and state safety.

What is tfbreak?

tfbreak analyzes Terraform module changes between two versions (e.g., a pull request diff) and detects changes that would:

• Break callers - Changes to inputs, outputs, or type constraints that would cause errors for existing module consumers
• Destroy state - Resource or module removals without proper moved blocks that would cause unintended destruction
• Change behavior unexpectedly - Default value changes, validation additions, or sensitivity changes that may surprise consumers

tfbreak vs tflint

tfbreak is complementary to tflint - use tflint for code quality and tfbreak for safe releases.

Installation

Using Go

go install github.com/jokarl/tfbreak-core/cmd/tfbreak@latest

Binary Releases

Download pre-built binaries from the GitHub Releases page.

Available platforms:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64, arm64)

From Source

git clone https://github.com/jokarl/tfbreak-core.git
cd tfbreak-core
go build -o tfbreak ./cmd/tfbreak

Quick Start

Basic Usage

Compare two Terraform module versions:

tfbreak check ./old-version ./new-version

Example Output

tfbreak - Terraform Breaking Change Detector

Comparing:
  Old: ./old-version
  New: ./new-version

Findings:

ERROR  BC001  required-input-added
  New required variable "api_key" has no default
  Location: variables.tf:15

WARNING  RC006  input-default-changed
  Variable "instance_type" default changed from "t3.micro" to "t3.small"
  Location: variables.tf:8

Summary: 1 error, 1 warning, 0 notices
Result: FAIL

CI Integration

# Fail on any errors (default)
tfbreak check ./old ./new --fail-on ERROR

# Fail on warnings too
tfbreak check ./old ./new --fail-on WARNING

# Output as JSON for programmatic processing
tfbreak check ./old ./new --format json

Configuration

tfbreak looks for .tfbreak.hcl in the current directory or the old directory.

Minimal Configuration

version = 1

Full Configuration Example

version = 1

# Path filtering
paths {
  include = ["**/*.tf"]
  exclude = [".terraform/**", "**/examples/**"]
}

# Output settings
output {
  format = "text"  # text, json
  color  = "auto"  # auto, always, never
}

# CI policy
policy {
  fail_on                  = "ERROR"  # ERROR, WARNING, NOTICE
  treat_warnings_as_errors = false
}

# Annotation settings
annotations {
  enabled        = true
  require_reason = false
}

# Per-rule configuration
rules "BC001" {
  enabled  = true
  severity = "ERROR"
}

See Configuration Reference for all options.

Suppressing Findings

Use inline annotations to suppress findings (tflint-style):

# tfbreak:ignore required-input-added # intentional breaking change for v2.0
variable "new_required_var" {
  type = string
}

See Annotations Guide for more details.

Built-in Rules

tfbreak includes rules for detecting:

See Rules Reference for detailed documentation of all rules.

Plugin System

tfbreak supports plugins for provider-specific rules (e.g., Azure ForceNew detection).

plugin "azurerm" {
  enabled = true
  version = "0.1.0"
  source  = "github.com/jokarl/tfbreak-ruleset-azurerm"
}

See Plugin Guide for details.

Documentation

• User Guide
  • Configuration Reference
  • Annotations Guide
  • Plugin Guide
• Rules Reference
• Developer Guide
  • Architecture

Commands

# Compare two directories
tfbreak check <old_dir> <new_dir> [flags]

# Show rule documentation
tfbreak explain <rule_id>

# Generate default config file
tfbreak init

# Show version
tfbreak version

Check Command Flags

Output flags:
  --format string       Output format: text, json
  -o, --output string   Write output to file
  --color string        Color mode: auto, always, never
  -q, --quiet           Suppress non-error output
  -v, --verbose         Verbose output

Policy flags:
  --fail-on string      Fail on severity: ERROR, WARNING, NOTICE
  --enable strings      Enable specific rules
  --disable strings     Disable specific rules
  --severity strings    Override rule severity (RULE=SEV)

Config flags:
  -c, --config string   Path to config file
  --include strings     Include patterns
  --exclude strings     Exclude patterns

Annotation flags:
  --no-annotations      Disable annotation processing
  --require-reason      Require reason in annotations

Enhancement flags:
  --include-remediation Include remediation guidance

License

Apache License 2.0 - see LICENSE for details.