Terraform の locals を使った命名と再利用の設計

locals は、モジュール内で繰り返し現れる式に名前を付けて再利用するための仕組みです。命名規約やタグの共通化のような“変わりにくい規則”を一箇所に集約できます。

本稿は、Terraform Associate 受験者が理解しておくべき安定的な概念と、現場で効果が高い使い方に絞って解説します。

locals の基本と設計原則

locals はモジュール内限定の名前付き式です。入力値ではなく、変換・結合・既定値の計算結果を指し示します。参照は local.<name> で行います。

テキストの定義順に評価されるわけではなく、依存グラフに基づき必要になった時点で評価されます。外部から上書きはできません。

• スコープは“そのモジュール内のみ”。親子間で共有しない
• 入力は variable、計算は locals、外部公開は output という役割分担
• 規約（命名・タグ・サフィックス/プレフィックス）を一元化すると保守性が上がる

locals を中心にした値の流れ

命名戦略: 一貫性と制約を locals に閉じ込める

クラウドやプロバイダごとに命名制約は異なりますが、共通して言えるのは“規則を一箇所に集約し、全リソースで使い回す”ことです。locals に命名の組み立てを集約すると、規約変更の影響範囲を局所化できます。

推奨は、組織・環境・アプリ・コンポーネントを配列にし、join で結合、lower で小文字化、必要に応じて substr で長さを制御する形です。禁止文字の置換が必要なときは regexreplace を使います。

• name_parts = [org, env, app, component] を基本形に
• join("-", compact(name_parts)) で空要素を自動スキップ
• lower と substr で小文字化と長さ制御を標準化
• regexreplace で禁止文字を一括サニタイズ
• name の生成は1カ所に集約し、全リソースで参照

再利用パターン実装例（命名・タグ・複数コンポーネント）

以下は locals を使って命名とタグを一元化し、複数コンポーネントの名前を派生させる例です。プロバイダに依存しないよう、モジュール呼び出しで利用しています。

ポイントは、locals のみで規約を完結させ、モジュールにはできるだけ“完成済みの名前/タグ”を渡すことです。

• compact と join の組み合わせで読みやすい命名
• merge でタグの共通集合を作る
• for_each と内包表記でコンポーネント名を量産
• 下位モジュールには name_prefix や tags を渡すだけにする

locals による命名とタグの一元化（例）

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"])  # 必要に応じて可変
  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
}

環境ごとの切替: tfvars と locals の役割分担

環境差分は variable に寄せ、環境ごとの tfvars で値を供給します。locals はその差分を取り込み、命名・タグ・しきい値など“派生値”を作る担当に徹します。

terraform.workspace を名前に埋め込むことは可能ですが、本番・検証などの環境分離をワークスペースに任せる設計は推奨されません。環境は明示的な variable と tfvars で管理し、再現性を高めます。

• env/dev.tfvars, env/stg.tfvars, env/prd.tfvars のように分離
• locals は環境差分を参照しつつ、規約化と派生値に限定
• workspace 依存の命名は避け、var.environment を基準に

モジュール境界と評価順序の押さえどころ

locals はモジュール内でのみ有効で、親や子から上書き・参照はできません。共有したい場合は output 経由で値を公開し、親から子へは variable で渡します。

評価は宣言順ではなく依存グラフで行われます。locals が“早めに確定する”わけではないため、plan 時点で未確定の値が含まれると unknown として伝播します。循環参照はエラーになります。

• ローカル値は不変・上書き不可
• resource を参照する locals も定義可能（依存で解決）
• 未確定値は unknown のまま伝播し、locals で“固定化”はできない

Associate 試験対策とよくある落とし穴

Associate レベルでは、locals の役割と他要素（variables/outputs/data）との違い、スコープ、代表的な使い所（命名・タグ・計算済み定数）が問われやすいです。

現場での落とし穴は、locals を“設定”のように誤用することです。入力は variable、規約や派生は locals、公開は output という基本の型を守りましょう。

• locals は外部入力ではない点を説明できるようにする
• 命名規約・タグ統一のために locals を使う設計例を用意する
• workspace で環境を分ける設計は推奨されない、を選べるようにする
• 循環参照・未確定値の伝播など評価モデルの基礎を押さえる

問題で確認

よくある質問