Terraform outputs を Markdown 化して docs に自動生成する（パラメータシート代替） #16
Description
背景 / 目的
Terraform で IaC を運用しているが、現状「どのリソースがどんな値でデプロイされているか」を人間が俯瞰しづらい。
Excel のパラメータシート相当として、Terraform の outputs を標準化し、人間が読める Markdown を自動生成してリポジトリに残す仕組みを作る。
ゴール
• Terraform の output から JSON を取得し、CIで Markdown に整形する
• 生成物を docs/infra/.md（例）として保存・更新する
• PR で outputs の差分がレビューできる状態にする
スコープ
• 対象: Terraform の outputs（利用者が知りたい値に限定）
• CI: GitHub Actions を想定
• 出力形式: Markdown（必要なら後でHTMLも検討）
非スコープ
• terraform show -json による plan/state 差分のドキュメント化（別Issue）
• SSM Parameter Store への同期（別Issue）
⸻
仕様案
出力する情報（例）
• エンドポイント: CloudFront domain, API invoke URL, ALB DNS など
• 認証: Cognito UserPool ID / Client ID など
• データ: DynamoDB table name など
• 環境情報: region, env 名、workspace など
※「ARNを全部載せる」より、運用で必要な URL / ID / Name を優先する。
出力先
• docs/infra/outputs-.md
• 例: docs/infra/outputs-dev.md, docs/infra/outputs-prod.md
⸻
実装タスク
-
outputs 設計・標準化
• output を「人間が知りたい値」に整理（URL/ID/Name中心）
• outputs をカテゴリ別に grouping（例: endpoints, ids, names など） -
Markdown整形スクリプト追加
• scripts/render_outputs_md.sh（または scripts/render_outputs_md.py）を追加
• 入力: terraform output -json
• 出力: docs/infra/outputs-.md
• 文字列・配列・map/object をそれなりに読みやすく整形 -
GitHub Actions 追加
• 対象ブランチ（例: main）へのマージ時に実行
• terraform init → terraform apply（または、既存apply後工程に組み込み）
• terraform output -json > artifacts/outputs.json
• スクリプトで Markdown 生成
• 生成Markdownをコミットして push（もしくは artifact として保存）
※運用ポリシーにより「コミット方式」か「artifact方式」か選択する。
（まずは差分レビューしやすい コミット方式を第一候補）
- ドキュメント
• docs/infra/README.md に運用手順（更新タイミング・見方）を記載
⸻
受け入れ条件（DoD）
• terraform output -json から自動生成された docs/infra/outputs-.md が存在する
• outputs の変更がPR差分として確認できる（またはCI artifactとして閲覧できる）
• 新規メンバーが docs/infra/outputs-.md を見て主要な接続先（URL/ID）を把握できる
⸻
補足 / リスク
• 秘密情報を outputs に出さない（token/secret/password は厳禁）
• outputs の更新タイミング（apply後）と、環境（dev/prod）の切り分けに注意
• コミット方式の場合、CIのpush権限（BOTトークン）を整備する