はじめに
こんにちは、クラウド事業部の松岡です。
CloudFormationのテンプレート管理において、ドキュメントの鮮度を保つことは意外と難しいものです。
本記事では、テンプレートからMarkdown形式のドキュメントを自動生成できるツール 「cfn-docs」 を実際に触ってみた内容をまとめています。
対象読者
- AWS経験が数ヶ月で、複数リソースの構築に挑戦したい方
- IaC（Infrastructure as Code）のドキュメント保守を自動化したい方
解説のポイント
- 実務を想定した最小権限のIAM設定
- 運用の手間を減らすリソース管理方法
- CloudFormationテンプレートの可視化によるレビュー効率化
cfn-docsとは？
cfn-docs は、AWS CloudFormation (Cfn) のテンプレートファイル（YAML/JSON）から、Markdown形式のドキュメントを自動生成してくれるコマンドラインツールです。
通常、CloudFormationのコードを読むには各リソースの定義を深く読み込む必要がありますが、cfn-docsを使うことで、誰でも読みやすい構成図のような「ドキュメント」として書き出すことができます。
主な特徴
Markdown出力
GitHub、Qiita、Notionなどでそのまま利用できる形式で出力されます。メタデータの抽出
Description、Parameters、Outputs などの情報を表形式で整理してくれます。リソースの可視化
テンプレートに含まれるリソース一覧を自動でリストアップ。
なぜ使うのか？（導入のメリット）
コードとドキュメントの乖離を防ぐ
自動生成により、常に最新のテンプレートに基づいたドキュメントを維持できます。レビューの効率化
Parameters や Outputs が一覧化され、インフラ全体像を素早く把握できます。チーム共有のコスト削減
エンジニア以外の担当者にも説明しやすいMarkdown形式で共有できます。
事前準備
1. 既存のIaCテンプレートを取得
例：test-ecs-traffic-change-lambda.yml
参考：https://github.com/tmatusoka-apc/Public/blob/main/blog/cfn-docs/test-ecs-traffic-change-lambda.yml
2. cfn-docgen のインストール
参考：https://pypi.org/project/cfn-docgen/
3. CloudShellの場合：Pythonを3.10以上にアップデート
※cfn-docgen の仕様のため
参考：https://qiita.com/minorun365/items/baa5038b5bfa4e35f6ad
実施手順
0. 事前準備を完了させる
・パッケージダウンロード ・テンプレートファイルを指定ディレクトリに配置
1. コマンドを実行
cfn-docgen docgen \
--format markdown \
--source <IaCテンプレート> \
--dest <出力先ディレクトリ>
2. 出力結果をダウンロードして確認する
触ってみて感じたこと・わかったこと
- 生成AIが使えない環境でも、詳細設計に落とし込む際に便利
- AWSコンソール（AWS UI）からコピペするより圧倒的に楽にドキュメント化できる
感想（個人の見解です）
カスタムフォーマットがもっと気軽に使えると嬉しい
→ カスタム可能な参考サイトはあるが、指定フォーマットに落とし込むには工夫が必要
https://github.com/horietakehiro/cfn-docgen/blob/master/docs/custom-specification.json一部フォーマットとリソースが異なる場合がある
※今回の場合は Lambda などで差異を確認
ほかの方法も調べてみる
調査を進めると、AWS公式の Bedrock などでも似たようなことが実現できそうなサービスがあることが分かりました。
用途に応じてツールを使い分けるのも良さそうです。
