mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-04-04 12:01:49 -04:00
57057aef27
Signed-off-by: Andrei Ciobanu <andrei.ciobanu@opentofu.org> Signed-off-by: Christian Mesh <christianmesh1@gmail.com> Co-authored-by: Christian Mesh <christianmesh1@gmail.com> Co-authored-by: Diógenes Fernandes <diofeher@opentofu.org> Signed-off-by: Christian Mesh <christianmesh1@gmail.com>
124 lines
3.7 KiB
Plaintext
124 lines
3.7 KiB
Plaintext
---
|
|
description: >-
|
|
Local values assign a name to an expression that can be used multiple times
|
|
within a module.
|
|
---
|
|
|
|
# Local Values
|
|
|
|
A local value assigns a name to an [expression](../../language/expressions/index.mdx),
|
|
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 modules to function definitions:
|
|
|
|
- [Input variables](../../language/values/variables.mdx) are like function arguments.
|
|
- [Output values](../../language/values/outputs.mdx) 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"
|
|
when the meaning is clear from context.
|
|
:::
|
|
|
|
## Declaring a Local Value
|
|
|
|
A set of related local values can be declared together in a single `locals`
|
|
block:
|
|
|
|
```hcl
|
|
locals {
|
|
service_name = "forum"
|
|
owner = "Community Team"
|
|
}
|
|
```
|
|
|
|
The expressions in local values are not limited to literal constants; they can
|
|
also reference other values in the module in order to transform or combine them,
|
|
including variables, resource attributes, or other local values:
|
|
|
|
```hcl
|
|
locals {
|
|
# Ids for multiple sets of EC2 instances, merged together
|
|
instance_ids = concat(aws_instance.blue.*.id, aws_instance.green.*.id)
|
|
}
|
|
|
|
locals {
|
|
# Common tags to be assigned to all resources
|
|
common_tags = {
|
|
Service = local.service_name
|
|
Owner = local.owner
|
|
}
|
|
}
|
|
```
|
|
|
|
## Using Local Values
|
|
|
|
Once a local value is declared, you can reference it in
|
|
[expressions](../../language/expressions/index.mdx) 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
|
|
to leave off the "s" when referencing a local value!
|
|
:::
|
|
|
|
```
|
|
resource "aws_instance" "example" {
|
|
# ...
|
|
|
|
tags = local.common_tags
|
|
}
|
|
```
|
|
|
|
A local value can only be accessed in expressions within the module where it
|
|
was declared.
|
|
|
|
## When To Use Local Values
|
|
|
|
Local values can be helpful to avoid repeating the same values or expressions
|
|
multiple times in a configuration, but if overused they can also make a
|
|
configuration hard to read by future maintainers by hiding the actual values
|
|
used.
|
|
|
|
Use local values only in moderation, in situations where a single value or
|
|
result is used in many places _and_ that value is likely to be changed in
|
|
future. The ability to easily change the value in a central place is the key
|
|
advantage of local values.
|
|
|
|
## Ephemerality
|
|
|
|
A local value can be computed by evaluating an expressions which contains ephemeral values.
|
|
If so, the local value will be allowed to be used only in other ephemeral contexts:
|
|
* [Ephemeral Resources](../ephemerality/ephemeral-resources.mdx)
|
|
* [Ephemeral Variables](../values/variables.mdx#ephemerality)
|
|
* [Ephemeral Outputs](../values/outputs.mdx#ephemerality)
|
|
* [Locals](../values/locals.mdx#ephemerality)
|
|
* [Providers](../providers/configuration.mdx)
|
|
* [Provisioners](../resources/provisioners/syntax.mdx#suppressing-provisioner-logs-in-cli-output)
|
|
* [Resource `connection` blocks](../resources/provisioners/connection.mdx#ephemeral-usage)
|
|
* [Resource `write-only` attributes](../ephemerality/write-only-attributes.mdx)
|
|
|
|
:::note
|
|
Any inclusion of an ephemeral value in an expression will make the local value ephemeral. Some examples:
|
|
```
|
|
variable "var1" {
|
|
type = string
|
|
}
|
|
|
|
variable "var2" {
|
|
type = string
|
|
ephemeral = true
|
|
}
|
|
|
|
locals {
|
|
l1 = var.var1 == "" ? "" : var.var1 // => not ephemeral
|
|
l2 = var.var2 // => ephemeral
|
|
l3 = var.var2 == "" ? "" : var.var1 // => ephemeral
|
|
}
|
|
```
|
|
:::
|
|
|
|
For an in-depth example on how to use ephemeral locals, please refer to [this example](../ephemerality/index.mdx#usage-example).
|