Amazon Web Services ブログ

AWS 環境の可視化を加速する Diagram-as-code とAmazon Bedrockの活用

「このシステム、全体像を見せてもらえますか？」この質問に即座に対応できる組織はどれくらいあるでしょうか。
多くの AWS ユーザーが直面している課題の一つが、インフラストラクチャの可視化です。AWS リソースの構築は Infrastructure as Code (IaC) を実現する AWS CloudFormation や AWS CDK などの発展により自動化が進んだ一方で、それらの構成図を作成する工程は依然として人の手に委ねられていることが多いのが現状です。
以下のような課題を抱えているチームは少なくないでしょう：

  • AWS CloudFormation で管理している本番環境の構成図が古いままで、実態と合っていない
  • 開発環境、ステージング環境、本番環境など、複数の環境の構成図を最新に保つのが困難
  • システム変更の際、アーキテクチャ図の更新まで手が回らない
  • チーム内でアーキテクチャ図の描き方にばらつきがあり、レビューに時間がかかる

このような状況は、以下のような問題につながる可能性があります：

  • チーム間のコミュニケーションロスによる開発の遅延
  • システム変更時の影響範囲の見落とし
  • 新メンバーのオンボーディングの長期化
  • セキュリティレビューやコンプライアンス監査への対応の複雑化

本記事では、これらの課題に対する新しいアプローチとして、定義されたドキュメントからアーキテクチャ図を生成するツールである Diagram-as-code と AWS が提供する生成 AI サービスである Amazon Bedrock を組み合わせることで、事前定義されたインフラ構成情報から自動的にアーキテクチャ図を生成し、効率的に管理する手法について実践的な例を交えて解説します。

前提：本記事は大規模言語モデル (LLM) の可能性を提示したもので、構成の規模・複雑度が大きい場合は、精度を高める工夫が追加で必要になります。また、Diagram as code は、一般的にアーキテクチャ図をコードや定義ベースで管理する概念を指す用語としても使われています。しかし本記事では、特に言及がない限り、同概念を実現するYAML形式の定義ファイルからアーキテクチャ図を自動生成できるCLIツールを指す用語として使用します。

アーキテクチャ図生成の自動化

システム開発・運用においてアーキテクチャ図は不可欠です。アーキテクチャ図はシステムの全体像や各コンポーネント間の関係を視覚的に表現し、ステークホルダーのシステム理解を深め、コミュニケーションを円滑化します。しかしながら、アーキテクチャ図の作成と管理には相当な労力がかかり、アーキテクチャ図が存在しないまま進行しているプロジェクトや、更新が滞っており実態と異なるアーキテクチャ図しか存在しないといった状況はよくみられる課題です。

この問題に対し、アーキテクチャ図の自動生成を目指す取り組みは既に存在します。とはいえ、プロジェクトやシステムによって必要な表現や粒度が千差万別であるため、高度で繊細な作業が求められ、「やはり人の手で作成する方が正確で早い」という状況が続いているのが実情です。この現状に共感される方も多いのではないでしょうか。

近年、生成 AI の登場によって、この状況が変わろうとしています。生成 AI の曖昧な要件に対するタスク実行能力や、以前よりも拡大したコンテキストウィンドウを活用することで、構造化されていない文章からの情報抽出や構造化されたテキストへの変換が容易に可能となりました。これにより、アーキテクチャ図作成の自動化における大きな課題だった多様な要件の図への反映作業が簡略化できるようになります。

Diagram-as-code とは

本記事で紹介する Diagram-as-code は、事前に準備された構造化されたテキストベースから自動でアーキテクチャ図を生成するツールです。図の生成にあたって画像編集ソフトウェアや手作業での配置を必要としないため、効率的にアーキテクチャ図を作成・管理することができます。

本ツールの主な特長とユースケースは以下のとおりです：

  • AWS アーキテクチャガイドラインに準拠した、一貫性のある図を簡潔に生成できます
  • ヘッドレスブラウザや GUI に依存せず軽量で、コンテナですぐに始めることができます。これにより CI/CD での活用に親和性があります
  • CloudFormation テンプレートからツールで使用する定義ファイル (Dac ファイル) への変換機能が存在するため、IaC を実現している環境でより一貫した図を生成できます
  • CLI ツールとしての提供の他、Golang のライブラリとしても提供されており、例えば import して他の IaC ツール、AI システム、または描画 GUI ツールとの統合が可能です
  • 拡張可能な定義ファイル形式により、AWS サービスに限らず、様々なクラウドプロバイダーやオンプレミスコンポーネントを含むダイアグラムの作成が可能です

