README.md

Terraform Plan Parser

This project provides a CLI and JavaScript API for parsing terraform plan output.

IMPORTANT: This tool does not parse the file produced by the -out=path argument to terraform plan which is a binary file. There is not a stable specification for this binary file format so, at this time, it is safer to parse the somewhat structured textual output that gets written to stdout.

Why should I use this?

This parser allows the textual log output from terraform plan to be converted to JSON which is more machine readable.

Here are some suggested use cases:

• Send notification when certain types of changes are detected. For example, email security team if an IAM policy is modified.
• Validate that certain changes are allowed for a given change management request before invoking terraform apply.
• Kick-off a special workflow for certain types of changes to the infrastructure (possibly, before calling terraform apply).

If you wish to perform linting or enforcement of best practices then your better option might be to analyze the source terraform code instead of only looking at the changes that are described by the terraform plan output.

Usage

JavaScript API

NPM:

npm install terraform-plan-parser

Yarn Package Manager:

yarn add terraform-plan-parser

IMPORTANT:

This project requires Node v8.9.0 (LTS) or newer because the source code utilizes language features such as async / await. If you are using an unsupported version of Node then you will see SyntaxError: Unexpected token function. It's possible to use babel to transpile the code for older versions of the Node runtime. The babel-preset-env is a good package for supporting this.

Parse string that contains stdout logs from terraform plan

const fs = require('fs');
const parser = require('terraform-plan-parser');

const stdout = fs.readFileSync('terraform-plan.stdout', {encoding: 'utf8'});
const result = parser.parseStdout(stdout);

Command Line

NPM:

npm install -g terraform-plan-parser

Yarn Package Manager:

yarn add global terraform-plan-parser

Command help:

# Get help on using command
parse-terraform-plan --help

Options:
  --help        Show help                                              [boolean]
  --version     Show version number                                    [boolean]
  -i, --input   Input file (stdin is used if not provided)              [string]
  -o, --output  Output file (stdout is used if not provided)            [string]
  --pretty      Output JSON in pretty format          [boolean] [default: false]

Read from stdin and write to stdout:

# Pipe output from "terraform plan" to parser which will convert it to JSON
terraform plan | parse-terraform-plan --pretty

Read from file and write to file:

# Store "terraform plan" output in file
terraform plan > terraform-plan.stdout

# Read from "terraform plan" output file and write to JSON file
parse-terraform-plan --pretty -i terraform-plan.stdout -o terraform-plan.json

Output Schema

The output is an object with these top-level properties:

• errors: An array of parsing errors
• changedResources: An array of changed resources
• changedDataSources: An array of changed data sources

Each changed resource has the following properties:

• action: One of "create", "destroy", "replace", "update"
• type: Type of resource (e.g. "aws_ecs_service")
• name: Resource name (e.g. "my_service")
• path: Full path to resource as printed in plan output (e.g. "module.module1.module.module2.aws_ecs_service.my_service")
• module: Fully qualified module name (e.g. "module1.module2") or undefined if resource not within module.
• changedAttributes: An object whose keys are an attribute name and value is an object
• newResourceRequired: A flag to indicate if a new resource is required (only present if true)
• tainted: A flag to indicate if resource is tainted (only present if true)

A changed attribute object has the following properties:

• old: An object with type property and value property which describes the old state of the attribute. The type will be "computed" or "string". The value will be a string.
• new: An object with type property and value property which describes the new state of the attribute. The type will be "computed" or "string". The value will be a string.

Each data source has the following properties:

• action: The action will always be "read"
• type: Type of resource (e.g. "external")
• name: Data source name (e.g. "ecr_image_digests")
• path: Full path to data source as printed in plan output (e.g. "module.module1.module.module2.data.external.ecr_image_digests")
• module: Fully qualified module name (e.g. "module1.module2") or undefined if data source not within module.
• changedAttributes: An object whose keys are an attribute name and value is an object

Example Output

{
  "errors": [],
  "changedResources": [
    {
      "action": "update",
      "type": "aws_ecs_service",
      "name": "sample_app",
      "path": "aws_ecs_service.sample_app",
      "changedAttributes": {
        "task_definition": {
          "old": {
            "type": "string",
            "value": "arn:aws:ecs:us-east-1:123123123123:task-definition/sample-app:186"
          },
          "new": {
            "type": "string",
            "value": "${ aws_ecs_task_definition.sample_app.arn }"
          }
        }
      }
    }
  ],
  "changedDataSources": [
    {
      "action": "read",
      "type": "external",
      "name": "ecr_image_digests",
      "path": "data.external.ecr_image_digests",
      "changedAttributes": {
        "id": {
          "new": {
            "type": "computed"
          }
        },
        "program.#": {
          "new": {
            "type": "string",
            "value": "1"
          }
        },
        "program.0": {
          "new": {
            "type": "string",
            "value": "extract-image-digests"
          }
        },
        "result.%": {
          "new": {
            "type": "computed"
          }
        }
      }
    }
  ]
}