Terra Graph

Auto-generated arhitecture diagrams from your terraform code.

Requirements

terra-graph manipulates the output from the terraform graph command and turns it into something useable and sensible which can then be rendered to an image. To do this the following things are required:

• terraform - duh!
• graphviz - the output from terraform graph is in the dot format which is readable by graphviz and used by graphviz to generate a graphical representation of the graph. Graphviz can be found here

Installation

Install via npm:

// globally
npm install -g terra-graph

// or add to your project
npm install terra-graph

Or globally via yarn:

// globally
yarn global add terra-graph

// or add to your project
yarn add terra-graph

Basic Use

Step 1

Generate the initial graph using terraform graph:

cd /my/terraform
terraform init
terraform graph > graph.txt

This probably won't be sufficient for most projects though. See "How to properly generate then initial graph" for more details.

Step 2

Use the terra-graph create command to parse the graph, apply some default formatting / filtering and output a (hopefully) beautiful diagram:

cat graph.txt | terra-graph create

This will use the default settings to generate an image called terra-graph.png in the location you ran the command.

Help

terra-graph [command] --help

How to properly generate the initial graph using terra-graph terraform:graph

In most projects you will be using a state file of some kind to manage the changes in your infrastructure. What terraform graph actually does is generat a graph of what actions it needs to complete (and in what order). Unless you are running terra-graph on brand new infrastructure it won't generate an accurate diagram as it will be using the diff of what new changes are needed. You also will likely have custom backend configuration (that might require credentials etc) for your terraform state.

To overcome this terra-graph has a command that will generate an isolated brand new graph without touching or going anywhere near your state or backend config.

terra-graph terraform:graph

This will create an override file for the file that contains your backend {} config block and then run terraform init and terraform graph. By default it expects the backend {} block to live in terraform.tf but that can be configured:

# (it still expects the file to have a .tf extension)
terra-graph terraform:graph --backendFile=backend.tf

This command can then be sent to terra-graph create as normal:

terra-graph terraform:graph | terra-graph create

Quick Start Use

# generate the graph from a brand new state
terra-graph terraform:graph > mygraph.txt
# send that graph to terra-graph
cat mygraph.txt | terra-graph create

Or more simply:

terra-graph terraform:graph | terra-graph create

Detailed Documentation

• Diagram Configuration - how to filter nodes, change the appearance, create a description box etc.
• Hooks - how to modify the diagram and filter elements using hooks, when and where to use them.
  • Matchers - built-in node matchers, how to write custom matchers. Matchers are used to identify elements in the graph to either filter or modify.
• All terra-graph Commands - a list of all terra-graph commands