Skip to content

Ianyliu/blast-radius-fork

 
 

Repository files navigation

Blast Radius Fork

Blast Radius Fork is an interactive visualizer for Terraform based off of Blast Radius, which hasn't been actively maintained since 2020.

It is not guaranteed to be bug free. Please feel free to contribute!


Table of Contents


Usage

Use Blast Radius to:

  • Learn about Terraform or one of its providers through real examples
  • Visualize your infrastructure
  • Reason about relationships between resources and evaluate changes to them
  • Interact with the diagram below (and many others) in the docs
  • Compare different infrastructure

screenshot

Prerequisites for Local Use

Note: For macOS you can brew install graphviz

Note: For Docker usage prerequisites, see Docker.md

Local Quickstart

The fastest way to run with Blast Radius is to install it with pip to your pre-existing environment:

python -m pip install git+https://github.com/Ianyliu/blast-radius-fork

or

python3 -m pip install git+https://github.com/Ianyliu/blast-radius-fork

You can then run Blast Radius from the command line:

blast-radius --serve 

If you want to create graphs for an initialized Terraform directory, you can just start Blast Radius within the initialized Terraform directory:

blast-radius --serve /path/to/terraform/directory

And you will shortly be rewarded with a browser link http://127.0.0.1:5000/.

Note: If you do not have an initialized Terraform directory but have the DOT script (the output of the terraform graph command, note that this is not the same as a JSON file or state graph). You can either copy and paste the DOT script into the text input field or uploaded the DOT script file.

Other ways to run it include Docker and Kubernetes

Docker Quickstart

Launch a container for a local directory with Blast Radius running:

sh, zsh, bash, etc. (Linux recommended):

docker run --rm -it -p 5000:5000 \
  -v $(pwd):/data:ro \
  --security-opt apparmor:unconfined \
  --cap-add=SYS_ADMIN \
  ianyliu/blast-radius-fork

Windows PowerShell:

docker run --rm -it -p 5000:5000 `
  -v ${pwd}:/data:ro `
  --security-opt apparmor:unconfined `
  --cap-add=SYS_ADMIN `
  ianyliu/blast-radius-fork

Note: If you have spaces in your directory then you may have to change -v ${pwd}:/data:ro to -v "${pwd}:/data:ro" instead.

A slightly more customized variant of this is also available as an example docker-compose.yml usecase for Workspaces.

For more details on Docker usage, see Docker.md

Kubernetes Quickstart

Launch Kubernetes locally using Minikube, Kubernetes, and Kubectl:

Kubernetes Prerequisites

