使用 tfplugindocs 命令生成 Terraform Provider 的文档

2 年 ago
清, 扬
1 minute

这篇文章是2023年Terraform圣诞日历的第五天文章。

我打算总结一下关于如何编写文档的事项，这是为了在创建 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 的架构，它们会从源代码自动生成文档。仅仅写好每个架构的描述，看起来 Provider 应该会得到基本的维护。

为 tfplugindocs 准备的文件

有些文件无法仅通过源代码自动生成。
我个人希望在使用Terraform提供程序时拥有以下两个功能。

例子运用

如果将.tf文件放在下面的位置，可以在文档顶部输入Provider、Resource和Data Source的用法。

由于仅通过架构的说明很难让使用者明白应该提供哪些内容，因此如果能提供使用示例，将非常有帮助。
个人觉得提供了示例用法的提供者会给人一种经过良好维护、易于使用的感觉。

根据要求，将例子写入常规的.tf文件中，并放置在指定路径上。

    • Provider examples/provider/provider.tf

Data Source examples/data-sources//data-source.tf

Resource examples/resources//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上显示如下。

image.png

进口

如果将 import.sh 放置在以下位置，则可以在文档底部编写 terraform import 示例命令。
导入操作常常很难指定 terraform [global options] import [options] ADDR ID 命令中的 ID 部分，如果没有示例使用说明，开发者很难知道应该输入什么内容，所以希望开发者务必写入提供者源代码以便开发者参考。

将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
image.png

摘要

    • Terraform Providerのドキュメントは tfplugindocs で自動生成できる

tfplugindocs 用に examples/ ディレクトリ以下に使用例を置けば利用者にやさしいドキュメントが生成できる

bannerAds