Terraformの課題の1つは、モジュールなどに実装を閉じ込めても、そのモジュールのvairables/outputsの型を判別するにはLSP¹が脆弱なことです。 VS CodeのLSP機能を使ってF12でコードジャンプして実装を確認するのもいいのですが、GitHubでコードを眺めている時はまだ難しいものがあります。そこで、README.mdにモジュールのvairables/outputsなどをを記載し、CIでドキュメントを自動更新されるようにしてみましょう。

どのようなドキュメントが欲しいか

例えばモジュールのREADMe.mdに以下のようなドキュメントがあると便利です。このドキュメントからは、モジュールで利用されているリソース/Inputs/Outputsが一目でわかります。

仮にモジュールが別のモジュールを参照している場合、それも記載されます。

ドキュメントのリソースをクリックするとTeraform Registryのドキュメントにジャンプできます。例えば、aws_iam_role.mainをクリックするとResource: aws_iam_role | Terraform Registryが開きます。

required_versionを記載したフォルダではRequirementsも記載されるので、どのterraform・AWS Providerバージョンが利用想定されているかもわかります。

CIでドキュメントを自動更新する

Terraformの構成を解析して、ドキュメントを起こすのに便利なのがterraform-docsです。macos/linux/Windowsに対応しているGo製のツールです。

terraform-docsのインストール

手元で動作を確認するのであれば、公式のREADMEを見てください。homebrew、scoop、curlに対応しているのでどうとでもなります。go installでも可能です。²

# macOS
$ brew install terraform-docs
# Windows
$ scoop bucket add terraform-docs https://github.com/terraform-docs/scoop-bucket
$ scoop install terraform-docs
# Linux
$ curl -Lo ./terraform-docs.tar.gz https://github.com/terraform-docs/terraform-docs/releases/download/v0.19.0/terraform-docs-v0.19.0-$(uname)-amd64.tar.gz
$ tar -xzf terraform-docs.tar.gz
$ chmod +x terraform-docs
$ mv terraform-docs /usr/local/bin/terraform-docs

GitHub Actionsで自動更新する

GitHub Actionsでterraform-docsを実行してみましょう。幸いにも公式サンプルがあるので、これをベースにパスでフィルタするようにするといいです。例えば以下のワークフローはawsフォルダ以下のtfファイルが更新されたときに実行されます。

name: Terraform Docs
on:
  pull_request:
    branches:
      - "main"
    paths:
      - ".github/workflows/terraform-docs.yaml"
      - "aws/**/*.tf"

jobs:
  docs:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.ref }}
      - name: Render terraform docs inside the README.md and push changes back to PR branch
        uses: terraform-docs/gh-actions@v1.3.0
        with:
          find-dir: aws/
          output-file: README.md
          output-method: inject
          git-push: "true"

GitHub Actionsで、モジュールのvariables変更したことに自動追随してドキュメントも更新されます。

READMEの自動更新箇所を指定する

terraform-docsは、とで囲まれた部分にドキュメントを追記します。既存のREADME.mdであっても、セクションを指定すれば思ったところに追記されるので便利です。

<!-- BEGIN_TF_DOCS -->
ここに追加される
<!-- END_TF_DOCS -->

まとめ

この仕組みをかれこれ2年以上使っていますが、どれだけ規模が大きくても素直に動いています。 Terraformコードを修正・追加したら、PRに出すだけでドキュメントも更新されるのはとても楽です。ドキュメントのメンテナンスから正しく解放されます。 READMEにAPIを記載して自分で更新するのは不毛なので、もし自力で更新していたり、まだREADMEでAPI判別可能にしていないならまずは導入としてオススメです。

2年経つので現状にあわせてもっといい方法がないかなぁ、と度々探していますがなかなかいい方法は見つかりませんね。おすすめがあればおしえてください。

LSP: Language Server Protocolの略。VS Codeなどのエディタで利用されている、言語サーバーとエディタの間で通信するプロトコルです。terraformは拡張で提供されインテリセンスやエラー検知、コードジャンプが可能になります。↩
わたしはgo installでインストールするのが好きじゃないので、curlを使っています。↩