From 428a2c05e72f7e2177b61c3948548769a791c965 Mon Sep 17 00:00:00 2001 From: Nick Fagerlund Date: Fri, 22 Mar 2019 15:08:55 -0700 Subject: [PATCH] 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`. --- .../docs/configuration-0-11/outputs.html.md | 4 +-- website/docs/configuration/outputs.html.md | 25 +++++++++++++------ website/docs/configuration/resources.html.md | 16 ++++++------ 3 files changed, 28 insertions(+), 17 deletions(-) diff --git a/website/docs/configuration-0-11/outputs.html.md b/website/docs/configuration-0-11/outputs.html.md index 343acc48f..7686c44a5 100644 --- a/website/docs/configuration-0-11/outputs.html.md +++ b/website/docs/configuration-0-11/outputs.html.md @@ -53,8 +53,8 @@ output "addresses" { The `output` block configures a single output variable. Multiple output variables can be configured with multiple output blocks. The `NAME` given to the output block is the name used to reference -the output variable. It must conform to Terraform variable naming -conventions if it is to be used as an input to other modules. +the output variable, and can include letters, numbers, underscores (`_`), +and hyphens (`-`). Within the block (the `{ }`) is configuration for the output. These are the parameters that can be set: diff --git a/website/docs/configuration/outputs.html.md b/website/docs/configuration/outputs.html.md index 1e28ba280..a0c270154 100644 --- a/website/docs/configuration/outputs.html.md +++ b/website/docs/configuration/outputs.html.md @@ -41,9 +41,10 @@ output "instance_ip_addr" { } ``` -The label immediately after the `output` keyword is the name that can be used -to access this output in the parent module, if any, or the name that will be -displayed to the user for output values in the root module. +The label immediately after the `output` keyword is the name, which must be a +valid [identifier](./syntax.html#identifiers). In a root module, this name is +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) 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 as an output value. -Several other optional arguments are allowed within `output` blocks. These -will be described in the following sections. +## Accessing Child Module Outputs -## Output Value Documentation +In a parent module, outputs of child modules are available in expressions as +`module..`. 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 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 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 `sensitive` argument: @@ -96,7 +105,7 @@ Sensitive output values are still recorded in the to access the state data. For more information, see [_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 usually not necessary to worry about their relationships with other nodes in diff --git a/website/docs/configuration/resources.html.md b/website/docs/configuration/resources.html.md index 1f0cad1a1..fdf5680de 100644 --- a/website/docs/configuration/resources.html.md +++ b/website/docs/configuration/resources.html.md @@ -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 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 -cases, [the `depends_on` meta-argument](#depends_on-hidden-resource-dependencies) -can explicitly specify a dependency. +cases, [the `depends_on` meta-argument][inpage-depend] can explicitly specify a +dependency. ## 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 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 -Terraform can't automatically infer. Hidden dependencies happen when a resource -relies on some other resource's behavior but _doesn't_ access any of that -resource's data in its arguments. +Terraform can't automatically infer. + +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 type. For example: