Feature Request: "Sequential" Resource / Data Source Flag

[tgoodsell-tempus]

Terraform Version

Terraform v1.5.7

Use Cases

Certain resources/APIs do not like "concurrent" operations, where the API is used at the same time as other operations (or in "too close" succession).

An example of this is the GCP Networking Peering API: https://registry.terraform.io/providers/hashicorp/google/latest/docs/resources/compute_network_peering, which can be found to fail when multiple peering operations against a project are being performed.

These API errors can either be put through provider specific retry logic, or just results in operation failure if the API errors have that result in the resource.

Attempted Solutions

Generally the "workarounds" for this I've found involve:

• Using depends_on and references to enforce a order of operations, this only works well for "related" resources, for example the peering resource, which requires configuration of an A side then a configuration of a B side.
• Reducing concurrency in the entire operation, which is unfortunate when only a small percentage of resources being used have this issue
• Manually ordering/managing additions to configuration

Most of these are not "ideal" in that they require attentive effort on the part of the operator to get it correct OR they require abusing the depends_on and reference system in a way which is not semantically correct (meaning we create dependencies which are not "real" in practical terms).

Proposal

For APIs where we know this limitation in usage exists, it would be nice if the Terraform interface supported marking these resources (or data sources) as "Sequential" (or pick your favorite term for this).

This is something I would expect to be added to the Resource Schema and configured by a provider developer (either in plugin-sdk-v2 or framework-sdk).

The results of this flag would be that the Terraform executor would not concurrently perform operations on resources of that type, globally within the full configuration. However, that would only apply to those specific resources, and standard rules would apply to everything else. This would have to be smart enough to sequentially order those resources globally and also not try to perform operations on resources that depend on those resources until they've gone through the process (in theory the use of the concurrency flag and standard operations shows that this is already supported as a pattern, but the implementation of how it would work when we're marking specific resources for sequential use could be far more complex than my knowledge can judge).

Ultimately, the "why" is to make a more semantic and standard mechanism for enforcing "sequential" operations on APIs which require it, rather than using workarounds or "provider specific" workaround which may be inconsistent and vary in quality.

Example of implementation expectation:

From https://github.com/hashicorp/terraform-provider-scaffolding-framework/blob/main/internal/provider/example_resource.go

func (r *ExampleResource) Schema(ctx context.Context, req resource.SchemaRequest, resp *resource.SchemaResponse) {
	resp.Schema = schema.Schema{
		// This description is used by the documentation generator and the language server.
		MarkdownDescription: "Example resource",

                // EXAMPLE IMPLEMENTATION: This would mark this as "Sequential"
                Sequential: True,

		Attributes: map[string]schema.Attribute{
			"configurable_attribute": schema.StringAttribute{
				MarkdownDescription: "Example configurable attribute",
				Optional:            true,
			},
			"defaulted": schema.StringAttribute{
				MarkdownDescription: "Example configurable attribute with default value",
				Optional:            true,
				Computed:            true,
				Default:             stringdefault.StaticString("example value when not configured"),
			},
			"id": schema.StringAttribute{
				Computed:            true,
				MarkdownDescription: "Example identifier",
				PlanModifiers: []planmodifier.String{
					stringplanmodifier.UseStateForUnknown(),
				},
			},
		},
	}
}

References

No response

[crw]

Thanks for this feature request! If you are viewing this issue and would like to indicate your interest, please use the 👍 reaction on the issue description to upvote this issue. We also welcome additional use case descriptions. Thanks again!

[jbardin]

Hi @tgoodsell-tempus,

Thanks for the enhancement request. The Terraform Plugin Framework, isn't developed here, the project is located https://github.com/hashicorp/terraform-plugin-framework/issues. Providers often do implement concurrency limits like this, so a builtin helper would need to be in the SDK they are using, not in the Terraform CLI.

Thanks

[tgoodsell-tempus]

@jbardin Can you explain further? Particularly, I would imagine the plugin framework would not be able to do this "itself", this needs to be functionality exposed by Terraform core via the RPC interface, since Terraform core actually "runs" the operations. I'm far from an expert so apologies if I just misunderstood the "flow" and how I should request this type of feature.

[jbardin]

@tgoodsell-tempus, the provider is what has the knowledge about exactly which API requests may have limitations, and it has fine-grained control over those calls, so it should be responsible for controlling access to those calls. Many providers already do this, or it's even built-in to the library used by the provider to access its APIs. The implementation for these types of limits tends to be pretty trivial, but maybe there is a good interface for defining some of these constraints in the resource schema, which is managed by the Plugin Framework.

Terraform core is actually not equipped to deal with this type of fine-grained control, because dependencies are handled at the level of resources, rather than individual instances. See some of the existing feature requests for more general ideas on the core side, which would require some larger changes to the core architecture to accomplish: #30841, #14258

[tgoodsell-tempus]

@jbardin Cheers and appreciate those other references. I think I understand what you mean here. I've cross-posted this request to: hashicorp/terraform-plugin-framework#907

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.