VSCodeとPlantUMLでAWS構成図を描く

はじめに

AWS の構成図を作るとき、最初は draw.io などのGUIツールを使うことが多いと思います。ですが、構成図をコードで管理できるようになると、修正履歴を残しやすく、再利用もしやすくなります。

Windows11のローカル環境で、VSCodeとPlantUMLを使用し、AWS公式アイコンを使った構成図を作成する手順をゼロから解説します。

なぜPlantUMLを使うのか？（メリットとデメリット）

構成図を描くツールはDraw.ioやLucidchartなど様々ですが、あえてPlantUML（コードベース）を選ぶことによるメリットとデメリットは下記となります。

導入するメリット

  • レイアウトの微調整から解放される: マウス操作でありがちな「矢印が少しずれている」「アイコンの高さが揃わない」といった1ピクセル単位の微調整が不要です。コードを書けば自動で整列されます。

  • 大量の図を効率よく量産・修正できる: 似たような構成図（例：問題集の設問ごとの解説図など）を複数作成する場合、コードをコピペして一部を書き換えるだけでサクッと量産できます。

  • 「Docs as Code」が実現できる: 図をテキストデータとして扱えるため、Gitなどで「いつ・どこを・なぜ変更したか」という履歴を簡単に管理できます。

知っておくべきデメリット

  • 独自の文法を覚える学習コストがかかる: 最初は「どう書けば線が繋がるのか」などの記法に慣れる必要があります。

  • 「数ミリ右に置きたい」といった緻密な配置が難しい: 自動レイアウトの裏返しとして、デザインツールのような細かな座標指定には不向きです。

  • 最初の環境構築に手間がかかる: ブラウザを開くだけのGUIツールに比べ、導入のハードルが少し高いです。

事前準備：ソフトウェアのインストール

PlantUMLをローカルで動かすためのベースを作ります。

① Java (JREまたはJDK) のインストール

PlantUMLはJavaで動作するため、Java環境が必須です。

  1. Adoptium (Eclipse Temurin) のサイトにアクセスします。

  2. 最新のLTS版のインストーラーをダウンロードして実行します。

  3. インストール時のオプション設定で、「Set JAVA_HOME variable」 と 「JavaSoft (Oracle) registry keys」 を有効にしてインストールを完了させます。

② Graphviz のインストール

複雑な図のレイアウトを計算・描画するために必要なツールです。

  1. Graphvizの公式サイト からWindows用のインストーラーをダウンロードします。

  2. インストーラーを実行し、途中の「Install Options」画面で 「Add Graphviz to the system PATH for all users」（または current user）を必ず選択してください。（※ここを忘れると後でエラーになります）

③ Visual Studio Code (VSCode) のインストール

公式サイト からダウンロードしてインストールします。

VSCodeのセットアップと最新版PlantUMLの配置

① 拡張機能のインストール

  1. VSCodeの左側のメニューから「拡張機能（Extensions）」アイコンをクリックします。

  2. 検索窓に PlantUML と入力し、作者が jebbs となっている拡張機能をインストールします。

② 【重要】最新の plantuml.jar を手動で配置する

拡張機能には古いPlantUMLが内蔵されていますが、最新のAWS公式アイコンをエラーなく描画するために、手動で最新版を配置します。ここが一番のポイントです。

  1. PlantUMLの公式サイト から、最新の plantuml.jar ファイルをダウンロードします。

  2. ダウンロードしたファイルを、PC内の分かりやすい場所（例：C:\tools\plantuml\ など）に保存します。

  3. VSCodeを開き、設定（Ctrl + ,）を開きます。

  4. 検索窓に plantuml.jar と入力します。

  5. 「Plantuml: Jar」の入力欄に、先ほど保存したファイルの絶対パス（例：C:\tools\plantuml\plantuml.jar）を入力します。

  6. 次に、検索窓に plantuml.render と入力し、「Plantuml: Render」が Local になっていることを確認します。

AWS公式アイコンを使った構成図の作成とプレビュー

実践的な「マルチAZのWebアプリケーション構成」を描いてみましょう。

  1. VSCodeで適当なフォルダを開き、新しいファイル sample.puml を作成します。

  2. 以下のコードを貼り付けてください。

    @startuml
