この記事は terraform Advent Calendar 2023 の5日目の記事です
Terraform Provider を自作するときにドキュメントの書き方について調べたのでまとめようと思います。
Terraform Providerのドキュメントは自動生成できる
Terraform Provider のドキュメントの書き方は公式ドキュメント https://developer.hashicorp.com/terraform/registry/providers/docs に記載があります。
この仕様に沿ってドキュメントを書いて適切なパスに配置すれば Terraform Registry 上できれいに表示することができます。
しかし、公式ドキュメント内にもあるように
//go:generate go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
を Provider のコードに書いておけば go generate を実行したときに Provider のソースコードや examples/ 以下のファイルからいい感じにドキュメントを自動生成してくれます。
実はこの tfplugindocs というツールを使えば、公式ドキュメントに書かれているドキュメントの仕様はほとんど意識する必要なくそれっぽいドキュメントが書けてしまいます。
tfplugindocs が自動生成してくれるもの
Provider, Resource, Data Source の Schema は特に意識しなくてもソースコードから自動でドキュメントを生成してくれます。
各 Schema の Description をちゃんと書いておだけでも、そこそこメンテされていそうな Provider に見えます。
tfplugindocs のために用意すべきファイル
ソースコードだけでは自動生成できないドキュメントもあります。
個人的に Terraform Provider を使うときに用意されていてほしい機能2つを紹介します。
Example Usage
examples/ 以下に .tf ファイルを置くとドキュメントの上部に Provider, Resource, Data Source の使い方を入れることができます。
Schema の説明だけでは利用者から見ると何を入れればいいのか分からないことが多いので、使用例があるととても助かります。
個人的に Example Usage が用意されている Provider はちゃんとメンテされているように感じて利用しやすくなる気がします。
普段 .tf ファイルを書くように例を書いて、決められたパスに配置します。
- Provider
examples/provider/provider.tf - Data Source
examples/data-sources/<data source name>/data-source.tf - Resource
examples/resources/<resource name>/resource.tf
複数のコードブロックを書くことはできないようなので、複数のリソースを書く場合は空行を使って区切るのがよいと思います。
resource "travis_env_var" "public_value" {
repository_slug = "bgpat/test"
name = "PUBLIC_VALUE"
public_value = "public"
}
resource "travis_env_var" "secret_values" {
for_each = toset(["foo", "bar", "buzz"])
repository_id = 2562785
name = "SECRET_VALUE_${upper(each.key)}"
value = each.value
}
Terraform Registry 上では以下のように表示されます。
Import
examples/ 以下に import.sh を置くとドキュメント下部に terraform import の例のコマンドを書くことができます。
Import は terraform [global options] import [options] ADDR ID の ID に当たる部分の指定が難しいことが多く、使用例が書かれていないと Provider のソースコードを読まないと何を入れていいか分からないので開発者の方にはぜひ書いておいてほしいです。
import.sh の内容はそのままコードブロックとしてドキュメントに挿入されるので、 $ 等は付けずに実行するコマンドをそのまま書きます。
terraform import travis_env_var.public_value bgpat/test/PUBLIC_VALUE
複数の書き方がある場合は # でコメントを書いて空行で分割するのがよいと思います。
# ${repository_id}/${name}
terraform import travis_env_var.public_value bgpat/test/PUBLIC_VALUE
# ${repository_slug}/${name}
terraform import 'travis_env_var.secret_values["foo"]' 2562785/SECRET_VALUE_FOO
Terraform Registry 上では以下のように表示されます。
まとめ
- Terraform Providerのドキュメントは
tfplugindocsで自動生成できる -
tfplugindocs用にexamples/ディレクトリ以下に使用例を置けば利用者にやさしいドキュメントが生成できる