github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/language/values/locals.html.md (about)

     1  ---
     2  layout: "language"
     3  page_title: "Local Values - Configuration Language"
     4  sidebar_current: "docs-config-locals"
     5  description: |-
     6    Local values assign a name to an expression that can then be used multiple times
     7    within a module.
     8  ---
     9  
    10  # Local Values
    11  
    12  > **Hands-on:** Try the [Simplify Terraform Configuration with
    13  Locals](https://learn.hashicorp.com/tutorials/terraform/locals?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
    14  tutorial on HashiCorp Learn.
    15  
    16  A local value assigns a name to an [expression](/docs/language/expressions/index.html),
    17  so you can use it multiple times within a module without repeating
    18  it.
    19  
    20  If you're familiar with traditional programming languages, it can be useful to
    21  compare Terraform modules to function definitions:
    22  
    23  - [Input variables](./variables.html) are like function arguments.
    24  - [Output values](./outputs.html) are like function return values.
    25  - Local values are like a function's temporary local variables.
    26  
    27  -> **Note:** For brevity, local values are often referred to as just "locals"
    28  when the meaning is clear from context.
    29  
    30  ## Declaring a Local Value
    31  
    32  A set of related local values can be declared together in a single `locals`
    33  block:
    34  
    35  ```hcl
    36  locals {
    37    service_name = "forum"
    38    owner        = "Community Team"
    39  }
    40  ```
    41  
    42  The expressions in local values are not limited to literal constants; they can
    43  also reference other values in the module in order to transform or combine them,
    44  including variables, resource attributes, or other local values:
    45  
    46  ```hcl
    47  locals {
    48    # Ids for multiple sets of EC2 instances, merged together
    49    instance_ids = concat(aws_instance.blue.*.id, aws_instance.green.*.id)
    50  }
    51  
    52  locals {
    53    # Common tags to be assigned to all resources
    54    common_tags = {
    55      Service = local.service_name
    56      Owner   = local.owner
    57    }
    58  }
    59  ```
    60  
    61  ## Using Local Values
    62  
    63  Once a local value is declared, you can reference it in
    64  [expressions](/docs/language/expressions/index.html) as `local.<NAME>`.
    65  
    66  -> **Note:** Local values are _created_ by a `locals` block (plural), but you
    67  _reference_ them as attributes on an object named `local` (singular). Make sure
    68  to leave off the "s" when referencing a local value!
    69  
    70  ```
    71  resource "aws_instance" "example" {
    72    # ...
    73  
    74    tags = local.common_tags
    75  }
    76  ```
    77  
    78  A local value can only be accessed in expressions within the module where it
    79  was declared.
    80  
    81  ## When To Use Local Values
    82  
    83  Local values can be helpful to avoid repeating the same values or expressions
    84  multiple times in a configuration, but if overused they can also make a
    85  configuration hard to read by future maintainers by hiding the actual values
    86  used.
    87  
    88  Use local values only in moderation, in situations where a single value or
    89  result is used in many places _and_ that value is likely to be changed in
    90  future. The ability to easily change the value in a central place is the key
    91  advantage of local values.