The terraform-plugin-framework now underpins the provider's resources. Since the generator targets that framework, the provider's resource schemas and CRUD operations were moved over as part of the same effort, retiring the SDKv2 internals for good.

Moving resources to terraform-plugin-framework

The model is grounded in the same underlying requirement at a structural level, not a simple stylistic choice. A provider needs its plugin layer to coordinate with the gRPC server driven by HashiCorp’s own types — moving that work implies reacquainting the schema level and the CRUD handlers with new internals. Different piece, same effect: in exchange, the provider’s foundations are now protected against the gaps that come with the legacy implementation.

The investment has been a worthwhile one in the long run. Terraform resources that previously expressed state via SDKv2 conventions had to be re-expressed in terms of the framework, and the generation pipeline now produces models against the targets that require less special-casing.

Using an existing test suite to catch bugs

The hard-to-spot bugs were never found via the purely theoretical approach. Because the existing provider already had a mix of regression and functionality tests across the entirety of resources, those were lifted and used to verify the generation output. Porting the suite largely meant copying tests across and adjusting for type-assertion differences — list to single nested list, for example — before running them to see whether each resource behaved correctly.

The tests create and manage real resources, so you can read HTTP traffic to judge whether the pipeline is working: the response from the API shows whether a call was accepted or rejected.

That, however, is not the same as finding bugs where one hides another. Three separate points can raise an error.1

  1. Terraform validates the schema logically before making calls; on failure it halts immediately.
  2. If an API call fails, it stops at the CRUD operation and returns diagnostics, halting immediately.
  3. After CRUD runs, Terraform checks that every value is known.

And so an old bug in step 1 could be found, fixed, and shipped — hiding a second bug that surfaced only in the next round of testing. There is no silver bullet here. The workaround turned instead into pattern detection: write CI lint rules against the OpenAPI schemas to catch problem behaviors before they enter the code generation pipeline. Iterating on that incrementally cut step 1 and 2 bugs to the point that step 3 was where most of the remaining errors were found.

Reusable model and struct conversion

Within Terraform CRUD, a fair amount of boilerplate is the type conversion between Go types and Terraform models, especially in the third step.

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
}

At a high level, the flow is:

  1. req.Plan.Get() fetches the proposed updates (the plan).
  2. The update API call is made with the new values.
  3. The API data is manipulated into a Terraform model (convertResponseToThingModel).
  4. State is set via resp.State.Set().

The middle step gets cumbersome quickly because every resource must implement it, which compounds into exactly the kind of complexity the generator is supposed to avoid.

To avoid generating complex code, all CRUD methods call one set of apijson.Marshal, apijson.Unmarshal, and apijson.UnmarshalComputed methods that centralize the conversion based on struct tags.

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)...)

So instead of generating hundreds of type-to-model converter methods, the Terraform model is decorated with tags and the marshal/unmarshal handling stays consistent. It makes generation reusable and readable — and bug fixing improves too, because fixing a field type in the unified interface repairs other occurrences you may not have found yet.

OpenAPI schema quality

Explicitly encoding what API designers intend matters at the schema level as well. Enabling the pipeline for Terraform forced us to enumerate defaults present in the API, response properties that vary with the request payload, and attributes that are computed server-side. These changes didn't come as a surprise to API designers but they allowed API consumers using Terraform to see what they should expect.

Documentation generated from the same pipeline

The schema investment also feeds Cloudflare's new API documentation site, which runs on the same pipeline the company has built over the past two years. Because SDKs and docs are now generated together, the documentation can show signed examples in every supported library rather than curl alone.

Example using cURL to fetch all zones.
Example using the Typescript library to fetch all zones.
Example using the Python library to fetch all zones.
Example using the Go library to fetch all zones.

The site remembers the language you pick, so selecting the TypeScript library keeps TypeScript examples in view as you navigate. When new attributes are added to existing endpoints or new SDK languages are introduced, the documentation stays in sync automatically.

Rendering 1,330 endpoints

Representing the full API surface has always been a tradeoff: at the time of writing there are 1,330 endpoints, each with a request payload, a response payload, and multiple associated types. The current site handles this volume in two ways:

  • A modern React application that combines an interactive client-side experience with statically pre-rendered content, giving a quick initial load and fast navigation. It works even with JavaScript disabled.
  • Underlying data is fetched incrementally as the user navigates.

With that foundational problem solved, further planned improvements to the documentation site and SDK ecosystem can be made without the compromises previous iterations required.

Minimum required permissions return

Minimum required permissions for API endpoints were among the most requested features for the rebuilt site. An earlier iteration offered them, but the values were manually maintained and regularly incorrect — something most users never knew — which generated support tickets.

Determining "what do I need to access this endpoint" is not simple inside Cloudflare's identity and access management system: in the normal control-plane request flow, two separate systems each supply part of the answer, and the parts must be combined. Because that could not initially be automated in the OpenAPI pipeline, the feature was left out rather than shipped incorrect with no way to verify it.

New tooling now abstracts that question so it can be integrated into the code generation pipeline, and every endpoint gets the information automatically. As with the rest of the platform, the focus is on service teams owning and maintaining high-quality schemas, with value-adds layered on without extra work from those teams.

BLOG-2570 image 6

Updates ship when endpoints are documented

Together these changes end the wait for the SDK ecosystem to catch up: new attributes and endpoints can reach the generated SDKs the moment teams document them. The Terraform provider and the API documentation site are both available now.