Consider Documentation and Tutorials for Common Use Cases

[bflad]

Use-cases

Provider developers across the ecosystem will have some common use cases they will want to research documentation on how to accomplish their goals. For example, how to implement provider configuration validation for attributes which should also source standard vendor SDK environment variables.

Currently provider developers are left to their own devices beyond piecing together the Go documentation and terraform.io documentation that typically describes in detail a single piece of the framework rather than implementations that require crossing those boundaries. This means that it can potentially take much longer to be successful as the next options may be researching other Terraform Provider implementations, asking on HashiCorp Discuss, or reaching out on other community forums.

Proposal

For a timeboxed period, use this issue to collect some "common" provider development use cases with a brief summary and potential solution, linking to other documentation or providing code examples as necessary. When the collection period is over, holistically evaluate which (if any or all) should potentially be surfaced in the terraform.io documentation website or learn.hashicorp.com tutorials and how best to accomplish that since they are very likely to be disparate in nature.

[bflad]

Provider Attribute Validation With Environment Variables

Providers may need to support attributes that are configurable via Terraform configuration as well as standard vendor environment variables (e.g. AWS_DEFAULT_REGION, AZURE_DEFAULTS_LOCATION, GITHUB_TOKEN, CLOUDSDK_CORE_PROJECT, etc.). To accomplish this, the attribute should be optional, and the validation implemention should occur in the provider Configure method. This ensures that terraform validate can remain offline (or put another way, statically validated anywhere), while also giving the provider the opportunity to set the expected precedence and potential unknown value handling.

Refer to terraform-provider-hashicups-pf for an example of how this can be accomplished.

[bflad]

Attribute Default Values

Resources and data sources often want to specify a default value for an attribute, so practitioners do not need to declare everything explicitly and to perform drift detection against the corresponding default value from the provider. While the framework documentation touches on this handling in the plan modifiers page, this probably warrants its own page to explain the necessary Computed: true schema as well.

We can separately consider whether the framework should be providing some standard plan modifiers for these cases.

[tmccombs]

Another common use case that should be documented is how to do retries, and what the equivalent of WaitForContextState is.

[bflad]

Use State For Unknown

Providers wishing to keep a prior state value for an Optional and Computed attribute, rather than having the framework show (known after apply) or more confusingly a set type situation like #302, should use the tfsdk.UseStateForUnknown attribute plan modifier. The Go documentation and terraform.io website documentation around this is quite lacking at the moment.

[bflad]

306 describes a fairly common pattern about using provider configuration data to influence resource behaviors

[bflad]

Drive-by comment: Folks working with dynamic variadic parameters (e.g. making a deep merge algorithm provider-defined function) could likely use some additional guidance about how to get started and what to consider.

[SBGoods]

Provider Developer Concurrency Best Practices

A commonly discussed topic on HashiCorp Discuss is provider development best practices for topics surrounding concurrency, parallelism, mutex, rate limiting, etc. We should consider documenting common considerations/pitfalls on these topics.

[azrdev]

Related:

• 512

• 939