TerraformのHCL変数設計｜variable・locals・output・data sourceで構成を整理する方法

この記事のポイント

・variable{}で入力値を外部化し、terraform.tfvarsで環境ごとに安全に切り替えられる
・locals{}は繰り返し使う式や計算結果を1箇所にまとめてDRYにするための要素
・output{}はモジュールから外部へ値を公開し、モジュール間の疎結合を保つ
・data{}ソースは「Terraformで作っていない既存リソース」をコードから参照するための機能
・precondition・postconditionはvariable validationで届かない実行時コンテキスト条件を多段で検証する

# 変数を使わないHCLの例 -- ハードコードの問題
resource "aws_instance" "web" {
  ami           = "ami-0abcdef1234567890"
  instance_type = "t3.micro"
  subnet_id     = "subnet-0abcdef1234"
  tags = {
    Name = "dev-web"
    Env  = "dev"
  }
}

resource "aws_instance" "app" {
  ami           = "ami-0abcdef1234567890"   # 同じ値が重複
  instance_type = "t3.micro"                # 同じ値が重複
  subnet_id     = "subnet-0abcdef1234"      # 同じ値が重複
  tags = {
    Name = "dev-app"
    Env  = "dev"
  }
}

# variables.tf
variable "aws_region" {
  description = "AWSリージョン"
  type        = string
  default     = "ap-northeast-1"
}

variable "env" {
  description = "環境名（dev/stg/prd）"
  type        = string
  # defaultなし -- 必ず外部から指定する必要がある
}

variable "instance_type" {
  description = "EC2インスタンスタイプ"
  type        = string
  default     = "t3.micro"
}

# main.tf
resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type
  tags = {
    Name = "${var.env}-web"
    Env  = var.env
  }
}

variable "env" {
  type        = string
  description = "環境名（dev/stg/prd のいずれか）"

  validation {
    condition     = contains(["dev", "stg", "prd"], var.env)
    error_message = "env は dev・stg・prd のいずれかを指定してください。"
  }
}

$ terraform plan -var='env=production'

Error: Invalid value for variable

  on variables.tf line 1:
   1: variable "env" {

env は dev・stg・prd のいずれかを指定してください。

# terraform.tfvars（デフォルト・開発環境用）
env           = "dev"
instance_type = "t3.micro"
ami_id        = "ami-0abcdef1234567890"

# dev.tfvars
env           = "dev"
instance_type = "t3.micro"
db_instance   = "db.t3.micro"

# prd.tfvars
env           = "prd"
instance_type = "t3.large"
db_instance   = "db.m6g.large"

# 開発環境でplanする
$ terraform plan -var-file=dev.tfvars

# 本番環境でplanする
$ terraform plan -var-file=prd.tfvars

# locals.tf
locals {
  # 環境名とプロジェクト名を組み合わせてプレフィックスを生成
  prefix = "${var.env}-${var.project}"

  # 全リソースに付与する共通タグ
  common_tags = {
    Environment = var.env
    Project     = var.project
    ManagedBy   = "terraform"
  }
}

resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = var.instance_type

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

resource "aws_instance" "app" {
  ami           = var.ami_id
  instance_type = var.instance_type

  tags = merge(local.common_tags, {
    Name = "${local.prefix}-app"
  })
}

locals {
  # 環境名をキーにしてインスタンスタイプをマッピング
  instance_type_map = {
    dev = "t3.micro"
    stg = "t3.small"
    prd = "t3.large"
  }

  # var.envで現在の環境のインスタンスタイプを選択
  selected_instance = local.instance_type_map[var.env]
}

resource "aws_instance" "web" {
  ami           = var.ami_id
  instance_type = local.selected_instance  # envに応じたタイプが自動選択
}

# outputs.tf
output "vpc_id" {
  description = "作成したVPCのID"
  value       = aws_vpc.main.id
}

output "web_instance_public_ip" {
  description = "Webインスタンスのパブリック IP"
  value       = aws_instance.web.public_ip
}

$ terraform output
vpc_id = "vpc-0abcdef1234567890"
web_instance_public_ip = "54.238.xxx.xxx"

# JSON形式で取得
$ terraform output -json

output "db_password" {
  description = "RDSインスタンスのパスワード"
  value       = aws_db_instance.main.password
  sensitive   = true  # terraform apply の出力とterraform showでは隠蔽される
}

# modules/vpc/outputs.tf（子モジュール側）
output "public_subnet_id" {
  value = aws_subnet.public.id
}

# ルートモジュールのmain.tf（呼び元）
module "vpc" {
  source = "./modules/vpc"
  env    = var.env
}

resource "aws_instance" "web" {
  ami       = data.aws_ami.amazon_linux.id
  subnet_id = module.vpc.public_subnet_id  # module.<名前>. で参照
}

# 既存のVPCをタグで検索して参照する
data "aws_vpc" "existing" {
  filter {
    name   = "tag:Name"
    values = ["existing-production-vpc"]
  }
}

# 取得したVPCのIDを使ってサブネットを作成
resource "aws_subnet" "new" {
  vpc_id            = data.aws_vpc.existing.id
  cidr_block        = "10.0.100.0/24"
  availability_zone = "ap-northeast-1a"
}

data "aws_ami" "amazon_linux" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["al2023-ami-*-x86_64"]
  }
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.amazon_linux.id  # 最新AMIが自動選択される
  instance_type = var.instance_type
}

