Stop Drawing Cloud Diagrams by Hand: Use Terravision Instead

Stop Drawing Cloud Diagrams by Hand: Use Terravision Instead

Your infrastructure team just shipped a massive Terraform refactor. Three weeks later, your architecture diagram still shows the old VPC layout. Sound familiar? Here's the brutal truth: manually maintained diagrams are lying to you. They're outdated before you finish exporting them. They're expensive time sinks. And they're silently eroding trust between engineering and leadership every single day.

But what if your diagrams could generate themselves? What if every pull request automatically produced a pixel-perfect, interactive architecture visualization that matched your actual infrastructure—down to the last security group and subnet?

Enter Terravision—the open-source tool that's making hand-drawn cloud diagrams extinct. Created by Patrick Chugh, Terravision reads your Terraform code and produces professional-grade architecture diagrams using official AWS^{↗ Bright Coding Blog}, GCP, and Azure icon sets. No cloud credentials required. No manual dragging boxes in draw.io. No $300/year Lucidchart licenses. Just pure, automated infrastructure visualization that stays in sync with your code.

In this deep dive, I'll show you why Terravision is becoming the secret weapon of platform engineers, how to get running in under five minutes, and the advanced tricks that will make your infrastructure documentation genuinely effortless. Let's destroy some manual diagramming workflows.

What is Terravision?

Terravision is a Python^{↗ Bright Coding Blog}-based CLI tool that parses Terraform configurations and renders them as professional cloud architecture diagrams. It was built by Patrick Chugh to solve a problem every infrastructure team knows intimately: the impossible task of keeping visual documentation synchronized with rapidly evolving infrastructure-as-code.

The tool operates 100% client-side—your Terraform code never leaves your machine. It doesn't need AWS credentials, doesn't call cloud APIs, and doesn't transmit your infrastructure state to any external service. This zero-trust architecture makes it safe for air-gapped environments, regulated industries, and security-conscious organizations.

Terravision supports 200+ AWS services with full fidelity, plus core services for Google Cloud Platform and Microsoft Azure. It outputs to multiple formats including PNG, SVG, PDF, and—critically—editable draw.io files. The interactive HTML mode produces self-contained, offline-capable visualizations with clickable nodes, pan/zoom, search functionality, and animated data flow visualization.

What makes Terravision genuinely different from generic diagramming tools is its deep Terraform integration. It understands module hierarchies, variable interpolation, Terragrunt configurations, and resource dependencies. It doesn't just draw boxes—it interprets your infrastructure's semantic meaning and renders it with appropriate icons, grouping, and logical connections.

The project has gained significant traction in the DevOps^{↗ Bright Coding Blog} community, with active CI/CD integrations, growing contributor base, and a comprehensive documentation site. It's available via PyPI and supports Python 3.10+ with minimal system dependencies.

Key Features That Make Terravision Insane

Always-Synchronized Diagrams The core value proposition: your diagrams are generated directly from source code. When your Terraform changes, your diagram changes. No drift. No forgotten updates. No more "the diagram says X but production shows Y" incidents during incident response.

Zero-Trust Security Model Terravision runs entirely locally. It parses .tf files, analyzes Terraform's dependency graph, and renders visuals without ever touching cloud APIs. For organizations under SOC 2, HIPAA, or FedRAMP constraints, this eliminates the compliance review cycle that SaaS diagramming tools require.

Multi-Format Output Flexibility

• PNG/SVG/PDF: Static images for documentation, presentations, compliance submissions
• draw.io (mxGraph): Fully editable for stakeholder collaboration
• Interactive HTML: Self-contained single file with pan, zoom, search, and animated data flows

AI-Powered Annotations (Optional) Terravision can leverage local LLMs via Ollama, AWS Bedrock, or any OpenAI-compatible API to generate intelligent labels, titles, and flow sequence descriptions. Crucially, only metadata and graph summaries are sent to LLMs—never your raw .tf source code.

Terragrunt Native Support Auto-detects both single-module and multi-module Terragrunt projects without configuration. This isn't bolted-on; it's architected into the parser from day one.

CI/CD Pipeline Integration Generate diagrams on every PR merge, attach them to release artifacts, or gate deployments on documentation freshness. The CLI interface makes GitHub Actions, GitLab CI, and Jenkins integration straightforward.

Simplified Executive Views The --simplified flag strips VPCs, subnets, and networking plumbing for leadership presentations—without maintaining separate diagram versions.

Real-World Use Cases Where Terravision Dominates

1. Incident Response Documentation

When PagerDuty screams at 3 AM, you need accurate infrastructure context now. Terravision-generated diagrams attached to runbooks ensure responders see current topology, not last quarter's architecture. The interactive HTML mode lets engineers click through resource dependencies to identify blast radius instantly.

2. Compliance and Audit Readiness

SOC 2 auditors, PCI-DSS assessors, and FedRAMP reviewers demand architecture documentation. Terravision produces dated, version-controlled diagrams from the exact Terraform state under audit. No more scrambling to recreate "what did production look like in Q2?" from memory.

3. Onboarding and Knowledge Transfer

