TerraformのHCLリソース命名規則とタグ戦略｜環境・サービス・コスト管理を支える一貫した設計パターン

この記事のポイント

・HCLブロックラベルとNameタグは役割が異なり、それぞれに命名規則が必要
・localsブロックで共通タグを一元管理すると、全リソースへの変更が1か所で完結する
・環境・サービス・コスト配分の3タグをデフォルト基本セットとして設計する
・命名が崩れるのは「env変数の渡し忘れ」と「コンソール手動上書き」が主な原因

# NG: 環境名を入れると環境ごとにリソースブロックが増殖する
resource "aws_instance" "prod_web_01" { ... }
resource "aws_instance" "stg_web_01"  { ... }

# OK: 役割中心・環境は変数で切り替える
resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  tags          = local.common_tags
}

# 形式: {env}-{project}-{role}-{index}
# 例
prod-lm-web-01       # 本番 / linuxmaster / Webサーバー / 1台目
stg-lm-web-01        # ステージング / linuxmaster / Webサーバー / 1台目
prod-lm-db-primary   # 本番 / linuxmaster / DBサーバー / プライマリ

# variables.tf
variable "env" {
  description = "デプロイ環境（dev / stg / prod）"
  type        = string
  validation {
    condition     = contains(["dev", "stg", "prod"], var.env)
    error_message = "envはdev / stg / prodのいずれかを指定してください。"
  }
}

variable "project" {
  description = "プロジェクト識別子"
  type        = string
  default     = "lm"
}

variable "cost_center" {
  description = "コスト配分タグ（AWSコスト配分タグ設定と一致させる）"
  type        = string
}

# locals.tf
locals {
  # 全リソースに付与する共通タグ
  common_tags = {
    env         = var.env
    project     = var.project
    managed_by  = "terraform"
    cost_center = var.cost_center
  }

  # Nameタグ付きのリソース別タグを生成するヘルパー
  # merge(local.common_tags, { Name = "..." }) を各リソースで呼ぶ
  name_prefix = "${var.env}-${var.project}"
}

# main.tf
resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = var.instance_type
  subnet_id     = aws_subnet.public.id

  tags = merge(local.common_tags, {
    Name = "${local.name_prefix}-web-01"
    role = "web"
  })
}

resource "aws_db_instance" "main" {
  identifier        = "${local.name_prefix}-db"
  engine            = "mysql"
  instance_class    = var.db_instance_class
  allocated_storage = 20

  tags = merge(local.common_tags, {
    Name = "${local.name_prefix}-db-primary"
    role = "database"
  })
}

# cost_allocation.tf
resource "aws_ce_cost_allocation_tag" "env" {
  tag_key = "env"
  status  = "Active"
}

resource "aws_ce_cost_allocation_tag" "project" {
  tag_key = "project"
  status  = "Active"
}

resource "aws_ce_cost_allocation_tag" "cost_center" {
  tag_key = "cost_center"
  status  = "Active"
}

# variables.tf
variable "web_servers" {
  description = "Webサーバーのマップ（キーがNameタグの一部になる）"
  type = map(object({
    instance_type = string
    subnet_id     = string
    extra_tags    = map(string)
  }))
  default = {}
}

# terraform.tfvars（dev環境）
web_servers = {
  "web-01" = {
    instance_type = "t3.micro"
    subnet_id     = "subnet-aabbcc11"
    extra_tags    = { az = "ap-northeast-1a" }
  }
  "web-02" = {
    instance_type = "t3.micro"
    subnet_id     = "subnet-ddeeff22"
    extra_tags    = { az = "ap-northeast-1c" }
  }
}

# main.tf
resource "aws_instance" "web" {
  for_each = var.web_servers

  ami           = data.aws_ami.amazon_linux.id
  instance_type = each.value.instance_type
  subnet_id     = each.value.subnet_id

  tags = merge(
    local.common_tags,
    {
      Name = "${local.name_prefix}-${each.key}"
      role = "web"
    },
    each.value.extra_tags   # AZなどリソース固有のタグ
  )
}

$ aws ec2 describe-instances \
  --filters "Name=tag:env,Values=dev" \
  --query 'Reservations[].Instances[]
    .{ID:InstanceId,
      Name:Tags[?Key==`Name`].Value|[0],
      Env:Tags[?Key==`env`].Value|[0],
      Cost:Tags[?Key==`cost_center`].Value|[0]}' \
  --output table

--------------------------------------------------------------------
|                      DescribeInstances                           |
+----------------------+----------+--------------+-----------------+
| Cost                 |   Env    |      ID      |      Name       |
+----------------------+----------+--------------+-----------------+
| backend-01           | dev      | i-0a1b2c3d4e | dev-lm-web-01   |
| backend-01           | dev      | i-0b2c3d4e5f | dev-lm-web-02   |
+----------------------+----------+--------------+-----------------+

# NG: デフォルト値があると渡し忘れを検出できない
variable "env" {
  type    = string
  default = "dev"  # ← 渡し忘れても通ってしまう
}

# OK: デフォルト値を設定せず、validationで許容値を明示する
variable "env" {
  type = string
  validation {
    condition     = contains(["dev", "stg", "prod"], var.env)
    error_message = "envはdev / stg / prodのいずれかを指定してください。"
  }
}

  # aws_instance.web will be updated in-place
  ~ resource "aws_instance" "web" {
      ~ tags = {
          ~ "cost_center" = "backend-02" -> "backend-01"
            # (3 unchanged elements hidden)
        }
    }

Plan: 0 to add, 1 to change, 0 to destroy.

# 変更前
resource "aws_instance" "web_server" { ... }   # stateキー: aws_instance.web_server

# 変更後（命名を直した）
resource "aws_instance" "web" { ... }           # stateキー: aws_instance.web

# moved.tf（一時的に追加し、apply後に削除する）
moved {
  from = aws_instance.web_server
  to   = aws_instance.web
}