armenr / tf-summarize Goto Github PK

tf-summarize (Terraform Summarizer)

tf-summarize is a command-line utility to print the summary of the terraform plan

• Demo
• Why do we need it ?
• Install
  • Using Go
  • Using Brew
  • Using Docker
  • Download zip in release page
  • Clone and Build Binary
• Usage
• Examples
  • Github Actions Workflow
  • Comment terraform plan summary in PRs
  • Interactive summary review
• Screenshot
• TODO

Demo

If demo is slower for you, please see examples and screenshot for more details

Why do we need it ?

• Most of the time, we make changes to the terraform files or tf-var files and run the plan command. And we precisely know which resources will get affected. In those time, we would like to just see the resource name and it's change.
• When our plan have more than say 10 changes, we will first see what are the deleted changes, or we will just see the list of resources that get affected.

Install

Using Go

go install github.com/dineshba/tf-summarize@latest

Using Brew

brew tap thecasualcoder/stable
brew install tf-summarize

Using Docker

docker run -v $PWD:/workspace -w /workspace ghcr.io/dineshba/tf-summarize -v # prints version
docker run -v $PWD:/workspace -w /workspace ghcr.io/dineshba/tf-summarize tfplan.json
docker run -v $PWD:/workspace -w /workspace ghcr.io/dineshba/tf-summarize -tree tfplan.json
# see example section for more examples


# add alias if needed
alias tf-summarize="docker run -v $PWD:/workspace -w /workspace ghcr.io/dineshba/tf-summarize"
tf-summarize tfplan.json
# see example section for more examples

tf-summarize will accept tfplan directly. Docker based tf-summarize is not having terraform-binary to convert tfplan to json. So it only works with json files. If you want to use with tfplan directly, You can build a base image with terraform (use same version as tfplan created) and have our binary in it.

Download zip in release page

1. Go to release page https://github.com/dineshba/terraform-plan-summary/releases
2. Download the zip for your OS and unzip it
3. Copy it to local bin using cp tf-summarize /usr/local/bin/tf-summarize or to location which is part of $PATH
4. (For Mac Only) Give access to run if prompted. Refer here

Clone and Build Binary

1. Clone this repo
2. Build binary using make build or go build -o tf-summarize .
3. Install it to local bin using make install or cp tf-summarize /usr/local/bin/tf-summarize

Usage

$ tf-summarize -h

Usage of tf-summarize [args] [tf-plan.json|tfplan]

  -draw
        [Optional, used only with -tree or -separate-tree] draw trees instead of plain tree
  -out string
        [Optional] write output to file
  -separate-tree
        [Optional] print changes in tree format for each add/delete/change/recreate changes
  -tree
        [Optional] print changes in tree format
  -v    print version

Examples

# run terraform plan command
terraform plan -out=tfplan

# provide plan itself directly
tf-summarize tfplan                           # summary in table format
tf-summarize -tree tfplan                     # summary in tree format
tf-summarize -tree -draw tfplan               # summary in 2D tree format
tf-summarize -json tfplan                     # summary in json format
tf-summarize -separate-tree tfplan            # summary in separate tree format
tf-summarize -separate-tree -draw tfplan      # summary in separate 2D tree format
tf-summarize -out=summary.md tfplan           # summary in output file instead of stdout

# provide json output from plan
terraform show -json tfplan | tf-summarize    # summary in table format
terraform show -json tfplan > output.json
tf-summarize output.json                      # summary in table format

Github Actions Workflow

Please refer this sample github actions file and the sample runs here

Note: If you are using hashicorp/setup-terraform github action to setup terraform, ensure terraform_wrapper is set to false.

Comment terraform plan summary in PRs

Refer this example to add comments in your PR. Sample comment added by github actions bot.

Interactive summary review

You can use tool fx to review the summary fo the terraform change

tf-summarize -json tfplan | fx

Screenshot

TODO

• Read terraform state file directly. (Currently need to convert to json and pass it)
• Directly run the terraform plan and show the summary
• Able to show summary of the current terraform state
• Include version subcommand in binary