Skip to content

Terraform Plan Parser — Developer & Usage Guide

Jump to bottom
billybox1926-jpg edited this page May 16, 2026 · 3 revisions

Terraform Plan Parser

A lightweight Rust CLI for transforming raw Terraform plan output into clear, actionable summaries.

This tool is designed for both humans and pipelines:

  • Humans get readable, noise-free output

  • CI systems get structured, enforceable signals

What This Tool Does

Terraform plans are powerful but hard to read at scale.

This parser:

  • Extracts meaningful changes (create, update, delete)

  • Filters out noise (like read-only actions)

  • Produces clean summaries for quick review

  • Enables CI/CD enforcement via exit codes

Quick Start

Run against a Terraform project

terraform_plan_parser ./my-project

Use a pre-generated plan file

terraform_plan_parser --plan-file plan.json

Pipe directly from Terraform

terraform plan -json | terraform_plan_parser

Core Concepts

1. Input Sources

The parser supports multiple input modes:

  • Terraform execution (default)

  • Plan file (--plan-file)

  • stdin piping

Priority: stdin > plan-file > terraform execution

2. Action Types

Each resource change is categorized as:

  • create → new infrastructure

  • update → modification

  • delete → destruction

  • read → no-op (data sources / refresh)

3. Filtering

Large plans can be overwhelming. Filtering helps isolate what matters.

Examples:

--filter-action create,update

--filter-changed-only

--include-type aws_instance

--exclude-module module.test

4. Output Modes

The tool supports both human and machine-friendly formats:

  • text → default readable output

  • json → structured output for automation

Additional controls:

  • --no-emoji

  • --quiet

  • --verbose

CI/CD Usage

This tool is designed to integrate directly into pipelines.

Example: Fail on destructive changes

terraform_plan_parser --fail-on delete

Example: Save output as artifact

terraform_plan_parser --output-file summary.txt

GitHub Actions integration

  • Automatically writes to $GITHUB_STEP_SUMMARY when available

  • Provides readable plan summaries in PR workflows

Output Example


+ aws_instance.web_server (create)

~ aws_security_group.main (update)

- aws_s3_bucket.old_logs (delete)

Summary:

1 to create, 1 to update, 1 to delete

Architecture Overview

The system is intentionally simple and modular:

1. Input Layer → Terraform / file / stdin

2. Parser Layer → JSON → internal structs

3. Filter Layer → applies user-defined constraints

4. Renderer Layer → text / JSON output

See docs/architecture.md for full details.

Roadmap

The project is evolving across several phases:

  • v0.2 → CLI foundation (input, filtering)

  • v0.3 → CI & automation features

  • v0.4 → UX & polish

  • v1.0 → distribution & installation

  • vNext → advanced analysis (diffing, state support)

Contributing

Contributions are welcome.

Before opening a PR:

  • Check existing issues and milestones

  • Follow the CLI design principles (simple, fast, predictable)

  • Prefer small, focused changes

Design Philosophy

This tool prioritizes:

  • Clarity over completeness

  • Speed over abstraction

  • Practicality over perfection

If a feature doesn't make plans easier to understand or automate, it probably doesn't belong.

License

See the LICENSE file for details.

Clone this wiki locally