website: Expand output values docs (#20790)
For 0.11 I just specified the naming rules; for 0.12, I added some info about referencing values and tightened up the layout of the optional arguments. This commit also syncs up descriptions of `depends_on`.
This commit is contained in:
parent
53cff99f84
commit
428a2c05e7
|
@ -53,8 +53,8 @@ output "addresses" {
|
||||||
The `output` block configures a single output variable. Multiple
|
The `output` block configures a single output variable. Multiple
|
||||||
output variables can be configured with multiple output blocks.
|
output variables can be configured with multiple output blocks.
|
||||||
The `NAME` given to the output block is the name used to reference
|
The `NAME` given to the output block is the name used to reference
|
||||||
the output variable. It must conform to Terraform variable naming
|
the output variable, and can include letters, numbers, underscores (`_`),
|
||||||
conventions if it is to be used as an input to other modules.
|
and hyphens (`-`).
|
||||||
|
|
||||||
Within the block (the `{ }`) is configuration for the output.
|
Within the block (the `{ }`) is configuration for the output.
|
||||||
These are the parameters that can be set:
|
These are the parameters that can be set:
|
||||||
|
|
|
@ -41,9 +41,10 @@ output "instance_ip_addr" {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
The label immediately after the `output` keyword is the name that can be used
|
The label immediately after the `output` keyword is the name, which must be a
|
||||||
to access this output in the parent module, if any, or the name that will be
|
valid [identifier](./syntax.html#identifiers). In a root module, this name is
|
||||||
displayed to the user for output values in the root module.
|
displayed to the user; in a child module, it can be used to access the output's
|
||||||
|
value.
|
||||||
|
|
||||||
The `value` argument takes an [expression](./expressions.html)
|
The `value` argument takes an [expression](./expressions.html)
|
||||||
whose result is to be returned to the user. In this example, the expression
|
whose result is to be returned to the user. In this example, the expression
|
||||||
|
@ -51,10 +52,18 @@ refers to the `private_ip` attribute exposed by an `aws_instance` resource
|
||||||
defined elsewhere in this module (not shown). Any valid expression is allowed
|
defined elsewhere in this module (not shown). Any valid expression is allowed
|
||||||
as an output value.
|
as an output value.
|
||||||
|
|
||||||
Several other optional arguments are allowed within `output` blocks. These
|
## Accessing Child Module Outputs
|
||||||
will be described in the following sections.
|
|
||||||
|
|
||||||
## Output Value Documentation
|
In a parent module, outputs of child modules are available in expressions as
|
||||||
|
`module.<MODULE NAME>.<OUTPUT NAME>`. For example, if a child module named
|
||||||
|
`web_server` declared an output named `instance_ip_addr`, you could access that
|
||||||
|
value as `module.web_server.instance_ip_addr`.
|
||||||
|
|
||||||
|
## Optional Arguments
|
||||||
|
|
||||||
|
`output` blocks can optionally include `description`, `sensitive`, and `depends_on` arguments, which are described in the following sections.
|
||||||
|
|
||||||
|
### `description` — Output Value Documentation
|
||||||
|
|
||||||
Because the output values of a module are part of its user interface, you can
|
Because the output values of a module are part of its user interface, you can
|
||||||
briefly describe the purpose of each value using the optional `description`
|
briefly describe the purpose of each value using the optional `description`
|
||||||
|
@ -73,7 +82,7 @@ string might be included in documentation about the module, and so it should be
|
||||||
written from the perspective of the user of the module rather than its
|
written from the perspective of the user of the module rather than its
|
||||||
maintainer. For commentary for module maintainers, use comments.
|
maintainer. For commentary for module maintainers, use comments.
|
||||||
|
|
||||||
## Sensitive Output Values
|
### `sensitive` — Suppressing Values in CLI Output
|
||||||
|
|
||||||
An output can be marked as containing sensitive material using the optional
|
An output can be marked as containing sensitive material using the optional
|
||||||
`sensitive` argument:
|
`sensitive` argument:
|
||||||
|
@ -96,7 +105,7 @@ Sensitive output values are still recorded in the
|
||||||
to access the state data. For more information, see
|
to access the state data. For more information, see
|
||||||
[_Sensitive Data in State_](/docs/state/sensitive-data.html).
|
[_Sensitive Data in State_](/docs/state/sensitive-data.html).
|
||||||
|
|
||||||
## Output Dependencies
|
### `depends_on` — Explicit Output Dependencies
|
||||||
|
|
||||||
Since output values are just a means for passing data out of a module, it is
|
Since output values are just a means for passing data out of a module, it is
|
||||||
usually not necessary to worry about their relationships with other nodes in
|
usually not necessary to worry about their relationships with other nodes in
|
||||||
|
|
|
@ -134,8 +134,8 @@ However, some dependencies cannot be recognized implicitly in configuration. For
|
||||||
example, if Terraform must manage access control policies _and_ take actions
|
example, if Terraform must manage access control policies _and_ take actions
|
||||||
that require those policies to be present, there is a hidden dependency between
|
that require those policies to be present, there is a hidden dependency between
|
||||||
the access policy and a resource whose creation depends on it. In these rare
|
the access policy and a resource whose creation depends on it. In these rare
|
||||||
cases, [the `depends_on` meta-argument](#depends_on-hidden-resource-dependencies)
|
cases, [the `depends_on` meta-argument][inpage-depend] can explicitly specify a
|
||||||
can explicitly specify a dependency.
|
dependency.
|
||||||
|
|
||||||
## Meta-Arguments
|
## Meta-Arguments
|
||||||
|
|
||||||
|
@ -151,14 +151,16 @@ any resource type to change the behavior of resources:
|
||||||
These arguments often have additional restrictions on what language features can
|
These arguments often have additional restrictions on what language features can
|
||||||
be used with them, which are described in each
|
be used with them, which are described in each
|
||||||
|
|
||||||
### `depends_on`: Hidden Resource Dependencies
|
### `depends_on`: Explicit Resource Dependencies
|
||||||
|
|
||||||
[inpage-depend]: #depends_on-hidden-resource-dependencies
|
[inpage-depend]: #depends_on-explicit-resource-dependencies
|
||||||
|
|
||||||
Use the `depends_on` meta-argument to handle hidden resource dependencies that
|
Use the `depends_on` meta-argument to handle hidden resource dependencies that
|
||||||
Terraform can't automatically infer. Hidden dependencies happen when a resource
|
Terraform can't automatically infer.
|
||||||
relies on some other resource's behavior but _doesn't_ access any of that
|
|
||||||
resource's data in its arguments.
|
Explicitly specifying a dependency is only necessary when a resource relies on
|
||||||
|
some other resource's behavior but _doesn't_ access any of that resource's data
|
||||||
|
in its arguments.
|
||||||
|
|
||||||
This argument is available in all `resource` blocks, regardless of resource
|
This argument is available in all `resource` blocks, regardless of resource
|
||||||
type. For example:
|
type. For example:
|
||||||
|
|
Loading…
Reference in New Issue