terraform/website/docs/configuration/locals.html.md

layout	page_title	sidebar_current	description
docs	Configuring Local Values	docs-config-locals	Local values assign a name to an expression that can then be used multiple times within a module.

Local Value Configuration

Local values assign a name to an expression, that can then be used multiple times within a module.

Comparing modules to functions in a traditional programming language, if variables are analogous to function arguments and outputs are analogous to function return values then local values are comparable to a function's local variables.

This page assumes you're already familiar with the configuration syntax.

Examples

Local values are defined in locals blocks:

# Ids for multiple sets of EC2 instances, merged together
locals {
  instance_ids = "${concat(aws_instance.blue.*.id, aws_instance.green.*.id)}"
}

# A computed default name prefix
locals {
  default_name_prefix = "${var.project_name}-web"
  name_prefix         = "${var.name_prefix != "" ? var.name_prefix : local.default_name_prefix}"
}

# Local values can be interpolated elsewhere using the "local." prefix.
resource "aws_s3_bucket" "files" {
  bucket = "${local.name_prefix}-files"
  # ...
}

Named local maps can be merged with local maps to implement common or default values:

# Define the common tags for all resources
locals {
  common_tags = {
    Component   = "awesome-app"
    Environment = "production"
  }
}

# Create a resource that blends the common tags with instance-specific tags.
resource "aws_instance" "server" {
  ami           = "ami-123456"
  instance_type = "t2.micro"

  tags = "${merge(
    local.common_tags,
    map(
      "Name", "awesome-app-server",
      "Role", "server"
    )
  )}"
}

Description

The locals block defines one or more local variables within a module. Each locals block can have as many locals as needed, and there can be any number of locals blocks within a module.

The names given for the items in the locals block must be unique throughout a module. The given value can be any expression that is valid within the current module.

The expression of a local value can refer to other locals, but as usual reference cycles are not allowed. That is, a local cannot refer to itself or to a variable that refers (directly or indirectly) back to it.

It's recommended to group together logically-related local values into a single block, particularly if they depend on each other. This will help the reader understand the relationships between variables. Conversely, prefer to define unrelated local values in separate blocks, and consider annotating each block with a comment describing any context common to all of the enclosed locals.