Diagram-as-code は CloudFormation テンプレートに類似したYAML形式のファイルを入力として、アーキテクチャ図を生成します。以下の図は活用中の CloudFormation テンプレートが存在する場合における Diagram-as-code の利用フローを示しています。

Diagram-as-code を活用すれば、既存の CloudFormation テンプレートからアーキテクチャ図を効率的に生成できます。しかし実際のプロジェクトで活用する段階においては、データフローやセキュリティ境界といった CloudFormation テンプレートに明示されていない要素をアーキテクチャ図に追加する必要が不可欠であり、この部分は依然として手作業による対応が求められます。さらに、目的に応じて表現の粒度や内容を変えたい場合、生成したい図ごとに手動での作業が発生します。そのため、用途の多様化やステークホルダーの増加、図に含まれるシステムの複雑さやリソース数に比例して、下図のように手作業の工数が増大していきます。

このように、IaC からのアーキテクチャ図の生成は、IaC に含まれない要件を反映する作業について効率化の余地が残されていました。

生成 AI によるアーキテクチャ図作成の自動化

Amazon Bedrock を活用した自動化のソリューション設計

この課題に対し、Amazon Bedrock と Diagram-as-code を組み合わせることで、より効率的かつ柔軟なアーキテクチャ図の生成が可能となります。

Amazon Bedrock は、フルマネージド型のサービスで、Anthropic、Cohere、Meta、Mistral AI、Amazon などの最先端の AI 企業が提供する高性能な基盤モデル (Foundation Model) を単一の API で利用できるほか、セキュリティ、プライバシー、責任ある AI に配慮した生成 AI アプリケーションを構築するための幅広い機能を提供します。

Amazon Bedrock を活用することで、本課題に対して以下の機能を実装できます：

  • 要件解釈機能: ユーザーが自然言語で入力した要件を理解する
  • 構造化出力機能: 理解した要件を含む構造化されたテキストを生成する
  • 対話的最適化機能: 生成結果に対するフィードバックを通じて出力したテキストの調整と改善を行う

前項で示した課題に対して Amazon Bedrock を取り入れた活用のフローは以下の通りです。ユーザーの自然言語での入力と CloudFormation テンプレートの情報から Dac ファイルの生成を行う手続きを Amazon Bedrock に任せることで、要件ごとに形式化された情報を手動で追加する作業を大幅に効率化できます。

中間定義ファイルの生成と直接描画手法の比較と考察

近年、マルチモーダル機能を持つモデルの発展により、モデルに対して入力から直接イメージを生成するよう指示する方法も可能になってきています。
入力から直接イメージを生成する方法と、一度中間ファイルを生成した後 Diagram-as-code のようなツールが描画を行う方法を比較した場合、後者には現時点で以下の特徴があります：

正確性と一貫性

  • 定義されたフォーマットに従った出力を描画ツールが保証
  • コンポーネント間の関係性をドキュメントベースで明確に表現

修正の容易さと柔軟性

  • コードベースでの差分管理が可能
  • 修正時にコードベースでの厳密な指示をすることも可能

検証とガバナンス

  • イメージを生成する前に、生成された中間ファイルに対する検証が可能

上記特徴は、ツールが引き受ける責任範囲とモデルが引き受ける責任範囲の差分によって生じます。したがって、将来は利用シーンごとに AI エージェントなどがモデルと使用するツールの適切な組み合わせを選ぶ形になると予想されます。例えば開発の初期段階では入力からアーキテクチャ図生成までを全てモデルに指示する方が開発速度向上の観点から好まれるかもしれません。一方、運用のフェーズでは正確性を重視し、中間ファイルから生成する方法が選択されることが多いと予想されます。

なお、AWS Blog 「Architecture to AWS CloudFormation code using Anthropic’s Claude 3 on Amazon Bedrock」では、本記事と逆の変換プロセス、つまりアーキテクチャ図から CloudFormation コードを生成する手法を紹介しています。この手法と本記事のアプローチを組み合わせることで、初期段階のラフスケッチから IaC とアーキテクチャ図の双方を効率的に生成し、本番環境への移行をスムーズに実現できます。

具体的な活用例の紹介

本記事後半では、前半で説明したアーキテクチャ図を生成する方法の具体例を示します。このアプローチにより、AWS環境の可視化を自動化し、作業時間を大幅に削減できます。

Step0 前提条件

