README.md

tf-summarize (Terraform Summarizer)

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

• tf-summarize (Terraform Summarizer)
  • Demo
  • Why do we need it ?
  • Install
    • Using Go
    • Using Brew
    • Using asdf
    • Using Docker
    • Using Github action
    • Download zip in release page
    • Clone and Build Binary
  • Usage
  • Examples
    • GitHub Actions Workflow
      • Using setup-tf-summarize action
      • Other approach
    • Codefresh example
    • 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 asdf

asdf plugin add tf-summarize
asdf install tf-summarize latest

See the asdf plugin source for more information.

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.

Using Github action

The below example uses kishaningithub/setup-tf-summarize

steps:
- uses: kishaningithub/setup-tf-summarize@v1

For more customization options, kindly refer to the documentation here

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
  -html
        [Optional] print changes in html format
  -json
        [Optional] print changes in json format
  -md
        [Optional, used only with table view] output table as markdown
  -out string
        [Optional] write output to file
  -separate-tree
        [Optional] print changes in tree format for 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

Using setup-tf-summarize action

The below example uses kishaningithub/setup-tf-summarize

name: Run tf-summarize

on:
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - uses: kishaningithub/setup-tf-summarize@v1

      - name: Print tf-summarize version and help
        run: |
          tf-summarize -v
          tf-summarize -h

For more customization options, kindly refer to the documentation here

Other approach

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

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

Codefresh example

The below assumes that you have a stage called show in your codefresh.yaml example

We need to output the plan to json as there were some strange issues on codefresh when we used the tfplan file

A full example is available at example/codefresh/codefresh.yaml

  TerraformPlan:
    title: Terraform Plan
    image: hashicorp/terraform:light
    stage: plan
    working_directory: "${{clone}}"
    commands:
      - terraform plan -out=tfplan
      - terraform show -json tfplan > output.json
  
  tfSummarize:
    title: Show Changes
    image: ghcr.io/dineshba/tf-summarize
    stage: show
    working_directory: "${{clone}}"
    commands:
      - tf-summarize output.json

⚠️ Not maintained by dineshba : The above example is maintained by userbradley - Any questions related please tag @userbradley on an issue

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