The Pain of the Plan

Running terragrunt run-all plan or its Terraform equivalent is a ritual familiar to anyone managing infrastructure as code. The output scrolls endlessly: dozens of units refreshing state, identical count instances being modified, and dynamic tags like tags_all.LastModified that shift on every run. Buried within this deluge of information are the few lines that truly matter—typically, a # forces replacement comment on a critical resource like a database. The problem is finding them. Users often scroll back up, lose the crucial information, or resort to piping the output to a file and grepping for specific keywords like must be replaced, often approving changes at 6 PM out of sheer exhaustion.

This common frustration led to the development of tgsieve, a tool designed to cut through the noise and present only the essential changes within a Terraform or Terragrunt plan. The goal is to transform the often overwhelming and time-consuming review process into a focused, efficient operation.

Introducing tgsieve

tgsieve automates the execution of Terraform or Terragrunt plans and then intelligently parses the structured output. Instead of presenting the full, verbose log, it filters this output to highlight only the critical modifications. This means developers and operators can quickly identify resource replacements, deletions, or significant changes that require careful consideration, without sifting through hundreds or thousands of lines of routine updates or refreshes.

The core functionality of tgsieve revolves around its ability to process the JSON output generated by Terraform's plan command. While Terraform's plan output can be verbose, its structured nature allows tools like tgsieve to programmatically extract and interpret the changes. This structured approach is key to moving beyond simple text-based grepping, which can be brittle and prone to false positives or negatives.

How tgsieve Works

At its heart, tgsieve leverages the structured output from Terraform plans. When you run terraform plan -json, Terraform emits a detailed, machine-readable JSON object describing all proposed changes. tgsieve consumes this JSON, effectively acting as a sophisticated filter. It identifies resources that are marked for replacement, destruction, or creation, and crucially, it prioritizes these based on resource type and potential impact.

For instance, a database requiring replacement is far more critical than a security group ingress rule being updated. tgsieve’s logic is designed to surface these high-impact changes prominently. It aims to provide a concise summary that directly answers the question: "What critical infrastructure changes am I about to make?"

The tool is designed for ease of integration into existing CI/CD pipelines. It can be invoked as a command-line utility, taking the plan output as input and providing a clean, actionable summary as output. This makes it straightforward for teams to incorporate it into their review gates, ensuring that critical changes are always visible and understood before deployment.

The Problem with Verbosity

The sheer volume of output from a large Terraform or Terragrunt plan is a significant productivity drain. Each plan execution can generate thousands of lines. This verbosity stems from Terraform’s detailed reporting of every state refresh, every resource attribute change, and every instance within a `count` or `for_each` block. While this detail is useful for deep debugging, it obscures the critical signals.

Consider a scenario where a database needs to be replaced. This is a high-risk operation that could lead to data loss if not handled carefully. Terraform will flag this with a clear indicator in the plan output. However, if this indicator is surrounded by hundreds of lines detailing minor changes to unrelated resources, it becomes easy to miss. The cognitive load required to scan through such extensive output is substantial, leading to fatigue and potential errors. This is akin to trying to find a specific sentence in an entire novel when you only need the last line to understand the plot twist.

tgsieve addresses this by acting as an intelligent summarizer. It doesn't discard information but rather re-contextualizes it, presenting the most impactful elements upfront. This allows engineers to focus their attention where it's most needed, improving the accuracy and efficiency of infrastructure reviews.

Beyond Grep: Structured Analysis

While piping output to grep is a common workaround, it has limitations. It relies on specific string patterns that can change between Terraform versions or be inadvertently modified by other parts of the output. Furthermore, grep lacks the context to understand the *significance* of a change. It can find the string "forces replacement" but cannot inherently distinguish between replacing a small, non-critical resource and replacing a large, stateful one.

tgsieve, by contrast, operates on the structured JSON output. This means it understands the relationships between resources, their types, and the specific actions proposed for each. This structured analysis allows for more sophisticated filtering and prioritization. For example, tgsieve can be configured to warn specifically about replacements of resources tagged as `production` or of a specific `type`, such as `aws_db_instance`.

The development of tgsieve represents a step towards more intelligent tooling for infrastructure as code. It moves beyond simple text processing to leverage the rich, structured data that tools like Terraform already provide. This allows for more robust and context-aware analysis of infrastructure changes.

What This Means for You

If you are managing infrastructure with Terraform or Terragrunt, the time spent reviewing plan outputs is likely a bottleneck. The risk of missing a critical change due to information overload is real. tgsieve offers a direct solution by distilling these lengthy plans into their most essential components.

By integrating tgsieve into your workflow, you can expect to:

  • Significantly reduce the time spent reviewing plan outputs.
  • Increase the accuracy of your infrastructure change reviews by ensuring critical modifications are never missed.
  • Improve team velocity by streamlining the approval process for infrastructure changes.
  • Enhance the overall reliability and security of your infrastructure by enforcing stricter review gates.

The project, available on GitHub, is open-source, inviting community contributions and adaptations. This approach ensures that the tool can evolve alongside Terraform and Terragrunt, addressing the ever-present challenge of managing complex cloud environments effectively.