Designing Naming and Reuse with Terraform locals

locals are a mechanism for giving a name to expressions that appear repeatedly inside a module and reusing them. You can consolidate "rules that rarely change" — naming conventions, shared tags, and the like — in a single place.

This article focuses on the stable concepts a Terraform Associate candidate should understand, and the high-impact uses that pay off in practice.

locals: fundamentals and design principles

locals are named expressions scoped to a single module. They do not represent input values; they represent the result of transformations, joins, and default-value calculations. Reference them with local.<name>.

They are not evaluated in textual definition order; Terraform evaluates them based on the dependency graph, at the moment they are needed. They cannot be overridden from outside.

• Scope is "that module only" — not shared between parent and child
• Roles split cleanly: variable for input, locals for computation, output for external exposure
• Centralizing conventions (naming, tags, suffixes/prefixes) improves maintainability

Value flow centered on locals

Naming strategy: confine consistency and constraints inside locals

Naming constraints differ across clouds and providers, but the universal advice is to "centralize the rules in one place and reuse them across every resource." Consolidating name assembly inside locals localizes the blast radius of any convention change.

The recommended shape: put org, environment, app, and component into an array, combine with join, lowercase with lower, and use substr for length control when needed. Use regexreplace when you need to substitute disallowed characters.

• Use name_parts = [org, env, app, component] as the canonical shape
• join("-", compact(name_parts)) automatically skips empty elements
• Standardize lowercasing and length control with lower and substr
• Use regexreplace to sanitize disallowed characters in one shot
• Generate the name in a single place and reference it from every resource

Reuse pattern examples (naming, tags, multiple components)

The example below uses locals to centralize naming and tags, and derives names for several components. To stay provider-agnostic, it is used through module calls.

The key is to finish the convention entirely within locals and pass "already-assembled names/tags" to modules as much as possible.

• Combine compact and join for readable names
• Build a common tag set with merge
• Mass-produce component names with for_each and comprehensions
• Pass only name_prefix and tags down to child modules

Centralizing naming and tags via locals (example)

variable "org"         { type = string }
variable "environment" { type = string }
variable "app"         { type = string }
variable "region"      { type = string }
variable "extra_tags"  { type = map(string) default = {} }

locals {
  env        = var.environment
  app        = var.app
  component  = "web"

  name_parts = [var.org, local.env, local.app, local.component]
  name       = lower(join("-", compact(local.name_parts)))
  name63     = substr(local.name, 0, 63)

  tags_base = {
    org = var.org
    env = local.env
    app = local.app
  }
  tags_common = merge(local.tags_base, var.extra_tags)

  component_names = toset(["web", "api", "db"])  # adjust as needed
  component_map   = { for c in local.component_names : c => lower(join("-", [var.org, local.env, local.app, c])) }
}

module "web" {
  source      = "./modules/web"
  name_prefix = local.name
  tags        = local.tags_common
}

module "components" {
  source      = "./modules/component"
  for_each    = local.component_map
  name        = each.value
  common_tags = local.tags_common
}

Environment switching: dividing roles between tfvars and locals

Push environment differences into variables and supply their values through per-environment tfvars. locals take those differences in and stay focused on producing "derived values" — names, tags, thresholds, and so on.

You can embed terraform.workspace in names, but leaning on workspaces to separate prod from staging is not recommended. Manage environments with explicit variables and tfvars to keep things reproducible.

• Split files like env/dev.tfvars, env/stg.tfvars, env/prd.tfvars
• locals consume the environment differences but stick to conventions and derived values
• Avoid workspace-dependent naming; use var.environment as the source of truth

Module boundaries and evaluation order: the key points

locals are valid only within a module; parents and children cannot override or reference them. To share, expose values through outputs and pass them from parent to child through variables.

Evaluation follows the dependency graph, not declaration order. locals do not become known any earlier than their dependencies, so values that are unknown at plan time propagate as unknown. Cycles are errors.

• Local values are immutable and cannot be overridden
• locals that reference resources are allowed (resolved through dependencies)
• Unknown values propagate as unknown; locals cannot "pin them down"

Associate exam prep and common pitfalls

At the Associate level, expect questions on the role of locals, how they differ from variables/outputs/data, their scope, and the canonical use cases (naming, tags, pre-computed constants).

The common real-world pitfall is misusing locals as if they were "configuration." Keep the basic pattern: input goes in variables, conventions and derivations go in locals, exposure goes in outputs.

• Be able to explain that locals are not external input
• Have a design example using locals to unify naming conventions and tags
• Be ready to pick "separating environments with workspaces is not recommended"
• Master evaluation-model basics like cycle detection and unknown-value propagation

Check Your Understanding

Frequently Asked Questions