技術4課の多田です.

AWS 環境の構成図を書く機会で PowerPoint や Cacoo 等のサービスを使うことがあると思います.作図もコードで制御する方法もないかと思い調べてみたら,「AWS-PlantUML」というツールがありました.今回はこのツールを使って作図する方法と所感を書いていきます.

「AWS-PlantUML」とは

「AWS-PlantUML」とは,PlantUML 形式で AWS 構成図を書くためのツールになります.PlantUML の実行環境は調べればたくさん出てきますが,僕は普段 Visual Studio Code(以下,vscode)を使うため vscode で使う環境をセットアップしました.

参考URL

「AWS-PlantUML」を導入するか

vscode の環境ができたら「AWS-PlantUML」のセットアップを行います.2つの方法があります.1つ目は,インターネット接続をしたくない場合に common.puml をダウンロードして !include ディレクトリパス/common.puml をpuml ファイルで @startumlの後に定義する方法です.

@startuml
!include ディレクトリパス/common.puml

2つ目は,下記のように直接リポジトリの URL を指定する方法です.今回は2つ目の方法で設定して進みます.

@startuml
!includeurl https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist/common.puml
!includeurl AWSPUML/common.puml

「AWS-PlantUML」の使い方

AWS アイコンの指定方法

それでは,実際に構成図を書いていきます.まず,AWS のサービスアイコンの指定方法は以下のように定義します. !includeurl AWSPUML/ までは共通ですが,それ以下のパスはリポジトリ内の dist ディレクトリパスで指定します.また,アイコンの指定方法は AWS_SERVICE_NAME_UPPERCASE(puml resource name, display name) のように行います.

!includeurl AWSPUML/ApplicationServices/AmazonAPIGateway/AmazonAPIGateway.puml
!includeurl AWSPUML/Compute/AWSLambda/LambdaFunction/LambdaFunction.puml
!includeurl AWSPUML/Database/AmazonDynamoDB/AmazonDynamoDB.puml
!includeurl AWSPUML/Database/AmazonDynamoDB/table/table.puml

USER(user)
CLIENT(browser)
JAVASCRIPT(js,SDK)

AWSCLOUD(aws) {

AMAZONS3(s3) {
BUCKET(site,www.insecurity.co)
BUCKET(logs,logs.insecurity.co)
}

AMAZONAPIGATEWAY(api)

AWSLAMBDA(lambda) {
LAMBDAFUNCTION(addComments,addComments)
}

AMAZONDYNAMODB(dynamo) {
TABLE(comments,Comments)
}
}

参考

サービス間のシーケンス図

サービス間のシーケンス図は下記のような指定で描画できます.例えば,以下の指定だと S3 バケット間の連携を記載できます.

AMAZONS3(s3) {
BUCKET(site,www.insecurity.co)
BUCKET(logs,logs.insecurity.co)
}
site .r.> logs : events

作図コードのサンプル例

コードの参考例として下記のような定義で vscode 上でプレビューして状況を確認できます.

@startuml
!define AWSPUML https://raw.githubusercontent.com/milo-minderbinder/AWS-PlantUML/release/18-2-22/dist

!includeurl AWSPUML/common.puml
!includeurl AWSPUML/ApplicationServices/AmazonAPIGateway/AmazonAPIGateway.puml
!includeurl AWSPUML/Compute/AWSLambda/AWSLambda.puml
!includeurl AWSPUML/Compute/AWSLambda/LambdaFunction/LambdaFunction.puml
!includeurl AWSPUML/Database/AmazonDynamoDB/AmazonDynamoDB.puml
!includeurl AWSPUML/Database/AmazonDynamoDB/table/table.puml
!includeurl AWSPUML/General/AWScloud/AWScloud.puml
!includeurl AWSPUML/General/client/client.puml
!includeurl AWSPUML/General/user/user.puml
!includeurl AWSPUML/SDKs/JavaScript/JavaScript.puml
!includeurl AWSPUML/Storage/AmazonS3/AmazonS3.puml
!includeurl AWSPUML/Storage/AmazonS3/bucket/bucket.puml

skinparam componentArrowColor Black
skinparam componentBackgroundColor White
skinparam nodeBackgroundColor White
skinparam agentBackgroundColor White
skinparam artifactBackgroundColor White

USER(user)
CLIENT(browser)
JAVASCRIPT(js,SDK)

AWSCLOUD(aws) {

AMAZONS3(s3) {
BUCKET(site,www.insecurity.co)
BUCKET(logs,logs.insecurity.co)
}

AMAZONAPIGATEWAY(api)

AWSLAMBDA(lambda) {
LAMBDAFUNCTION(addComments,addComments)
}

AMAZONDYNAMODB(dynamo) {
TABLE(comments,Comments)
}
}

user - browser

browser -d-> site :**1a**) get\nstatic\ncontent
site ~> logs :1a
site .u.> browser :**1b**
browser - js
js -r-> comments :**2a**) get\ncomments
comments ..> js :**2b**

js -r-> api :**3**) add\ncomment

api -d-> addComments :**4**

addComments -> comments :**5**

comments ..> js :**6**) new\ncomments
@enduml

プレビュー画面例

構成図をアウトプットする

作図したデータを HTML や PDF ファイルなどに出力する方法も見ておきます.プレビュー画面上で右クリックし, Open in Browser をクリックします.ブラウザで表示後,右クリックし別名で保存をクリックすれば HTML ファイルで保存でき,印刷をクリックして PDF 保存も可能です.

まとめ

PlantUML 形式で AWS 構成図を作図する「AWS-PlantUML」の紹介と,簡単な使い方を紹介しました.手動で細かく描画するよりコードでサービス間のシーケンス図を書けるのは普段の手間を考えると楽ですし,コードで管理できるのでバージョン管理もしていきやすいのではと思いました.AWS のアイコンの中にはまだ対応が追いついていないもの(EKSなど)もあるので,issue出してリクエスト出してよりよくしていくようにしていきたいですね!