resilien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

website: Elaborate the "expressions" sub-pages in the language section 

When we did the earlier documentation rework for Terraform v0.12 we still
had one big "Expressions" page talking about the various operators and
constructs, and so we had to be a bit economical with the details about
some more complicated constructs in order to avoid the page becoming even
more overwhelming.

However, we've recently reorganized the language documentation again so
that the expressions section is split across several separate pages, and
that gives some freedom to go into some more detail about and show longer
examples for certain features.

My changes here are not intended to be an exhaustive rewrite but I did
try to focus on some areas I've commonly seen questions about when helping
in the community forum and elsewhere, and also to create a little more
connectivity between the different content so readers can hopefully find
what they are looking for more easily when they're not yet sure what
terminology to look for.
This commit is contained in:
Martin Atkins 2020-12-04 16:15:54 -08:00
parent 627a2121b8
commit ab1dd87540
7 changed files with 467 additions and 68 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
website/docs/configuration/expressions/conditionals.html.md
View File

@ -41,3 +41,28 @@ The two result values may be of any type, but they must both
be of the _same_ type so that Terraform can determine what type the whole
conditional expression will return without knowing the condition value.
If the two result expressions don't produce the same type then Terraform will
attempt to find a type that they can both convert to, and make those
conversions automatically if so.
For example, the following expression is valid and will always return a string,
because in Terraform all numbers can convert automatically to a string using
decimal digits:
```hcl
var.example ? 12 : "hello"
```
Relying on this automatic conversion behavior can be confusing for those who
are not familiar with Terraform's conversion rules though, so we recommend
being explicit using type conversion functions in any situation where there may
be some uncertainty about the expected result type.
The following example is contrived because it would be easier to write the
constant `"12"` instead of the type conversion in this case, but shows how to
use [`tostring`](../functions/tostring.html) to explicitly convert a number to
a string.
```hcl
var.example ? tostring(12) : "hello"
```

67
website/docs/configuration/expressions/dynamic-blocks.html.md
View File

