Local Values

A local value is a named expression computed once and reused — Terraform's answer to "I am writing the same constructed string in nine places." Where a variable is an input the caller supplies, a local is an intermediate the configuration derives: the common-labels map every Hatch resource carries, the "${var.project}-events-raw" bucket name, the environment-derived flags.

Locals exist to make a configuration DRY and readable, not to be parameterized. The caller cannot set them — that is the whole point. A value derived from other inputs belongs in a local precisely so two callers cannot supply it inconsistently and produce mismatched resource names.

The locals Block

A locals block defines one or many named values, each referenced as local.<name>. Unlike a variable, a local can reference other locals, variables, resources, and functions freely — it is a computed expression, not a declared input with a fixed shape. One configuration can have several locals blocks; they merge into a single namespace.

locals {
  name_prefix = "hatch-${var.environment}"
}

resource "google_pubsub_topic" "events" {
  name = "${local.name_prefix}-events"   # derived once, reused everywhere
}

The prefix is computed in one place and read as local.name_prefix wherever a name is built. Change the derivation once and every resource that references it follows.

Local vs Variable

A variable is a knob the caller turns; a local is a value the config computes and the caller cannot override. The test is simple: if the value is supplied from outside, it is a variable; if it is derived from other inputs, it is a local. Exposing a derived value as a variable just invites someone to set it inconsistently with the inputs it was supposed to follow from.

The Common-Labels Pattern

The canonical use is a local.common_labels map defined once and merged into every resource's labels. Define { team = "data", environment = var.environment, managed_by = "terraform" } in one place, then merge(local.common_labels, { role = "raw" }) on each resource to add its specific label. Changing the team or environment label across the whole pipeline is then a one-line edit, not a hunt through every resource.

locals {
  common_labels = {
    team        = "data"
    environment = var.environment
    managed_by  = "terraform"
  }
}

resource "google_storage_bucket" "raw" {
  name     = "${local.name_prefix}-events-raw"
  location = var.region
  labels   = merge(local.common_labels, { role = "raw" })
}

Every Hatch resource carries the same base labels plus its own role, and the base set lives in exactly one place. Inlining that map on ten resources instead means ten edits to change one label, and one you will miss.

Computed Intermediates and DRY

A local also earns its place pulling a complex expression out of a resource block and naming it. A jsonencode'd policy, a constructed resource name, a filtered list — lifted into a named local, the resource block reads as intent rather than mechanics, and the expression is written once instead of duplicated. The name itself documents what the expression produces.

When a Local Hurts

A local is not free: every one is a layer of indirection the reader has to resolve. A local aliasing a single value used once — local.bucket = google_storage_bucket.raw — adds that layer with no DRY payoff, since the original reference was already clear. Locals earn their place when the expression is genuinely reused or genuinely complex, not as a rename.

The same caution applies to depth. A chain of locals referencing locals referencing locals, five deep, defeats the readability they exist for — no one can trace where a value comes from. Keep them shallow, and reach for one only when reuse or complexity justifies the indirection.