# 現在のAWSアカウントIDをdata sourceで取得
data "aws_caller_identity" "current" {}

locals {
  account_id = data.aws_caller_identity.current.account_id
}

# ARN内にアカウントIDをハードコードせず動的に埋め込む
resource "aws_iam_policy" "example" {
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["s3:GetObject"]
      Resource = "arn:aws:s3:::my-bucket-${local.account_id}/*"
    }]
  })
}

# data sourceでAMIの実体を取得してpreconditionで検証する
data "aws_ami" "selected" {
  most_recent = true
  owners      = ["amazon"]
  filter {
    name   = "image-id"
    values = [var.ami_id]
  }
}

resource "aws_instance" "web" {
  ami           = data.aws_ami.selected.id
  instance_type = var.instance_type

  lifecycle {
    precondition {
      # AMIアーキテクチャとインスタンスタイプの整合性を実行前に検証する
      condition = (
        can(data.aws_ami.selected.architecture == "x86_64") &&
        startswith(var.instance_type, "t3.")
      )
      error_message = "t3系インスタンスにはx86_64 AMIが必要です。AMIのアーキテクチャ: ${data.aws_ami.selected.architecture}"
    }
  }
}

$ terraform apply

Planning failed. Terraform encountered an error while generating this plan.

| Error: Resource precondition failed
|
|   on main.tf line 24, in resource "aws_instance" "web":
|   24:       condition = (
|
| t3系インスタンスにはx86_64 AMIが必要です。AMIのアーキテクチャ: arm64

resource "aws_security_group" "web" {
  name   = "web-sg"
  vpc_id = var.vpc_id

  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  lifecycle {
    postcondition {
      # selfで作成されたリソース属性を参照して検証する
      condition     = self.vpc_id == var.vpc_id
      error_message = "セキュリティグループのVPC IDが期待値と異なります。expected: ${var.vpc_id}, actual: ${self.vpc_id}"
    }
  }
}

# Terraform 1.5以降: checkブロックでALBエンドポイントを継続監視する
check "https_health_check" {
  data "http" "lb_endpoint" {
    url = "https://${aws_lb.main.dns_name}/health"
  }

  assert {
    condition     = data.http.lb_endpoint.status_code == 200
    error_message = "ロードバランサーのヘルスチェックが200を返していません。status: ${data.http.lb_endpoint.status_code}"
  }
}

project/
├── main.tf           # resource{}ブロックを中心に記述
├── variables.tf      # variable{}をすべてここに集約
├── locals.tf         # locals{}を集約（mainに書いてもよいが分離を推奨）
├── outputs.tf        # output{}をすべてここに集約
├── provider.tf       # provider{}とbackend{}の設定
├── versions.tf       # required_version・required_providersのバージョン制約
├── terraform.tfvars  # デフォルト（dev）の変数値（自動読み込み）
├── stg.tfvars        # ステージング環境用（-var-file指定が必要）
└── prd.tfvars        # 本番環境用（-var-file指定が必要）

# versions.tf
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0.0"
    }
  }
}

Error: No value for required variable

  on variables.tf line 5:
   5: variable "env" {

The root module input variable "env" is not set, and has no default value.
Use a -var or -var-file command line argument to provide a value for this variable.

Error: Variables not allowed

  on variables.tf line 6, in variable "env":
   6:   default = var.aws_region

Variables may not be used here.

Error: Your query returned no results. Please change your search criteria
and try again.

  with data.aws_vpc.existing,
  on main.tf line 3, in data "aws_vpc" "existing":

# タグで既存VPCを確認する（AWS CLI）
$ aws ec2 describe-vpcs --filters "Name=tag:Name,Values=existing-production-vpc"   --query 'Vpcs[*].{ID:VpcId,Name:Tags[?Key==`Name`]|[0].Value}'

# NG: data.aws_ami.selectedが取得できない場合に評価エラーが発生する
condition = data.aws_ami.selected.architecture == "x86_64"

# OK: can()でラップすることで評価エラーをfalseに変換する
condition = can(data.aws_ami.selected.architecture == "x86_64")

Error: Unsupported attribute

  on main.tf line 20, in resource "aws_instance" "web":
  20:   subnet_id = module.vpc.aws_subnet.public.id

This object does not have an attribute named "aws_subnet".