@ -9,7 +9,8 @@ page_title: "Dynamic Blocks - Configuration Language"
Within top-level block constructs like resources, expressions can usually be
used only when assigning a value to an argument using the `name = expression`
form. This covers many uses, but some resource types include repeatable _nested
blocks_ in their arguments, which do not accept expressions:
blocks_ in their arguments, which typically represent separate objects that
are related to (or embedded within) the containing object:
```hcl
resource "aws_elastic_beanstalk_environment" "tfenvtest" {
@ -42,9 +43,10 @@ resource "aws_elastic_beanstalk_environment" "tfenvtest" {
}
```
A `dynamic` block acts much like a `for` expression, but produces nested blocks
instead of a complex typed value. It iterates over a given complex value, and
generates a nested block for each element of that complex value.
A `dynamic` block acts much like a [`for` expression](for.html), but produces
nested blocks instead of a complex typed value. It iterates over a given
complex value, and generates a nested block for each element of that complex
value.
- The label of the dynamic block (`"setting"` in the example above) specifies
what kind of nested block to generate.
@ -86,6 +88,56 @@ and
[`setproduct`](/docs/configuration/functions/setproduct.html)
functions.
## Multi-level Nested Block Structures
Some providers define resource types that include multiple levels of blocks
nested inside one another. You can generate these nested structures dynamically
when necessary by nesting `dynamic` blocks in the `content` portion of other
`dynamic` blocks.
For example, a module might accept a complex data structure like the following:
```hcl
variable "load_balancer_origin_groups" {
type = map(object({
origins = set(object({
hostname = string
}))
}))
}
```
If you were defining a resource whose type expects a block for each origin
group and then nested blocks for each origin within a group, you could ask
Terraform to generate that dynamically using the following nested `dynamic`
blocks:
```hcl
dynamic "origin_group" {
for_each = var.load_balancer_origin_groups
content {
name = origin_group.key
dynamic "origin" {
for_each = origin_group.value.origins
content {
hostname = origin.value.hostname
}
}
}
}
```
When using nested `dynamic` blocks it's particularly important to pay attention
to the iterator symbol for each block. In the above example,
`origin_group.value` refers to the current element of the outer block, while
`origin.value` refers to the current element of the inner block.
If a particular resource type defines nested blocks that have the same type
name as one of their parents, you can use the `iterator` argument in each of
`dynamic` blocks to choose a different iterator symbol that makes the two
easier to distinguish.
## Best Practices for `dynamic` Blocks
Overuse of `dynamic` blocks can make configuration hard to read and maintain, so
@ -93,3 +145,10 @@ we recommend using them only when you need to hide details in order to build a
clean user interface for a re-usable module. Always write nested blocks out
literally where possible.
If you find yourself defining most or all of a `resource` block's arguments and
nested blocks using directly-corresponding attributes from an input variable
then that might suggest that your module is not creating a useful abstraction.
It may be better for the calling module to define the resource itself then
pass information about it into your module. For more information on this design
tradeoff, see [When to Write a Module](/docs/modules/#when-to-write-a-module)
and [Module Composition](/docs/modules/composition.html).

192
website/docs/configuration/expressions/for.html.md
View File

@ -10,8 +10,8 @@ another complex type value. Each element in the input value
can correspond to either one or zero values in the result, and an arbitrary
expression can be used to transform each input element into an output element.
For example, if `var.list` is a list of strings, then the following expression
produces a list of strings with all-uppercase letters:
For example, if `var.list` were a list of strings, then the following expression
would produce a tuple of strings with all-uppercase letters:
```hcl
[for s in var.list : upper(s)]
@ -22,10 +22,41 @@ evaluates the expression `upper(s)` with `s` set to each respective element.
It then builds a new tuple value with all of the results of executing that
expression in the same order.
## Input Types
A `for` expression's input (given after the `in` keyword) can be a list,
a set, a tuple, a map, or an object.
The above example showed a `for` expression with only a single temporary
symbol `s`, but a `for` expression can optionally declare a pair of temporary
symbols in order to use the key or index of each item too:
```hcl
[for k, v in var.map : length(k) + length(v)]
```
For a map or object type, like above, the `k` symbol refers to the key or
attribute name of the current element. You can also use the two-symbol form
with lists and tuples, in which case the additional symbol is the index
of each element starting from zero, which conventionally has the symbol name
`i` or `idx` unless it's helpful to choose a more specific name:
```hcl
[for i, v in var.list : "${i} is ${v}"]
```
The index or key symbol is always optional. If you specify only a single
symbol after the `for` keyword then that symbol will always represent the
_value_ of each element of the input collection.
## Result Types
The type of brackets around the `for` expression decide what type of result
it produces. The above example uses `[` and `]`, which produces a tuple. If
`{` and `}` are used instead, the result is an object, and two result
expressions must be provided separated by the `=>` symbol:
it produces.
The above example uses `[` and `]`, which produces a tuple. If you use `{` and
`}` instead, the result is an object and you must provide two result
expressions that are separated by the `=>` symbol:
```hcl
{for s in var.list : s => upper(s)}
@ -33,39 +64,146 @@ expressions must be provided separated by the `=>` symbol:
This expression produces an object whose attributes are the original elements
from `var.list` and their corresponding values are the uppercase versions.
For example, the resulting value might be as follows:
```hcl
{
foo = "FOO"
bar = "BAR"
baz = "BAZ"
}
```
A `for` expression alone can only produce either an object value or a tuple
value, but Terraform's automatic type conversion rules mean that you can
typically use the results in locations where lists, maps, and sets are expected.
## Filtering Elements
A `for` expression can also include an optional `if` clause to filter elements
from the source collection, which can produce a value with fewer elements than
the source:
from the source collection, producing a value with fewer elements than
the source value:
```
[for s in var.list : upper(s) if s != ""]
```
The source value can also be an object or map value, in which case two
temporary variable names can be provided to access the keys and values
respectively:
One common reason for filtering collections in `for` expressions is to split
a single source collection into two separate collections based on some
criteria. For example, if the input `var.users` is a map of objects where the
objects each have an attribute `is_admin` then you may wish to produce separate
maps with admin vs non-admin objects:
```
[for k, v in var.map : length(k) + length(v)]
```hcl
variable "users" {
type = map(object({
is_admin = boolean
}))
}
locals {
admin_users = {
for name, user in var.users : name => user
if user.is_admin
}
regular_users = {
for name, user in var.users : name => user
if !user.is_admin
}
}
```
Finally, if the result type is an object (using `{` and `}` delimiters) then
the value result expression can be followed by the `...` symbol to group
together results that have a common key:
## Element Ordering
```
{for s in var.list : substr(s, 0, 1) => s... if s != ""}
Because `for` expressions can convert from unordered types (maps, objects, sets)
to unordered types (lists, tuples), Terraform must choose an implied ordering
for the elements of an unordered collection.
For maps and objects, Terraform sorts the elements by key or attribute name,
using lexical sorting.
For sets of strings, Terraform sorts the elements by their value, using
lexical sorting.
For sets of other types, Terraform uses an arbitrary ordering that may change
in future versions of Terraform. For that reason, we recommend converting the
result of such an expression to itself be a set so that it's clear elsewhere
in the configuration that the result is unordered. You can use
[the `toset` function](../functions/toset.html)
to concisely convert a `for` expression result to be of a set type.
```hcl
toset([for e in var.set : e.example])
```
For expressions are particularly useful when combined with other language
features to combine collections together in various ways. For example,
the following two patterns are commonly used when constructing map values
to use with
[the `for_each` meta-argument](/docs/configuration/meta-arguments/for_each.html):
## Grouping Results
* Transform a multi-level nested structure into a flat list by
[using nested `for` expressions with the `flatten` function](/docs/configuration/functions/flatten.html#flattening-nested-structures-for-for_each).
* Produce an exhaustive list of combinations of elements from two or more
collections by
[using the `setproduct` function inside a `for` expression](/docs/configuration/functions/setproduct.html#finding-combinations-for-for_each).
If the result type is an object (using `{` and `}` delimiters) then normally
the given key expression must be unique across all elements in the result,
or Terraform will return an error.
Sometimes the resulting keys are _not_ unique, and so to support that situation
Terraform supports a special _grouping mode_ which changes the result to support
multiple elements per key.
To activate grouping mode, add the symbol `...` after the value expression.
For example:
```hcl
variable "users" {
type = map(object({
role = string
}))
}
locals {
users_by_role = {
for name, user in var.users : user.role => name...
}
}
```
The above represents a situation where a module expects a map describing
various users who each have a single "role", where the map keys are usernames.
The usernames are guaranteed unique because they are map keys in the input,
but many users may all share a single role name.
The `local.users_by_role` expression inverts the input map so that the keys
are the role names and the values are usernames, but the expression is in
grouping mode (due to the `...` after `name`) and so the result will be a
map of lists of strings, such as the following:
```hcl
{
"admin": [
"ps",
],
"maintainer": [
"am",
"jb",
"kl",
"ma",
],
"viewer": [
"st",
"zq",
],
}
```
Due to [the element ordering rules](#element-ordering), Terraform will sort
the users lexically by username as part of evaluating the `for` expression,
and so the usernames associated with each role will be lexically sorted
after grouping.
## Repeated Configuration Blocks
The `for` expressions mechanism is for constructing collection values from
other collection values within expressions, which you can then assign to
individual resource arguments that expect complex values.
Some resource types also define _nested block types_, which typically represent
separate objects that belong to the containing resource in some way. You can't
dynamically generated nested blocks using `for` expressions, but you _can_
generate nested blocks for a resource dynamically using
[`dynamic` blocks](dynamic-blocks.html).

48
website/docs/configuration/expressions/function-calls.html.md
View File

@ -30,6 +30,11 @@ min(55, 3453, 2)
A function call expression evaluates to the function's return value.
## Available Functions
For a full list of available functions, see
[the function reference](/docs/configuration/functions.html).
## Expanding Function Arguments
If the arguments to pass to a function are available in a list or tuple value,
@ -43,8 +48,45 @@ min([55, 2453, 2]...)
The expansion symbol is three periods (`...`), not a Unicode ellipsis character
(`…`). Expansion is a special syntax that is only available in function calls.
## Available Functions
## When Terraform Calls Functions
For a full list of available functions, see
[the function reference](/docs/configuration/functions.html).
Most of Terraform's built-in functions are, in programming language terms,
[pure functions](https://en.wikipedia.org/wiki/Pure_function). This means that
their result is based only on their arguments and so it doesn't make any
practical difference when Terraform would call them.
However, a small subset of functions interact with outside state and so for
those it can be helpful to know when Terraform will call them in relation to
other events that occur in a Terraform run.
The small set of special functions includes
[`file`](../functions/file.html),
[`templatefile`](../functions/templatefile.html),
[`timestamp`](../functions/timestamp.html),
and [`uuid`](../functions/uuid.html).
If you are not working with these functions then you don't need
to read this section, although the information here may still be interesting
background information.
The `file` and `templatefile` functions are intended for reading files that
are included as a static part of the configuration and so Terraform will
execute these functions as part of initial configuration validation, before
taking any other actions with the configuration. That means you cannot use
either function to read files that your configuration might generate
dynamically on disk as part of the plan or apply steps.
The `timestamp` function returns a representation of the current system time
at the point when Terraform calls it, and the `uuid` function returns a random
result which differs on each call. Without any special behavior these would
would both cause the final configuration during the apply step not to match the
actions shown in the plan, which violates the Terraform execution model.
For that reason, Terraform arranges for both of those functions to produce
[unknown value](references.html#values-not-yet-known) results during the
plan step, with the real result being decided only during the apply step.
For `timestamp` in particular, this means that the recorded time will be
the instant when Terraform began applying the change, rather than when
Terraform _planned_ the change.
For more details on the behavior of these functions, refer to their own
documentation pages.

29
website/docs/configuration/expressions/operators.html.md
View File

@ -30,15 +30,15 @@ in the following order of operations:
1. `&&`
1. `||`
Parentheses can be used to override the default order of operations. Without
parentheses, higher levels are evaluated first, so `1 + 2 * 3` is interpreted
as `1 + (2 * 3)` and _not_ as `(1 + 2) * 3`.
Use parentheses to override the default order of operations. Without
parentheses, higher levels will be evaluated first, so Terraform will interpret
`1 + 2 * 3` as `1 + (2 * 3)` and _not_ as `(1 + 2) * 3`.
The different operators can be gathered into a few different groups with
similar behavior, as described below. Each group of operators expects its
given values to be of a particular type. Terraform will attempt to convert
values to the required type automatically, or will produce an error message
if this automatic conversion is not possible.
if automatic conversion is impossible.
## Arithmetic Operators
@ -53,6 +53,11 @@ as results:
generally useful only when used with whole numbers.
* `-a` returns the result of multiplying `a` by `-1`.
Terraform supports some other less-common numeric operations as
[functions](function-calls.html). For example, you can calculate exponents
using
[the `pow` function](../functions/pow.html).
## Equality Operators
The equality operators both take two values of any type and produce boolean
@ -62,6 +67,18 @@ values as results.
value, or `false` otherwise.
* `a != b` is the opposite of `a == b`.
Because the equality operators require both arguments to be of exactly the
same type in order to decide equality, we recommend using these operators only
with values of primitive types or using explicit type conversion functions
to indicate which type you are intending to use for comparison.
Comparisons between structural types may produce surprising results if you
are not sure about the types of each of the arguments. For example,
`var.list == []` may seem like it would return `true` if `var.list` were an
empty list, but `[]` actually builds a value of type `tuple([])` and so the
two values can never match. In this situation it's often clearer to write
`length(var.list) == 0` instead.
## Comparison Operators
The comparison operators all expect number values and produce boolean values
@ -80,3 +97,7 @@ The logical operators all expect bool values and produce bool values as results.
* `a || b` returns `true` if either `a` or `b` is `true`, or `false` if both are `false`.
* `a && b` returns `true` if both `a` and `b` are `true`, or `false` if either one is `false`.
* `!a` returns `true` if `a` is `false`, and `false` if `a` is `true`.
Terraform does not have an operator for the "exclusive OR" operation. If you
know that both operators are boolean values then exclusive OR is equivalent
to the `!=` ("not equal") operator.

88
website/docs/configuration/expressions/references.html.md
View File

@ -60,24 +60,58 @@ For more information about how to use resource references, see
`var.<NAME>` is the value of the [input variable](/docs/configuration/variables.html) of the given name.
If the variable has a type constraint (`type` argument) as part of its
declaration, Terraform will automatically convert the caller's given value
to conform to the type constraint.
For that reason, you can safely assume that a reference using `var.` will
always produce a value that conforms to the type constraint, even if the caller
provided a value of a different type that was automatically converted.
In particular, note that if you define a variable as being of an object type
with particular attributes then only _those specific attributes_ will be
available in expressions elsewhere in the module, even if the caller actually
passed in a value with additional attributes. You must define in the type
constraint all of the attributes you intend to use elsewhere in your module.
### Local Values
`local.<NAME>` is the value of the [local value](/docs/configuration/locals.html) of the given name.
Local values can refer to other local values, even within the same `locals`
block, as long as you don't introduce circular dependencies.
### Child Module Outputs
* `module.<MODULE NAME>.<OUTPUT NAME>` is the value of the specified
[output value](/docs/configuration/outputs.html) from a
[child module](/docs/configuration/blocks/modules/index.html) called by the
current module.
`module.<MODULE NAME>` is an value representing the results of
[a `module` block](../blocks/modules/).
If the corresponding `module` block does not have either `count` nor `for_each`
set then the value will be an object with one attribute for each output value
defined in the child module. To access one of the module's
[output values](../outputs.html), use `module.<MODULE NAME>.<OUTPUT NAME>`.
If the corresponding `module` uses `for_each` then the value will be a map
of objects whose keys correspond with the keys in the `for_each` expression,
and whose values are each objects with one attribute for each output value
defined in the child module, each representing one module instance.
If the corresponding module uses `count` then the result is similar to for
`for_each` except that the value is a _list_ with the requested number of
elements, each one representing one module instance.
### Data Sources
* `data.<DATA TYPE>.<NAME>` is an object representing a
[data resource](/docs/configuration/data-sources.html) of the given data
source type and name. If the resource has the `count` argument set, the value
is a list of objects representing its instances. If the resource has the `for_each`
argument set, the value is a map of objects representing its instances.
`data.<DATA TYPE>.<NAME>` is an object representing a
[data resource](/docs/configuration/data-sources.html) of the given data
source type and name. If the resource has the `count` argument set, the value
is a list of objects representing its instances. If the resource has the `for_each`
argument set, the value is a map of objects representing its instances.
For more information, see
[References to Resource Attributes](#references-to-resource-attributes), which
also applies to data resources aside from the addition of the `data.` prefix
to mark the reference as for a data resource.
### Filesystem and Workspace Info
@ -91,6 +125,36 @@ For more information about how to use resource references, see
* `terraform.workspace` is the name of the currently selected
[workspace](/docs/state/workspaces.html).
Use the values in this section carefully, because they include information
about the context in which a configuration is being applied and so may
inadvertently hurt the portability or composability of a module.
For example, if you use `path.cwd` directly to populate a path into a resource
argument then later applying the same configuration from a different directory
or on a different computer with a different directory structure will cause
the provider to consider the change of path to be a change to be applied, even
if the path still refers to the same file.
Similarly, if you use any of these values as a form of namespacing in a shared
module, such as using `terraform.workspace` as a prefix for globally-unique
object names, it may not be possible to call your module more than once in
the same configuration.
Aside from `path.module`, we recommend using the values in this section only
in the root module of your configuration. If you are writing a shared module
which needs a prefix to help create unique names, define an input variable
for your module and allow the calling module to define the prefix. The
calling module can then use `terraform.workspace` to define it if appropriate,
or some other value if not:
```hcl
module "example" {
# ...
name_prefix = "app-${terraform-workspace}"
}
```
### Block-Local Values
Within the bodies of certain blocks, or in some other specific contexts,
@ -110,6 +174,12 @@ _temporary variables_ in their documentation. These are not [input
variables](/docs/configuration/variables.html); they are just arbitrary names
that temporarily represent a value.
The names in this section relate to top-level configuration blocks only.
If you use [`dynamic` blocks](dynamic-blocks.html) to dynamically generate
resource-type-specific _nested_ blocks within `resource` and `data` blocks then
you'll refer to the key and value of each element differently. See the
`dynamic` blocks documentation for details.
## Named Values and Dependencies
Constructs like resources and module calls often use references to named values

86
website/docs/configuration/expressions/splat.html.md
View File

@ -39,34 +39,75 @@ The above expression is equivalent to the following `for` expression:
[for o in var.list : o.interfaces[0].name]
```
Splat expressions are for lists only (and thus cannot be used [to reference resources
created with `for_each`](/docs/configuration/meta-arguments/for_each.html#referring-to-instances),
which are represented as maps in Terraform). However, if a splat expression is applied
to a value that is _not_ a list or tuple then the value is automatically wrapped in
a single-element list before processing.
## Splat Expressions with Maps
For example, `var.single_object[*].id` is equivalent to `[var.single_object][*].id`,
or effectively `[var.single_object.id]`. This behavior is not interesting in most cases,
but it is particularly useful when referring to resources that may or may
not have `count` set, and thus may or may not produce a tuple value:
The splat expression patterns shown above apply only to lists, sets, and
tuples. To get a similar result with a map or object value you must use
[`for` expressions](for.html).
```hcl
aws_instance.example[*].id
Resources that use the `for_each` argument will appear in expressions as a map
of objects, so you can't use splat expressions with those resources.
For more information, see
[Referring to Resource Instances](/docs/configuration/meta-arguments/for_each.html#referring-to-instances).
## Single Values as Lists
Splat expressions have a special behavior when you apply them to a value that
isn't a list, set, or tuple.
If the value is anything other than a null value then the splat expression will
transform it into a single-element list, or more accurately a single-element
tuple value. If the value is _null_ then the splat expression will return an
empty tuple.
This special behavior can be useful for modules that accept optional input
variables whose default value is `null` to represent the absense of any value,
to adapt the variable value to work with other Terraform language features that
are designed to work with collections. For example:
```
variable "website" {
type = object({
index_document = string
error_document = string
})
default = null
}
resource "aws_s3_bucket" "example" {
# ...
dynamic "website" {
for_each = var.website[*]
content {
index_document = website.value.index_document
error_document = website.value.error_document
}
}
}
```
The above will produce a list of ids whether `aws_instance.example` has
`count` set or not, avoiding the need to revise various other expressions
in the configuration when a particular resource switches to and from
having `count` set.
The above example uses a [`dynamic` block](dynamic-blocks.html), which
generates zero or more nested blocks based on a collection value. The input
variable `var.website` is defined as a single object that might be null,
so the `dynamic` block's `for_each` expression uses `[*]` to ensure that
there will be one block if the module caller sets the website argument, or
zero blocks if the caller leaves it set to null.
This special behavior of splat expressions is not obvious to an unfamiliar
reader, so we recommend using it only in `for_each` arguments and similar
situations where the context implies working with a collection. Otherwise,
the meaning of the expression may be unclear to future readers.
## Legacy (Attribute-only) Splat Expressions
An older variant of the splat expression is available for compatibility with
code written in older versions of the Terraform language. This is a less useful
version of the splat expression, and should be avoided in new configurations.
Earlier versions of the Terraform language had a slightly different version
of splat expressions, which Terraform continues to support for backward
compatibility. This older variant is less useful than the modern form described
above, and so we recommend against using it in new configurations.
An "attribute-only" splat expression is indicated by the sequence `.*` (instead
of `[*]`):
The legacy "attribute-only" splat expressions use the sequence `.*`, instead of
`[*]`:
```
var.list.*.interfaces[0].name
@ -81,4 +122,7 @@ This form has a subtly different behavior, equivalent to the following
Notice that with the attribute-only splat expression the index operation
`[0]` is applied to the result of the iteration, rather than as part of
the iteration itself.
the iteration itself. Only the attribute lookups apply to each element of
the input. This limitation was confusing some people using older versions of
Terraform and so we recommend always using the new-style splat expressions,
with `[*]`, to get the more consistent behavior.