pcasteran / terraform-graph-beautifier

Terraform graph beautifier

Terraform graph beautifier

Command line tool allowing to convert the barely usable output of the terraform graph command to something more meaningful and explanatory.

terraform graph raw output	Processed output

Installation

You can download the binary corresponding to the required platform from the release page.

You can also build the binary from the sources:

go install github.com/pcasteran/terraform-graph-beautifier

Finally, you can also use the Docker images available for the Linux and Darwin operating systems:

# Linux
docker pull ghcr.io/pcasteran/terraform-graph-beautifier:latest-linux

# Darwin
docker pull ghcr.io/pcasteran/terraform-graph-beautifier:latest-darwin

Basic usage

cd samples/config1/
terraform init

# Using the binary.
terraform graph | terraform-graph-beautifier \
    --output-type=cyto-html \
    > config1.html

# Using the Docker image.
terraform graph | docker run --rm -i \
    --name terraform-graph-beautifier \
    ghcr.io/pcasteran/terraform-graph-beautifier:latest-linux \
    --output-type=cyto-html \
    > config1.html

Input and outputs

The command performs the following:

1. Parsing of the Graphviz Dot script generated by terraform graph from the standard input or the specified file (--input parameter).
2. Extraction of the graph containing the Terraform configuration elements and their dependencies.
3. Generation of the result to the standard output or file (--output parameter). The following output types (--output-type parameter) are supported:
   • cyto-html (default): an HTML page using Cytoscape.js to render the graph ( see example);
   • cyto-json: a JSON document of the graph in the Cytoscape.js format (see example);
   • graphviz: a cleaned and prettier Dot script that can be piped to a Graphviz rendering command (see example).

Input graph loading and processing

The loading of the input graph involves the following steps:

1. Cleaning the Dot script
   1. Renaming the nodes using a more consistent pattern: [root] rsc_type.rsc_name => module.root.rsc_type.rsc_name.
   2. Using the ' character instead of " fot the maps keys: buckets["artefacts"] => buckets['artefacts'].
   3. Removing the nodes and edges generated by Terraform but not corresponding to configuration elements (aka TF junk). This can be deactivated via the --keep-tf-junk parameter.
2. Filtering
   • Using user-provided pattern(s) to exclude some elements (resource, var, module, provider, ...) from the output.
   • These patterns are Go regexp and are matched line by line against the output of the cleaning step, so use the "root.rsc_type.rsc_name" naming convention.
   • These patterns are provided using the --exclude parameter, you can repeat it multiple times.

Output configuration

Modules embedding

An important option is to choose whether to embed a submodule in its parent module or not. The --embed-modules parameter allows to control this behavior:

• if true (default), the modules subgraphs will be embedded inside their parent;
• if false, all the subgraphs are drawn at the same level and an edge is drawn from a parent to its children.

As a rule of thumb, --embed-modules=true works well for small to medium size graphs but for larger ones it can produce a very dense and compact result with a lot of overlapping nodes and intersecting edges.

Output type	--embed-modules=true	--embed-modules=false
cyto-html
graphviz

HTML output templating

The command uses Go templates to create the HTML output. The following annotations will be replaced during the output generation:

• {{.PageTitle}}: will be replaced by the graph name (see --graph-name parameter).
• {{.GraphElementsJSON}}: will be replaced by the graph elements JSON object.

A basic template, with sensible default values for the graph rendering (style and layout), is provided and is embedded in the binary.

If you want to customize the output, you can provide your own template and specify to use it with the --cyto-html-template parameter. It is good practice to check in your custom templates alongside your Terraform configuration.

terraform-graph-beautifier's Issues

Prebuilt binaries for darwin don't work

Hi, I downloaded prebuilt binaries for darwin from GitHub Releases but they don't work on my laptops.

Prebuilt binaries

• https://github.com/pcasteran/terraform-graph-beautifier/releases/download/v0.3.3/terraform-graph-beautifier_0.3.3_darwin_amd64.tar.gz
• https://github.com/pcasteran/terraform-graph-beautifier/releases/download/v0.3.3/terraform-graph-beautifier_0.3.3_darwin_arm64.tar.gz

My laptops

• macOS 13.6 Apple M1
• macOS Ventura 13.5.2 Intel Core i5

macOS 13.6 Apple M1

I tried both prebuilt binaries for darwin/amd64 and darwin/arm64.

darwin/arm64

$ ./terraform-graph-beautifier_0.3.3_darwin_arm64.tar.gz/terraform-graph-beautifier --help
zsh: killed      --help

darwin/amd64

