helper/schema: Introduce context-aware resource CRUD functions without default timeout

[bflad]

Closes #675

(Test changes may be easiest to view with the "hide whitespace changes" option in GitHub as they are just introducing looping to cover relevant Create/CreateContext/CreateWithoutTimeout method implementations.)

The Terraform Plugin SDK has always supported customizable timeouts, declared at the helper/schema.Resource.Timeouts level with the operation aware helper/schema.ResourceTimeout type. These were designed to allow practitioners to implement a timeout per resource, e.g.

resource "example_thing" "example" {
  timeouts {
    create = "60m"
  }
}

Where the resource logic could fetch the timeout value via (helper/schema.ResourceData).Timeout() function.

Recently, context-aware resource operation functions were introduced and the existing non-context-aware functions were deprecated. These new context-aware resource operations forcibly introduce an operation timeout (defaults to 20 minutes) for the called logic, e.g.

terraform-plugin-sdk/helper/schema/resource.go

Lines 283 to 285 in e21a5bb

	ctx, cancel := context.WithTimeout(ctx, d.Timeout(TimeoutCreate))
	defer cancel()
	return r.CreateContext(ctx, d, meta)

Previously, the non-context-aware resources could be implemented with helper/schema.Resource.Timeouts.Create defined and operation logic such as:

func resourceExampleThingCreate(d *schema.ResourceData, meta interface{}) error {
  mutexkv.Lock("somekey")
  defer mutexkv.Unlock("somekey")
  // ... reference to d.Timeout(schema.TimeoutCreate) ...
}

Where in this case, the create timeout could be referenced in the code via d.Timeout(schema.TimeoutCreate) after the synchronization coordination. The creation timeout only affected this single operation, even if multiple operations were going to occur.

In the case of the context-aware functionality however, the timeout is configured before the mutex. So when multiple operations are waiting on the mutex, they are now sharing the same resource operation timeout. Since the timeout cannot be extended within the resource logic, developers are stuck either setting an arbitrarily high timeout (losing its usefulness) or practitioners are arbitrarily hitting the timeout as they scale out their configuration.

To characterize how some remote systems can require that operations must be serialized or otherwise synchronized:

• Only 1 resource type can be created at a time
• Only 1 child resource type can be created at a time per parent resource
• Only 10 concurrent updates of a resource type can be performed at a time
• Remote system may support configurable synchronization limits (either by the customer or remote system operators)

This essentially means the semantics of the synchronization can be based off resource configuration, operation type, and potentially accordant to the limits set by a remote system.

Here we introduce separate CRUD methods that are invoked before the context is set with the timeout, so as to not "force" the resource timeout. If timeout behavior is still desired, developers must manually implement timeout handling in the function logic when using these.

Most developers should prefer the existing context-aware functions and this is documented as such. However, another minor side benefit of these functions is that it also allows developers to upgrade CRUD function signatures for context awareness without logically changing resource behavior, then slowly switch to the timeout functions over time.

[paddycarver]

This looks reasonable to me. As we discussed, I find the proliferation of CRUD functions alarming--we're up to 12--but I think this is a pragmatic tradeoff given the compatibility constraints (the ability to restore prior behavior using sed) and the fact that we accidentally opted people into behavior without realizing it matters when discussing what solution is appropriate. I think in the future a boolean on the schema.Resource struct to toggle this behavior would be the right answer, but this is a bit of a special case.

[ghost]

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.