Resource schema-based support for static default values

[bendbennett]

Module version

v1.1.1

Use-cases

Provider developers have been desiring (#285, #516) the framework support default value plan modifications more easily. Any schema-based or resource-based plan modification for default values must be manually implemented by provider developers currently. The prior SDK supported Default and DefaultFunc fields for this use case.

Attempted Solutions

Provider developers have been using attribute-based or resource-level plan modifiers with varying degrees of success owing to the fact that when Terraform constructs the proposed new state for a computed attribute with a null configuration, it will copy the prior state. If the attribute met the following criteria, the framework will either not show an expected plan to fix the value or propose a plan missing the unknown value marking for other attributes:

• Attribute is optional and computed.
• Attribute has a default value, potentially with an associated plan modifier.
• Attribute is previously configured to a value that differs from the default value, then the configuration is removed.

Provider developers do not have a straightforward methodology for handling this situation, given all provider-defined logic occurs after the unknown marking (#183, #456, #615).

Proposal

Add resource schema-based support for static default values to the framework. This default value handling would occur during the PlanResourceChange RPC and modify the Terraform-provided proposed new state value before the framework performs its check between the proposed new state and prior state to automatically mark computed attributes with null configuration as unknown. The framework would handle the semantics of only consulting the default value handling when the configuration is null.

Similar to the existing type-specific plan modifier support in schema attributes, the default value handling would require implementations to use new typed interfaces. These interfaces would require description methods for future documentation generation needs and a logical method. The framework will implement common use case default value handlers, such as static default value implementations for each type. Provider developers could create their own custom default value implementations to suit more advanced use cases.

Existing resource create and update logic would require no updates assuming it is correctly consulting plan data already, which would have existing bugs if they were not. Existing resource read logic would require no updates unless the default value is not returned in the refreshed state, which would have already required special logic or raised perpetual plan differences. Existing resource configure, delete, import, and upgrade state logic is unaffected.

Existing schema-based plan modifiers that are attempting to handle default values should migrate to the new default value handling to simplify implementations and prevent the unexpected plan differences mentioned in the Background section. This will be denoted in the CHANGELOG for this feature.

An example resource attribute implementation after this change would look like:

"example_attr": schema.StringAttribute{
  // ... other fields ...
  Default: stringdefault.StaticValue("hello"),
},

Default Value Interfaces

Introduce a new resource/schema/default package. It will implement the interfaces, request, and response types for framework-defined and provider-defined implementations, similar to the resource/schema/planmodifier package.

For example:

type Describer interface {
  Description(context.Context) string
  MarkdownDescription(context.Context) string
}

type String interface {
	Describer

	DefaultString(context.Context, StringRequest, *StringResponse)
}

type StringRequest struct {
  Path path.Path
}

type StringResponse struct {
  Diagnostics diag.Diagnostics
  PlanValue types.String
}

Framework-Defined Default Value Implementations

Introduce new resource/schema/{TYPE}default packages, similar to the existing resource/schema/{TYPE}planmodifier packages. These will implement the framework-defined default value handlers, such as static string value default handling. These will be included in the framework, rather than split out like validators in the terraform-plugin-framework-validators repository, as they should be rather trivial in implementation and therefore have less versioning concerns once implemented.

For the initial implementation, only "static value" handlers will be introduced. As other use cases are decided for inclusion in the framework based on ecosystem desire, they can be incrementally introduced.

For example:

func StaticValue(default string) default.String {
	return staticValueDefault{
		default: default,
	}
}

type staticValueDefault struct{
  default string
}

func (d staticValueDefault) Description(_ context.Context) string {
	return "value defaults to "+d.default
}

func (d staticValueDefault) MarkdownDescription(_ context.Context) string {
	return "value defaults to `"+d.default+"`"
}

func (d staticValueDefault) DefaultString(_ context.Context, req default.StringRequest, resp *default.StringResponse) {
  resp.PlanValue = types.StringValue(d.default)
}

Framework Schema Interface

In the internal/fwschema/fwxschema package, new type-specific interfaces for default value handling would be introduced.

For example:

type AttributeWithStringDefaultValue interface {
	fwschema.Attribute

	DefaultValue() default.String
}

Resource Attribute Interface

In the resource/schema package, existing attribute implementation types would be updated to check for the new fwxschema interface, implement a new Default field, and implement the DefaultValue method to satisfy the fwxschema interface.

For example:

var (
	_ Attribute                                  = StringAttribute{}
	_ fwxschema.AttributeWithStringDefaultValue  = StringAttribute{} // new
	_ fwxschema.AttributeWithStringPlanModifiers = StringAttribute{}
	_ fwxschema.AttributeWithStringValidators    = StringAttribute{}
)

type StringAttribute struct {
	// ... existing fields ...
	Default default.String
}

func (a StringAttribute) DefaultValue() {
	return a.Default
}

Framework Schema Data

In the internal/fwschemadata package, the Data type can implement a new transform method which walks the schema and applies schema defined default values when the source Data type contains a null value at the same path.

For example:

func (d *Data) TransformPlanDefaults(ctx context.Context, config Data) diag.Diagnostics {
	// Errors are handled as richer diag.Diagnostics instead.
	d.TerraformValue, _ = tftypes.Transform(d.TerraformValue, func(tfTypePath *tftypes.AttributePath, tfTypeValue tftypes.Value) (tftypes.Value, error) {
		// ...
	})
}

Framework Server

In the internal/fwserver package, the PlanResourceChange method logic can be updated to call the new fwschemadata transform method on the proposed new state data before its checked against the prior state. The existing unknown marking transformer will need to be updated to skip over attributes that declare the new default value handling, so it does not undo what the default value handling just transformed.

For example:

func (s *Server) PlanResourceChange(ctx context.Context, req *PlanResourceChangeRequest, resp *PlanResourceChangeResponse) {
	// ... existing logic ...

	resp.PlannedState = planToState(*req.ProposedNewState)

	// not accurate at the moment, but as pseudo-code
	resp.PlannedState.TransformPlanDefaults(ctx, req.Config)

	if !resp.PlannedState.Raw.IsNull() && !resp.PlannedState.Raw.Equal(req.PriorState.Raw) {

	// ... existing logic ...
}

References

• Plan Modifiers Not Executed Before Plan Computed-Only Unknown Marking #183
• AttributePlanModifier for default value #285
• Computed attrs are not set to unknown after a AttributePlanModifier causes a non-empty plan #456
• Improve Ergonomics of Setting Default Values #516
• Two computed values on a resource with one planmodifier results in unexpected new value #615

[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.