AWSスタイルのアーキテクチャ図
概要
AWSの参照アーキテクチャ図の規則に従った図を作成します。正確なサービス名、ラベル付きのアカウント/リージョン/VPC境界、短いフローラベル、そしてすっきりとしたキャンバスが特徴です。「AWSスタイル」とはこれらの規則を指し、公式のAWSアイコンやGraphvizを必須とするものではありません。
MermaidとGraphviz DOTは同等のオーサリングフォーマットです。Mermaidは多くの場合、インラインで、テーマに対応し、テキストレビュー可能なドキュメントに適しています。DOTは多くの場合、正確なローカルAWSアイコンアセット、制御された構成、プレゼンテーション対応のSVG/PNGに適しています。完全なデリバリー契約を満たす場合はどちらか一方を使用し、異なる視聴者やアーティファクトによって追加のメンテナンスコストが正当化される場合は両方を使用します。
使用する場面
エビデンスに基づいたAWSアーキテクチャ、トポロジー、システムコンテキスト、またはデータフロー図が必要な場合にこのスキルを使用します。非AWSのビジュアルが必要な場合や、表だけで要求された情報を明確に伝えられる場合は使用しないでください。
よくある誤った理由付け
- 「AWSスタイル＝DOT」という考えは、実際の契約を満たすMermaidレンダラーを無視しています。
- 「両方のフォーマットの方が安全」という考えは、名前の付けられた2つの利用者がいないのに同期コストを生み出します。
- 「このサービスはおそらくここに接続するはず」はエッジのエビデンスにはなりません。
レッドフラグ
描画やライブインフラへのクエリを開始する前に、サポートされていないリソースや関係性、曖昧なターゲットレンダラー、不足しているアイコンの権利やアセット、矛盾するソースエビデンス、許可された範囲外の要求されたリージョンがないか確認し、解決してください。
美学に優先するルール
ソースが確立したものだけを描くこと。 すべてのノード、エッジ、境界、リージョン、プロトコルは、Terraform、CloudFormation、CDK、デプロイ済み設定、または所有者の書面による声明などの実際のものに基づいている必要があります。図とは、たまたま視覚的であるエビデンスのアーティファクトです。
絵のバランスが悪いからといって、サービス、接続、アベイラビリティゾーン、VPC、リージョンを決して追加しないでください。ソースが境界を確立していない場合は、それを省略します。正直でスパースな図は、装飾的な完全な図よりも優れています。何かがデプロイされているが無効になっている場合は、それがライブであるかのように描くのではなく、ノードにその旨を記載し（WEB_PUSH_ENABLED=false、「デプロイ済み、リリース無効」）、他のチームが所有するものにはマークを付けて、読者が自分が制御していると思い込まないようにします。
図自体に出典を明記します。ソースを命名したサブタイトル、例えば "<iac-dir>/*.tf の <revision> からトレース" や "ライブ読み取り専用インベントリ、<date>" を付け、DOTソースのヘッダーコメントでも繰り返します。
リソースに名前を付け、サービスだけを名付けない
サービスアイコンだけでは何も識別できません。「Operations」とラベル付けされたマゼンタ色のDynamoDBグリフは、テーブル、ストリーム、インデックスのいずれかであり、読者はコンソールでそれを見つける方法がありません。すべてのノードは3つの事実を述べます。
- AWS内での呼び名。 実際のデプロイ名 —
acme-orders-events、フレンドリーなエイリアス「Orders」ではありません。アカウントIDは数字ではなく<account>と書き、シークレット、トークン、エンドポイントを図に絶対に入れないでください。 - リソースのタイプ。 名前の下に、灰色で、書き出します。「DynamoDBテーブル」、「S3バケット」、「Lambda関数」、「API Gateway HTTP API」、「WAFv2 Web ACL」、「SES v2 メールID」。
- それが何のためのものか。 1行で、読者が推測できない場合にのみ記載します。
Graphviz出力の場合は、AWSが公開しているリソースアイコンを使用します。Res_Amazon-DynamoDB_Table、Res_Amazon-Simple-Storage-Service_Bucket、Res_AWS-Lambda_Lambda-Function — それ以外はサービス（Arch_）アイコンを使用します。アイコンはIDを補強します。アイコンだけがIDを伝えるものであってはなりません。アイコンはグレースケール、サムネイルサイズ、スクリーンリーダーでは読めないからです。
要件からフォーマットを選択する
絶対的な勝者やデフォルトのフォーマットはありません。明示的に要求されたソースフォーマットを尊重します。ただし、それが他の受理基準と競合する場合は除きます。それ以外の場合は、実際のデリバリーニーズを比較します。
| 要件 | Mermaidの方が適している傾向 | Graphviz DOTの方が適している傾向 |
|---|---|---|
| リポジトリレビュー | インラインMarkdownレンダリング、コンパクトなテキストdiff | レビュー可能なテキストソースと個別にレンダリングされたアーティファクト |
| 図のタイプ | シーケンス、フロー、状態、依存関係、および単純なアーキテクチャビュー | 高密度トポロジー、ネストされた境界、および意図的なエッジルーティングが必要なグラフ |
| AWSビジュアル | AWSスタイルの名前、境界、色、またはレンダラー提供のアイコンパック | リポジトリローカルのAWS公開アイコンアセット |
| レイアウト | レンダラー管理のレスポンシブレイアウトとテーマ適応 | 正確なランク、ポート、クラスター、スペーシング、固定構成 |
| デリバリー | 書かれた場所でレンダリングされるべきドキュメント | デッキ、ドキュメント、プレゼンテーションサーフェス用の制御されたSVG/PNG |
| ツール | ターゲットレンダラーが既に必要なMermaid構文とバージョンをサポートしている | Graphvizと必要なローカルアセットがビルドまたはオーサリング環境で利用可能 |
要求されたコンテンツが実際に表形式の場合は、画像にするのではなくMarkdownテーブルを使用します。順序付けられた参加者のやり取りには、MermaidのsequenceDiagramが通常自然な選択です。これは図タイプの利点であり、Mermaid全般の好みではありません。
Mermaidはアーキテクチャ図と設定可能なアイコンパックをサポートしていますが、ホスト型レンダラーがリポジトリローカルのAWSアセット、カスタムパック登録、または制御されたローカルレンダラーと同じMermaidバージョンを提供するとは限りません。Graphvizはローカルイメージアセットを直接ロードできるため、正確なアイコンアセットと固定エクスポート構成が受理基準である場合に信頼できる選択肢です。単にリクエストが「AWSスタイル」と言っているからという理由ではありません。
両方のトレードオフを数えます。Mermaidはレンダラーバージョン、利用可能なアイコンパック、ホストテーマによって異なる場合があります。DOTはレンダリングステップと、編集可能なソースと同期を保つ必要がある生成アーティファクトを追加します。どちらかのツールの強みを普遍的と見なすのではなく、そのコストがリポジトリと出力先に合うフォーマットを選択します。
レンダラーのサポート、アイコンの忠実度、固定構成、または期待される出力ファイルが結果を実質的に変更し、リクエストが曖昧な場合は、デリバリー契約を明確にします。それ以外の場合は、既知の要件を最小のプロジェクト固有の仕組みで満たすフォーマットを選択します。
Mermaidが選択された場合、上記のエビデンス、出典、リソース命名、アクセシビリティのルールを保持し、ターゲットレンダラーでソースを検証し、以下のGraphviz固有のワークフローの前に停止します。
両方のフォーマットが正当化される場合
MermaidとDOTは、インラインリポジトリレビューと正確なAWSアイコンプレゼンテーション出力など、異なる実際の要件を満たす場合に作成します。両方のデリバリーが自動的に優れているわけではありません。両方のアーティファクトに名前の付けられたコンシューマーまたは受理基準がある場合にのみ正当化されます。
デフォルトでどちらかのソースが正規であるとは限りません。両方とも同じ検証済みのリソースと関係のインベントリから導出し、同じ出典を持ち、ノード、エッジ、境界、リージョン、所有権、不確実性が一致することを確認します。フォーマットは、それが主張するアーキテクチャを変更せずに、プレゼンテーション固有の構造を追加する場合があります。ユーザーまたはリポジトリポリシーが明示的にその役割を割り当てる場合にのみ、一方のフォーマットを権威あるものとして指定します。
正確なAWSアイコン、固定構成、またはポートレベルのコネクタ配置が必要な、非常に密度の高い完全システムマップの場合、DOTとそのSVGおよびPNGがプレゼンテーションおよびAWSアイコンアーティファクトとして機能します。Mermaidレンダリングは、それも必要な場合に、保守可能でインラインレビュー可能なコンパニオンとして機能します。それらのDOT固有の要件がない焦点を絞ったフローの場合、Mermaidだけで契約を満たす場合があります。これらは要件駆動型の選択であり、すべての図に対して両方のフォーマットを作成する理由ではありません。
Mermaidワークフロー
1. Mermaid図タイプを選択する
アーキテクチャとトポロジーにはarchitecture-betaまたはフローチャートを、順序付けられたやり取りにはsequenceDiagramを、実際の状態遷移にのみ状態図を使用します。ターゲットレンダラーが選択した構文とアイコンパックをサポートしていることを確認します。GitHub、ドキュメンテーションサイト、ローカルのMermaid CLIが同じバージョンまたは設定で実行されていると想定しないでください。Iconifyシンボルを使用する場合、完全なAWSリソース名とタイプをテキストで保持します。アイコンだけがリソース識別子であってはなりません。
2. 検証済みインベントリをエンコードする
AWSアカウント、リージョン、VPC、アベイラビリティゾーン、サブネット、所有権の境界は、エビデンスがそれらを確立する場合にのみ表現します。完全なリソース名とタイプ、短いラベルの付いたエッジ、許可または推論された関係の可視アノテーションを使用します。出典を近くのMarkdownと、構文が許可する場合はソースコメントに保持します。
3. ターゲット環境でレンダリングして検査する
リポジトリの固定されたMermaidコマンドまたはドキュメントビルドを使用します。出荷される正確なフェンス付きブロックまたは.mmdソースを検証し、意図された幅とテーマでレンダリングされた結果を検査します。クリップされたラベル、重複するエッジ、サポートされていないアイコンや構文、アクセス不可能なコントラスト、検証済みインベントリからのセマンティックドリフトを確認します。編集可能なソースを修正し、読み取れるようになるまで再レンダリングします。
組み込みでないアイコンパックは明示的に登録します。Mermaid CLIの場合、再現可能なAWSシンボルレンダリングは次のように行います。
mmdc --iconPacks '@iconify-json/logos' \
-i system-context-aws.mmd -o system-context-aws.svg -b white
?フォールバックは、外観上の低下ではなく、レンダリングの失敗として扱います。アイコンパックのサポートはMermaidのバージョンとレイアウトレンダラーによって異なる場合があります。実際の出力を視覚的かつ構造的に検証します。サポートされているレンダラーの1つが登録済みアイコンを失う場合は、それらを保持する別のサポートされているレンダラーを使用し、レイアウトのトレードオフを文書化します。ターゲットホストも必要なパックを登録しない限り、インラインの移植性を主張しないでください。
4. 必要なアーティファクトを提供する
それがリポジトリ契約である場合は、Mermaidをインラインに保ちます。スタンドアロンのSVGまたはPNG出力が必要な場合は、リポジトリの固定されたMermaidバージョンで決定論的にレンダリングし、再現コマンドを文書化します。
Graphvizワークフロー
1. ソースからアーキテクチャを確立する
IaCを読み、描画する前に実際に存在するものをインベントリします。このプロジェクトがそれを保持しているディレクトリ — infra/、terraform/、deploy/、CDKアプリ — を見つけます。レイアウトを想定しないでください。
iac_dir=infra # このリポジトリが実際に使用するもの
ho -E '^resource "aws_[a-z0-9_]+"' "$iac_dir"/*.tf | sort | uniq -c | sort -rn
次に、エッジを現実のものにする具体的情報およびノードに表示される名前を取得します。関数名、テーブル名、バケット名、イベントルールとそのスケジュール、S3通知、オーソライザー、クロスアカウントまたはクロススタックの権限付与。変数やローカルを通じて名前を、実際にデプロイされた値に解決します。想定ではなく、それを設定する変数からリージョンをメモします。
1b. IaCがない場合、またはIaCが全体の一部にすぎない場合
図にしたいものが誰もTerraformを持っていない実行中のアカウントである場合や、Terraformがデプロイされたものの一部のみをカバーする場合があります。その場合、ソースはライブアカウント（読み取り専用）であり、図はそれが何であるかを明示する必要があります。
サービスごとのスイープではなく、タグ述語から始めます。これは「このシステムに属するもの」を範囲指定する唯一の方法だからです。
aws resourcegroupstaggingapi get-resources --region <region> \
--tag-filters 'Key=<key>,Values=<v1>,<v2>'
いくつかのタグキーはそれぞれ1つのリクエストが必要で、その後ARNで結合します。1つのリクエストで2つのキーを渡すとANDが適用され、そのうちの1つだけを持つすべてのものが暗黙的にドロップされます。結果のカウントと日付を記録します。それはスナップショットであり、事実ではありません。
タグ付けAPIはすべてのリソースタイプを返すわけではなく、タグは所有権ではありません。そのため、タグクエリはノードセットを提供し、関係は実際にそれらをモデル化するAPIから取得します。
| 確立するもの | 読み取るもの |
|---|---|
| イングレス配線 | elbv2 describe-load-balancers、describe-target-groups |
| 許可されるパス | ec2 describe-security-groups、describe-vpcs |
| コンピュート層が呼び出す可能性があるもの | iam get-instance-profile、次にget-policy-version |
| データ層の形状とレプリカ | rds describe-db-instances、elasticache describe-* |
| 非同期配線 | キューのリドライブポリシー、S3通知、イベントルール |
見つけたすべてのCIDRを、描画する前に名前付きVPCに解決します。図上で未解決の10.16.0.0/16は読者に何も伝えません。
1c. 各エッジがどの種類のエビデンスに基づいているかを示す
これはライブアカウントを読み取るときに最も重要です。2つのリソースが命名プレフィックスを共有しているため、線を引きたくなるからです。クラスを視覚的に分離し、図とその散文で定義します。
- AWS自体が報告する配線 — ターゲットグループのターゲット、レプリカのソース。最強のクラス。AWSが関係をモデル化しています。
- 何かが許可するパス — セキュリティグループルール、バケットポリシー。これは呼び出しが発生する可能性があることを確立しますが、発生することを確立するわけではありません。ルールがセキュリティグループスコープではなくCIDRスコープの場合に注意してください。矢印を引いた単一のワークロードではなく、範囲全体を許可します。
- IDが保持する権限付与 — IAMポリシーステートメント。同じ注意、さらにSCP、許可境界、リソースポリシーが評価されるまで、権限付与は有効な許可ではありません。
- 命名またはタグからの推論 — 破線で描画し、不確実性をラベル付けするか、省略します。実線にしないでください。
不在も描く価値のある発見です。「明らかに」キューと通信するロールがsqs:*アクションをまったく保持していないことが判明した場合、その旨を伝えるノードは、欠落した矢印よりも有用です。なぜなら、それは間違った仮定を先送りするのではなく、排除するからです。