' 最新のAWS公式アイコンライブラリ（v23.0）を読み込み
!define AWSPuml https://raw.githubusercontent.com/awslabs/aws-icons-for-plantuml/v23.0/dist
!include AWSPuml/AWSCommon.puml
!include AWSPuml/Groups/AWSCloud.puml
!include AWSPuml/Groups/VPC.puml
!include AWSPuml/Groups/AvailabilityZone.puml
!include AWSPuml/Groups/PublicSubnet.puml
!include AWSPuml/Groups/PrivateSubnet.puml
!include AWSPuml/NetworkingContentDelivery/ElasticLoadBalancing.puml
!include AWSPuml/Compute/EC2.puml
!include AWSPuml/Database/RDS.puml
!include AWSPuml/General/Users.puml
!include AWSPuml/NetworkingContentDelivery/VPCInternetGateway.puml

' 図の全体設定
hide stereotype
skinparam linetype ortho
skinparam nodesep 40
skinparam ranksep 40

' 外部ネットワーク
Users(users, "ユーザー", "Internet")

' AWSクラウド内部の定義
AWSCloudGroup(cloud, "AWS Cloud") {
    VPCInternetGateway(igw, "Internet Gateway", "")

    VPCGroup(vpc, "Production VPC") {

        AvailabilityZoneGroup(az1, "Availability Zone A") {
            PublicSubnetGroup(pub_subnet_a, "Public Subnet A") {
                ElasticLoadBalancing(alb_a, "ALB", "")
            }
            PrivateSubnetGroup(priv_subnet_a, "Private Subnet A") {
                EC2(ec2_a, "Web Server A", "Amazon EC2")
                RDS(rds_master, "RDS (Master)", "Amazon Aurora")
            }
        }

        AvailabilityZoneGroup(az2, "Availability Zone C") {
            PublicSubnetGroup(pub_subnet_c, "Public Subnet C") {
                ElasticLoadBalancing(alb_c, "ALB", "")
            }
            PrivateSubnetGroup(priv_subnet_c, "Private Subnet C") {
                EC2(ec2_c, "Web Server C", "Amazon EC2")
                RDS(rds_standby, "RDS (Standby)", "Amazon Aurora")
            }
        }
    }
}

' リソース間の通信フロー（矢印）
users -down-> igw : アクセス
igw -down-> alb_a
igw -down-> alb_c
alb_a -down-> ec2_a
alb_a -down-> ec2_c
alb_c -down-> ec2_a
alb_c -down-> ec2_c
ec2_a -down-> rds_master
ec2_c -down-> rds_master
rds_master .right.> rds_standby : 同期レプリケーション

@enduml

プレビュー表示

sample.puml を開いた状態で、キーボードの Alt + D（Macは Option + D）を押すと、右側にプレビュー画面が分割して表示されます。コードを修正して保存するたびに、リアルタイムで図が更新されます。

実践Tips：出力・運用・エラー対策

① 画像ファイル（PNGやSVG）として出力・保存する

ブログに貼り付けるために、作成した図を画像データとして書き出します。WordPressなどに掲載する場合は、拡大しても画質が荒れないSVG形式が特におすすめです。

  1. プレビュー画面を表示した状態で、VSCodeのコマンドパレット（Ctrl + Shift + P）を開きます。

  2. PlantUML: カーソル位置のダイアグラムをエクスポート（Export Current Diagram） を選択します。

  3. ファイル形式（png や svg など）を選ぶと、作業中のファイルと同じ階層に out フォルダが自動作成され、その中に画像が保存されます。

② AWSアイコンを最新バージョンにアップデートする

AWSのサービスは日々増え続けているため、公式アイコンのライブラリも定期的に更新されます。

最新のアイコンを使いたい場合は、AWS公式のGitHubリポジトリ（aws-icons-for-plantuml）で最新バージョンを確認し、コード3行目のURL内にある v23.0 の数字を最新のものに書き換えるだけで対応可能です。

③ よくあるエラーと解決策（トラブルシューティング）

初学者がつまずきやすい2大エラーとその対処法です。

  • エラー：「%splitstr_regex」や「$AWS_DARK」に関する構文エラーが出る

    • 原因： VSCode拡張機能の裏で動いているPlantUMLのバージョンが古いため、新しいAWSアイコンの描画機能に対応できていません。

    • 対策： 本記事の「3. VSCodeのセットアップと最新版PlantUMLの配置」の手順に戻り、最新の plantuml.jar を手動でダウンロードしてVSCodeの設定（plantuml.jar のパス）を正しく指定し直してください。

  • エラー：「Cannot find Graphviz」や「dot executable not found」と表示される

    • 原因： Graphvizのインストール時に、環境変数（PATH）を通す設定を忘れています。

    • 対策： Graphvizのインストーラーを再度実行し、「Add Graphviz to the system PATH」に必ずチェックを入れて再インストールしてください。

以上です。

コメント

タイトルとURLをコピーしました