Skip to content

Interactive visualizations of Terraform dependency graphs using d3.js

License

Notifications You must be signed in to change notification settings

obourdon/blast-radius

 
 

Repository files navigation

Blast Radius

PyPI version CircleCI

Blast Radius is a tool for reasoning about Terraform dependency graphs with interactive visualizations. Use Blast Radius to:

  • Learn about Terraform or one of its cloud providers, through example configurations.
  • Document your infrastructure
  • Reason about relationships between resources, and evaluate changes to them.

  • Interact with this diagram (and many others) here.

Quickstart

Install Blast Radius with pip, and Graphviz through your system's package manager.

[...]$ pip3 install BlastRadius
[...]$ brew install graphviz

Point Blast Radius at an init-ed Terraform project, and connect with your browser.

[...]$ blast-radius --serve /path/to/terraform-project
 * Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)

Docker

Alternatively, you can launch Blast Radius in a docker container. (In this example, the current working directory contains a Terraform project.)

[...]$ docker run --security-opt apparmor:unconfined --cap-add=SYS_ADMIN -it --rm -p 5000:5000 -v $(pwd):/workdir:ro 28mm/blast-radius

Please note: because terraform saves module links as absolute paths in .terraform/modules/ we mount the host's filesystem read-only and force terraform to update the modules path at start. This way we don't interfere with the real project. Thus docker has to be run with the --cap-add=SYS_ADMIN flag to use the overlayFS see Docker's documentation.

Additional note: If you organised your terraform directories with stacks and modules, please call Blast Radius from the root directory and give the stack's directory as argument (plus the --serve argument).

Additional note: You can specify DO_TF_INIT=true in the docker command line as an environment variable (-e DO_TF_INIT=true) if you want terraform init to be applied

Additional note: You can specify TF_DATA_DIR in the docker command line as an environment variable (-e TF_DATA_DIR=$(pwd)/.terraform) if you want terraform to use an alternate state repository

[...]$ tree -d
/-- project
    |-- modules
    |   |-- foo
    |   |-- bar
    |   `-- dead
    `-- stacks
        `-- beef
             `-- .terraform

[...]$ cd project
docker run --cap-add=SYS_ADMIN -it --rm -p 5000:5000 -v $(pwd):/workdir:ro 28mm/blast-radius --serve stacks/beef

Embedded Figures

You may wish to embed figures produced with Blast Radius in other documents. You will need the following:

  1. an svg file and json document representing the graph and its layout.
  2. javascript and css found in .../blastradius/server/static
  3. a uniquely identified DOM element, where the <svg> should appear.

Further details available here.

Implementation Details

Blast Radius uses the Graphviz package to layout graph diagrams, PyHCL to parse Terraform configurations, and d3.js to implement interactive features and animations.

Further Reading

The development of Blast Radius is documented in a series of blog posts:

  • part 1: motivations, d3 force-directed layouts vs. vanilla graphviz.
  • part 2: d3-enhanced graphviz layouts, meaningful coloration, animations.
  • part 3: limiting horizontal sprawl, supporting modules.
  • part 4: search, pan/zoom, prune-to-selection, docker.

A catalog of example Terraform configurations, and their dependency graphs can be found here.

These examples are drawn primarily from the examples/ directory distributed with various Terraform providers, and aren't necessarily ideal. Additional examples, particularly demonstrations of best-practices, or of multi-cloud configurations strongly desired.

About

Interactive visualizations of Terraform dependency graphs using d3.js

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 81.3%
  • Python 12.3%
  • CSS 3.0%
  • HTML 2.3%
  • Dockerfile 0.4%
  • Shell 0.4%
  • Makefile 0.3%