2022 年 11 月，我们宣布 Cloudflare API 过渡到 OpenAPI 模式。当时，我们有一个大胆的目标，就是使 OpenAPI 模式成为我们 SDK 生态系统和参考文档的真实来源。为此，在 2024 年的 Developer Week 期间，我们宣布：我们的 SDK 库现在从这些 OpenAPI 模式自动生成。今天，我们隆重宣布，该生态系统的最新组成部分现将自动生成——Terraform 提供者和 API 参考文档。
这意味着，一旦我们的产品中添加新的功能或属性，并由团队记录到文档，您将能看到它在我们的 SDK 生态系统应当如何使用，并能立即投入使用。不再存在延误。不再遗漏 API 端点。 点击 https://developers.cloudflare.com/api-next/ 查看新文档站点，您可以通过安装 5.0.0-alpha1 来尝试 Terraform 提供者的预览发布候选版 。
为什么使用 Terraform？
对于不熟悉 Terraform 的人来说，它是一个用于以代码形式管理基础设施的工具，就像管理应用代码一样。我们的许多客户(无论大小)都依赖 Terraform 以技术无关的方式协调他们的基础设施。从本质上讲，它是一个具备生命周期管理的 HTTP 客户端，这意味着它利用我们公开文档化的 API，以理解如何在资源的整个生命周期内进行创建、读取、更新和删除操作。
保持 Terraform 更新 —— 老方式
在过去， Cloudflare 一直手动维护 Terraform 提供者，但由于该提供者的内部结构需要自己独特的操作方式，维护和支持的责任落在了少数人的肩上。服务团队总是难以跟上更改的数量，因为在提供者中进行一个更改都需要大量的认知开销。一个团队要更改提供者，至少需要 3 个拉取请求（如果您要添加对 cf-terraforming 的支持，则需要 4 个请求）。
即使在 4 个拉取请求完成后，也不能保证覆盖所有可用属性，这意味着可能会忘记小而重要的细节而没有暴露给客户，导致在尝试配置资源时受挫。 为了解决这个问题，我们的 Terraform 提供者需要依赖于我们的 SDK 生态系统的其他部分已经从中受益的相同 OpenAPI 模式。
自动更新 Terraform
Terraform 与我们的 SDK 的不同之处在于，它管理资源的生命周期。随之而来的是与已知值以及管理请求和响应有效负载中的差异相关的一系列新问题。 我们来比较一下创建新 DNS 记录并将其取回的两种不同方法。
使用我们的 Go SDK：
// Create the new record
record, _ := client.DNS.Records.New(context.TODO(), dns.RecordNewParams{
ZoneID: cloudflare.F("023e105f4ecef8ad9ca31a8372d0c353"),
Record: dns.RecordParam{
Name: cloudflare.String("@"),
Type: cloudflare.String("CNAME"),
Content: cloudflare.String("example.com"),
},
})
// Wasteful fetch, but shows the point
client.DNS.Records.Get(
context.Background(),
record.ID,
dns.RecordGetParams{
ZoneID: cloudflare.String("023e105f4ecef8ad9ca31a8372d0c353"),
},
)
使用 Terraform 时：
resource "cloudflare_dns_record" "example" {
zone_id = "023e105f4ecef8ad9ca31a8372d0c353"
name = "@"
content = "example.com"
type = "CNAME"
}表面上看，Terraform 方法更简单，您是对的。我们已为您处理了了解如何创建新资源和维护更改的复杂性。但问题在于，为了让 Terraform 提供这种抽象和数据保证，在应用时必须知道所有值。这意味着，即使您没有使用代理值 value，Terraform 也需要知道这个值需要是什么，以便将其保存在状态文件中，并在日后管理该属性。以下错误是 Terraform 操作人员在应用值未知时，通常会从提供者那里看到的错误。
Error: Provider produced inconsistent result after apply
When applying changes to example_thing.foo, provider "provider[\"registry.terraform.io/example/example\"]"
produced an unexpected new value: .foo: was null, but now cty.StringVal("").而在使用 SDK 时，如果您不需要某个字段，则可以忽略它，永远不需要担心维护已知值。
为我们的 OpenAPI 模式解决这个问题不是易事。自从引入 Terraform 生成支持以来，我们模式的质量已经提高了一个数量级。现在，我们显式地调用所有存在的默认值，基于请求有效负载的变量响应属性，以及任何服务器端计算的属性。这一切都意味着为与我们 API 交互的任何人提供更好的体验。
从 terraform-plugin-sdk 迁移到 terraform-plugin-framework
要构建 Terraform 提供者并向操作人员公开资源或数据源，您需要两个主要的东西：一个提供者服务器和一个提供者。
提供者服务器负责暴露一个 gRPC 服务器，Terraform 核心(通过 CLI)使用该服务器在管理资源或从操作人员提供的配置中读取数据源时使用该服务器进行通信。
提供者负责包装资源和数据源，与远程服务通信，并管理状态文件。为此，您可以依赖 terraform-plugin-sdk （通常称为 SDKv2）或 terraform-plugin-framework ，其中包括 Terraform 提供的所有接口和方法，以便正确管理其内部机制。使用哪一个插件取决于提供者的年龄。 SDKv2 存在的时间更长，大多数 Terraform 提供者都使用它，但由于时间长和复杂性，它有许多核心未解决的问题必须保留，以便为依赖它的客户提供向后兼容性。terraform-plugin-framework 是新版本，虽然缺乏 SDKv2 的功能广度，但提供了一种更像 Go 的方法来构建提供者，并解决了 SDKv2 中的许多底层错误。
（有关 SDKv2 和该框架的更深入比较，您可以查看我和来自 Octopus Deploy 的 John Bristowe 之间的对话。）
Cloudflare Terraform 提供者的大部分内容都是使用 SDKv2 构建的，但在 2023 年初，我们采用了多路复用方式，在我们的提供者中同时提供两者。要理解为什么需要这样做，我们必须对 SDKv2 有所了解。 SDKv2 的组织方式并不利于一致且可靠地表示 null 或“未设置”的值。您可以使用实验性的 ResourceData.GetRawConfig 来检查配置中是否已设置值、为 null 或未知，但实际上并不支持将其写回为 null。
我们首次发现这个限制是在边缘规则引擎（规则集）开始引入新服务的时候，这些服务需要支持的 API 响应中包含未设置（或缺失）、 true 或 false 状态的布尔值，每个状态都有自己的原因和目的。虽然这不是 Cloudflare 的常规 API 设计，但它是一种合法的方式，我们应该能够处理。但是，如上所述，SDKv2 提供者不能处理。这是因为，当一个值没有出现在响应中或读入状态时，它会获得一个与 Go 兼容的零值作为默认值。表现为在写入状态为假值后无法取消设置值（反之亦然）。
要可靠地使用这些布尔值的三个状态，我们拥有的唯一解决方案是迁移到 terraform-plugin-framework，该框架具有写回未设置值的正确实现。
在我们开始在老提供者中使用 terraform-plugin-framework 添加更多功能后，开发人员体验显然得到了改善，因此我们添加了一个限制，以防止未来任何人继续使用 SDKv2 并无意中让自己陷入这个问题。
当我们决定将自动生成 Terraform 提供者时，最理想的做法是将所有资源都基于 terraform-plugin-framework，并彻底摆脱 SDKv2 中的问题。这确实使迁移复杂化了，因为内部结构改进后，主要组件也发生了变化，例如我们需要熟悉的模式和 CRUD 操作。但是，这是一项值得的投资，因为通过这样做，我们已经为提供者的基础做好了面向未来的准备，并减少了因存在缺陷的遗留内部机制而导致的妥协，以提供优秀的 Terraform 体验。
以迭代方式发现缺陷
代码生成管道常见的一个问题是，除非您有现成的工具来实现你的新产品，否则很难判断它是否有效或是否值得使用。当然，您也可以生成测试来演练新产品，但如果管道中存在错误，因为你生成的测试断言会显示这个缺陷是预期的行为。
我们已有的一个重要反馈回路就是现有的验收测试套件。对现有提供者中的所有资源进行回归和功能测试。最棒的是，由于测试套件正在创建和管理真实资源，我们只需查看 HTTP 流量，看看 API 调用是否被远程端点接受，就能很容易判断结果是否是一个有效的实现。移植测试套件只需复制所有现有的测试，并检查任何类型断言的差异（例如列表到单个嵌套列表），然后启动测试运行以确定资源是否正常工作。
虽然集中式模式管道显著提高了效率，模式修复几乎瞬间即可传播到整个生态系统，但它无法帮助我们解决最大的障碍，即揭露隐藏其他缺陷的缺陷。这非常耗时，因为修复 Terraform 中的问题时，有三个地方可能遇到错误：
在进行任何 API 调用之前，Terraform 会实施逻辑模式验证，当遇到验证错误时，它将立即停止。
如果任何 API 调用失败，它会在 CRUD 操作处停止并返回诊断信息，并立即停止。
在 CRUD 操作运行后，Terraform 会进行检查，以确保所有的值都是已知的。
这意味着，如果我们在第一步遇到缺陷，然后予以修复，不能保证或无法知道是否还有两个错误在等着我们。更不用说，如果我们在第 2 步中发现了一个错误并发布了修复，就不会在下一轮测试中的第 1 步发现一个错误。
对此没有灵丹妙药，我们的解决办法是注意模式行为中的有问题模式，并在它进入代码生成管道之前，在 OpenAPI 架构中应用 CI lint 规则。采用这种方法逐步减少第 1 步和第 2 步的错误数量，直到基本上只要处理第三步中的错误类型。
可重用性更高的模型和结构体转换方法
在 Terraform 提供者的 CRUD 操作中，相当常见如下样板文件：
var plan ThingModel
diags := req.Plan.Get(ctx, &plan)
resp.Diagnostics.Append(diags...)
if resp.Diagnostics.HasError() {
return
}
out, err := r.client.UpdateThingModel(ctx, client.ThingModelRequest{
AttrA: plan.AttrA.ValueString(),
AttrB: plan.AttrB.ValueString(),
AttrC: plan.AttrC.ValueString(),
})
if err != nil {
resp.Diagnostics.AddError(
"Error updating project Thing",
"Could not update Thing, unexpected error: "+err.Error(),
)
return
}
result := convertResponseToThingModel(out)
tflog.Info(ctx, "created thing", map[string]interface{}{
"attr_a": result.AttrA.ValueString(),
"attr_b": result.AttrB.ValueString(),
"attr_c": result.AttrC.ValueString(),
})
diags = resp.State.Set(ctx, result)
resp.Diagnostics.Append(diags...)
if resp.Diagnostics.HasError() {
return
}总体而言：
我们使用
req.Plan.Get()获取建议的更新（称为计划）执行使用新值的更新 API 调用
将数据从 Go 类型转换为 Terraform 模型 (
convertResponseToThingModel)调用
resp.State.Set()来设置状态
最初，这似乎没有太大问题。然而，第 3 步将 Go 类型转换为 Terraform 模型时，很快就会变得繁琐、容易出错且复杂，因为所有资源都需要这样做才能在类型和相关的 Terraform 模型之间切换。
为了避免生成比必要更复杂的代码，我们的提供者中进行的一项改进是，所有 CRUD 方法使用统一的 apijson.Marshal、 apijson.Unmarshal 和 apijson.UnmarshalComp 方法，这些方法通过基于结构体标签集中转换和处理逻辑来解决这个问题。
var data *ThingModel
resp.Diagnostics.Append(req.Plan.Get(ctx, &data)...)
if resp.Diagnostics.HasError() {
return
}
dataBytes, err := apijson.Marshal(data)
if err != nil {
resp.Diagnostics.AddError("failed to serialize http request", err.Error())
return
}
res := new(http.Response)
env := ThingResultEnvelope{*data}
_, err = r.client.Thing.Update(
// ...
)
if err != nil {
resp.Diagnostics.AddError("failed to make http request", err.Error())
return
}
bytes, _ := io.ReadAll(res.Body)
err = apijson.UnmarshalComputed(bytes, &env)
if err != nil {
resp.Diagnostics.AddError("failed to deserialize http request", err.Error())
return
}
data = &env.Result
resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)我们不需要生成数百个类型到模型转换方法的实例，而是给 Terraform 模型添加正确的标签，以一致的方式处理数据的序列化和反序列化。这只是对代码的一个小改动，但从长远来看，却使生成的代码更具可重用性和可读性。这种方法的另一个好处是，它非常适合错误修复，因为一旦您识别出特定类型字段的错误，只要在统一界面中修复该错误，就能解决其他您可能还没有发现的错误。
等等，还有更多（文档）！
为了提升我们的 OpenAPI 模式使用，我们正在加强 SDK 与新 API 文档站点的集成。它使用了我们过去两年投资并解决了一些常见使用问题的相同管道。
SDK 感知
如果您使用过我们的 API 文档站点，您就知道我们提供使用 curl 等命令行工具与 API 交互的示例。这是一个很好的起点，但如果您使用的是其中一个 SDK 库，您需要设法将其转换为您想要使用的方法或类型定义。现在我们使用相同的管道来生成 SDK 和文档，我们将通过提供您可能使用的所有库中的示例来解决这个问题，而不限于 curl 。
使用 cURL 获取所有区域的示例。
使用 Typescript 库获取所有区域的示例。
使用 Python 库获取所有区域的示例。
使用 Go 库获取所有区域的示例。.
通过这一改进，我们还可以记住语言选择，因此，如果您选择使用 Typescript 库查看文档并继续浏览，我们将一直向您显示使用 Typescript 的示例，直至更换到其他语言。
最棒的是，当我们向现有端点引入新属性或添加 SDK 语言时，这个文档站点会自动与管道保持同步。使其保持最新不再需要付出巨大的努力。
渲染更快、更高效
我们一直难以解决的一个问题是 API 端点的庞大数量以及如何表示它们。截至本文，我们有 1,330 个端点，对于每个端点，我们有一个请求有效负载，一个响应有效负载，以及多个关联的类型。在渲染这么多信息时，我们过去使用的解决方案不得不做出一些权衡，以便让部分表示能够正常工作。
API 文档站点的下一个迭代通过几种方式解决了这个问题：
它被实施为一个现代 React 应用，将交互式客户端体验与静态预渲染内容结合起来，从而实现快速初始加载和快捷导航。（是的，即使不启用 JavaScript，它也能正常工作！）。
它会随着您浏览时逐步获取底层数据。
通过解决这个基本问题，我们还解锁了对文档站点和 SDK 生态系统的其他计划改进，以提升用户体验，而不再需要像过去那样做出权衡。
权限
在文档网站中，用户最希望重新实现的功能之一就是 API 端点的最低所需权限。文档网站的早期版本中曾经提供这个功能。然而，大多数使用它的人并不知道，这些值是手动维护的，且经常不正确，导致用户提交支持工单并感到沮丧。
在 Cloudflare 的身份和访问管理系统中，“我需要什么才能访问这个端点”并不是一个简单的问题。这样做的原因是，在请求发送到控制平面的正常流程中，我们需要两个不同的系统来回答问题的一部分，然后将这些信息结合起来给出完整的答案。由于我们最初无法作为 OpenAPI 管道的一部分自动执行此操作，因此我们选择将其排除在外，而不是提供一个错误且无法验证的值。
快进到今天，我们很高兴地宣布，端点权限已经回来了！我们构建了一些新的工具，以抽象的方式回答这个问题，让我们可以将其集成到代码生成管道中，并让所有端点自动获取这些信息。与代码生成平台的其他部分非常类似，它专注于让服务团队拥有并维护高质量的模式，可供重复使用并增加价值，无需他们进行任何工作。
不再等待更新
随着这些公告发布，我们将不再需要等待更新进入 SDK 生态系统。通过这些新的改进，我们能够在团队记录新属性和端点时立即优化它们的能力。您还在犹豫什么？欢迎探索 Terraform 提供者和 API 文档站点。