本エントリは「エーピーコミュニケーションズ Advent Calendar 2024」の2日目のエントリです。 TerraformのコードのREADME作成時に何かいいのが無いか調べてみたらterraform-docsというプロダクトを見つけたので、使い方について簡単にまとめました。

始め方

インストールして使うか、または、コンテナ版も公開されてるのでDockerあるいはPodmanのrunでも実行できます。
本エントリではインストールはせずにpodman runで実行する例について紹介します。

インストール

前述の通りこのエントリでは触れないけど、READMEのInstallationにbrew(mac)、scoop/choco(win)、あとgo installとcurlでバイナリインストールが載ってるので参照してください。

コンテナ版

インストール不要で気軽に利用できるので今回はこちらを採用。
READMEはUsing dockerに使い方が載っています。
環境(Fedora40)の都合で本エントリではpodmanを使用しました。

使い方

.tfファイルを置いているディレクトリで以下コマンドを実行します。
なお、本エントリ執筆時点で最新安定板が0.19.0なので、そのバージョンを指定しています。
※ 指定可能なタグはquay.ioでタグ一覧を参照

podman run --rm -v "$(pwd):/tmp:Z" quay.io/terraform-docs/terraform-docs:0.19.0 markdown /tmp --output-file README.md

インストール済みコマンドとの違いは、コンテナ起動するための記載で主に podman run --rm -v "$(pwd):/tmp:Z" の部分

--rm: 実行後にコンテナ削除
-v "$(pwd):/tmp:Z": 実行時のカレントディレクトリをコンテナ内/tmpにマウント (:Zはpodman用のオプションでSELinux対応)

そしてterraform-docsコマンドのオプションとして、対象ディレクトリ/tmpの指定を追加している。
これは実行元ホストの.tfファイルをコンテナ内/tmpにマウントし、terraform-docs実行時に/tmpにあるファイルを対象にドキュメンテーションを行う、という構成。
(なのでディレクトリは/aでも別にどこでも良い。ドキュメントの実行例は/terraform-docsとなっていますが長くてタイプが面倒なため短いパスにしてるだけ)

実行結果

カレントディレクトリにREADME.mdが生成されます。
お題は以前作ったAWSにVPCからEC2までざっくり作成するコードをディレクトリ構成をベストプラクティスに寄せた修正したもので、出力されたREADMEのGitHub表示は以下の通りで、使用リソースやインプットなどがドキュメンテーションされます。

また、README.mdファイルが既に存在する場合は、の行からの行の間に挿入する動作になります。マークがない場合はファイル末尾に追記されます。なので、任意のREADMEの内容を記述しつつ、tfコードの内容をドキュメンテーションすることもできる。

オプション

書式

前述は比較的使い勝手の良いmarkdownを指定してますが、他にもjsonやyaml、xmlなどいくつか用意されていて、--helpで確認可能。

markdownの書式もtableとdocumentがあり、tableは表形式、documentはリスト形式で出力される。(デフォルトtable)
説明はmarkdown --helpで確認可能。

再帰実行(モジュール)

デフォルトではカレントのtfファイルのみがドキュメンテーション対象。
モジュールなどのサブディレクトリがある場合は--recursiveをつければ処理対象となる。その際はmodulesディレクトリが対象。modules以外のディレクトリ名の場合は--recursive-pathでディレクトリ名を指定する。

設定ファイル指定

各パラメタはYAMLの設定ファイルで指定もできる。 .terraform-docs.ymlファイルをカレントディレクトリ(他にも$HOME/.tfdocs.dなどいくつか置ける。ドキュメント参照)

例えばmarkdown document形式なら以下の通り。

formatter: markdown document
recursive:
  enabled: true
output:
  file: README.md

このファイルがあればディレクトリだけ指定して実行する。

podman run --rm -v "$(pwd):/tmp:Z" quay.io/terraform-docs/terraform-docs:0.19.0 /tmp

https://github.com/terraform-docs/terraform-docs?tab=readme-ov-file#configuration

GitHub Actions

GitHub Actionsを使ったCIでドキュメンテーションするアクションも用意されています。

name: Generate terraform docs
on:
  - pull_request

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: Render terraform docs and push changes back to PR
      uses: terraform-docs/gh-actions@main
      with:
        working-dir: .
        output-file: README.md
        recursive: true
        git-push: true

この定義でプルリクエスト作成時に起動します。

個別のパラメタでなくCLIと同様にterraform-docs.ymlファイルを使ったパラメタ定義を指定する場合はconfig-fileにファイル名を指定すれば反映されるます。

name: Generate terraform docs
on:
  - pull_request

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
      with:
        ref: ${{ github.event.pull_request.head.ref }}

    - name: Render terraform docs and push changes back to PR
      uses: terraform-docs/gh-actions@main
      with:
        config-file: .terraform-docs.yml
        git-push: true

実行例と出力例はこちら

github.com

その他

ドキュメントにはGitのpre-commitの設定も掲載されているので、ローカルで完結させることもできるのでご参考まで。

AnsibleってplaybookのYAMLファイルからドキュメンテーションするツールってないのかな…欲しい。(コレクションをドキュメンテーションするツールはあるけど)

zaki work log

作業ログやら生活ログやらなんやら

[Terraform] HashiCorp Configuration Language(HCL)コードのドキュメンテーションとGitHub Actionsで自動化 (terraform-docs)

始め方