Document Mitigation for Empty String to Null Plans for SDK Migrations

[bflad]

Module version

v0.14.0

Description

In certain situations, terraform-plugin-sdk would save unconfigured (null) string attributes into the Terraform state as "" instead of null. When migrating to the framework, this can cause unexpected plan differences as the framework correctly now handles null values and since Terraform correctly considers these values to be different.

Separately, Terraform CLI does not currently show certain plan differences relating to "" => null and vice-versa, which can make this extra confusing for provider developers.

Provider developers have (at least) two options to handle this migration situation:

• Switch the attribute to Optional, Computed, and include an attribute plan modifier that handles the "" behavior similarly to terraform-plugin-sdk. This would prevent the plan differences and prevent potential issues with modules where differences between "" and null may matter.
• Not do anything, but consider the change to be a breaking change as part of the migration, and bump the provider major version.

We'll also need to determine all the cases where terraform-plugin-sdk would have done this. One known case is Optional-only string attributes within list blocks.

It may be preferable to also introduce a built-in attribute plan modifier for this particular situation, but that can be treated separately as having some documentation around this issue is more important.

References

• tls_self_signed_cert is unintentionally replaced on 4.0.0 and later terraform-provider-tls#284
• CLI Plan Output Not Showing null to "" Differences for Non-Legacy Type System Providers terraform#31887

[bflad]

From an out-of-band conversation, please note that adding configuration to state upgrades to potentially update these "transparently" is not being considered upstream.

[ewbankkit]

The Terraform AWS Provider recently encountered this issue during the migration of the aws_globalaccelerator_accelerator data source from Plugin SDK v2 to Plugin Framework: hashicorp/terraform-provider-aws#27282.
In particular, an existing acceptance test case caught a nested attribute (attributes.0.flow_logs_s3_prefix) not being present vs. having an empty string value.

The relevant code is https://github.com/hashicorp/terraform-provider-aws/blob/2d2308a4872843b878a292dd2c95730e16a7a2e6/internal/service/globalaccelerator/accelerator_data_source.go#L281-L297.

From experience this will likely affect more than just strings - other types have their zero value (0, false etc.) set instead of null.

[bflad]

Another odd one, doing d.Set("map_attribute", nil) in the sdk would save a known empty map into the state, not null, at least for data sources.

[austinvalle]

A relevant write-up that might be useful when we document this: https://discuss.hashicorp.com/t/framework-migration-test-produces-non-empty-plan/54523/12