ndiagでAWSのアーキテクチャドキュメントを書く
What's
ndiag が素敵なのでAWS上に構築したアーキテクチャドキュメントを書いてみます。
[email protected]を使用しました。
↓できあがりはこちら
https://github.com/watarukura/ndiag-study
準備
https://github.com/k1LoW/ndiag/blob/main/README.md#install を参照。
goはインストール済みなので、go getしました。
go get github.com/k1LoW/ndiag
ドキュメント用のディレクトリを作って、AWSアイコンをダウンロード。
mkdir -p aws_doc_sample
cd $_
ndiag fetch-icons aws
書き始める
とりあえずチュートリアルを一周しました。
https://github.com/k1LoW/ndiag/blob/main/docs/tutorial.ja.md
チュートリアルの順に、nodesを書いてみてndiag doc --rm-dist、networksを書いてndiag ...、relationsを書いて以下略、とするのが良さそうです。
アイコンのキーはndiag list iconsで表示できるので、これを見ながらndiag.ymlに書き込んでいきます。
VSCode ExtensionsでMarkdown Preview Enhancedをインストール。
Previewを見ながらndiag.ymlを書いては生成、書いては生成します。
とりあえず
---
name: Sample AWS web service
docPath: docs/arch
views:
-
name: overview
nodes:
-
name: cdn
components:
- CloudFront?icon=aws-cloud-front
- Waf?icon=aws-waf
-
name: frontend
components:
- Beanstalk?icon=aws-res-elastic-beanstalk-application
-
name: api
components:
- ECS?icon=aws-res-elastic-container-service-service
-
name: db
components:
- AuroraMySQL?icon=aws-aurora
-
name: dynamodb
components:
- DynamoDB?icon=aws-dynamo-db
networks:
-
route:
- "internet"
- "cdn:CloudFront"
-
route:
- "cdn:CloudFront"
- "frontend:Beanstalk"
-
route:
- "frontend:Beanstalk"
- "api:ECS"
-
route:
- "api:ECS"
- "dynamodb:DynamoDB"
-
route:
- "api:ECS"
- "db:AuroraMySQL"
-
route:
- "api:ECS"
- "Payment API"
relations:
-
components:
- "cdn:CloudFront"
- "cdn:Waf"
感想
アーキテクチャ概要ドキュメントを描いたものの更新が億劫になり、マイグレーション後にドキュメントの更新を忘れていて新人さんへの説明資料に使えない、みたいな事態がままありました・・・。
ndiagを使ってGitHub等でドキュメントを更新するようにすれば、アーキテクチャの更新時にIssue/Pull Requestを作る運用にしたり、既存の構成との差分が発生したときに検知させたり、ということができるかも。
AWSアカウント -> VPC -> AZでうまくClusterを作ってグルーピングしたり、Elastic Beanstalkの中でALBを使ってるのかCLBのままなのかを段階的に詳細化したり。工夫次第で新メンバーへの説明に使いやすいドキュメントを作れそうです。
Author And Source
この問題について(ndiagでAWSのアーキテクチャドキュメントを書く), 我々は、より多くの情報をここで見つけました https://zenn.dev/watarukura/articles/20210330-qvne4ivs33y3g088gyudat5t3b7h著者帰属：元の著者の情報は、元のURLに含まれています。著作権は原作者に属する。
Collection and Share based on the CC protocol