defaults Function
Note: This function is available only in Terraform 0.15 and later.
Experimental: This function is part of
the optional attributes experiment
and is only available in modules where the module_variable_optional_attrs
experiment is explicitly enabled.
The defaults
function is a specialized function intended for use with
input variables whose type constraints are object types or collections of
object types that include optional attributes.
When you define an attribute as optional and the caller doesn't provide an
explicit value for it, Terraform will set the attribute to null
to represent
that it was omitted. If you want to use a placeholder value other than null
when an attribute isn't set, you can use the defaults
function to concisely
assign default values only where an attribute value was set to null
.
The defaults
function expects that the input_value
argument will be the
value of an input variable with an exact type constraint
(not containing any
). The function will then visit every attribute in
the data structure, including attributes of nested objects, and apply the
default values given in the defaults object.
The interpretation of attributes in the defaults
argument depends on what
type an attribute has in the input_value
:
- Primitive types (
string
,number
,bool
): if a default value is given then it will be used only if theinput_value
's attribute of the same name has the valuenull
. The default value's type must match the input value's type. - Structural types (
object
andtuple
types): Terraform will recursively visit all of the attributes or elements of the nested value and repeat the same defaults-merging logic one level deeper. The default value's type must be of the same kind as the input value's type, and a default value for an object type must only contain attribute names that appear in the input value's type. - Collection types (
list
,map
, andset
types): Terraform will visit each of the collection elements in turn and apply defaults to them. In this case the default value is only a single value to be applied to all elements of the collection, so it must have a type compatible with the collection's element type rather than with the collection type itself.
The above rules may be easier to follow with an example. Consider the following Terraform configuration:
To test this out, we can create a file terraform.tfvars
to provide an example
value for var.storage
:
The above value conforms to the variable's type constraint because it only
omits attributes that are declared as optional. Terraform will automatically
populate those attributes with the value null
before evaluating anything
else, and then the defaults
function in local.storage
will substitute
default values for each of them.
The result of this defaults
call would therefore be the following object:
Notice that enabled
and website.index_document
were both populated directly
from the defaults. Notice also that the "terraform.exe"
element of
documents
had its content_type
attribute populated from the documents
default, but the default value didn't need to predict that there would be an
element key "terraform.exe"
because the default values apply equally to
all elements of the map where the optional attributes are null
.
Using defaults
elsewhere
The design of the defaults
function depends on input values having
well-specified type constraints, so it can reliably recognize the difference
between similar types: maps vs. objects, lists vs. tuples. The type constraint
causes Terraform to convert the caller's value to conform to the constraint
and thus defaults
can rely on the input to conform.
Elsewhere in the Terraform language it's typical to be less precise about
types, for example using the object construction syntax { ... }
to construct
values that will be used as if they are maps. Because defaults
uses the
type information of input_value
, an input_value
that doesn't originate
in an input variable will tend not to have an appropriate value type and will
thus not be interpreted as expected by defaults
.
We recommend using defaults
only with fully-constrained input variable values
in the first argument, so you can use the variable's type constraint to
explicitly distinguish between collection and structural types.