From 2238fbda1bbb9b9896c9b90a7e849f1cd9410ac1 Mon Sep 17 00:00:00 2001 From: Martin Atkins Date: Wed, 17 Apr 2019 10:05:30 -0700 Subject: [PATCH] website: v0.12 upgrade guide about list variables and brackets --- website/upgrade-guides/0-12.html.markdown | 52 +++++++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/website/upgrade-guides/0-12.html.markdown b/website/upgrade-guides/0-12.html.markdown index 38ea0e9e8b..47cd65171e 100644 --- a/website/upgrade-guides/0-12.html.markdown +++ b/website/upgrade-guides/0-12.html.markdown @@ -275,6 +275,58 @@ because it does not have enough information to know if floating point or integer division was intended by the configuration author, so this change must be made manually where needed. +## Referring to List Variables + +In early versions of Terraform, before list support became first-class, we +required using seemingly-redundant list brackets around a single expression +in order to hint to the language interpreter that a list interpretation was +desired: + +```hcl + # Example for older versions of Terraform; not valid for v0.12 + example = ["${var.any_list}"] +``` + +This strange requirement was subsequently lifted after the introduction of +first-class list support, but we retained compatibility with this older usage +for a transitional period by including some fixup logic that would detect when +list brackets contain list expressions and automatically flatten to a single +list. + +As part of implementing the first-class expressions support for v0.12, we needed +to finally remove that backward-compatibility mechanism to avoid ambiguity +in the language, so an expression like the above will now produce a list of +lists and thus produce a type checking error for any argument that was expecting +a list of some other type. + +The upgrade tool is able to recognize most simple usage of this pattern and +rewrite automatically to just refer to the list directly: + +```hcl + example = var.any_list +``` + +However, an unintended side-effect of this compatiblity mechanism was to +also flatten mixed lists of single-value and list expressions into a single +list automatically. We didn't intend for this to be a part of the language, but +in retrospect it was an obvious consequence of how the compatibility mechanism +was implemented. If you have expressions in your modules that produce a list +of strings by using list brackets with a mixture of string and list-of-string +sub-expressions, you will need to rewrite this to explicitly use +[the `flatten` function](/docs/configuration/functions/flatten.html) +to make the special treatment more obvious to the reader: + +```hcl + example = flatten([ + "single string", + var.any_list, + ]) +``` + +The configuration upgrade tool unfortunately cannot make this change +automatically, because it doesn't have enough information to know for certain +which interpretation was intended for a given list. + ## Terraform Configuration upgrades requiring human intervention There are some known situations that will be detected, but not upgrade, by the