【TerraVision】Terraform のコードからアーキテクチャ図を自動作成する

はじめに

こんにちは @masa-asa です。Terraform でアーキテクチャを書く際に普段は draw.io で書いている私ですが、
Terraform からアーキテクチャ図を自動生成してくれる TerraVision というツールを見つけました。
システムに変更が入ったり複雑になるにつれて人力できれいなアーキテクチャ図を書く難易度は飛躍的に上がります。
そのため、アーキテクチャ図自動作成ツールは個人的に気になることもあり、
日本語での紹介もなさそうですので、この記事で紹介します。

TerraVision インストール

インストール方法には二種類あり、Docker を用いるものとローカルで動作するものがあります。
本記事では、ローカルで動作する方法で進めていきます。

ローカルでのインストール

事前に以下のツールが必要です。

• Python 3.10 以上
• Terraform 1.x
• Graphviz
• Git

筆者の環境では、Python、Terraform を mise で管理、
Graphviz、Git は Homebrew で管理しています。

brew install graphviz
brew install git

参考として mise.toml は次のようにします。バージョンは適宜変更が必要です。

[tools]
terraform = "1.14.3"
python = "3.13.10"
uv = "0.11.7"

mise install
uv init
uv add terravision

uv add terravision 実行時、python の設定の問題で最新の TerraVision がインストールされずに動かないことがありました。
その場合、pyproject.toml の requires-python = ">=3.10" の 3.10 を 3.13 に、
.python-version を 3.13 に修正するとうまくいきました。

使い方

drawio の形式で TerraVision の結果を出力するには以下のようなコマンドを実行します。
uv を使っている場合は source ./.venv/bin/activate か、uv run を頭につけて
仮想環境で実行する必要があります。

--source に指定するのは、terraform plan を実行するディレクトリです。
--outfile で結果のファイルを出力するファイル名を指定します。

terravision draw --source ./terraform --format drawio --outfile my-diagram

では、実行してみます。まずこちらが私が書いたアーキテクチャです。
Cloud Run から Direct VPC Egress を使って Cloud SQL にアクセスするシステムのアーキテクチャです。

そしてこちらが TerraVision が作成したアーキテクチャ図です。

AI によるアノテーション

TerraVision では --ai-annotate というオプションが用意されており、ollama もしくは bedrock を指定して動作させることができます。
ローカルでなく、外部サービスを用いる場合は --source に指定する Terraform ディレクトリや terraform plan の成果物に
シークレット情報が含まれる可能性もあるためご注意ください。
今回は ollama を使う場合を例にします。
また、ollama 環境は構築済みとします。

ollama の場合、llama3 のモデルが必要になります。
ollama run llama3 コマンドで llama3:latest が取得できます。4.7GB で 8B パラメータのモデルです。

下記のコマンド例のように、末尾に --ai-annotate ollama を追加して実行します。

terravision draw --source ./terraform --format drawio --outfile my-diagram --ai-annotate ollama

その結果がこちらです。少し見えにくいですが、「Invokes Cloud Run」などのアノテーションがついていることがわかります。

おまけ

claude code のスキルでアーキテクチャを作成する

TerraVision と drawio MCP を使ってアーキテクチャ図を作成するためのスキルを作成して利用してみます。
drawio MCP のリンクは以下です。

.mcp.json の作成

プロジェクトのルートディレクトリに「.mcp.json」を作成し、以下のように記述します。

{
  "mcpServers": {
    "drawio": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@drawio/mcp"
      ],
      "env": {}
    }
  }
}

スキルの作成〜実行

次にスキルを作成します。 draw-architecture という名前で以下のように作成しました。

---
name: draw-architecture
description: アーキテクチャの作成を支援するスキル
---

指定されたディレクトリのシステムについてアーキテクチャを作成する。

# 使い方
- ツールは mise で管理しているため、`mise exec -- uv run` でコマンドを実行する
- <output_file> のパスは、ソースと同じディレクトリにする
- terravision の --source 指定先は terraform plan を実行するディレクトリである
- `terravision draw --source <source_directory> --format drawio --outfile <output_file> --ai-annotate ollama` でアーキテクチャ図を生成する
- 生成された drawio ファイルを、drawio MCP を用いて人間の可視性の高い内容に修正しなさい
- アーキテクチャ図内の文章は日本語で記載する

このスキルを使って、先ほどの「Cloud Run から Direct VPC Egress を使って Cloud SQL にアクセスするシステムのアーキテクチャ」を作成してもらいます。

その結果が以下です。

まとめ

今回は TerraVision 単体でのアーキテクチャ図生成と、drawio MCP と組み合わせた自動化を試しました。
特に drawio MCP と連携することで高品質な図を作成できる可能性を感じました。
特に以下の点では恩恵が大きそうです。

• Terraform コードがベースになっているため、コードを真として乖離を防げる
• AI アノテーションでコンポーネント間の関係が言語化ができるので、理解の向上に役立つ
• drawio MCP と組み合わせることで、ゼロからの手書きよりアーキテクチャ図の取っ掛かりが圧倒的に早くなる
• drawio、png、svg など様々な形式に対応している

逆に以下の点には注意が必要だと感じました。

• TerraVision が対応していないリソースタイプがある可能性がある
• AI アノテーション機能を利用するには、 ollama (ローカルで ~4.7GB) か Bedrock の用意が必要

TerraVision は現在も頻繁に更新がされていますので、これから機能や使いやすさが進化していきそうです。
将来的にアーキテクチャ図の作成に人力が必要無くなる時代が来るかもしれないと感じました。
お読みいただきありがとうございました！