まずは前提となる活用シチュエーションの設定と解説を行います。
今回対象とするシステムは、以下で掲載されているAWS ソリューションの CloudFormation テンプレート（空白を除き約 2.6 万文字、リソース数 23 個) とします。

Cognito User Profiles Export リファレンスアーキテクチャ

Step1 Diagram-as-code のセットアップ

はじめに Diagram-as-code を使用するための準備を行います。以下に示す通り、数ステップを完了することでツールの動作を確認することができます。

まず、以下いずれかの方法で awsdac をインストールします。

# Goを使用してインストール
go install github.com/awslabs/diagram-as-code/cmd/awsdac@latest

# macOS の場合
brew install awsdac

次にリファレンスアーキテクのチャページから CloudFormation テンプレートファイルをダウンロードします。ダウンロードしたファイルをターゲットとした以下コマンドを実行すると、中間ファイルと描画結果である png ファイルの両方を作成できます。

awsdac cognito-user-profiles-export-reference-architecture.template --cfn-template --dac-file

デフォルトでは一部の親子関係が明確なリソースを除いてアイコン間の関係情報が存在しないため、以下のように多数のリソースが横並びになった結果が表示されます。

中間生成ファイルを修正し、関係情報や位置情報を追加することで、元となる CloudFormation テンプレートでは表現できないリソース間の関係性やグループを表現することは可能です。しかし前述したように、リソースの数や要件の数に比例して作業時間が増大します。

Step2 Amazon Bedrock で利用するプロンプトの準備

効率よくリソース間の関係や要件を補完するため、Amazon Bedrock を活用することを考えます。まずは、モデルに入力するためのプロンプトを作成します。今回は、ユーザーの口語的な表現を Diagram-as-code のフォーマットに従った表現に変換するプロンプトを作成しました。
以下にプロンプトのサンプルを示します。

User: CloudFormation テンプレートとユーザー要件という2つの入力ソースに基づいて、Diagram-as-code の YAML ファイルを生成します。
CloudFormation テンプレートは<cloudformation-template></cloudformation-template>セクションに、ユーザー要件は<user-requirements></user-requirements>セクションに記載されています。
Diagram-as-codeファイル形式はYAML構文を使用し、3つの主要セクションで構成されています。また、<custom-rules></custom-rules>にカスタムルールセクションがあります。

<diagram-as-code-format>
{DAC_FORMAT_INTRODUCTION}
</diagram-as-code-format>

<custom-rules>
{CUSTOM_RULES}
</custom-rules>

<cloudformation-template>
{INPUT_CLOUDFORMATION_TEMPLATE}
</cloudformation-template>

<user-requirements>
{INPUT_USER_REQUIREMENTS}
</user-requirements>

最終的なYAML出力を生成するには、以下の手順に従ってください:
1. CloudFormationテンプレートを確認し、図に表示する必要のあるAWSリソースの定義を抽出します。
2. ユーザー要件とカスタムルールを確認し、CloudFormationテンプレートに含まれていないシステムアーキテクチャに関する追加のコンテキストや詳細を収集します。
3. 以下の方法でDiagram-as-code YAMLファイルを構築します:
- DefinitionFilesセクションでリソース定義ファイルの場所を指定する。
- Diagram-as-code形式に従って、Resourcesセクションでリソースとその関係を定義する。
- Diagram-as-code形式とカスタムルールに従って、Linksセクションでリソース間のリンクを定義する。
4. 最終的なYAML出力が入力ソースに基づいてシステムアーキテクチャを正確に表現していることを確認します。

<example>
{INPUT_EXAMPLE}
</example>

実際にプロンプトテンプレートを利用する場合、可変値となる部分は変数として定義しています。上記テンプレートに埋め込まれた5つの変数の用途は以下のとおりです。接頭辞として INPUT がついている変数は特に入力毎に変化する値として想定しています。

  • DAC_FORMAT_INTRODUCTION : ツールのバージョンアップとともに更新されるDiagram-as-code の仕様
  • CUSTOM_RULES : 美しい図を生成するためのヒント
  • INPUT_CLOUDFORMATION_TEMPLATE : ユーザー入力となる、生成元の CloudFormation テンプレート
  • INPUT_USER_REQUIREMENTS : ユーザーが生成する図の方向性を指示するための要件
  • INPUT_EXAMPLE : 生成の精度を向上させるためのサンプル。一度生成した図を編集したい場合も活用する

Step3 プロンプトを使用したプログラムからの中間ファイルの生成と図の生成