$ ./terraform-graph-beautifier_0.3.3_darwin_amd64.tar.gz/terraform-graph-beautifier --help
zsh: segmentation fault   --help

macOS Ventura 13.5.2 Intel Core i5

darwin/amd64

./terraform-graph-beautifier_0.3.3_darwin_amd64.tar.gz/terraform-graph-beautifier --help
zsh: segmentation fault   --help

Prebuilt binary for linux/arm64 works well

On the other hand, the prebuilt binary for linux/arm64 works well on linux/arm64 (lima).

$ ./terraform-graph-beautifier_0.3.3_linux_arm64.tar.gz/terraform-graph-beautifier --help
Usage of /home/shunsukesuzuki.linux/.local/share/aquaproj-aqua/pkgs/github_release/github.com/pcasteran/terraform-graph-beautifier/v0.3.3/terraform-graph-beautifier_0.3.3_linux_arm64.tar.gz/terraform-graph-beautifier:
  -cyto-html-template string
    	Path of the HTML template to use for Cytoscape.js rendering (output-type="cyto-html"), if not set a default one is used
  -debug
    	Print debugging information to stderr
  -embed-modules
    	Embed a module subgraph inside its parent if true; otherwise the two modules are drawn at the same level and an edge is drawn from the parent to the child (default true)
  -exclude value
    	Pattern (regexp) of the resource to filter out (can be repeated multiple times)
  -graph-name string
    	Name of the output graph, defaults to working directory name (default "aqua-registry")
  -input string
    	Path of the input Graphviz file to read, if not set 'stdin' is used
  -keep-tf-junk
    	Do not remove the "junk" nodes and edges generated by 'terraform graph' (default false)
  -output string
    	Path of the output file to write, if not set 'stdout' is used
  -output-type string
    	Type of output, can be one the following : cyto-json, cyto-html, graphviz (default "cyto-html")
  -v	Print command version and exit

So this is the issue of prebuilt binaries for darwin.

Build a binary on my laptop works well

I tried to build terraform-graph-beautifier from source code by go install, then it works well.

$ go install github.com/pcasteran/terraform-graph-beautifier@latest
go: downloading github.com/pcasteran/terraform-graph-beautifier v0.3.3
go: downloading github.com/awalterschulze/gographviz v2.0.3+incompatible

$ ~/go/bin/terraform-graph-beautifier --help
Usage of /Users/shunsukesuzuki/go/bin/terraform-graph-beautifier:
  -cyto-html-template string
    	Path of the HTML template to use for Cytoscape.js rendering (output-type="cyto-html"), if not set a default one is used
  -debug
    	Print debugging information to stderr
  -embed-modules
    	Embed a module subgraph inside its parent if true; otherwise the two modules are drawn at the same level and an edge is drawn from the parent to the child (default true)
  -exclude value
    	Pattern (regexp) of the resource to filter out (can be repeated multiple times)
  -graph-name string
    	Name of the output graph, defaults to working directory name (default "aqua-registry")
  -input string
    	Path of the input Graphviz file to read, if not set 'stdin' is used
  -keep-tf-junk
    	Do not remove the "junk" nodes and edges generated by 'terraform graph' (default false)
  -output string
    	Path of the output file to write, if not set 'stdout' is used
  -output-type string
    	Type of output, can be one the following : cyto-json, cyto-html, graphviz (default "cyto-html")
  -v	Print command version and exit

Feature Request: Export as SVG/PNG

If the graph beautifier had the ability to export directly to svg/png format files,
these could be embedded into our terrform repos readme.md

Support Terraform 0.13

Using terraform-graph-beautifier with Terraform 0.13:

• renders unexpected nodes (module.module_name (expand) and module.module_name (close))
• adds (expand) label on every node.

Using 0.12:
terraform graph | terraform-graph-beautifier --exclude="module.root.provider" --output-type=cyto-html > tf-0.12.html

Using 0.13:
terraform graph | terraform-graph-beautifier --exclude="module.root.provider" --output-type=cyto-html > tf-0.13.html

Ability to see only the connected component of a given resource?

Hi and thanks for a great tool!

It's great for understanding existing Terraform code. I'm aware of the -exclude option but it doesn't quite cut it. What would be great to have is an option to specify a resource name, and based on that, the tool would filter out everything else that doesn't either depend on it or is depended on the given resource thereby presenting just a "slice" of the graph. This is to aid working with big graphs, especially that it doesn't seem to be possible to CTRL-F on the generated .html file (I guess that's due to how Cytoscape.js works).

This would require implementing some simple graph traversals but would reduce the graph to "just the interesting parts" when debugging some Terraform issue.

Curious to hear your thoughts