New engineers can explore interactive HTML diagrams, clicking resources to see Terraform metadata, instead of reading thousand-line .tf files. The visual abstraction accelerates understanding of complex multi-account, multi-region AWS architectures dramatically.

4. Pre-Deployment Architecture Review

Generate proposed architecture diagrams from feature branch Terraform before applying. Stakeholders review visual proposals without reading HCL. Catch design flaws in PR review, not after production deployment.

5. Multi-Cloud Environment Documentation

Organizations running workloads across AWS, GCP, and Azure face documentation fragmentation. Terravision's unified rendering pipeline produces consistent visual language across providers, reducing cognitive load for platform teams.

Step-by-Step Installation & Setup Guide

Prerequisites

Before installing Terravision, ensure your system has:

• Python 3.10 or newer
• Terraform 1.x (for parsing)
• Graphviz (rendering engine)
• Git (for remote repository cloning)

Platform-Specific Graphviz Installation

macOS:

brew install graphviz

Ubuntu/Debian:

sudo apt-get update && sudo apt-get install -y graphviz

Windows (Chocolatey):

choco install graphviz

Install Terravision

The recommended method uses pipx for isolated installation:

pipx install terravision

Alternatively, in an active virtual environment:

pip install terravision

Docker^{↗ Bright Coding Blog} Installation (Optional)

For containerized environments or CI/CD pipelines, Docker images are available. See the Installation Guide for platform-specific Docker and Nix instructions.

Verify Installation

terravision --version
terravision --help

Quick Validation Test

Clone the repository and run an included example:

git clone https://github.com/patrickchugh/terravision.git
cd terravision

# Generate and auto-open an EKS cluster diagram
terravision draw --source tests/fixtures/aws_terraform/eks_automode --show

This produces architecture.png and opens it automatically. Success!

REAL Code Examples from the Repository

Let's examine actual Terravision usage patterns from the official documentation, with detailed explanations of each technique.

Example 1: Basic Local Directory Diagram Generation

# Generate from a local Terraform directory
terravision draw --source ./path-to-your-terraform

# Generate from a Git repository URL
terravision draw --source https://github.com/user/repo.git

# Custom format and explicit output filename
terravision draw --source ./path-to-your-terraform --format svg --outfile my-architecture

# Generate editable draw.io file for stakeholder collaboration
terravision draw --source ./path-to-your-terraform --format drawio --outfile my-architecture

What's happening here: The draw command is Terravision's primary interface. The --source flag accepts either local filesystem paths or Git repository URLs. When pointing to Git repos, Terravision clones, parses, and cleans up automatically. The --format flag selects output rendering—drawio is particularly powerful because it produces fully editable diagrams that stakeholders can modify in draw.io, Lucidchart, or any mxGraph-compatible editor. This bridges the gap between automated generation and human curation where needed.

Example 2: Zero-Credential Diagram Generation from Terraform Plan

# Step 1: In your Terraform environment with cloud credentials
terraform plan -out=tfplan.bin           # Create binary plan file
terraform show -json tfplan.bin > plan.json   # Export plan to JSON
terraform graph > graph.dot              # Export dependency graph to DOT format

# Step 2: Diagram generation WITHOUT any cloud credentials or Terraform access
terravision draw --planfile plan.json --graphfile graph.dot --source ./path-to-your-terraform

This pattern is powerful for security-sensitive environments. The first phase requires cloud credentials to generate the plan, but the second phase is completely air-gapped. Security teams can generate plans in restricted environments, then transfer only the plan.json and graph.dot files to less restricted machines for visualization. This enables diagram generation in production without exposing credentials to developer workstations or CI/CD pipelines that don't need them. The --planfile and --graphfile flags tell Terravision to skip all Terraform execution and work purely from pre-generated artifacts.

Example 3: Interactive HTML Visualization with Full Interactivity

# Generate self-contained interactive HTML diagram
terravision visualise --source ./path-to-your-terraform --show

The visualise command (note British spelling) produces a fundamentally different output than draw. Instead of static images, it generates a single self-contained HTML file with embedded JavaScript^{↗ Bright Coding Blog}. This file works completely offline—no CDN dependencies, no external resources. Users can click any resource node to inspect its Terraform metadata (resource type, name, module path), search across all resources by name or type, pan and zoom the canvas, and watch animated data flow along dependency edges. This is ideal for architecture exploration sessions, incident response runbooks, and executive briefings where stakeholders want to "play with" the infrastructure without reading code.

Example 4: AI-Powered Annotations with Local LLM

# Use local Ollama instance—zero data leaves your machine
terravision draw --source ./path-to-your-terraform --ai-annotate ollama

# Use AWS Bedrock via standard boto3 credential chain
terravision draw --source ./path-to-your-terraform --ai-annotate bedrock

# Use any OpenAI-compatible API endpoint
terravision draw --source ./path-to-your-terraform --ai-annotate restapi

