Description
Module version
v0.13.0
Use-cases
When accessing schema-based data (such as configuration, plan, and state), there are a plethora of various rules associated with the possible values being null or unknown. Some of this is based on the following:
- Which RPC is involved
- Whether it is the RPC request or response data
- How the attribute is defined (Computed, Optional, or Required)
Some of these rules are documented in the current website documentation:
- Required attributes will never be null or unknown in Create, Read, Update, or Delete methods.
- Optional attributes that are not computed will never be unknown in Create, Read, Update, or Delete methods.
- Computed attributes, whether optional or not, will never be null in the plan for Create, Read, Update, or Delete methods.
- Computed attributes that are read-only (Optional is not true) will always be unknown in the plan for Create, Read, Update, or Delete methods. They will always be null in the configuration for Create, Read, Update, and Delete methods.
Required attributes will never be null in a provider's Configure method. They may be unknown. - The state never contains unknown values.
- The configuration for Create, Read, Update, and Delete methods never contains unknown values.
These all tend to confuse provider developers as evidenced by the various amount of inbound GitHub issues, HashiCorp Discuss posts, and out-of-public feedback the framework maintainers receive. Provider developers are free to implement Go standard library types or provider-defined types to accept this schema-based data, however the current framework design takes a runtime error approach when it comes to feedback the provider developer. This feedback loop likely involves practitioners, since the provider developer may not be able to tease out this potential issue during development or testing.
Attempted Solutions
The next version of the framework will improve the runtime error messaging for null and unknown values, however there is potential for unknown values based on the practitioner configuration. This is outside the provider developers control and leaving a potential practitioner-based feedback to provider developers is a poor experience. The potential for a value to be unknown can also tends to be hard to acceptance test, as acceptance testing tends to use either hardcoded values or a preference to not include unnecessary data sources or resources.
Proposal
Adjust the implementations of (tfsdk.Config).Get(), (tfsdk.Config).GetAttribute(), (tfsdk.Plan).Get(), (tfsdk.Plan).GetAttribute(), (tfsdk.State).Get(), and (tfsdk.State).GetAttribute() to always return an error if the target type (or struct field within the target type) does not support null or unknown values. Essentially, provider developers will be required to either use types types or provider-defined types that properly implement the attr.Value interface.
In practice, this will simplify the framework's recommendations, regardless of the RPC or schema definition. It will be generally recommended to types types for directly accessing schema-based data. Provider developers can then use the associated type methods, such as (types.Object).As() to convert to other Go types, if still desirable.
This work may be tangentially paired with other types package refactoring, which is aimed to prevent the ability to create invalid values. Refer to #447 for more details there.