Amazon Bedrock 上の Claude を利用し、文書化された要件から Diagram-as-code で利用可能なフォーマットを生成します。以下は一連の流れを実行するサンプルスクリプトです。

import boto3
import os
import subprocess

# プロンプトテンプレート
prompt_template = """
<Step3 で記述しているため省略>
"""

# prompt_variables フォルダから入力用の変数を読み込む
variables = {}
for filename in os.listdir('prompt_variables'):
    if filename.endswith('.txt'):
        with open(os.path.join('prompt_variables', filename), 'r') as f:
            variable_name = os.path.splitext(filename)[0]
            variables[variable_name] = f.read().strip()

# プロンプトテンプレートに変数を挿入
prompt = prompt_template.format(
    **variables
)

# Amazon Bedrock Runtime client を作成
client = boto3.client("bedrock-runtime", region_name="us-east-1")
model_id = "us.anthropic.claude-3-7-sonnet-20250219-v1:0"

conversation = [
    {
        "role": "user",
        "content": [{"text": prompt}],
    }
]

# Amazon Bedrock へメッセージを送信
response = client.converse(
    modelId = model_id,
    messages = conversation,
    inferenceConfig={"maxTokens": 8192, "temperature": 0.2, "topP": 0.9},
)

response_text = response["output"]["message"]["content"][0]["text"]

# 中間 Dac ファイル保存
yaml_filename = f"output.yaml"
with open(yaml_filename, 'w') as f:
    f.write(response_text)

# PNG ファイル生成
png_filename = f"output.png"
try:
    subprocess.run(["awsdac", yaml_filename, "-o", png_filename], check=True)
    print(f"PNG ファイル生成完了: {png_filename}")
except subprocess.CalledProcessError as e:
    print(f"PNG ファイル生成中にエラーが発生しました: {e}")
except FileNotFoundError:
    print("Error: awsdac コマンドが見つかりません。")

python ファイルを配置した場所に prompt_variables フォルダを作成し、以下の各テキストファイルを作成します。今回実行にあたって指定した内容を以下に示します。

DAC_FORMAT_INTRODUCTION.txt

Diagram-as-code の Introduction guide に掲載された内容を記述しています。

CUSTOM_RULES.txt

整った画像を表示するためのヒントを記述します。今回記述した指示は以下の通りとなります。

全体に関する指示
- YAML構文に従い、回答に不要な説明や説明文を含めないでください。
- 回答の最初と最後にトリプルバッククォートのYAMLマーカーを含めないでください。

Links に関する指示
- 特に指示がない場合、CloudFormation template に含まれる Resource は全て表示してください。
- Resources の後に Links を出力してください
- Links セクションでは、SourcePosition が S の場合、TargetPosition は N が望ましく、その逆も同様です。また、SourcePosition が E の場合、TargetPosition は W が望ましく、その逆も同様です。
- Links セクションの要素は、Resource セクションに存在する Resource 間でのみ接続する必要があり、存在しない Resource を Source もしくは Target に指定することはできません。
- Links セクションの要素には必ず orthogonal プロパティを追加し、Source から Target への方向を明示してください。
- AWS::Diagram::VerticalStackとAWS::Diagram::HorizontalStack はグループ化に使用し描画しないソースであるため、Link の Source と Target に指定しないでください。
- 同じ SourcePosition や TargetPosition を指定する Link が 3 つ以上存在する場合、2文字目に同じ方角を重ねた後、3文字目に違う方角を追加し Link が重なることを避けてください（例: 同じ Resource の同じ Position である N を指定する複数の Link が存在する場合、Position の値を NNE, NNW とすることで描画時の Link の重なりを避けることができます)

Resource に関する指示
- 同じ Resource を 複数の Resource の Children プロパティに指定できません。子の親は必ず 1 つです。
- Resource が所属するグループを明示的に指定する場合は、AWS::Diagram::Resource を使用し、その Children プロパティにグループに所属させたい Resource を指定してください。
- 指示がありUserアイコンを表示した方が良い場合には、以下の表記を使用できます：
```
    User:
      Type: AWS::Diagram::Resource
      Preset: "User"
```

Label に関する指示
- 同じ Resource を Target もしくは Source として指定する複数の Link があり、それぞれに Label がある場合、Label の重なりを防ぐため Label のプロパティに TargetLeftまたはTargetRight を使用してください。
- Resource アイコンの下には Label が付与されるため、SourcePositionがSのLink の Label は TargetLeft か TargetRight のプロパティ使用して配置してください

