terraform-docsをGithub Actions上で実行して、プルリクエスト時にモジュールのドキュメントを自動生成してみる

「terraform モジュールのドキュメントを簡単に作成したい」

terrafrom moduleの自動生成に便利な terraform-docs みなさん使っていますか？

今回は、terraform-docsをGithub Actions上で動かして、プルリクエスト時にモジュールのドキュメントを 自動生成してみます。

terraform-docsとは

terraform-docsは、 terraformモジュールからREADMEなどドキュメントを生成することができるツールです。

Introduction | terraform-docs

コマンド一つで、以下のようにドキュメントを作成してくれます。

$ terraform-docs markdown <モジュールディレクトリ>

やってみた

手動で実行するだけでも便利ですが、モジュールを更新した際に自動で実行してくれたらさらに便利そうです。

terraform-docsのドキュメントに、Github Actionsで実行する方法が載っていたのでやってみます。

GitHub Action | terraform-docs terraform-docs/gh-actions: A Github action for generating Terraform module documentation using terraform-docs and gomplate

テスト用のterraform-module

msato0731/terraform-docs-sample

├── ./.github
│   └── ./.github/workflows
│       └── ./.github/workflows/documentation.yml
├── ./README.md
├── ./backend.tfvars
├── ./backend.tfvars_sample
├── ./main.tf
├── ./modules
│   └── ./modules/ecr
│       ├── ./modules/ecr/main.tf
│       ├── ./modules/ecr/output.tf
│       └── ./modules/ecr/variables.tf
└── ./provider.tf

テスト用にECRのモジュールを作ってみました。

modules/ecr/main.tf

resource "aws_ecr_repository" "this" {
  name = var.name
  force_delete = true
  image_scanning_configuration {
    scan_on_push = var.image_scan_on_push
  }
  tags = {
    Name = var.name
  }
}

modules/ecr/output.tf

output "ecr_repository_this_repository_url" {
  value = aws_ecr_repository.this.repository_url
}

modules/ecr/variables.tf

variable "name" {
  type = string
  description = "ecr repo name"
}

variable "image_scan_on_push" {
  type = bool
  description = "ecr repo image scan on push"
  default = true
}

Github Actions ワークフローファイルの準備

Github Actionsのワークフローファイルを用意します。

.github/workflows/documentation.yml

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: ./modules/ecr/
        output-file: README.md
        output-method: inject
        git-push: "true"

実行結果の確認

terraform-docsによって生成されたドキュメントが自動でcommitされることを確認できました。

https://github.com/msato0731/terraform-docs-sample/pull/1

その他 pre-commitへの組み込み

pre-commit-terraformでも、terraform_docsのhookは使用可能です。

default_stages: [commit]
repos:
    - repo: https://github.com/antonbabenko/pre-commit-terraform
      rev: v1.75.0
      hooks:
          - id: terraform_docs

antonbabenko/pre-commit-terraform: pre-commit git hooks to take care of Terraform configurations ??

pre-commit-terraformを使用しなくても、terraform-docsのリポジトリを指定してpre-commit hookを使うことも可能です。

antonbabenko/pre-commit-terraform: pre-commit git hooks to take care of Terraform configurations ??

おわりに

terraform-docsの紹介でした。

このツールを使用することで、terarform module開発が捗りそうです。 「moduleのドキュメント書きたいけど面倒くさい」と思っている方は、ぜひ試してほしいです。

以上、AWS事業本部の佐藤(@chari7311)でした。