Fastly Terraform 提供程序

网站: https://www.terraform.io
文档: https://registry.terraform.io/providers/fastly/fastly/latest/docs
问题: https://github.com/fastly/terraform-provider-fastly/blob/main/ISSUES.md
邮件列表: http://groups.google.com/group/terraform-tool

需求

Terraform 0.12.x or higher
Go 1.25 (to build the provider plugin)

注意：支持 Terraform 0.11.x 及更早版本的 Fastly provider 最后一个版本是 v0.26.0

版本管理与发布计划

本模块的维护者致力于维护语义化版本 (SemVer)。这意味着破坏性变更（移除功能，或对现有功能的不兼容更改）将在第一个版本组件（major）递增的版本中发布。功能新增将递增第二个版本组件（minor），而不影响兼容性的错误修复将递增第三个版本组件（patch）。

每月第三个星期三，将发布一个版本，包含所有已准备好发布的破坏性变更、功能变更和错误修复。如果该星期三恰逢美国节假日，发布将推迟到下一个可用的工作日。

如果在主要版本发布之间，关键或紧急的 bug 修复已准备就绪，则会根据需要发布补丁版本，以使这些修复可用。

构建 Provider

将仓库克隆到：$GOPATH/src/github.com/fastly/terraform-provider-fastly

$ mkdir -p $GOPATH/src/github.com/fastly; cd $GOPATH/src/github.com/fastly
$ git clone git@github.com:fastly/terraform-provider-fastly

进入 provider 目录并构建 provider

$ cd $GOPATH/src/github.com/fastly/terraform-provider-fastly
$ make build

开发 Provider

如果你希望参与 provider 的开发，首先需要在你的机器上安装 Go（版本 1.25+ 为必需）。

要编译 provider，请运行 make build。这将构建 provider 并将 provider 二进制文件放入本地的 bin 目录中。

$ make build
...

在新构建的二进制文件旁边，将创建一个名为 developer_overrides.tfrc 的文件。 make build 目标将返回用于设置 TF_CLI_CONFIG_FILE 环境变量的详细信息，该环境变量将启用 Terraform 使用您本地构建的 provider 二进制文件。

HashiCorp - Development Overrides for Provider developers.

NOTE: 如果您在查看对 provider 所做的代码更改的任何行为时遇到问题，那么可能是 terraform CLI 对应该使用哪个 provider 二进制文件感到困惑。请检查 ./bin/ 目录，查看是否存在具有不同 commit 哈希值的多个 provider（例如 terraform-provider-fastly_v2.2.0-5-gfdc37cee），并在运行 make build 之前先删除它们。这应该有助于 Terraform CLI 解析到正确的二进制文件。

Debugging the provider

之前使用 dev_overrides 的方法对于大多数开发用途（包括使用实际的 Terraform 代码测试您的本地更改）应该是足够的。然而，有时如果您需要附加诸如 delve 这样的调试器来解决特定问题，以调试模式运行 provider 可能会很有帮助。

Terraform 通常的工作方式是启动一个 provider 子进程，并通过本地套接字使用 GRPC 与其连接。（有关此信息的更多详情，请参阅 hashicorp/go-plugin）。为了进行调试，可以绕过此机制，在单独进程中执行 provider，然后告知 Terraform 如何与其通信。这样做的优点是，provider 可以像调试器附加到任何常规可执行文件一样，在附加调试器的情况下启动。

根据所使用的调试器不同，有几种实现方式，但这里我们将使用 delve，因为对于其他调试器，过程应该非常相似。需要配置的两件事是：provider 必须在不进行优化的情况下编译，并且可执行文件必须使用 --debug 标志运行。在不进行优化的情况下编译可确保调试器能够访问二进制文件中所需的所有符号，而 --debug 标志则告知 Terraform plugin SDK 预期在独立进程中运行，并在启动后显示连接说明。

使用 delve 可以通过一条命令完成：

