From 0172fed7d4c4224ad1227f75b96baa101503d051 Mon Sep 17 00:00:00 2001 From: Nick Fagerlund Date: Mon, 6 May 2019 13:07:54 -0700 Subject: [PATCH] (website) Adjust intro of attr-blocks page - Note that we intentionally omitted it from the sidebar, to reduce confusion. - Write a summary up top so you can stop reading sooner if you don't actually need this. --- .../docs/configuration/attr-as-blocks.html.md | 22 +++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/website/docs/configuration/attr-as-blocks.html.md b/website/docs/configuration/attr-as-blocks.html.md index 5c49b2dbf..b0ea71b81 100644 --- a/website/docs/configuration/attr-as-blocks.html.md +++ b/website/docs/configuration/attr-as-blocks.html.md @@ -9,6 +9,28 @@ description: |- # Attributes as Blocks +-> **Note:** This page is an appendix to the Terraform documentation, and is +outside the normal navigation hierarchy. Most users do not need to know the full +details of the behavior described below. + +## Summary + +Many resource types use repeatable nested blocks to manage collections of +sub-objects related to the primary resource. + +Rarely, some resource types _also_ support an argument with the same name as a +nested block type, and will purge any sub-objects of that type if that argument +is set to an empty list (` = []`). + +Most users do not need to know any further details of this "nested block or +empty list" behavior. However, read further if you need to: + +- Use Terraform's [JSON syntax](/docs/configuration/syntax-json.html) with this + type of resource. +- Create a reusable module that wraps this type of resource. + +## Details + In Terraform v0.12 and later, the language makes a distinction between [argument syntax and nested block syntax](/docs/configuration/syntax.html#arguments-and-blocks) within blocks: