Consider adding (deprecated) support for blocks 😢

[paddycarver]

Module version

v0.2.0

Use-cases

We decided to model nested fields as nested attributes, because they're better in basically every way™, and I think that was a good decision.

However, for providers that currently exist and want to adopt the framework using mux, this presents two problems:

1. Provider blocks need to match perfectly when muxing. But SDKv2 has no way to model nested attributes, and the framework has no way to model blocks, meaning if you have nested fields of any kind in your provider configuration, you just can't mux across SDKv2 and the framework. This is suboptimal, and makes migration to the framework much, much more difficult.
2. Changing a group of nested fields from a block to an attribute is a breaking change, because it requires practitioners to add the = to their configuration. Meaning piecemeal migration of resources is not possible, as you can't model blocks in the framework, and need to migrate to nested attributes at that point, which is a practitioner-visible change.

Both of these problems severely limit how palatable our migration story can be.

Attempted Solutions

I thought about just relaxing mux to consider blocks and nested attributes the same for considering whether provider blocks are "equivalent" or not, as they'll both show up as objects in the config and can be accessed the same way. But that seems brittle, and would lead to weird situations where things aren't treated as sensitive properly, or where things can be expressed in the framework that SDKv2 doesn't know how to handle... it just feels like a really leaky abstraction and lossy mapping. It also doesn't address point 2 basically at all.

Proposal

I'm proposing that we add support to the framework for modeling blocks, and make it clear from its introduction that it is deprecated, we recommend everyone use nested attributes, and that it's only supported to ease migration from SDKv2. This isn't ideal, but I don't see a way to get a clean, piecemeal, non-practitioner-impacting migration strategy if we don't.

[bflad]

To further hone on the proposal, I presume:

• We should specifically only support tfprotov6.SchemaNestedBlockNestingModeList and tfprotov6.SchemaNestedBlockNestingModeSet since those were the two types of blocks supported in SDKv2?
• We should explicitly not support tfprotov6.SchemaNestedBlockNestingModeMap (blocks with additional name label that serves as the map key) that's requested in Allow providers' schema to define named HCL blocks terraform-plugin-sdk#220, since we likely will never support that in SDKv2 due to the complexity of handling it in the underlying flatmap/field mapping and would feel weird with other block types being deprecated? I'm wondering if now is the best time to close that feature request.

[aareet]

Next step: create an epic with more granular implementation so we can discuss with provider devs and get their input on which path is preferable.

[dpifke]

If deprecation of nested block syntax is planned, the documentation at https://www.terraform.io/docs/language/attr-as-blocks.html should probably be updated ASAP to no longer recommend it over nested attribute syntax.

Otherwise, providers using the framework will face confusion from users as to why the "recommended" syntax is not allowed.

Lack of support for nested blocks might also be worth a mention at https://www.terraform.io/docs/plugin/which-sdk.html.

[paddycarver]

I think that's a slightly confusing "we don't have good terms around this yet" case. SDKv2 can't currently use the recommended syntax, which is a framework-only feature.

Likewise, the "which SDK?" update may be more confusing than illuminating, as there's not really a difference in capability, just in syntax. Unsure, though. 🤔

[apparentlymart]

FWIW, the intent of that "Attributes as Blocks" page is only to describe the funny special-case behavior for the arguments which use that weird legacy mode. It's not a recommendation to do anything in particular. Its intended audience is end-users of providers that use the mechanism, to explain the end-user-visible consequences of using that special mode.