hashicorp / hashicorp/terraform-plugin-framework
Feature Request: "Sequential" Resource / Data Source Flag
- Dominant language
- Go
- Stars
- 384
- Forks
- 107
- Avg merge
- 3m
- Merged PRs (30d)
- 1
Description
### Module version
```
v1.5.0
```
### 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).
Plugin / Provider Specific:
- Catching the concurrent API call errors (if possible), and doing waiting/retries on them. (Only works if the upstream API reports them in a consistent way)
### Proposal
For APIs where we know this limitation in usage exists, it would be nice if the Resource schema 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 provider 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.
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
```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
- https://github.com/hashicorp/terraform/issues/14258
- https://github.com/hashicorp/terraform/issues/30841
- https://github.com/hashicorp/terraform/issues/34537
Contributor guide
Assessment
This issue has not been assessed yet.