Terravision：TerraformコードからAWSアーキテクチャ図を自動生成するOSSツール

インフラのアーキテクチャ図は書いた翌日から古くなる。Terraformコードが変わるたびにdraw.ioやLucidchartを手で更新するのは現実的でなく、多くの現場ではドキュメントが実態と乖離したまま放置されている。TerravisionはTerraformコードを読み込み、AWS・GCP・Azureのアーキテクチャ図を自動生成するOSSツールだ。完全クライアントサイド処理で、コードは外部サーバーに送られない。CI/CDパイプラインに組み込めばPRマージのたびにダイアグラムが更新される「生きたドキュメント」を実現できる。

この記事ではTerraformインフラの可視化ツールTerravisionを解説します。Terraformのクラウドコスト可視化についてはInfracost活用ガイド：Terraformのクラウドコストをデプロイ前に可視化するOSSツール完全解説をご覧ください。

Terravisionとは：インフラドキュメントの陳腐化問題を解決するOSS

Terravisionは「Turn Terraform code into professional cloud architecture diagrams that stay in sync with your infrastructure」をコンセプトにしたPython製OSSだ。AGPL-3.0ライセンスで公開されており、商用環境での利用は派生物のソース公開義務を伴う（社内ツールとしての利用は一般的にAGPLの制約外）。

なぜ「コードからの自動生成」が必要か

4分でわかる：公式紹介動画

開発者によるデモ動画だ。TerraformコードをそのままTerravisionに渡してAWSアーキテクチャ図が生成されるまでの流れがわかる。

インストールと基本的な使い方

必要な依存関係はPython 3.10以上・Terraform 1.x・Graphviz・Gitだ。Graphvizのシステムインストールを忘れずに。

# Graphviz のインストール（macOS）
brew install graphviz

# Graphviz のインストール（Ubuntu/Debian）
sudo apt-get install graphviz

# Terravision のインストール（推奨: pipx）
pipx install terravision

# または pip（仮想環境内）
pip install terravision

ローカルディレクトリから生成

# PNG形式（デフォルト）で生成
terravision draw --source ./path-to-your-terraform

# SVG形式で生成
terravision draw --source ./path-to-your-terraform --format svg

# draw.io形式（Lucidchartでも読み込み可）
terravision draw --source ./path-to-your-terraform --format drawio

GitリポジトリURLから直接生成

ローカルにリポジトリをクローンしなくても、GitのURLを直接渡せる。

# GitHub リポジトリから直接生成（パブリックリポジトリ）
terravision draw --source https://github.com/user/my-terraform-repo.git

# ブランチ指定
terravision draw --source https://github.com/user/repo.git --branch develop

インタラクティブHTMLで生成・ブラウザで開く

visualiseコマンドはブラウザで開けるインタラクティブHTMLを生成する。ノードのクリック・パン/ズーム・検索・データフローアニメーションが使える。

terravision visualise --source ./path-to-your-terraform --show

--showを付けると生成後に自動でブラウザが開く。出力されたHTMLファイルは単体で動作し、チームへのURL共有やWikiへの添付にそのまま使える。

事前生成のTerraformプランファイルを使う

本番環境のTerraformにクラウド認証を通さずに図を生成したい場合、terraform planの出力を使う方法がある。

# Terraform プランをファイルに書き出す
terraform plan -out=tfplan.bin
terraform show -json tfplan.bin > plan.json
terraform graph > graph.dot

# plan ファイルから生成（クラウド認証不要）
terravision draw \
  --planfile plan.json \
  --graphfile graph.dot \
  --source ./path-to-your-terraform

この方法はCI/CD環境でも有効だ。CIパイプラインでTerraformプランを生成し、そのアーティファクトをTerravisionに渡すことで、本番クラウドへのアクセス権がないCIエージェントでも図の生成が完結する。

200以上のAWSサービスに対応：主要サービスの一覧

Terravisionが対応するAWSサービスは公式ドキュメントに一覧があるが、主なものを挙げる。

GCPとAzureはコアサービス（Compute Engine/GKE/Cloud Storage/Cloud SQL等）に対応している。将来的なフルサポートに向けて開発中だ。

AIアノテーション機能：各コンポーネントに説明を自動付与

v0.39.0で強化されたAIアノテーション機能は、生成した図の各コンポーネントに自然言語の説明を自動で付与する。アーキテクチャレビューや新メンバーのオンボーディング資料として使いやすくなる。

対応するAIバックエンドは3種類だ。

Ollama（ローカルLLM）

# Ollama でアノテーション（完全ローカル）
terravision draw \
  --source ./path-to-your-terraform \
  --ai-annotate ollama

# 使用モデルの指定（デフォルト: llama3）
terravision draw \
  --source ./path-to-your-terraform \
  --ai-annotate ollama \
  --ai-model mistral

コードも説明もすべてローカルで完結する。機密インフラの場合はこの方法が最も安全だ。

AWS Bedrock

# AWS Bedrock でアノテーション（boto3 認証が必要）
terravision draw \
  --source ./path-to-your-terraform \
  --ai-annotate bedrock

