Merge pull request #29845 from hashicorp/jbardin/nullable-variable-docs

nullable variable docs

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

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,37 @@ 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 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.
+
+```
+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
+`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 Terraform uses the default when a module input argument is `null`.
+
+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.
+
+
 ## Using Input Variable Values
 
 Within the module that declared a variable, its value can be accessed from