こんにちは、とりです。
皆さんは Terraform リポジトリを管理する際、CIを組んでいるでしょうか?
プルリク公開時に Terraform Plan を自動実行して、結果をGithub上で確認できると、変更箇所が伝わりやすくなりハッピーかと思います。
tfcmt はそんなTerraformのCIを組みたいときに活躍するツールで、terraform plan の結果を素敵な感じに整形して、プルリクにコメントしてくれます
ただ、Terragrunt のような複数の Statefile を管理するリポジトリの場合、プルリク上に大量にコメントが流れてしまい、かえって見づらくなることもあるかなと思います。
今回触っていた IaC リポジトリでも、6環境×モジュールが6~7個あったため、最大40個強のPlan結果がプルリクコメントに並んでしまうことになり、さすがにこれを運用すると辛そうだな…という印象でした。
↓ は Bot が PR に大量にコメントを流している様子です
そこで、Github Workflow の Summary に結果を見やすくまとめることで、上記の課題を解決しつつ、快適に terraform の CI を運用する方法を紹介したいと思います。
Terragrunt でなく生の Terraform を使っていても、Module 等で State の分割管理を行っている場合、同様の課題感を持っていたりすると思うので、そういった方の参考にもなれば幸いです。
ついでに Github Enterprise 環境で tfcmt を構築している記事もあまり見かけなかったので、その解説もできたらと思っています。
結論
いろいろ試した結果、こんな形で落ち着きました。
環境ごとに Github Actions のワークフローを作成し、サマリー部分にモジュールごと実行した Plan 結果を見やすくまとめています。
逆にプルリクのラベル付けやコメントを書き込む機能などは、明示的に無効化を行いました。
実装
全体のディレクトリ構成
Terraform リポジトリのディレクトリ構成としてはこんな感じになっています
.
├── .github
│ ├── workflows
│ │ ├── develop_terraform_plan.yml
│ │ ├── staging_terraform_plan.yml
│ │ └── ... (other files)
│ └── tfcmt
│ ├── tfcmt.yml
│ └── tfwrapper.sh
├── environments
│ ├── develop
│ │ └── ap-northeast-1
│ │ └── ... (modules)
│ └── ... (other environments)
├── modules
│ ├── ecs
│ │ ├── main.tf
│ │ ├── outputs.tf
│ │ ├── variables.tf
│ │ └── ... (other files)
│ └── ... (other modules)
└── terragrunt.hcl
tfcmt.yml の設定
tfcmt.yml という名前で config ファイルを書いておき、tfcmt コマンド実行時にオプションに指定してあげることで、plan 結果を整形するフォーマットをカスタマイズできます。
かなりカスタマイズしやすく、個人的に感動したポイントでした。
参考: https://suzuki-shunsuke.github.io/tfcmt/config#default-configuration
今回設定した tfcmt.yml の内容になります
embedded_var_names: []
terraform:
plan:
# github enterprise の時のみ設定が必要
# 参考: https://suzuki-shunsuke.github.io/tfcmt/github-enterprise
ghe_base_url: https://XXX.github.com
ghe_graphql_endpoint: https://XXX.github.com/api/graphql
# terragrunt だと statefile 毎ラベルが上書きされて逆に管理し辛かったので無効化
disable_label: true
template: |
<details><summary><strong> :package: Target Module: {{.Vars.target}} </strong></summary>
{{template "result" .}}
{{template "updated_resources" .}}
{{template "changed_result" .}}
{{template "change_outside_terraform" .}}
{{template "warning" .}}
{{template "error_messages" .}}
</details>
ポイントとしては以下になります
- Github Enterprise の場合は plan 実行時の 環境変数に
ghe_base_url
とghe_graphql_endpoint
を足してあげる必要があります。 - tfcmt は自動で plan 結果を要約するようなラベル付けを行ってくれるのですが、複数の Statefile を管理するリポジトリの場合は、逆に見辛さが勝ってしまったので無効化しています。
- template: に続くブロックで plan 結果をどんな感じで整形するか指定できるので、お好みでいじってみても良いかと思います。
tfwrapper.sh の設定
Terragrunt の場合、tfcmt が terragrunt run-all plan
コマンドをそのまま叩けないので wrapper のスクリプトをかませてあげる必要があります。
Terraform をそのまま使っている場合はこの作業は不要かなと思います。
#!/bin/bash
set -euo pipefail
# コマンドの種類を取得(例: apply, plan, fmt...)
type=$(echo "$@" | awk '{print $1}')
# カレントディレクトリを整形して、target の module 名を取得
base_dir=$(git rev-parse --show-toplevel)
target=${PWD#"$base_dir"/}
target=$(echo "$target" | sed 's|/\.terragrunt-cache/.*||')
if [ "$type" == "plan" ]; then
tfcmt --config "$GITHUB_WORKSPACE/.github/tfcmt/tfcmt.yml" \
--output "/tmp/tgplan.md" \
-var "target:${target}" \
plan -patch -- terraform "$@"
fi
ここが terragrunt run-all plan コマンドを実行した時の実体のスクリプトになるのですが、その際に tfcmt の処理を噛ませてあげる流れとなっています
以下オプションの説明になります
- –config オプション: plan 結果の整形フォーマットなどを config ファイルに書くことができます。上のステップで作成した tfcmt.yml ファイルを config として指定します
- –output オプション: tfcmt のメインの使い方は、プルリクのコメントに plan 結果を出力することだと思いますが、今回はそれを無効化しローカルにファイルに吐き出しています
- -var オプション: tfcmt に変数を渡すことができます。今回は terraform のモジュール名を渡して、tfcmt が Plan 結果を整形する際に、モジュール名も含めて出力できるようにしています
細かい仕様は 公式 doc を参照ください。
参考: https://suzuki-shunsuke.github.io/tfcmt/terragrunt-run-all
Github Actions のワークフロー
name: Execute terragrunt plan
on:
pull_request:
branches:
- 'main'
paths:
- 'environments/develop/**'
- 'modules/**'
workflow_dispatch:
env:
Enviromnet: develop
IAM_ROLE_ARN: XXX
jobs:
plan-common:
runs-on: XXX
steps:
- uses: actions/checkout@v3
# plan 用の権限を assume する
- name: assume ECS Role
uses: aws-actions/configure-aws-credentials@v4
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ap-northeast-1
# tfcmt のインストール
- name: setup tfcmt
env:
TFCMT_VERSION: v4.13.0
run: |
curl -L "https://github.com/suzuki-shunsuke/tfcmt/releases/download/${TFCMT_VERSION}/tfcmt_linux_amd64.tar.gz" -o /tmp/tfcmt.tar.gz
tar xzf /tmp/tfcmt.tar.gz -C /tmp
mv /tmp/tfcmt /usr/local/bin
tfcmt --version
# terragrunt plan の実行
- name: Excute terragrunt plan
shell: bash
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
cd ./environments/${{ env.Enviromnet }}
terragrunt run-all init
chmod a+x $GITHUB_WORKSPACE/.github/tfcmt/tfwrapper.sh
terragrunt run-all plan -no-color -input=false --terragrunt-tfpath $GITHUB_WORKSPACE/.github/tfcmt/tfwrapper.sh
# actions の workflow summary に plan 結果の summary を通知する
- name: Create Job Summary
if: always()
uses: actions/github-script@v6
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
script: |
const fs = require('fs');
const filePath = '/tmp/tgplan.md';
const output = fs.readFileSync(filePath, 'utf8');
await core.summary
.addHeading('Terragrunt plan report')
.addRaw(output)
.write();
まず terragrunt plan を実行するための IAM 権限の Assume Role と、tfcmt をローカルにインストール処理を実行後、メインとなる terragrunt run-all plan を実行しています。
ここで補足した通り、tfcmt が直接 terragrunt run-all plan を実行することができないので、--terragrunt-tfpath
オプションで wrapper スクリプトを呼び出し、そのスクリプト内で tfcmt を実行させています。
その後、actions/github-script@v6
を使い、tfcmt が吐き出した md ファイルを Github の Summary 部分に書き込む処理を入れています。
結果、こんな感じで Summary に環境ごとの Plan 結果をまとめることができました!
改善ポイント
使い勝手自体の改善は満足したので、このまま他のいろんなIaCリポジトリに横展開していきたいと考えています。
横展開する際、毎回 tfcmt の Config やらを設定するのは面倒なので、共通部品化して Actions モジュールを他の IaC リポジトリに配布できるといいなと考えています。機会があればチャレンジしてみようと思います。
tfcmt のおかげで Terraform の CI 体験が大分改善しそうで楽しみです!
コメント