AI annotations solve the "blank diagram" problem. Raw infrastructure diagrams show boxes and connections, but humans need context—what does this Lambda do? Why does this security group exist? The --ai-annotate flag sends only resource metadata and graph structure (never your .tf source code) to LLM backends for intelligent labeling. The ollama option is remarkable for air-gapped environments: it runs entirely locally with no network egress. The bedrock option leverages existing AWS credential chains—no additional infrastructure to deploy. The restapi option supports OpenAI, LiteLLM, vLLM, and any compatible endpoint, configured via environment variables TV_RESTAPI_URL, TV_RESTAPI_KEY, and TV_RESTAPI_MODEL.

Example 5: Simplified Executive View and Public Git Repository Parsing

# Strip networking plumbing for leadership presentations
terravision draw --source ./path-to-your-terraform --simplified

# Parse from public Git repo with subfolder path (note // syntax)
terravision draw --source https://github.com/patrickchugh/terraform-examples.git//aws/wordpress_fargate --show

Two critical productivity patterns here. The --simplified flag removes VPCs, subnets, route tables, and other networking infrastructure—producing clean application-layer views that executives actually want to see, without maintaining separate diagram versions. The Git URL with // subfolder syntax enables direct diagram generation from public or private repositories without local cloning—perfect for CI/CD pipelines, architecture review tools, or quickly visualizing open-source Terraform modules you're evaluating.

Advanced Usage & Best Practices

Version-Control Your Diagrams Alongside Code Generate diagrams in pre-commit hooks or CI pipelines and commit them to docs/architecture/. This creates automatic documentation history that correlates with infrastructure changes.

Use Planfile Mode for Production Safety Never run Terravision with live cloud credentials in CI if you don't have to. The planfile separation pattern (terraform plan → terravision draw --planfile) eliminates credential exposure in diagram generation pipelines.

Combine Simplified and Full Views Maintain two generation commands in your Makefile: make diagram-full for engineering, make diagram-exec with --simplified for leadership. Same source, different audiences.

Leverage Interactive HTML for Runbooks Attach terravision visualise outputs to PagerDuty incidents or Confluence runbooks. Responders explore infrastructure interactively instead of parsing Terraform during outages.

Terragrunt Auto-Detection Requires No Configuration Stop manually specifying module hierarchies. Terravision's Terragrunt parser handles terragrunt.hcl files automatically—just point --source at your Terragrunt root.

Comparison with Alternatives

Why Terravision wins: It's the only tool that generates professional diagrams from code without requiring cloud access, without SaaS lock-in, and without per-user licensing costs. CloudCraft requires live AWS credentials and expensive subscriptions. Lucidchart and draw.io demand manual maintenance that inevitably drifts from reality. Terraform Cloud focuses on state management, not visualization. Terravision occupies a unique intersection: developer-native, security-first, automation-ready, and completely free.

FAQ

Does Terravision require AWS/GCP/Azure credentials?

No. Terravision parses Terraform source code locally. It never calls cloud APIs. The optional planfile mode lets you generate diagrams from pre-computed plans without any credentials present.

Is my Terraform code sent to any external service?

Never. Terravision runs 100% client-side. The optional AI annotation feature sends only metadata summaries to LLMs—never your raw .tf source code. The ollama backend keeps everything on your machine.

Can I use Terravision in CI/CD pipelines?

Absolutely. The CLI interface integrates cleanly with GitHub Actions, GitLab CI, Jenkins, and others. Generate diagrams on every PR, attach to releases, or gate deployments on documentation freshness.

Does it support Terraform modules and Terragrunt?

Yes. Terravision natively understands module hierarchies, variable passing, and both single-module and multi-module Terragrunt projects without manual configuration.

What output formats are available?

PNG, SVG, PDF, draw.io (editable), and interactive HTML. The draw.io export preserves full editability in Lucidchart, diagrams.net, and any mxGraph editor.

How does Terravision compare to terraform graph?

terraform graph outputs raw DOT format with generic nodes. Terravision renders professional diagrams with official cloud icons, logical grouping, interactive features, and multiple export formats—it's a complete visualization layer, not just a dependency dump.

Can I contribute new resource types or cloud providers?

Yes. The project welcomes contributions. See the Resource Handler Guide and Contributing Guide for extending support.

Conclusion

Manual architecture diagramming is a tax on engineering velocity that compounds with infrastructure complexity. Every hour spent dragging boxes in draw.io is an hour not spent shipping features. Every outdated diagram is a liability during incident response. Every expensive SaaS license is budget that could fund actual infrastructure improvements.

Terravision eliminates this tax entirely. It transforms your Terraform code—already the source of truth for your infrastructure—into living, interactive, professional documentation that updates itself. The zero-trust security model, multi-format outputs, AI annotations, and native CI/CD integration make it uniquely positioned for modern platform engineering workflows.

I've evaluated dozens of infrastructure visualization tools. None match Terravision's combination of security posture, automation capability, and cost (free). If your team manages non-trivial Terraform estates, this tool belongs in your standard toolkit.

Your next step: Install Terravision in under five minutes with pipx install terravision, point it at your Terraform repository, and watch your first automatic architecture diagram render. Then ask yourself: why did we ever do this manually?

⭐ Star the repository at github.com/patrickchugh/terravision to follow development, and contribute back to the community that's making infrastructure documentation effortless.