Narcoleptic Pasta Manufacturer

    terraform-plan-parser
    TypeScript icon, indicating that this package has built-in type declarations

    1.6.0 • Public • Published

    Terraform Plan Parser

    Greenkeeper badge Build Status Coverage Status npm version

    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"
              }
            }
          }
        }
      ]
    }

    Keywords

    none

    Install

    npm i terraform-plan-parser

    DownloadsWeekly Downloads

    713

    Version

    1.6.0

    License

    MIT

    Unpacked Size

    70.6 kB

    Total Files

    18

    Last publish

    Collaborators

    • lifeomicdev
    • npm-lifeomicdev-github
    • philidem