$ dlv debug . -- --debug
Type 'help' for list of commands.
(dlv) continue
{"@level":"debug","@message":"plugin address","@timestamp":"2021-03-26T12:10:13.320981Z","address":"/var/folders/qm/swg2hf4h5t8sdht8yhds4dg6m0000gn/T/plugin865249851","network":"unix"}
Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:

        TF_REATTACH_PROVIDERS='{"fastly/fastly":{"Protocol":"grpc","Pid":54132,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/qm/swg2hf4h5t8sdht8yhds4dg6m0000gn/T/plugin865249851"}}}'

这也可以通过两个独立的步骤来完成。-gcflags 禁用了优化（-N）和内联（-l）。

$ go build -gcflags="all=-N -l" -o terraform-provider-fastly_debug
$ dlv exec terraform-provider-fastly_debug -- --debug

按照消息中的说明，切换到另一个 shell 并导出 TF_REATTACH_PROVIDERS 环境变量。然后像往常一样使用 Terraform，它将自动使用调试器中的 provider。

$ export TF_REATTACH_PROVIDERS='{"fastly/fastly":{"Protocol":"grpc","Pid":54132,"Test":true,"Addr":{"Network":"unix","String":"/var/folders/qm/swg2hf4h5t8sdht8yhds4dg6m0000gn/T/plugin865249851"}}}'
$ terraform plan

之后，您将能够设置断点，并使用调试器按预期跟踪提供程序的执行。

设置调试模式的实现假定使用的是 Terraform 0.13.x。如果您使用的是 Terraform 0.12.x，则需要手动修改分配给 TF_REATTACH_PROVIDERS 的值，使键 "fastly/fastly" 变为 "registry.terraform.io/-/fastly"。有关更多详细信息，请参阅 HashiCorp 的 "Support for Debuggable Provider Binaries"。

摘要

(first shell)  dlv debug . --headless -- --debug
(second shell) dlv connect <output from first shell>
               continue
               <Ctrl-c>
               break fastly/block_fastly_service_package.go:123
(third shell)  export TF_REATTACH_PROVIDERS="..."
               terraform apply
(second shell) continue (do your step debugging)
               <Ctrl-c> (then run another terraform command from third shell)

测试

为了测试该 provider，您只需运行 make test。

$ make test

为了运行完整的 Acceptance 测试套件，请运行 make testacc。

注意： Acceptance 测试会创建真实资源，并且运行通常会产生费用。您应预期完整的 acceptance 测试套件需要数小时才能运行完毕。

$ make testacc

要运行单个验收测试，可以将 '-run' 标志与正则表达式一起使用。以下示例使用匹配名为 'TestAccFastlyServiceVCL_basic' 的单个测试的正则表达式。

$ make testacc TESTARGS='-run=TestAccFastlyServiceVCL_basic'

以下示例使用正则表达式来执行一组基本验收测试。

$ make testacc TESTARGS='-run=TestAccFastlyServiceVCL.*_basic'

为了在测试中运行额外的调试上下文，请在 make 命令前加上 TF_LOG（详见 terraform 文档]）。

$ TF_LOG=trace make testacc

默认情况下，测试以 4 的并行度运行。如果某些测试因网络相关问题而失败，可以降低此值；如果可能，也可以增加此值，以减少测试的运行时间。在 make 命令前加上 TEST_PARALLELISM，如下例所示，以进行此配置。

$ TEST_PARALLELISM=8 make testacc

根据所使用的 Fastly 账户，某些功能可能未启用（例如 Platform TLS）。这可能导致在运行完整测试套件时，某些测试失败，并可能伴随 403 Unauthorised 错误。请查阅 Fastly API 文档以确认失败的测试是否使用了处于有限可用性（Limited Availability）状态或仅对特定客户可用的功能。如果情况如此，请使用上述描述的 TESTARGS 正则表达式，或临时在应排除的任何测试顶部添加 t.SkipNow()。

构建文档

请参阅文档指南。

贡献

参见 CONTRIBUTING.md