"Attributes as Blocks" documentation should mention that dynamic blocks don't work

[apparentlymart]

Terraform Version

v0.12 through to v1.3, at least

Affected Pages

Attributes as Blocks

What is the docs issue?

Since Terraform v0.12 we've had a special "attributes as blocks" mode which allows providers to opt specific attribute names into a special legacy treatment which tries its best to simulate HCL 1's confusion about attribute syntax vs. block syntax, at the expense of inheriting various quirks and oddities from Terraform v0.11 that had otherwise been fixed by drawing a stronger distinction between the two in HCL 2.

Over in #22340 we learned that for provider arguments that have opted in to that special mode the dynamic block feature doesn't work properly, because the configuration schema is ambiguous and the dynamic block decoder (which is part of HCL rather than Terraform, and so it doesn't know about Terraform's attributes as blocks hack) ends up behaving very strangely.

However, in that same issue we concluded that there wasn't really any workable fix and that this legacy mode should phase out over time anyway, and so the impact was limited only to specific parts of older providers that have not yet adopted modern design patterns.

What we didn't do in response to that decision is update the "attributes as blocks" documentation to be clearer about the problem. Currently the page describes what to do instead of using a dynamic block in the section Arbitrary Expressions with Argument Syntax. However, it only hints in passing at the end that this is an alternative to dynamic blocks, and the writing implies that it's only a preference to not use dynamic blocks.

Proposal

As part of the original Attributes as Blocks compromise we organized the information architecture in a specific way so that we could avoid concerning most readers with learning about this strange mode, and instead bring it up only in specific situations where it is relevant. That approach came in two parts:

• The main Terraform docs have the Attributes as Blocks page which allows us to centralize all of the details about the various quirks this mode causes.
• For each argument in a provider that uses this mode, the documentation for that specific argument should link to the Attributes as Blocks page. This means that the folks who are using those legacy arguments will learn about the special mode but most folks using modernized providers will never need to learn that this mode even exists.

In light of that original plan, I think we should add a new section to the Attributes as Blocks page which discusses dynamic blocks specifically, stating without any ambiguity that they do not work at all for attributes that are using this special mode. That section can then point to the existing section "Arbitrary Expressions with Attribute Syntax" as the guidance on what to do instead. Finally, we should either remove the closing statement in that section which talks about dynamic blocks or rework it so that it points back to the new section we've added on that topic.

References

• Cannot use dynamic inside block defined with ConfigModeAttr #22340