From 6a1afd2dc30064097a55f510fae30b3fef40dd9d Mon Sep 17 00:00:00 2001 From: James Bardin Date: Mon, 1 Nov 2021 13:16:19 -0400 Subject: [PATCH 1/6] nullable variable docs Add `nullable` to the variable documentation. Remove "module" from the "null means omission" part of the null type documentation. --- .../docs/language/expressions/types.html.md | 2 +- website/docs/language/values/variables.html.md | 18 ++++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/website/docs/language/expressions/types.html.md b/website/docs/language/expressions/types.html.md index a787a2a86..99830cdd3 100644 --- a/website/docs/language/expressions/types.html.md +++ b/website/docs/language/expressions/types.html.md @@ -31,7 +31,7 @@ Strings, numbers, and bools are sometimes called _primitive types._ Lists/tuples Finally, there is one special value that has _no_ type: * `null`: a value that represents _absence_ or _omission._ If you set an - argument of a resource or module to `null`, Terraform behaves as though you + argument of a resource to `null`, Terraform behaves as though you had completely omitted it — it will use the argument's default value if it has one, or raise an error if the argument is mandatory. `null` is most useful in conditional expressions, so you can dynamically omit an argument if a diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index a1e0fcf9f..cd72c5abb 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -84,6 +84,7 @@ Terraform CLI defines the following optional arguments for variable declarations - [`description`][inpage-description] - This specifies the input variable's documentation. - [`validation`][inpage-validation] - A block to define validation rules, usually in addition to type constraints. - [`sensitive`][inpage-sensitive] - Limits Terraform UI output when the variable is used in configuration. +- [`nullable`][inpage-nullable] - Specify if the variable can be `null` within the module. ### Default values @@ -303,6 +304,23 @@ random_pet.animal: Creating... random_pet.animal: Creation complete after 0s [id=jae-known-mongoose] ``` +### Disallowing null Module Input Values + +[inpage-nullable]: #disallowing-null-input-values + +-> This feature was introduced in Terraform v1.1.0. + +The default value for `nullable` is `true`. When `nullable` is `true`, `null` +is a valid value for the variable, and the module configuration must always +account for the possibility of the variable value being `null`. Passing a +`null` value as a module input argument will override any `default` value. + +Setting `nullable` to `false` ensures that the variable value will never be +`null` within the module. If `nullable` is `false` and the variable has a +`default` value, then the default will be used when a `null` value is given as +a module input argument. + + ## Using Input Variable Values Within the module that declared a variable, its value can be accessed from From 03ed7664545c7966809066ffe463d92601ccfcee Mon Sep 17 00:00:00 2001 From: James Bardin Date: Mon, 1 Nov 2021 14:30:25 -0400 Subject: [PATCH 2/6] nullable doc update --- website/docs/language/values/variables.html.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index cd72c5abb..c540be2c7 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -310,6 +310,16 @@ random_pet.animal: Creation complete after 0s [id=jae-known-mongoose] -> This feature was introduced in Terraform v1.1.0. +The `nullable` argument in a variable block controls whether the module caller +may assign the value `null` to the variable: + +``` +variable "example" { + type = string + nullable = false +} +``` + The default value for `nullable` is `true`. When `nullable` is `true`, `null` is a valid value for the variable, and the module configuration must always account for the possibility of the variable value being `null`. Passing a @@ -320,6 +330,11 @@ Setting `nullable` to `false` ensures that the variable value will never be `default` value, then the default will be used when a `null` value is given as a module input argument. +`nullable` only controls where the direct value of the variable may be `null`. +For variables of collection or structural types, such as list or object types, +the caller may still use `null` in nested elements or attributes, as long as +the collection or structure itself is not null. + ## Using Input Variable Values From 46bbe66cd029ae6851efb9295460bfbee2985c0a Mon Sep 17 00:00:00 2001 From: James Bardin Date: Mon, 1 Nov 2021 15:17:21 -0400 Subject: [PATCH 3/6] Update website/docs/language/values/variables.html.md Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/values/variables.html.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index c540be2c7..a008ae300 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -327,8 +327,7 @@ account for the possibility of the variable value being `null`. Passing a Setting `nullable` to `false` ensures that the variable value will never be `null` within the module. If `nullable` is `false` and the variable has a -`default` value, then the default will be used when a `null` value is given as -a module input argument. +`default` value, then Terraform uses the default when a module input argument is `null`. `nullable` only controls where the direct value of the variable may be `null`. For variables of collection or structural types, such as list or object types, From 2195d7a45fc397f0a8b2d6b78657e3aa1266ff97 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Mon, 1 Nov 2021 15:17:32 -0400 Subject: [PATCH 4/6] Update website/docs/language/values/variables.html.md Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/values/variables.html.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index a008ae300..2107b073d 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -329,8 +329,8 @@ Setting `nullable` to `false` ensures that the variable value will never be `null` within the module. If `nullable` is `false` and the variable has a `default` value, then Terraform uses the default when a module input argument is `null`. -`nullable` only controls where the direct value of the variable may be `null`. -For variables of collection or structural types, such as list or object types, +The `nullable` argument only controls where the direct value of the variable may be `null`. +For variables of collection or structural types, such as lists or objects, the caller may still use `null` in nested elements or attributes, as long as the collection or structure itself is not null. From 4f88445d05e5b6e348a351b58ee87ac0bf880866 Mon Sep 17 00:00:00 2001 From: James Bardin Date: Mon, 1 Nov 2021 15:17:43 -0400 Subject: [PATCH 5/6] Update website/docs/language/values/variables.html.md Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/values/variables.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index 2107b073d..54b2f297a 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -311,7 +311,7 @@ random_pet.animal: Creation complete after 0s [id=jae-known-mongoose] -> This feature was introduced in Terraform v1.1.0. The `nullable` argument in a variable block controls whether the module caller -may assign the value `null` to the variable: +may assign the value `null` to the variable. ``` variable "example" { From 8b53637230876fdf93ac3fe9d38060e0f75b953a Mon Sep 17 00:00:00 2001 From: James Bardin Date: Mon, 1 Nov 2021 15:17:51 -0400 Subject: [PATCH 6/6] Update website/docs/language/values/variables.html.md Co-authored-by: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> --- website/docs/language/values/variables.html.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index 54b2f297a..a983192be 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -308,7 +308,7 @@ random_pet.animal: Creation complete after 0s [id=jae-known-mongoose] [inpage-nullable]: #disallowing-null-input-values --> This feature was introduced in Terraform v1.1.0. +-> This feature is available in Terraform v1.1.0 and later. The `nullable` argument in a variable block controls whether the module caller may assign the value `null` to the variable.