# AWS プロファイルを指定
AWS_PROFILE=my-profile terravision draw \
  --source ./path-to-your-terraform \
  --ai-annotate bedrock

OpenAI互換 REST API

# OpenAI 互換エンドポイントを指定（OpenAI / Azure OpenAI / ローカルサーバー等）
terravision draw \
  --source ./path-to-your-terraform \
  --ai-annotate restapi \
  --ai-endpoint https://api.openai.com/v1 \
  --ai-model gpt-4o

CI/CDパイプラインへの組み込み：PRマージのたびに図を更新

Terravisionの実用的な価値が最も発揮されるのはCI/CD統合だ。Terraformコードが変わるたびにアーキテクチャ図を自動生成し、GitHubのWikiやドキュメントリポジトリに自動コミットするパイプラインを作れる。

GitHub Actionsでの例

# .github/workflows/terravision.yml
name: Generate Architecture Diagram

on:
  push:
    branches: [main]
    paths:
      - 'terraform/**'
  pull_request:
    paths:
      - 'terraform/**'

jobs:
  diagram:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install dependencies
        run: |
          sudo apt-get install -y graphviz
          pip install terravision

      - name: Generate architecture diagram
        run: |
          terravision draw \
            --source ./terraform \
            --format svg \
            --output docs/architecture.svg

      - name: Commit diagram to docs/
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: "docs: アーキテクチャ図を自動更新"
          file_pattern: "docs/architecture.svg"

PRのたびにダイアグラムが更新されるため、レビュアーはコードの差分だけでなく図の変化も確認できる。「このPRでLambdaが増えた」「RDSの接続経路が変わった」といった変化が一目でわかる。

draw.io形式でエクスポートしてチームで共有

# draw.io 形式で生成（Lucidchartでも読み込み可）
terravision draw --source ./terraform --format drawio --output infra.drawio

draw.io（diagrams.net）はブラウザベースの無料ツールで、生成した.drawioファイルをそのまま開いてチームで編集できる。Confluenceへの埋め込みやGoogleスライドへの貼り付けにも対応している。

--simplifiedオプション：VPC/サブネットを省略した簡略図

大規模なインフラではVPCやサブネットの入れ子構造が図を複雑にしすぎることがある。--simplifiedオプションで省略した見やすい図も生成できる。

# VPC・サブネットを省略した簡略図
terravision draw --source ./terraform --simplified

# Terragrunt のマルチモジュールプロジェクト
terravision draw --source ./terragrunt-root --terragrunt

Infracostとの組み合わせ：図とコストを一緒に把握する

Terravisionはアーキテクチャの構造を可視化し、Infracostはそのコストを可視化する。2つをCIに組み込むことで、PRのたびに「何がどう変わり、コストはいくら増減するか」がセットでわかる運用ができる。

# GitHub Actions で Terravision + Infracost を同時実行する例
jobs:
  infra-review:
    steps:
      - name: Generate architecture diagram
        run: terravision draw --source ./terraform --format svg

      - name: Estimate cost diff
        uses: infracost/actions/setup@v3
        with:
          api-key: $
      - run: infracost diff --path ./terraform --format json > cost.json

      - name: Comment on PR
        # diagram + cost diff を PR コメントに投稿

AWSのローカルエミュレータと組み合わせたい場合はMiniStack徹底解説：MIT・無料のAWSローカルエミュレータも参照されたい。

インタラクティブHTMLデモ：生成された図の操作感

公式サイトに3つのクラウドプロバイダーのインタラクティブデモが公開されている。

• AWSデモ — EC2・RDS・ALB・S3・CloudFrontなどを含む典型的な3層構成
• Azureデモ — Azure App Service・SQL Database・Cosmos DB等
• GCPデモ — GKE・Cloud SQL・Cloud Storage等

デモを開くと、以下のインタラクティブ機能が体験できる。

このHTMLファイルは単体で動作する。terravision visualiseコマンドで生成したファイルをS3に置いてチームに共有すれば、Confluenceに貼るよりずっとインタラクティブな体験を届けられる。

他のTerraformドキュメントツールとの比較

Terraformエコシステムにはアーキテクチャ図の生成やドキュメント化を支援するツールがいくつか存在する。Terravisionがどの位置にあるかを整理する。

terraform-docsはモジュールのinput/outputをMarkdownに書き出すツールで、Terravisionとは補完関係にある。両方をCIに組み込むことで「コードの仕様書（terraform-docs）」と「アーキテクチャの全体図（Terravision）」を自動生成できる。

まとめ：「ドキュメントが古い」問題をコードで解決する

Terravisionが解決する問題はシンプルだ。「アーキテクチャ図は変更のたびに陳腐化する」という不変の課題に対して、コードから図を生成することで陳腐化の原因そのものを取り除く。

インフラのドキュメント運用に課題を感じているチームであれば、まずpip install terravisionして手元のTerraformディレクトリに向けて実行してみるのが最速の評価方法だ。

参照ソース

• patrickchugh/terravision - GitHub
• Terravision 公式ドキュメント
• インタラクティブデモ（AWS）
• terravision - PyPI