Start the App on Kubernetes

  1. Start Minikube
    minikube start
  2. Change directories to the file containing the 2 YAML files (k8-blast-radius-deployment.yaml and
  3. k8-blast-radius-service.yaml apply the YAML configuration files to the default namespace (or any other namespace)
kubectl apply -f k8-blast-radius-deployment.yaml
kubectl apply -f k8-blast-radius-service.yaml

Access the app

minikube service  k8-blast-radius-service

Kubernetes Debugging/Helpful Commands

  • To check the state of your pods (containers), execute the following:
    kubectl get pods
  • To see more details about a pod. (Replace <namespace> and <pod> with the corresponding values)
    kubectl describe -n=<namespace> pod/<pod>
  • To see logs for a pod (replace corresponding values)
    kubectl logs -f -n=<ns> <pod>
  • The most helpful tool is probably Minikube's dashboard, where you can more things
    minikube dashboard

Parameters

  • Directory: Defaults to $PWD or current directory. The directory in which to look for Terraform files. This is required if the user wants to use a Terraform project as input (instead of uploading a file or pasting DOT script).
  • --host: Defaults to 0.0.0.0. The IP address to bind to, to access the app (http://HOST:5000)
  • --port: Defaults to 5000. The port to access the app (http://localhost:PORT) Any valid localhost port is allowed.
  • --serve: Starts a webserver locally with Terraform's interactive graph
  • --json: Prints a JSON representation of a Terraform graph. The JSON has 2 items, edges and nodes.
  • --dot: Returns a string consisting of Graphviz DOT script of graph. (no colors)
  • --svg: Prints SVG representation of graph (with colors).
  • --graph:
  • --module-depth: Takes an integer as input and only eliminates display of deeply nested modules. This will not show every node on the graph unless the user specifies a depth larger than the graph.
  • --focus: Show only specified resource and its dependencies. Not available in web app. Only works with --json and --svg.
  • Example: terraform graph | blast-radius --focus \ "[root] module.us-west-2.module.secondary_subnet.data.aws_vpc.target" --svg
  • --center: Prunes the graph to a subgraph (same thing as red button in web app). Only works with --json and --svg.
    • Example: terraform graph | blast-radius --center \ "[root] module.us-west-2.module.secondary_subnet.data.aws_vpc.target" --svg

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.

You can read more details in the documentation for embedded figures.

How It Works

Blast Radius uses

Terraform generates graphs in the form of DOT language. Blast Radius uses Graphviz to layout the graph after converting to SVG, and D3.js to implement interactive features. Terraform configurations are then parsed by python-hcl2 to generate a JSON representation of the graph, which provides details of each resource on hover. All of this is hosted on Flask and runs on a local server.

Motivation

The original creator of this open source project, Patrick McMurchie, has been inactive on this project for some time. There are many issues waiting to be resolved, and features to be added. This repository presents some basic modifications, additional features, and enhanced accessibility.

What's Different

  • Independence from Terraform and Terraform files
    • App can run on its own, accepting DOT file or keyboard input
  • Multi-graph feature
    • The app can display multiple graphs and can be compared side by side with tabs
  • Print
    • The graph can be printed, although the print can sometimes cut off the graph at times
  • UI changes
    • To enable a better design, the multi-colored buttons and other parts of the page have been changed to follow the 60-30-10 design rule
  • Compatability with recent versions of Terraform, Python, and Python packages
  • Created a new Docker image at ianyliu/blast-radius-fork for multi-cpu architectures equipped with updated features
  • Added Shell scripts that can be used to run & build the Docker image with aliases for convenience
  • Updated README.md
  • Integrated changes across other forks and pull requests of Blast Radius, including:
    • PowerShell scripts for running and building Docker containers
    • Running Terratests during Docker build
    • Allowing Blast Radius to run even if JSON data couldn't be parsed

Future Implementations & Possible Functionalities

  • Accept file input as a command-line argument
    • (Ex. blast-radius --serve --graphfile ./graphraw.txt)
  • Allow downloading of other file formats such as .json, .png, .jpg, .zip with entire static assets
  • Hovering over tabs display number of resources or perhaps a snapshot of the graph
  • Allow upload of multiple files and folders
  • Drag and drop file upload
  • Dark mode
  • Support for Terragrunt
  • Support for Tfenv
  • Compress Docker image size (currently 180+MB)
  • Editable tab names
  • Reorder tabs via drag
  • Responsive webpage
  • Add filter by color option for graphs
  • Graph sharing
    • Generate unique URL to allow users to view graphs created by others
  • Create standalone executable (run without CLI)
    • Docker2exe
    • PyInstaller
  • Mobile interface formatting
  • Loading spinner before graphs load (and disable buttons)
  • Cache DOT script or SVG in local storage so it can be loaded next time without re-upload
  • Animation
    • Shows difference between current state and state after apply
    • Shows difference between one Terraform graph and another via animation
  • Add example Terraform DOT files that allow Blast Radius to be run on Microsoft Azure, Google Cloud, IBM Cloud Services, etc.
  • Integration with Neo4j or other graph database, parse Terraform files and find relationships between resources

Further Reading

The original development of Blast Radius is documented in a series of blog posts by the original creator:

  • 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.

There are 258 forks as of October 2024, each containing new updates or features of some sort. Notable ones include:

An alternate working Docker image for Blast Radius is https://hub.docker.com/r/grubertech/blast-radius

It would greatly help if you could contribute to bringing all of these forks into one repository so that we can have a tool that can be used by everyone.

Other Tools to Check Out

  • Pluralith
    • "A tool for Terraform state visualisation and automated generation of infrastructure documentation"
    • Written in: Golang
    • Pros
      • Change Highlighting
      • Apply plan within application
      • Cost information
      • Provides granular details on click
      • Plan-to-plan comparison (tabs)
      • Filter (by Created, Destroyed, Updated, Recreated)
      • GUI (Graphical User Interface)
      • Lots more features... there's so many!
    • Cons
      • More advanced features cost money (understandably)
      • Newer, with less tutorials and tests
  • Inframap
    • "Read your tfstate or HCL to generate a graph specific for each provider, showing only the resources that are most important/relevant."
    • Input: tfstate or HCL
    • Written in: Golang
    • Pros:
      • Works directly with Terraform state files or .tf files, instead of DOT input
      • Docker
      • Simplifies graph
    • Cons:
      • Cannot provide more detail, oversimplification
  • Terraform Graph Beautifier
    • "Terraform graph beautifier"
    • Input: DOT script output from terraform graph command in Terraform init directory
    • Written in: Golang
    • Pros
      • Outputs to: HTML page, JSON document, cleaner version of Graphviz DOT script
    • Cons
      • Requires Terraform init directory and Terraform installation
  • Terraform Visual
    • "Terraform Visual is an interactive way of visualizing your Terraform plan"
    • Input: Terraform JSON plan files
    • Written in: TypeScript, JavaScript, CSS
    • Pros
  • Rover
    • "Interactive Terraform visualization. State and configuration explorer."
    • Inputs: Terraform files in a directory or provided plan file
    • Written in: Golang, VueJS
    • Pros
      • Very granular view and control of resources
      • Shareable via .svg, .html, .json
      • Standalone mode generates .zip file containing all static assets
      • Docker compatible
    • Cons
      • Requires Terraform directory to be init, or else it will not work (even in Docker it also needs init)

Star History

Star History Chart

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 76.6%
  • Python 12.9%
  • HTML 4.9%
  • CSS 3.0%
  • Shell 1.0%
  • HCL 1.0%
  • Other 0.6%