配置に関する指示
- VerticalStack の Children は西(W)から東(E)に描画されます。HorizontalStack の Children は北(N)から南(S)に描画されます。
- Userからの距離が2より大きい Resource については、HorizontalStackまたはVerticalStackをネストして使用することを積極的に検討してください。これにより Links で Resource を接続した時に、 Links がアイコンと重なる可能性が下がります
- Vertical と Horizontal を交互に使ってリソースを配置することで図全体が一方向に長くならないようにしてください。
- 以下の優先度のルールに従って配置してください。優先度は値が小さいものが優先されます。
  1. Link は SourcePosition: S と TargetPosition: N で固定してください。ただし、深い階層から浅い階層へフィードバックする Link のみ SourcePosition, TargetPosition に E もしくは W が許可されます。
  2. AWSCloud (AWS::Diagram::Cloud) の中で AWS::Diagram::HorizontalStack で hierarchy を作成してください。hierarchy は User から辿れる Link 数です。hierarchy は何個作成しても構いません。
  3. Link が交差しないように Children の順序を入れ替えてください。Link(A->D), Link(B->C) ならば VerticalStack(HorizontalStack(A, B), HorizontalStack(D, C)) が Link が交差しない HorizontalStack 内の Children の順序です。前の hierarchy の並び順から Link されている Resource の順序を決定してください。
INPUT_CLOUDFORMATION_TEMPLATE

Step 0 で提示した CloudFormation テンプレートを使用します。

INPUT_USER_REQUIREMENTS

以下に示す、ユーザーや状況によって異なる要件を記述します。今回はソリューションのページは閲覧しているが、実際にデプロイされるリソースについては把握していないという状況を想定して記述しました。

- これは ユーザーが認証に使う Amazon Cognito User Pools のユーザー情報をエクスポートして、別のリージョンにバックアップするソリューションです。
- Cognito のユーザー情報がバックアップされまでの道筋を明確にしてほしいです
- 各リージョンにどの AWS リソースが所属しているかを明確に示してください
- 可能な範囲で役割ごとに関連する AWS リソース群をグループ化してその役割を明示して欲しいですが、AWS リソースの省略はしないでください
- IAM と KMS に関する AWS リソース以外は全ての AWS リソースを必ず表示してください
INPUT_EXAMPLE.txt

今回の実行時は空白の状態にしています。一度生成したファイルを修正したい時はこちらに記載します。

Step4 実行結果の確認と修正

上記手順を実行した際に生成したアーキテクチャ図の例を複数以下に記載します。デフォルトで生成された図はアイコンが横並びでしたが、以下より、配置がグループ化されリソース間の関係が確認できます。指示の通りリージョンの要素が表示され、IAM や KMS の情報は逆に含まれないことなどが確認できることから、ユーザー要件がモデルによって解釈され適切な中間ファイルがモデルによって生成されていることが確認できます。

この後は、生成された中間ファイルを入力とし、追加の要件や修正の指示を与えることで、よりきめ細やかな表現の調整が可能です。

また、より正確性を求める場合、生成された中間ファイルと入力として使用した CloudFormation テンプレートのそれぞれに含まれるリソース情報の差分を YAML 形式で解析して抽出し、図の生成に使用されているリソースと入力に含まれているリソースが一致しているか、意図した通りのリソースの省略が行われているかの確認をスクリプトベースで実現することも可能です。

サマリー

本記事ではアーキテクチャ図の生成管理に関する既存の課題について説明し、生成 AI を活用することで課題を解決し、容易に環境を視覚化する新しいインフラストラクチャ管理の方式を紹介しました。さらに、Diagram-as-code と Amazon Bedrock を組み合わせ、中間ファイルを生成した後にアーキテクチャ図を生成する手順を示しました。

紹介した方法は、直接アーキテクチャ図を生成する代わりに、描画するための情報を含んだ中間ファイルを生成します。これは生成 AI でプロンプトから直接図を生成する方法と比較すると 1 ステップ手間が増える一方、生成した図の微修正の容易さや中間ファイルに対する検証が可能であるというメリットもあります。本記事では Diagram-as-code というツールにて実例を示しましたが、利用シーンごとに別のツールを利用する場合でも同様の構成が実現できます。

本記事を参考に、中間生成したファイルに対する検証チェックの実装や、CI/CD パイプラインへの組み込みなど、要件に応じた応用と発展の例が今後多数出てくることを期待しています。

著者

  • 秋山 周平（ゲームソリューションアーキテクト）
  • 北村 裕汰（クラウドサポートエンジニア）