IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-02-25 18:45:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

Update website/docs/language/values (#240)

Browse Source 
Signed-off-by: Marcin Białoń <mbialon@spacelift.io>
This commit is contained in:
Marcin Białoń 2023-08-30 00:00:58 +02:00 committed by GitHub
parent be5ce291f4
commit 566749d817
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
4 changed files with 92 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
website/docs/language/values/index.mdx
View File

@ -1,20 +1,19 @@
---
page_title: Variables and Outputs
description: >-
An overview of input variables, output values, and local values in Terraform
An overview of input variables, output values, and local values in OpenTF
language.
---
# Variables and Outputs
The Terraform language includes a few kinds of blocks for requesting or
The OpenTF language includes a few kinds of blocks for requesting or
publishing named values.
- [Input Variables](/terraform/language/values/variables) serve as parameters for
a Terraform module, so users can customize behavior without editing the source.
- [Input Variables](/opentf/language/values/variables) serve as parameters for
a module, so users can customize behavior without editing the source.
- [Output Values](/terraform/language/values/outputs) are like return values for a
Terraform module.
- [Output Values](/opentf/language/values/outputs) are like return values for a module.
- [Local Values](/terraform/language/values/locals) are a convenience feature for
- [Local Values](/opentf/language/values/locals) are a convenience feature for
assigning a short name to an expression.

14
website/docs/language/values/locals.mdx
View File

@ -2,22 +2,20 @@
page_title: Local Values - Configuration Language
description: >-
Local values assign a name to an expression that can be used multiple times
within a Terraform module.
within a module.
---
# Local Values
> **Hands-on:** Try the [Simplify Terraform Configuration with Locals](/terraform/tutorials/configuration-language/locals?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
A local value assigns a name to an [expression](/terraform/language/expressions),
A local value assigns a name to an [expression](/opentf/language/expressions),
so you can use the name multiple times within a module instead of repeating
the expression.
If you're familiar with traditional programming languages, it can be useful to
compare Terraform modules to function definitions:
compare modules to function definitions:
- [Input variables](/terraform/language/values/variables) are like function arguments.
- [Output values](/terraform/language/values/outputs) are like function return values.
- [Input variables](/opentf/language/values/variables) are like function arguments.
- [Output values](/opentf/language/values/outputs) are like function return values.
- Local values are like a function's temporary local variables.
-> **Note:** For brevity, local values are often referred to as just "locals"
@ -57,7 +55,7 @@ locals {
## Using Local Values
Once a local value is declared, you can reference it in
[expressions](/terraform/language/expressions) as `local.<NAME>`.
[expressions](/opentf/language/expressions) as `local.<NAME>`.
-> **Note:** Local values are _created_ by a `locals` block (plural), but you
_reference_ them as attributes on an object named `local` (singular). Make sure

48
website/docs/language/values/outputs.mdx
View File

@ -1,29 +1,25 @@
---
page_title: Output Values - Configuration Language
description: Output values are the return values of a Terraform module.
description: Output values are the return values of a module.
---
# Output Values
Output values make information about your infrastructure available on the
command line, and can expose information for other Terraform configurations to
command line, and can expose information for other OpenTF configurations to
use. Output values are similar to return values in programming languages.
> **Hands-on:** Try the [Output Data From
> Terraform](/terraform/tutorials/configuration-language/outputs)
> tutorial.
Output values have several uses:
- A child module can use outputs to expose a subset of its resource attributes
to a parent module.
- A root module can use outputs to print certain values in the CLI output after
running `terraform apply`.
- When using [remote state](/terraform/language/state/remote), root module outputs can be
running `opentf apply`.
- When using [remote state](/opentf/language/state/remote), root module outputs can be
accessed by other configurations via a
[`terraform_remote_state` data source](/terraform/language/state/remote-state-data).
[`terraform_remote_state` data source](/opentf/language/state/remote-state-data).
Resource instances managed by Terraform each export attributes whose values
Resource instances managed by OpenTF each export attributes whose values
can be used elsewhere in configuration. Output values are a way to expose some
of that information to the user of your module.
@ -42,18 +38,18 @@ output "instance_ip_addr" {
```
The label immediately after the `output` keyword is the name, which must be a
valid [identifier](/terraform/language/syntax/configuration#identifiers). In a root module, this name is
valid [identifier](/opentf/language/syntax/configuration#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](/terraform/language/expressions)
The `value` argument takes an [expression](/opentf/language/expressions)
whose result is to be returned to the user. In this example, the expression
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.
-> **Note:** Outputs are only rendered when Terraform applies your plan. Running
`terraform plan` will not render outputs.
-> **Note:** Outputs are only rendered when OpenTF applies your plan. Running
`opentf plan` will not render outputs.
## Accessing Child Module Outputs
@ -81,7 +77,7 @@ output "api_base_url" {
Custom conditions can help capture assumptions, helping future maintainers understand the configuration design and intent. They also return useful information about errors earlier and in context, helping consumers more easily diagnose issues in their configurations.
Refer to [Custom Condition Checks](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) for more details.
Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#preconditions-and-postconditions) for more details.
## Optional Arguments
@ -123,8 +119,8 @@ output "db_password" {
}
```
Terraform will hide values marked as sensitive in the messages from
`terraform plan` and `terraform apply`. In the following scenario, our root
OpenTF will hide values marked as sensitive in the messages from
`opentf plan` and `opentf apply`. In the following scenario, our root
module has an output declared as sensitive and a module call with a
sensitive output, which we then use in a resource attribute.
@ -155,7 +151,7 @@ output "a" {
When we run a plan or apply, the sensitive value is redacted from output:
```
Terraform will perform the following actions:
OpenTF will perform the following actions:
# test_instance.x will be created
+ resource "test_instance" "x" {
@ -168,16 +164,10 @@ Changes to Outputs:
+ out = (sensitive value)
```
-> **Note:** In Terraform versions prior to Terraform 0.14, setting an output
value in the root module as sensitive would prevent Terraform from showing its
value in the list of outputs at the end of `terraform apply`. However, the
value could still display in the CLI output for other reasons, like if the
value is referenced in an expression for a resource argument.
Terraform will still record sensitive values in the [state](/terraform/language/state),
OpenTF will still record sensitive values in the [state](/opentf/language/state),
and so anyone who can access the state data will have access to the sensitive
values in cleartext. For more information, see
[_Sensitive Data in State_](/terraform/language/state/sensitive-data).
[_Sensitive Data in State_](/opentf/language/state/sensitive-data).
<a id="depends_on"></a>
@ -188,13 +178,13 @@ usually not necessary to worry about their relationships with other nodes in
the dependency graph.
However, when a parent module accesses an output value exported by one of its
child modules, the dependencies of that output value allow Terraform to
child modules, the dependencies of that output value allow OpenTF to
correctly determine the dependencies between resources defined in different
modules.
Just as with
[resource dependencies](/terraform/language/resources/behavior#resource-dependencies),
Terraform analyzes the `value` expression for an output value and automatically
[resource dependencies](/opentf/language/resources/behavior#resource-dependencies),
OpenTF analyzes the `value` expression for an output value and automatically
determines a set of dependencies, but in less-common cases there are
dependencies that cannot be recognized implicitly. In these rare cases, the
`depends_on` argument can be used to create additional explicit dependencies:

137
website/docs/language/values/variables.mdx
View File

@ -7,30 +7,28 @@ description: >-
# Input Variables
> **Hands-on:** Try the [Customize Terraform Configuration with Variables](/terraform/tutorials/configuration-language/variables?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
Input variables let you customize aspects of Terraform modules without altering
Input variables let you customize aspects of modules without altering
the module's own source code. This functionality allows you to share modules across different
Terraform configurations, making your module composable and reusable.
OpenTF configurations, making your module composable and reusable.
When you declare variables in the root module of your configuration, you can
set their values using CLI options and environment variables.
When you declare them in [child modules](/terraform/language/modules),
When you declare them in [child modules](/opentf/language/modules),
the calling module should pass values in the `module` block.
If you're familiar with traditional programming languages, it can be useful to
compare Terraform modules to function definitions:
compare modules to function definitions:
* Input variables are like function arguments.
* [Output values](/terraform/language/values/outputs) are like function return values.
* [Local values](/terraform/language/values/locals) are like a function's temporary local variables.
* [Output values](/opentf/language/values/outputs) are like function return values.
* [Local values](/opentf/language/values/locals) are like a function's temporary local variables.
-> **Note:** For brevity, input variables are often referred to as just
"variables" or "Terraform variables" when it is clear from context what sort of
variable is being discussed. Other kinds of variables in Terraform include
_environment variables_ (set by the shell where Terraform runs) and _expression
"variables" or "OpenTF variables" when it is clear from context what sort of
variable is being discussed. Other kinds of variables in OpenTF include
_environment variables_ (set by the shell where OpenTF runs) and _expression
variables_ (used to indirectly represent a value in an
[expression](/terraform/language/expressions)).
[expression](/opentf/language/expressions)).
## Declaring an Input Variable
@ -68,22 +66,22 @@ be unique among all variables in the same module. This name is used to
assign a value to the variable from outside and to reference the variable's
value from within the module.
The name of a variable can be any valid [identifier](/terraform/language/syntax/configuration#identifiers)
The name of a variable can be any valid [identifier](/opentf/language/syntax/configuration#identifiers)
_except_ the following: `source`, `version`, `providers`, `count`, `for_each`, `lifecycle`, `depends_on`, `locals`.
These names are reserved for meta-arguments in
[module configuration blocks](/terraform/language/modules/syntax), and cannot be
[module configuration blocks](/opentf/language/modules/syntax), and cannot be
declared as variable names.
## Arguments
Terraform CLI defines the following optional arguments for variable declarations:
OpenTF CLI defines the following optional arguments for variable declarations:
* [`default`][inpage-default] - A default value which then makes the variable optional.
* [`type`][inpage-type] - This argument specifies what value types are accepted for the variable.
* [`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.
* [`sensitive`][inpage-sensitive] - Limits OpenTF UI output when the variable is used in configuration.
* [`nullable`][inpage-nullable] - Specify if the variable can be `null` within the module.
### Default values
@ -92,7 +90,7 @@ Terraform CLI defines the following optional arguments for variable declarations
The variable declaration can also include a `default` argument. If present,
the variable is considered to be _optional_ and the default value will be used
if no value is set when calling the module or running Terraform. The `default`
if no value is set when calling the module or running OpenTF. The `default`
argument requires a literal value and cannot reference other objects in the
configuration.
@ -101,13 +99,13 @@ configuration.
[inpage-type]: #type-constraints
The `type` argument in a `variable` block allows you to restrict the
[type of value](/terraform/language/expressions/types) that will be accepted as
[type of value](/opentf/language/expressions/types) that will be accepted as
the value for a variable. If no type constraint is set then a value of any type
is accepted.
While type constraints are optional, we recommend specifying them; they
can serve as helpful reminders for users of the module, and they
allow Terraform to return a helpful error message if the wrong type is used.
allow OpenTF to return a helpful error message if the wrong type is used.
Type constraints are created from a mixture of type keywords and type
constructors. The supported type keywords are:
@ -128,7 +126,7 @@ collections:
The keyword `any` may be used to indicate that any type is acceptable. For
more information on the meaning and behavior of these different types, as well
as detailed information about automatic conversion of complex types, see
[Type Constraints](/terraform/language/expressions/types).
[Type Constraints](/opentf/language/expressions/types).
If both the `type` and `default` arguments are specified, the given default
value must be convertible to the specified type.
@ -158,8 +156,6 @@ commentary for module maintainers, use comments.
[inpage-validation]: #custom-validation-rules
-> This feature was introduced in Terraform CLI v0.13.0.
You can specify custom validation rules for a particular variable by adding a `validation` block within the corresponding `variable` block. The example below checks whether the AMI ID has the correct syntax.
```hcl
@ -173,24 +169,20 @@ variable "image_id" {
}
}
```
Refer to [Custom Condition Checks](/terraform/language/expressions/custom-conditions#input-variable-validation) for more details.
Refer to [Custom Condition Checks](/opentf/language/expressions/custom-conditions#input-variable-validation) for more details.
### Suppressing Values in CLI Output
[inpage-sensitive]: #suppressing-values-in-cli-output
-> This feature was introduced in Terraform v0.14.0.
> **Hands-on:** Try the [Protect Sensitive Input Variables](/terraform/tutorials/configuration-language/sensitive-variables?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial.
Setting a variable as `sensitive` prevents Terraform from showing its value in
Setting a variable as `sensitive` prevents OpenTF from showing its value in
the `plan` or `apply` output, when you use that variable elsewhere in your
configuration.
Terraform will still record sensitive values in the [state](/terraform/language/state),
OpenTF will still record sensitive values in the [state](/opentf/language/state),
and so anyone who can access the state data will have access to the sensitive
values in cleartext. For more information, see
[_Sensitive Data in State_](/terraform/language/state/sensitive-data).
[_Sensitive Data in State_](/opentf/language/state/sensitive-data).
Declare a variable as sensitive by setting the `sensitive` argument to `true`:
@ -214,7 +206,7 @@ as sensitive themselves, and so in the above example the two arguments of
`resource "some_resource" "a"` will also be hidden in the plan output:
```
Terraform will perform the following actions:
OpenTF will perform the following actions:
# some_resource.a will be created
+ resource "some_resource" "a" {
@ -225,7 +217,7 @@ Terraform will perform the following actions:
Plan: 1 to add, 0 to change, 0 to destroy.
```
In some cases where you use a sensitive variable inside a nested block, Terraform
In some cases where you use a sensitive variable inside a nested block, OpenTF
may treat the entire block as redacted. This happens for resource types where
all of the blocks of a particular type are required to be unique, and so
disclosing the content of one block might imply the content of a sibling block.
@ -241,17 +233,17 @@ disclosing the content of one block might imply the content of a sibling block.
```
A provider can also
[declare an attribute as sensitive](/terraform/plugin/sdkv2/best-practices/sensitive-state#using-the-sensitive-flag),
which will cause Terraform to hide it from regular output regardless of how
[declare an attribute as sensitive](/opentf/plugin/sdkv2/best-practices/sensitive-state#using-the-sensitive-flag),
which will cause OpenTF to hide it from regular output regardless of how
you assign it a value. For more information, see
[Sensitive Resource Attributes](/terraform/language/expressions/references#sensitive-resource-attributes).
[Sensitive Resource Attributes](/opentf/language/expressions/references#sensitive-resource-attributes).
If you use a sensitive value as part of an
[output value](/terraform/language/values/outputs) then Terraform will require
[output value](/opentf/language/values/outputs) then OpenTF will require
you to also mark the output value itself as sensitive, to confirm that you
intended to export it.
#### Cases where Terraform may disclose a sensitive variable
#### Cases where OpenTF may disclose a sensitive variable
A `sensitive` variable is a configuration-centered concept, and values are sent to providers without any obfuscation. A provider error could disclose a value if that value is included in the error message. For example, a provider might return the following error even if "foo" is a sensitive value: `"Invalid value 'foo' for field"`
@ -278,8 +270,6 @@ random_pet.animal: Creation complete after 0s [id=jae-known-mongoose]
[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.
@ -297,7 +287,7 @@ account for the possibility of the variable value being `null`. Passing a
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`.
`default` value, then OpenTF 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,
@ -307,7 +297,7 @@ 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
within [expressions](/terraform/language/expressions) as `var.<NAME>`,
within [expressions](/opentf/language/expressions) as `var.<NAME>`,
where `<NAME>` matches the label given in the declaration block:
-> **Note:** Input variables are _created_ by a `variable` block, but you
@ -328,7 +318,6 @@ the module where it was declared.
When variables are declared in the root module of your configuration, they
can be set in a number of ways:
* [In a Terraform Cloud workspace](/terraform/cloud-docs/workspaces/variables).
* Individually, with the `-var` command line option.
* In variable definitions (`.tfvars`) files, either specified on the command line
or automatically loaded.
@ -337,23 +326,23 @@ can be set in a number of ways:
The following sections describe these options in more detail. This section does
not apply to _child_ modules, where values for input variables are instead
assigned in the configuration of their parent module, as described in
[_Modules_](/terraform/language/modules).
[_Modules_](/opentf/language/modules).
### Variables on the Command Line
To specify individual variables on the command line, use the `-var` option
when running the `terraform plan` and `terraform apply` commands:
when running the `opentf plan` and `opentf apply` commands:
```
terraform apply -var="image_id=ami-abc123"
terraform apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_type=t2.micro"
terraform apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'
opentf apply -var="image_id=ami-abc123"
opentf apply -var='image_id_list=["ami-abc123","ami-def456"]' -var="instance_type=t2.micro"
opentf apply -var='image_id_map={"us-east-1":"ami-abc123","us-east-2":"ami-def456"}'
```
The above examples show appropriate syntax for Unix-style shells, such as on
Linux or macOS. For more information on shell quoting, including additional
examples for Windows Command Prompt, see
[Input Variables on the Command Line](/terraform/cli/commands/plan#input-variables-on-the-command-line).
[Input Variables on the Command Line](/opentf/cli/commands/plan#input-variables-on-the-command-line).
You can use the `-var` option multiple times in a single command to set several
different variables.
@ -368,13 +357,10 @@ or `.tfvars.json`) and then specify that file on the command line with
`-var-file`:
```
terraform apply -var-file="testing.tfvars"
opentf apply -var-file="testing.tfvars"
```
-> **Note:** This is how Terraform Cloud passes
[workspace variables](/terraform/cloud-docs/workspaces/variables) to Terraform.
A variable definitions file uses the same basic syntax as Terraform language
A variable definitions file uses the same basic syntax as OpenTF language
files, but consists only of variable name assignments:
```hcl
@ -385,7 +371,7 @@ availability_zone_names = [
]
```
Terraform also automatically loads a number of variable definitions files
OpenTF also automatically loads a number of variable definitions files
if they are present:
* Files named exactly `terraform.tfvars` or `terraform.tfvars.json`.
@ -403,43 +389,43 @@ the root object properties corresponding to variable names:
### Environment Variables
As a fallback for the other ways of defining variables, Terraform searches
As a fallback for the other ways of defining variables, OpenTF searches
the environment of its own process for environment variables named `TF_VAR_`
followed by the name of a declared variable.
This can be useful when running Terraform in automation, or when running a
sequence of Terraform commands in succession with the same variables.
This can be useful when running OpenTF in automation, or when running a
sequence of OpenTF commands in succession with the same variables.
For example, at a `bash` prompt on a Unix system:
```
$ export TF_VAR_image_id=ami-abc123
$ terraform plan
$ opentf plan
...
```
On operating systems where environment variable names are case-sensitive,
Terraform matches the variable name exactly as given in configuration, and
OpenTF matches the variable name exactly as given in configuration, and
so the required environment variable name will usually have a mix of upper
and lower case letters as in the above example.
### Complex-typed Values
When variable values are provided in a variable definitions file, you can use
Terraform's usual syntax for
[literal expressions](/terraform/language/expressions/types#literal-expressions)
OpenTF's usual syntax for
[literal expressions](/opentf/language/expressions/types#literal-expressions)
to assign complex-typed values, like lists and maps.
Some special rules apply to the `-var` command line option and to environment
variables. For convenience, Terraform defaults to interpreting `-var` and
variables. For convenience, OpenTF defaults to interpreting `-var` and
environment variable values as literal strings, which need only shell quoting,
and no special quoting for Terraform. For example, in a Unix-style shell:
and no special quoting for OpenTF. For example, in a Unix-style shell:
```
$ export TF_VAR_image_id='ami-abc123'
```
However, if a root module variable uses a [type constraint](#type-constraints)
to require a complex value (list, set, map, object, or tuple), Terraform will
to require a complex value (list, set, map, object, or tuple), OpenTF will
instead attempt to parse its value using the same syntax used within variable
definitions files, which requires careful attention to the string escaping rules
in your shell:
@ -452,7 +438,7 @@ For readability, and to avoid the need to worry about shell escaping, we
recommend always setting complex variable values via variable definitions files.
For more information on quoting and escaping for `-var` arguments,
see
[Input Variables on the Command Line](/terraform/cli/commands/plan#input-variables-on-the-command-line).
[Input Variables on the Command Line](/opentf/cli/commands/plan#input-variables-on-the-command-line).
### Values for Undeclared Variables
@ -469,7 +455,7 @@ you will get a warning. This is to help in cases where you have provided a varia
value _meant_ for a variable declaration, but perhaps there is a mistake in the
value definition. For example, the following configuration:
```terraform
```hcl
variable "moose" {
type = string
}
@ -481,25 +467,25 @@ And the following `.tfvars` file:
mosse = "Moose"
```
Will cause Terraform to warn you that there is no variable declared `"mosse"`, which can help
Will cause OpenTF to warn you that there is no variable declared `"mosse"`, which can help
you spot this mistake.
If you use `.tfvars` files across multiple configurations and expect to continue to see this warning,
you can use the [`-compact-warnings`](/terraform/cli/commands/plan#compact-warnings)
you can use the [`-compact-warnings`](/opentf/cli/commands/plan#compact-warnings)
option to simplify your output.
If you provide values for undeclared variables on the [command line](#variables-on-the-command-line),
Terraform will return an error. To avoid this error, either declare a variable block for the value, or remove
the variable value from your Terraform call.
OpenTF will return an error. To avoid this error, either declare a variable block for the value, or remove
the variable value from your OpenTF call.
### Variable Definition Precedence
The above mechanisms for setting variables can be used together in any
combination. If the same variable is assigned multiple values, Terraform uses
combination. If the same variable is assigned multiple values, OpenTF uses
the _last_ value it finds, overriding any previous values. Note that the same
variable cannot be assigned multiple values within a single source.
Terraform loads variables in the following order, with later sources taking
OpenTF loads variables in the following order, with later sources taking
precedence over earlier ones:
* Environment variables
@ -508,10 +494,9 @@ precedence over earlier ones:
* Any `*.auto.tfvars` or `*.auto.tfvars.json` files, processed in lexical order
of their filenames.
* Any `-var` and `-var-file` options on the command line, in the order they
are provided. (This includes variables set by a Terraform Cloud
workspace.)
are provided.
~> **Important:** In Terraform 0.12 and later, variables with map and object
~> **Important:** Variables with map and object
values behave the same way as other variables: the last value found overrides
the previous values. This is a change from previous versions of Terraform, which
the previous values. This is a change from previous versions of OpenTF, which
would _merge_ map values instead of overriding them.