Locals: The Configuration Internal Variables

A local is a configuration-internal variable. It is not exposed to operators or other configurations. Locals are useful for reducing duplication and documenting derived values. The lesson teaches when to use locals and when not to.

Declaring a local

The locals block declares one or more values:

locals {
  common_tags = {
    Environment = var.environment
    ManagedBy   = "terraform"
    Owner       = "platform-team"
  }

  vpc_cidr_blocks = {
    dev     = "10.0.0.0/16"
    staging = "10.1.0.0/16"
    prod    = "10.2.0.0/16"
  }

  vpc_cidr = lookup(local.vpc_cidr_blocks, var.environment, "10.0.0.0/16")
}

The local values are referenced via local.<name>:

resource "aws_vpc" "main" {
  cidr_block = local.vpc_cidr
  tags       = local.common_tags
}

resource "aws_subnet" "public" {
  vpc_id = aws_vpc.main.id
  tags   = local.common_tags
}

The locals are not inputs. They are computed during the configuration phase.

When locals help

Locals help when:

• A value is used multiple times. A common tag set, a computed CIDR, a derived name.
• A value is derived from other values. A bucket name derived from a project name and an environment.
• Documentation is needed. A complex expression that the reader should understand.

# A derived value
locals {
  bucket_name = "${var.project}-${var.environment}-${var.region}"
}

resource "aws_s3_bucket" "data" {
  bucket = local.bucket_name
}

The reader can see the bucket names structure without parsing the resource block.

When locals hurt

Locals hurt when:

• The local hides a complex computation. A local with a 50-line expression is hard to read.
• The local is used only once. A local that is used only once is a tax.
• The local is a wrapper for noise. A local that just renames a variable is not useful.

# Bad: a local that just renames a variable
locals {
  vpc_cidr = var.vpc_cidr
}

The local adds nothing. The variable can be used directly.

The complexity trade-off

Locals are a readability tool. They are useful when:

• The local is more readable than the value it replaces.
• The local is used multiple times.
• The local expresses a meaningful name.

Locals are a complexity tool when:

• The local hides a complex computation.
• The local is used only once.
• The local is a wrapper for noise.

The principle is: locals should make the configuration easier to read, not harder.

The locals and the state

Locals are not in the state. They are computed during the configuration phase. A local that depends on a resource attribute is re-computed when the resource changes.

locals {
  instance_dns = aws_instance.web.public_dns
}

output "instance_dns" {
  value = local.instance_dns
}

The local is re-computed when the instance changes. The output is updated.

The locals and the modules

Locals are scoped to the module (or root configuration). A local declared in a module is not visible to other modules.

# modules/network/main.tf
locals {
  vpc_id = aws_vpc.main.id
}

# modules/compute/main.tf
# This would NOT see local.vpc_id from the network module

The cross-module communication is via outputs, not locals.

What comes next

The next lesson is outputs — the configurations return statement.

Verification