Terramaid

A utility for creating Mermaid diagrams from Terraform configurations

Introduction

Terramaid transforms your Terraform resources and plans into visually appealing Mermaid diagrams. By converting complex infrastructure into easy-to-understand diagrams, Terramaid enhances documentation, simplifies review processes, and fosters better collaboration among team members. Whether you're looking to enrich your project's documentation, streamline reviews, or just bring a new level of clarity to your Terraform configurations, Terramaid is the perfect utility to integrate into your development workflow.

Demo

Output

flowchart TD
	subgraph Terraform
		subgraph Aws
			awsdbinstance.maindb["awsdbinstance.maindb"]
			awsinstance.appserver["awsinstance.appserver"]
			awsinstance.webserver["awsinstance.webserver"]
			awslb.web["awslb.web"]
			awslblistener.web["awslblistener.web"]
			awslbtargetgroup.web["awslbtargetgroup.web"]
			awslbtargetgroupattachment.web["awslbtargetgroupattachment.web"]
			awss3bucket.logs["awss3bucket.logs"]
			awss3bucket.test["awss3bucket.test"]
			awss3bucketpolicy.logspolicy["awss3bucketpolicy.logspolicy"]
			awss3bucketpolicy.testpolicy["awss3bucketpolicy.testpolicy"]
			awssecuritygroup.db["awssecuritygroup.db"]
			awssecuritygroup.web["awssecuritygroup.web"]
			awssubnet.private["awssubnet.private"]
			awssubnet.public["awssubnet.public"]
			awsvpc.main["awsvpc.main"]
		end
		awslb.web --> awssecurity_group.web
		awslb.web --> awssubnet.public
		awslblistener.web --> aws_lb.web
		awslblistener.web --> awslbtarget_group.web
		awslbtargetgroup.web --> awsvpc.main
		awslbtargetgroupattachment.web --> awsinstance.webserver
		awslbtargetgroupattachment.web --> awslbtarget_group.web
		awss3bucketpolicy.logspolicy --> awss3bucket.logs
		awss3bucketpolicy.testpolicy --> awss3bucket.test
		awssecuritygroup.db --> awssecuritygroup.web
		awssecuritygroup.web --> aws_vpc.main
		awssubnet.private --> awsvpc.main
		awssubnet.public --> awsvpc.main
	end

[!TIP]

### You can try out terramaid directly in your browser using GitHub Codespaces

Installation

Homebrew

brew install terramaid

If you have a functional Go environment, you can install with:

go install github.com/RoseSecurity/terramaid@latest

Apt

To install packages, you can quickly setup the repository automatically:

curl -1sLf \
  'https://dl.cloudsmith.io/public/rosesecurity/terramaid/setup.deb.sh' \
  | sudo -E bash

Once the repository is configured, you can install with:

apt install terramaid=<VERSION>

Nix

# Using nix run (no installation required)
nix run github:RoseSecurity/terramaid run
Install globally with Nix flakes
nix profile install github:RoseSecurity/Terramaid
Add to your system configuration or home-manager
In your flake.nix inputs:
inputs.Terramaid.url = "github:RoseSecurity/Terramaid";
Then add to your packages: inputs.Terramaid.packages.${system}.default

Source

git clone git@github.com:RoseSecurity/terramaid.git
cd terramaid
make build

Usage

terramaid can be configured using CLI parameters and environment variables.

[!NOTE]

CLI parameters take precedence over environment variables.

The following configuration options are available:

> terramaid run -h
Generate Mermaid diagrams from Terraform configurations
Usage:   terramaid run [flags]
Flags:   -c, --chart-type string      Specify the type of Mermaid chart to generate (env: TERRAMAIDCHARTTYPE) (default "flowchart")   -r, --direction string       Specify the direction of the diagram (env: TERRAMAID_DIRECTION) (default "TD")   -h, --help                   help for run   -o, --output string          Output file for Mermaid diagram (env: TERRAMAID_OUTPUT) (default "Terramaid.md")   -s, --subgraph-name string   Specify the subgraph name of the diagram (env: TERRAMAIDSUBGRAPHNAME) (default "Terraform")   -b, --tf-binary string       Path to Terraform binary (env: TERRAMAIDTFBINARY)   -p, --tf-plan string         Path to Terraform plan file (env: TERRAMAIDTFPLAN)   -w, --working-dir string     Working directory for Terraform (env: TERRAMAIDWORKINGDIR) (default ".")   -v, --verbose bool           Verbose output to terminal (env: TERRAMAID_VERBOSE) (default false)
Use "terramaid [command] --help" for more information about a command.

Docker Image

Run the following command to utilize the Terramaid Docker image:

docker run -it -v $(pwd):/usr/src/terramaid rosesecurity/terramaid:latest run

CI/CD Integrations

Terramaid is designed to easily integrate with existing pipelines and workflows. For more information on sample GitHub Actions and GitLab CI/CD Pipelines, feel free to check out GitHub Actions Integrations and Gitlab Pipelines Integrations.

Contributing

For bug reports & feature requests, please use the issue tracker.

PRs are welcome! We follow the typical "fork-and-pull" Git workflow. 1. Fork the repo on GitHub 2. Clone the project to your own machine 3. Commit changes to your own branch 4. Push your work back up to your fork 5. Submit a Pull Request so that we can review your changes

[!TIP]

Be sure to merge the latest changes from "upstream" before making a pull request!

Many Thanks to Our Contributors