このエントリでは、
AWS CloudFormationのテンプレートからパラメータシートを生成して、
実装とパラメータ設計の乖離を防ぐように運用する対応を検討します。

テンプレートからパラメータ生成は次のツールがありますが、
フォーマット等をカスタマイズしたいニーズもあると思うので、
このエントリでは自前で実装することにします。

cfn-docgen - AWS CloudFormationテンプレートからドキュメントを自動生成するツールを公開しました | Qiita
https://qiita.com/horietakehiro/items/359ae6e9cb40fef50604

実装と利用方法

Resourcesの部分だけ出力するものを実装してみました。
実装としては、次のgen_cfn_docs.pyとspec_md.jinjaの通りです。
出力形式をカスタマイズしたい場合は、spec_md.jinjaを変更します。

gen_cfn_docs.py

import sys
import yaml
from jinja2 import Environment
from awscli.customizations.cloudformation.yamlhelper import yaml_parse

def generate_doc(input_yaml, template_jinja):
    with open(input_yaml) as fp:
        data = yaml_parse(fp.read())
    with open(template_jinja) as fp:
        tpl_str = fp.read()
    template = Environment().from_string(source=tpl_str)
    print(template.render(resources=data["Resources"]))

if __name__ == "__main__":
    if len(sys.argv) <= 2:
        print("usage: python gen_cfn_docs.py [input(yaml)] [template(jinja)]")
        exit(1)
    input = sys.argv[1]
    template = sys.argv[2]
    generate_doc(input, template)

spec_md.jinja

{% for re, rv in resources.items() %}

## {{ re }} ({{ rv["Type"] }})
{% for pe, pv in rv["Properties"].items() %}
- {{ pe }}{% if pv.__class__.__name__ != 'list' %}: {{ pv }}{% endif %}
{% if pv.__class__.__name__ == 'list' %}{% for sr in rv["Properties"][pe] %}
  - {% for spe, spv in sr.items() %}
      {{ spe }}: {{ spv }}
    {% endfor %}
{% endfor %}{% endif %}
{% endfor %}
{% endfor %}

PyYaml, awscli, jinja2に依存するのでインスト－ルします。

pip install PyYAML
pip install awscli
pip install Jinja2

実行方法は次の通りです。
target.yamlの部分に、CloudFormationのテンプレートファイルを指定します。

python gen_cfn_docs.py target.yaml spec_md.jinja > spec.md

未実装な点など

最低限という感じで作ってみたので、まだまだ実装すべき点はあると思います。
例えば、以下のような点です。

  • Resourcesのみ実装しているので、Parameterなどは必要に応じて変更が必要
  • Fn::Sub, Ref等の出力は、Jinja2のフィルタなども実装した方が良い

このエントリでは、この程度の生成は簡単にできると言うことが伝われば十分かなと。。

以下のエントリを参考にさせて頂きました、ありがとうございます。

【小ネタ】PythonでCloudFormationテンプレートをパースする時に組み込み関数の短縮系構文に邪魔されない方法 | DevelopersIO
https://dev.classmethod.jp/articles/dynamolocal-from-cfn/

以上。