locals block reference

Use the locals block to define values and reuse them within a Terraform module.

Hands-on: Try the Simplify Terraform Configuration with Locals tutorial.

Background

The locals block is similar to function-scoped variables in other programming languages. Local values assign names to expressions, letting you use the name multiple times within a module instead of repeating the expression.

You can define local values in any module. Local values can be any valid Terraform expression, and can reference variables, resource attributes, function outputs, or other local values to transform or combine data.

To learn more about using locals blocks in your configurations, refer to Define locals to reuse expressions.

Configuration model

The locals block supports assigning a name to an expression:

• locals   block
  • <LOCAL_NAME> = <EXPRESSION>   assignment

Complete configuration

The locals block supports assigning names to expressions:

locals {
  <LOCAL_NAME> = <EXPRESSION>
  <OTHER_LOCAL_NAME> = <OTHER_EXPRESSION>
}

Specification

A locals block supports the following configuration.

locals

You can define any number of temporary values within a module using a locals block. You can declare multiple locals blocks in a single module, Terraform treats them as if they were all defined in a single block.

locals {
  value_name = <expression>
}

locals {
  other_value_name = <other_expression>
}

Local value names must be valid identifiers. You can assign any valid Terraform expression as a locals value, and can include references to variables, resources, data sources, or other local values.

Summary

• Data type: Block
• Required: Must assign at least one value for each locals block you define.
• Example: Basic locals example

Examples

The following examples demonstrate common use cases for locals blocks.

Basic locals example

In the following example, the locals block defines local values for service metadata, then the aws_instance resource references those values using local.<value_name> syntax:

locals {
  service_name = "forum"
  owner        = "community-team"
  environment  = "production"
}

resource "aws_instance" "web" {
  ami           = "ami-12345678"
  instance_type = "t3.micro"

  tags = {
    Name        = local.service_name
    Owner       = local.owner
    Environment = local.environment
  }
}

The locals block defines local values, but you reference them as attributes on an object named local, which is singular. You can access local values in the module where you define them, but not in other modules.

Combine and transform data

In the following example, local.instance_ids combines instance IDs from two different resource lists with the concat function. The local.common_tags value is a map that references other local values and variables.

locals {
  instance_ids = concat(aws_instance.blue[*].id, aws_instance.green[*].id)

  common_tags = {
    Service     = local.service_name
    Owner       = local.owner
    Environment = var.environment
    ManagedBy   = "terraform"
  }
}

Multiple locals blocks

In the following example, multiple locals blocks organize related values. The first locals block organizes network configuration, the second application configuration, and the third contains computed values:

locals {
  # Network configuration
  vpc_cidr = "10.0.0.0/16"
  az_count = length(data.aws_availability_zones.available.names)
}

locals {
  # Application configuration
  app_name = "${var.project_name}-${var.environment}"
  app_port = 8080
}

locals {
  # Computed values
  subnet_cidrs = [
    for i in range(local.az_count) :
    cidrsubnet(local.vpc_cidr, 8, i)
  ]
}

Terraform treats multiple locals blocks as if they were defined in a single block, but you can use separate blocks to organize your related values into visually distinct blocks to make it easier for users to understand your configuration.