Terraform IaCベストプラクティス：モジュール設計からGitOpsまでの5つのプロダクションパターン

2026年、Terraform IaCは「やるかやらないか」ではなく「どう良くやるか」の問題

2023年にHashiCorpがTerraformのライセンスをBSL 1.1に変更した後、コミュニティはOpenTofuをフォークしました。しかし、Terraformを選ぶにせよOpenTofuを選ぶにせよ、HCLはIaC分野で最も広く使われている言語です。問題は「IaCを使うべきか」ではなく「IaCをプロダクションレディにするにはどうすればよいか」です。

多すぎるチームのTerraformコードはこんな状態です：巨大なmain.tfが1つ、状態ファイルはローカル、すべての環境が同じ変数を共有、モジュールにバージョン管理なし、CI/CDで手動terraform apply。これはIaCではなく、「コードで書いた手動運用」です。

本記事では5つのプロダクション級IaCパターンをカバーし、モジュール構成設計からGitOps自動化まで、Terraformを「動く」から「良く動く」へアップグレードします。

主要な学び

モジュール構成設計パターンの習得：再利用可能、テスト可能、バージョン管理可能なモジュールアーキテクチャ
リモート状態管理の3層保護の理解：リモートバックエンド、状態ロック、ドリフト検出
ワークスペース環境分離と変数管理のベストプラクティスの実装
TerraformからOpenTofuへのシームレスな移行の完了
GitOpsワークフローの統合：Atlantis + CI/CD自動化plan/apply

Terraform IaCコア概念
Pattern 1: モジュール構成設計
Pattern 2: 状態管理
Pattern 3: ワークスペース環境分離
Pattern 4: OpenTofu移行
Pattern 5: GitOps統合
5つのよくある落とし穴と解決策
10のよくあるエラートラブルシューティング
高度な最適化のヒント
比較分析
おすすめオンラインツール

Terraform IaCコア概念

IaC成熟度モデル

┌─────────────────────────────────────────────────────────────┐
│                 IaC成熟度モデル                                │
├──────────┬──────────────────┬────────────────────────────────┤
│  Level 1 │  Level 2         │  Level 3                       │
│  スクリプト│  モジュール化     │  プラットフォーム化             │
├──────────┼──────────────────┼────────────────────────────────┤
│ 単一     │  モジュール分割   │  モジュール構成+レジストリ      │
│ ファイル │                  │                                 │
│ ローカル │  リモート状態     │  状態レイヤー+分離              │
│ 状態     │                  │                                 │
│ 手動     │  CI/CDトリガー   │  GitOps自動化                   │
│ 実行     │                  │                                 │
│ テスト   │  基本テスト       │  Policy as Code               │
│ なし     │                  │                                 │
│ バージョン│  Gitバージョン   │  セマンティックバージョニング+  │
│ なし     │                  │  チェンジログ                   │
│ 環境     │  ワークスペース   │  マルチ環境                     │
│ 結合     │  分離            │  抽象レイヤー                   │
└──────────┴──────────────────┴────────────────────────────────┘

Terraformコアワークフロー

┌──────────┐     ┌──────────┐     ┌──────────┐     ┌──────────┐
│  Write   │────▶│  Plan    │────▶│  Apply   │────▶│  State   │
│ (HCL記述)│     │ (変更確認)│     │ (変更実行)│     │ (状態更新)│
└──────────┘     └──────────┘     └──────────┘     └──────────┘
     │                │                │                │
     ▼                ▼                ▼                ▼
  Git Commit    terraform plan   terraform apply   Remote Backend
  Pull Request  Plan File出力    リソース作成/更新  S3/GCS/Cloud

2026年のTerraformエコシステムの主要な変化

変化	影響	対応戦略
BSL 1.1ライセンス	企業利用の制限	OpenTofu移行の評価
OpenTofu 1.9+	コミュニティ主導の代替	新規プロジェクトで優先
Terraform 1.10+	ネイティブテストフレームワーク	`terraform test`の採用
Crossplane台頭	K8sネイティブIaC	補完的であり代替ではない
Pulumi成熟	汎用言語IaC	チームスキルに基づき選択

Pattern 1: モジュール構成設計

モジュールはTerraform IaCの基石です。しかし、ほとんどのチームは「ファイルの分割」はできても「構成可能」にはできていません。プロダクション級のモジュール設計には3層アーキテクチャが必要です：ベースモジュール、構成モジュール、環境モジュール。

3層モジュールアーキテクチャ

┌──────────────────────────────────────────────────────┐
│              Environment Module (環境モジュール)        │
│  ┌──────────────────────────────────────────────────┐ │
│  │         Composition Module (構成モジュール)        │ │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐      │ │
│  │  │  Base    │  │  Base    │  │  Base    │      │ │
│  │  │ Module   │  │ Module   │  │ Module   │      │ │
│  │  │ (VPC)    │  │ (RDS)    │  │ (ECS)    │      │ │
│  │  └──────────┘  └──────────┘  └──────────┘      │ │
│  └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────┘

ベースモジュール：VPC

modules/
└── vpc/
    ├── main.tf
    ├── variables.tf
    ├── outputs.tf
    ├── versions.tf
    └── README.md

# modules/vpc/versions.tf
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0, < 6.0"
    }
  }
}

# modules/vpc/variables.tf
variable "cidr_block" {
  description = "VPC CIDR block"
  type        = string
  default     = "10.0.0.0/16"
}

variable "environment" {
  description = "Environment name"
  type        = string
}

variable "public_subnets" {
  description = "List of public subnet CIDR blocks"
  type        = list(string)
  default     = ["10.0.1.0/24", "10.0.2.0/24"]
}

variable "private_subnets" {
  description = "List of private subnet CIDR blocks"
  type        = list(string)
  default     = ["10.0.10.0/24", "10.0.11.0/24"]
}

variable "enable_nat_gateway" {
  description = "Enable NAT Gateway for private subnets"
  type        = bool
  default     = true
}

variable "single_nat_gateway" {
  description = "Use single NAT Gateway to reduce cost"
  type        = bool
  default     = false
}

variable "tags" {
  description = "Additional tags for all resources"
  type        = map(string)
  default     = {}
}

# modules/vpc/main.tf
resource "aws_vpc" "this" {
  cidr_block           = var.cidr_block
  enable_dns_hostnames = true
  enable_dns_support   = true

  tags = merge(
    {
      Name        = "${var.environment}-vpc"
      Environment = var.environment
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_internet_gateway" "this" {
  vpc_id = aws_vpc.this.id

  tags = merge(
    {
      Name        = "${var.environment}-igw"
      Environment = var.environment
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_subnet" "public" {
  count                   = length(var.public_subnets)
  vpc_id                  = aws_vpc.this.id
  cidr_block              = var.public_subnets[count.index]
  availability_zone       = data.aws_availability_zones.available.names[count.index]
  map_public_ip_on_launch = true

  tags = merge(
    {
      Name        = "${var.environment}-public-${count.index + 1}"
      Environment = var.environment
      Tier        = "public"
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_subnet" "private" {
  count             = length(var.private_subnets)
  vpc_id            = aws_vpc.this.id
  cidr_block        = var.private_subnets[count.index]
  availability_zone = data.aws_availability_zones.available.names[count.index]

  tags = merge(
    {
      Name        = "${var.environment}-private-${count.index + 1}"
      Environment = var.environment
      Tier        = "private"
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_eip" "nat" {
  count  = var.enable_nat_gateway ? (var.single_nat_gateway ? 1 : length(var.private_subnets)) : 0
  domain = "vpc"

  tags = merge(
    {
      Name        = "${var.environment}-nat-eip-${count.index + 1}"
      Environment = var.environment
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_nat_gateway" "this" {
  count         = var.enable_nat_gateway ? (var.single_nat_gateway ? 1 : length(var.private_subnets)) : 0
  allocation_id = aws_eip.nat[count.index].id
  subnet_id     = aws_subnet.public[count.index % length(aws_subnet.public)].id

  tags = merge(
    {
      Name        = "${var.environment}-nat-${count.index + 1}"
      Environment = var.environment
      ManagedBy   = "terraform"
    },
    var.tags
  )

  depends_on = [aws_internet_gateway.this]
}

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.this.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.this.id
  }

  tags = merge(
    {
      Name        = "${var.environment}-public-rt"
      Environment = var.environment
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_route_table" "private" {
  count  = length(var.private_subnets)
  vpc_id = aws_vpc.this.id

  route {
    cidr_block     = "0.0.0.0/0"
    nat_gateway_id = var.single_nat_gateway ? aws_nat_gateway.this[0].id : aws_nat_gateway.this[count.index].id
  }

  tags = merge(
    {
      Name        = "${var.environment}-private-rt-${count.index + 1}"
      Environment = var.environment
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

resource "aws_route_table_association" "public" {
  count          = length(var.public_subnets)
  subnet_id      = aws_subnet.public[count.index].id
  route_table_id = aws_route_table.public.id
}

resource "aws_route_table_association" "private" {
  count          = length(var.private_subnets)
  subnet_id      = aws_subnet.private[count.index].id
  route_table_id = aws_route_table.private[count.index].id
}

data "aws_availability_zones" "available" {
  state = "available"
}

# modules/vpc/outputs.tf
output "vpc_id" {
  description = "VPC ID"
  value       = aws_vpc.this.id
}

output "vpc_cidr" {
  description = "VPC CIDR block"
  value       = aws_vpc.this.cidr_block
}

output "public_subnet_ids" {
  description = "List of public subnet IDs"
  value       = aws_subnet.public[*].id
}

output "private_subnet_ids" {
  description = "List of private subnet IDs"
  value       = aws_subnet.private[*].id
}

output "nat_gateway_ids" {
  description = "List of NAT Gateway IDs"
  value       = aws_nat_gateway.this[*].id
}

output "igw_id" {
  description = "Internet Gateway ID"
  value       = aws_internet_gateway.this.id
}

構成モジュール：完全なアプリケーションインフラ

# modules/app-stack/main.tf
module "vpc" {
  source = "../vpc"

  cidr_block         = var.vpc_cidr
  environment        = var.environment
  public_subnets     = var.public_subnet_cidrs
  private_subnets    = var.private_subnet_cidrs
  enable_nat_gateway = true
  single_nat_gateway = var.environment != "prod"
  tags               = local.common_tags
}

module "rds" {
  source = "../rds"

  environment       = var.environment
  vpc_id            = module.vpc.vpc_id
  subnet_ids        = module.vpc.private_subnet_ids
  engine            = var.db_engine
  engine_version    = var.db_engine_version
  instance_class    = var.db_instance_class
  allocated_storage = var.db_allocated_storage
  database_name     = var.database_name
  username          = var.db_username
  password          = var.db_password
  tags              = local.common_tags
}

module "ecs" {
  source = "../ecs"

  environment         = var.environment
  vpc_id              = module.vpc.vpc_id
  subnet_ids          = module.vpc.private_subnet_ids
  cluster_name        = "${var.environment}-cluster"
  container_image     = var.container_image
  container_port      = var.container_port
  desired_count       = var.desired_count
  cpu                 = var.cpu
  memory              = var.memory
  environment_variables = merge(
    {
      DATABASE_URL = "postgresql://${var.db_username}:${var.db_password}@${module.rds.endpoint}/${var.database_name}"
      ENVIRONMENT  = var.environment
    },
    var.extra_environment_variables
  )
  tags = local.common_tags
}

locals {
  common_tags = merge(
    {
      Environment = var.environment
      Project     = var.project_name
      ManagedBy   = "terraform"
    },
    var.tags
  )
}

モジュールバージョニング

# Terraform Registryモジュールの使用
module "vpc" {
  source  = "terraform-aws-modules/vpc/aws"
  version = "~> 5.0"
}

# Gitリポジトリモジュールの使用（タグ付き）
module "app_stack" {
  source = "git::https://github.com/myorg/terraform-modules.git//modules/app-stack?ref=v2.1.0"
}

# ローカルモジュールの使用（開発段階）
module "vpc" {
  source = "../../modules/vpc"
}

# S3保存モジュールパッケージの使用
module "app_stack" {
  source = "s3::https://my-terraform-modules.s3.amazonaws.com/app-stack/v2.1.0.zip"
}

モジュールテスト

# modules/vpc/tests/main.tftest.hcl
run "validate_vpc_cidr" {
  command = plan

  variables {
    cidr_block  = "10.0.0.0/16"
    environment = "test"
  }

  assert {
    condition     = aws_vpc.this.cidr_block == "10.0.0.0/16"
    error_message = "VPC CIDR block should match input"
  }
}

run "validate_subnets" {
  command = plan

  variables {
    cidr_block      = "10.0.0.0/16"
    environment     = "test"
    public_subnets  = ["10.0.1.0/24", "10.0.2.0/24"]
    private_subnets = ["10.0.10.0/24", "10.0.11.0/24"]
  }

  assert {
    condition     = length(aws_subnet.public) == 2
    error_message = "Should create 2 public subnets"
  }

  assert {
    condition     = length(aws_subnet.private) == 2
    error_message = "Should create 2 private subnets"
  }
}

run "validate_nat_gateway_production" {
  command = plan

  variables {
    cidr_block         = "10.0.0.0/16"
    environment        = "prod"
    enable_nat_gateway = true
    single_nat_gateway = false
    private_subnets    = ["10.0.10.0/24", "10.0.11.0/24", "10.0.12.0/24"]
  }

  assert {
    condition     = length(aws_nat_gateway.this) == 3
    error_message = "Production should have one NAT Gateway per AZ"
  }
}

# モジュールテストの実行
cd modules/vpc
terraform test

# すべてのモジュールテストの実行
terraform test -recursive

Pattern 2: 状態管理

Terraformの状態ファイルはIaCで最も重要なデータです。状態を失うことはインフラの制御を失うことを意味します。プロダクション環境ではリモートバックエンドを使用し、状態ロックを有効にし、定期的にドリフトを検出する必要があります。

リモートバックエンドアーキテクチャ

┌──────────────────────────────────────────────────────┐
│              状態管理3層保護                             │
│                                                       │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 1: リモートバックエンド                   │    │
│  │  S3 + DynamoDB / GCS / Azure Blob             │    │
│  │  (状態の永続化、チーム共有)                       │    │
│  └──────────────────────────────────────────────┘    │
│                                                       │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 2: 状態ロック                            │    │
│  │  DynamoDB / GCSネイティブロック / Azure Blobリース│   │
│  │  (同時変更の防止、applyの直列化)                 │    │
│  └──────────────────────────────────────────────┘    │
│                                                       │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 3: ドリフト検出                          │    │
│  │  terraform refresh + CI/CD定期チェック          │    │
│  │  (手動変更の検出、状態の一貫性維持)               │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

S3 + DynamoDBバックエンド設定

# backend.tf
terraform {
  backend "s3" {
    bucket         = "myorg-terraform-state"
    key            = "app-infra/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
    kms_key_id     = "arn:aws:kms:us-east-1:123456789012:key/abc123"

    state_lock_timeout = "30m"
  }
}

バックエンドインフラのブートストラップ

# bootstrap/main.tf
resource "aws_s3_bucket" "terraform_state" {
  bucket = "myorg-terraform-state"

  lifecycle {
    prevent_destroy = true
  }
}

resource "aws_s3_bucket_versioning" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  versioning_configuration {
    status = "Enabled"
  }
}

resource "aws_s3_bucket_server_side_encryption_configuration" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm     = "aws:kms"
      kms_master_key_id = aws_kms_key.terraform_state.arn
    }
  }
}

resource "aws_s3_bucket_public_access_block" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

resource "aws_s3_bucket_lifecycle_configuration" "terraform_state" {
  bucket = aws_s3_bucket.terraform_state.id

  rule {
    id     = "cleanup-old-versions"
    status = "Enabled"

    noncurrent_version_transition {
      noncurrent_days = 90
      storage_class   = "GLACIER"
    }

    noncurrent_version_expiration {
      noncurrent_days = 365
    }
  }
}

resource "aws_dynamodb_table" "terraform_locks" {
  name         = "terraform-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

  attribute {
    name = "LockID"
    type = "S"
  }
}

resource "aws_kms_key" "terraform_state" {
  description             = "Terraform state encryption key"
  deletion_window_in_days = 30
  enable_key_rotation     = true
}

resource "aws_kms_alias" "terraform_state" {
  name          = "alias/terraform-state"
  target_key_id = aws_kms_key.terraform_state.key_id
}

# ブートストラッププロセス
cd bootstrap
terraform init
terraform apply

# リモートバックエンドへの移行
# backend.tf作成後に実行
terraform init -migrate-state

# 状態がS3に移行されたことを確認
aws s3 ls s3://myorg-terraform-state/app-infra/

状態レイヤリング

┌──────────────────────────────────────────────────────┐
│                  状態レイヤリングアーキテクチャ           │
│                                                       │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 0: bootstrap (ローカル状態)              │    │
│  │  S3 Bucket / DynamoDB / KMS / IAM             │    │
│  └──────────────────────────────────────────────┘    │
│                     │ データフロー                    │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 1: networking (リモート状態)             │    │
│  │  VPC / Subnets / Route Tables / NAT GW        │    │
│  └──────────────────────────────────────────────┘    │
│                     │ データフロー                    │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 2: compute (リモート状態)                │    │
│  │  ECS / EKS / RDS / ElastiCache                │    │
│  └──────────────────────────────────────────────┘    │
│                     │ データフロー                    │
│  ┌──────────────────────────────────────────────┐    │
│  │  Layer 3: services (リモート状態)               │    │
│  │  DNS / CDN / Monitoring / Alerts              │    │
│  └──────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────┘

# Layer 2がLayer 1の出力を参照
data "terraform_remote_state" "networking" {
  backend = "s3"

  config = {
    bucket = "myorg-terraform-state"
    key    = "networking/terraform.tfstate"
    region = "us-east-1"
  }
}

module "ecs" {
  source = "../../modules/ecs"

  vpc_id     = data.terraform_remote_state.networking.outputs.vpc_id
  subnet_ids = data.terraform_remote_state.networking.outputs.private_subnet_ids
}

ドリフト検出

# 手動ドリフト検出
terraform plan -detailed-exitcode
# 0 = 変更なし
# 1 = エラー
# 2 = 変更あり（ドリフト存在）

# 状態のリフレッシュ
terraform refresh

# .github/workflows/drift-detection.yml
name: Drift Detection
on:
  schedule:
    - cron: "0 8 * * 1-5"
  workflow_dispatch:

jobs:
  drift-detection:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v3
        with:
          terraform_version: "1.10.0"

      - name: Terraform Init
        run: terraform init -backend-config=backend.hcl

      - name: Check Drift
        run: |
          terraform plan -detailed-exitcode -out=plan.out || exit_code=$?
          if [ "${exit_code:-0}" -eq 2 ]; then
            echo "::warning::Infrastructure drift detected!"
            terraform show -json plan.out | jq -r '.resource_changes[] | select(.change.actions != ["no-op"]) | "\(.type).\(.name): \(.change.actions | join(", "))"'
            exit 1
          fi

Pattern 3: ワークスペース環境分離

マルチ環境管理はIaCの最も基本的な要件です。dev/staging/prodの3つの環境がモジュールを共有しつつ設定が異なります。Terraform Workspaceは軽量な環境分離を提供しますが、適切な変数管理と組み合わせる必要があります。

ワークスペース vs ディレクトリ分離

┌─────────────────────────────────────────────────────────────┐
│          環境分離：2つのアプローチ                              │
├──────────────────────┬──────────────────────────────────────┤
│  ワークスペース分離     │  ディレクトリ分離                     │
├──────────────────────┼──────────────────────────────────────┤
│  環境ごとに1つの状態   │  環境ごとに独立した状態ファイル          │
│  ファイル             │                                      │
│  同じコードベース     │  環境ごとに独立したコードディレクトリ     │
│  ワークスペース切替   │  ディレクトリ切替                      │
│  単純な環境に適する   │  複雑な環境に適する                    │
│  状態パス:            │  状態パス:                            │
│  env:/dev/state      │  dev/terraform.tfstate               │
│  env:/prod/state     │  prod/terraform.tfstate              │
└──────────────────────┴──────────────────────────────────────┘

推奨アプローチ：ディレクトリ分離 + 共有モジュール

infra/
├── modules/
│   ├── vpc/
│   ├── rds/
│   └── ecs/
├── environments/
│   ├── dev/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── backend.tf
│   │   └── terraform.tfvars
│   ├── staging/
│   │   ├── main.tf
│   │   ├── variables.tf
│   │   ├── outputs.tf
│   │   ├── backend.tf
│   │   └── terraform.tfvars
│   └── prod/
│       ├── main.tf
│       ├── variables.tf
│       ├── outputs.tf
│       ├── backend.tf
│       └── terraform.tfvars
└── shared/
    └── locals.tf

環境設定

# environments/dev/backend.tf
terraform {
  backend "s3" {
    bucket         = "myorg-terraform-state"
    key            = "dev/app-infra/terraform.tfstate"
    region         = "us-east-1"
    encrypt        = true
    dynamodb_table = "terraform-locks"
  }
}

# environments/dev/main.tf
module "vpc" {
  source = "../../modules/vpc"

  cidr_block         = "10.0.0.0/16"
  environment        = "dev"
  public_subnets     = ["10.0.1.0/24"]
  private_subnets    = ["10.0.10.0/24"]
  enable_nat_gateway = true
  single_nat_gateway = true
}

module "rds" {
  source = "../../modules/rds"

  environment       = "dev"
  vpc_id            = module.vpc.vpc_id
  subnet_ids        = module.vpc.private_subnet_ids
  engine            = "postgres"
  engine_version    = "16.4"
  instance_class    = "db.t3.micro"
  allocated_storage = 20
  database_name     = "appdb_dev"
  username          = "appadmin"
  password          = var.db_password
}

module "ecs" {
  source = "../../modules/ecs"

  environment     = "dev"
  vpc_id          = module.vpc.vpc_id
  subnet_ids      = module.vpc.private_subnet_ids
  container_image = "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:dev-latest"
  desired_count   = 1
  cpu             = 256
  memory          = 512
}

# environments/prod/main.tf
module "vpc" {
  source = "../../modules/vpc"

  cidr_block         = "10.100.0.0/16"
  environment        = "prod"
  public_subnets     = ["10.100.1.0/24", "10.100.2.0/24", "10.100.3.0/24"]
  private_subnets    = ["10.100.10.0/24", "10.100.11.0/24", "10.100.12.0/24"]
  enable_nat_gateway = true
  single_nat_gateway = false
}

module "rds" {
  source = "../../modules/rds"

  environment       = "prod"
  vpc_id            = module.vpc.vpc_id
  subnet_ids        = module.vpc.private_subnet_ids
  engine            = "postgres"
  engine_version    = "16.4"
  instance_class    = "db.r6g.xlarge"
  allocated_storage = 500
  database_name     = "appdb_prod"
  username          = "appadmin"
  password          = var.db_password
  multi_az          = true
}

module "ecs" {
  source = "../../modules/ecs"

  environment     = "prod"
  vpc_id          = module.vpc.vpc_id
  subnet_ids      = module.vpc.private_subnet_ids
  container_image = "123456789012.dkr.ecr.us-east-1.amazonaws.com/app:v2.1.0"
  desired_count   = 3
  cpu             = 1024
  memory          = 2048
}

変数検証

# variables.tf
variable "environment" {
  description = "Environment name"
  type        = string

  validation {
    condition     = contains(["dev", "staging", "prod"], var.environment)
    error_message = "Environment must be one of: dev, staging, prod."
  }
}

variable "db_password" {
  description = "Database password"
  type        = string
  sensitive   = true

  validation {
    condition     = length(var.db_password) >= 16
    error_message = "Database password must be at least 16 characters."
  }
}

Pattern 4: OpenTofu移行

2023年8月、HashiCorpはTerraformのライセンスをMozilla Public License 2.0からBusiness Source License 1.1に変更しました。BSL 1.1は「競合的使用」を禁止しています。これはほとんどの企業にとって問題になりませんが、オープンソースコミュニティの反応としてOpenTofuが誕生しました。

移行評価

次元	Terraform (BSL 1.1)	OpenTofu (MPL 2.0)
ライセンス	BSL 1.1（競合的使用制限）	MPL 2.0（完全オープンソース）
CLI互換性	ネイティブ	Terraform 1.6と100%互換
Provider互換性	ネイティブ	すべてのコミュニティProviderと互換
状態ファイル	ネイティブ形式	100%互換
エンタープライズサポート	HashiCorpサポート	Linux Foundationコミュニティ
新機能	1.10+ネイティブテスト	1.9+暗号化状態
レジストリ	Terraform Registry	OpenTofu Registry

移行手順

# Step 1: OpenTofuのインストール
# macOS
brew install opentofu

# Linux
curl -fsSL https://get.opentofu.org/install-opentofu.sh | bash

# バージョン互換性の確認
tofu version
# OpenTofu v1.9.0

# Step 2: CLIコマンドの置き換え
# terraform init → tofu init
# terraform plan → tofu plan
# terraform apply → tofu apply
# terraform destroy → tofu destroy

# Step 3: 互換性の確認
tofu init
tofu plan
# plan出力がterraform planと一致すれば移行成功

# Step 4: CI/CD設定の更新
# すべてのterraformコマンドをtofuに置き換え

OpenTofu独自機能：暗号化状態

# OpenTofu 1.9+はネイティブ状態暗号化をサポート
terraform {
  encryption {
    key_provider "pbkdf2" "mykey" {
      passphrase = var.encryption_passphrase
      key_length = 32
      iterations = 600000
      salt       = "fixed-salt-for-key-derivation"
    }

    method "aes_gcm" "myencryption" {
      keys = key_provider.pbkdf2.mykey
    }

    state {
      method = method.aes_gcm.myencryption
      fallback {
        method = method.aes_gcm.myencryption
      }
    }

    plan {
      method = method.aes_gcm.myencryption
      fallback {
        method = method.aes_gcm.myencryption
      }
    }
  }
}

段階的移行戦略

┌──────────────────────────────────────────────────────┐
│            段階的移行ロードマップ                        │
│                                                       │
│  Phase 1: 評価（1-2週間）                             │
│  ├── すべてのTerraformプロジェクトの棚卸し              │
│  ├── ProviderとModuleの互換性チェック                   │
│  └── 移行優先度の定義                                  │
│                                                       │
│  Phase 2: 非本番環境の移行（2-4週間）                  │
│  ├── dev/staging環境をOpenTofuに切り替え               │
│  ├── plan出力の一貫性を検証                            │
│  └── CI/CDパイプラインの更新                           │
│                                                       │
│  Phase 3: 本番環境の移行（1-2週間）                    │
│  ├── 本番環境をOpenTofuに切り替え                      │
│  ├── 状態暗号化の有効化                                │
│  └── 1週間の監視で安定性を確認                         │
│                                                       │
│  Phase 4: クリーンアップ（1週間）                      │
│  ├── Terraform CLI依存の削除                          │
│  ├── ドキュメントとランブックの更新                     │
│  └── チームトレーニングの完了                          │
└──────────────────────────────────────────────────────┘

Pattern 5: GitOps統合

Terraform IaCの最終目標はGitOpsです：コードのコミットがplanをトリガーし、承認後に自動的にapplyされます。Atlantisは現在、最も成熟したTerraform GitOpsツールであり、Pull Request内で直接terraform planとterraform applyを実行します。

Atlantisアーキテクチャ

┌──────────────────────────────────────────────────────┐
│                  Atlantis GitOpsアーキテクチャ          │
│                                                       │
│  ┌──────────┐     webhook     ┌──────────────────┐  │
│  │  GitHub   │───────────────▶│    Atlantis       │  │
│  │  /GitLab  │                │    Server         │  │
│  │          │◀───────────────│                    │  │
│  │          │  PR Comment     │  ┌──────────────┐│  │
│  │          │  (plan/apply)   │  │ terraform    ││  │
│  └──────────┘                │  │ plan/apply   ││  │
│                               │  └──────────────┘│  │
│                               └────────┬─────────┘  │
│                                        │             │
│                               ┌────────▼─────────┐  │
│                               │  AWS / GCP /     │  │
│                               │  Azure API       │  │
│                               └──────────────────┘  │
└──────────────────────────────────────────────────────┘

Atlantisのデプロイ

# atlantis-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: atlantis
  namespace: atlantis
spec:
  replicas: 1
  selector:
    matchLabels:
      app: atlantis
  template:
    metadata:
      labels:
        app: atlantis
    spec:
      containers:
        - name: atlantis
          image: ghcr.io/runatlantis/atlantis:v0.30.0
          ports:
            - containerPort: 4141
          env:
            - name: ATLANTIS_GH_USER
              value: "myorg-bot"
            - name: ATLANTIS_GH_TOKEN
              valueFrom:
                secretKeyRef:
                  name: atlantis-secrets
                  key: github-token
            - name: ATLANTIS_GH_WEBHOOK_SECRET
              valueFrom:
                secretKeyRef:
                  name: atlantis-secrets
                  key: webhook-secret
            - name: ATLANTIS_ALLOW_REPO_CONFIG
              value: "true"
            - name: ATLANTIS_PARALLEL_PLAN_COUNT
              value: "4"
            - name: ATLANTIS_PARALLEL_APPLY_COUNT
              value: "2"
            - name: ATLANTIS_AUTOPLAN_ENABLED
              value: "true"
            - name: ATLANTIS_REPO_CONFIG_JSON
              value: |
                {
                  "repos": [
                    {
                      "id": "/.*/",
                      "apply_requirements": ["approved", "mergeable"],
                      "plan_requirements": [],
                      "import_requirements": [],
                      "allowed_overrides": ["apply_requirements", "workflow"],
                      "allow_custom_workflows": true
                    }
                  ]
                }
          resources:
            requests:
              cpu: "500m"
              memory: "1Gi"
            limits:
              cpu: "2"
              memory: "4Gi"
          volumeMounts:
            - name: atlantis-data
              mountPath: /home/atlantis
            - name: repo-config
              mountPath: /etc/atlantis
      volumes:
        - name: atlantis-data
          persistentVolumeClaim:
            claimName: atlantis-data
        - name: repo-config
          configMap:
            name: atlantis-config

Atlantisリポジトリ設定

# atlantis.yaml (プロジェクトルート)
version: 3
projects:
  - name: dev-infra
    dir: environments/dev
    workflow: terraform
    autoplan:
      when_modified: ["../../modules/**/*.tf", "*.tf", "*.tfvars"]
      enabled: true
    apply_requirements:
      - approved
      - mergeable

  - name: staging-infra
    dir: environments/staging
    workflow: terraform
    autoplan:
      when_modified: ["../../modules/**/*.tf", "*.tf", "*.tfvars"]
      enabled: true
    apply_requirements:
      - approved
      - mergeable

  - name: prod-infra
    dir: environments/prod
    workflow: terraform
    autoplan:
      when_modified: ["../../modules/**/*.tf", "*.tf", "*.tfvars"]
      enabled: true
    apply_requirements:
      - approved
      - mergeable
      - undiverged

workflows:
  terraform:
    plan:
      steps:
        - env:
            name: TF_VAR_db_password
            value: ${DB_PASSWORD}
        - run: terraform init -backend-config=backend.hcl -reconfigure
        - run: terraform plan -out=$PLANFILE -var-file=terraform.tfvars
        - run: terraform show -json $PLANFILE > $SHOWFILE
    apply:
      steps:
        - run: terraform apply $PLANFILE

Policy as Code：Sentinel / OPA

# sentinel/require-tags.sentinel
import "tfplan/v2" as tfplan

allResources = filter tfplan.resource_changes as _, rc {
    rc.mode == "managed" and
    rc.type != "null_resource" and
    rc.change.actions != ["delete"]
}

tagsRequired = rule {
    all allResources as _, rc {
        rc.change.after.tags contains "Environment" and
        rc.change.after.tags contains "ManagedBy"
    }
}

main = rule {
    tagsRequired
}

# opa/require-tags.rego
package terraform

import future.keywords.if
import future.keywords.in

deny[msg] if {
    some rc in input.resource_changes
    rc.mode == "managed"
    rc.change.actions[_] != "delete"
    not "Environment" in object.keys(rc.change.after.tags)
    msg := sprintf("Resource %s of type %s missing Environment tag", [rc.name, rc.type])
}

deny[msg] if {
    some rc in input.resource_changes
    rc.mode == "managed"
    rc.change.actions[_] != "delete"
    not "ManagedBy" in object.keys(rc.change.after.tags)
    msg := sprintf("Resource %s of type %s missing ManagedBy tag", [rc.name, rc.type])
}

# OPAでTerraform Planをチェック
terraform plan -out=plan.out
terraform show -json plan.out > plan.json

# OPAポリシーチェックの実行
opa eval --data opa/ --input plan.json "data.terraform.deny"

5つのよくある落とし穴と解決策

落とし穴1: 状態ファイルの破損

現象: terraform planがstate snapshot was created by a newer versionまたはinvalid characterを報告。

原因: 状態ファイルの手動編集、ディスク障害、S3バージョンのロールバック。

解決策:

# 1. S3バージョン履歴から復元
aws s3api list-object-versions \
  --bucket myorg-terraform-state \
  --prefix dev/app-infra/terraform.tfstate

# 以前のバージョンに復元
aws s3api copy-object \
  --bucket myorg-terraform-state \
  --copy-source myorg-terraform-state/dev/app-infra/terraform.tfstate?versionId=PREVIOUS_VERSION \
  --key dev/app-infra/terraform.tfstate

# 2. 強制プルと修復
terraform state pull > state.json
# JSONを手動修復（慎重に実行）
terraform state push state.json

落とし穴2: ProviderバージョンロックによるCI失敗

現象: ローカルのterraform planは正常だが、CI/CDでProviderダウンロード失敗やバージョン非互換のエラー。

原因: ローカルにキャッシュがあり、CI環境は毎回新規インストール。Providerバージョンがロックされていない。

解決策:

# versions.tf - Providerバージョンのロック
terraform {
  required_version = ">= 1.5.0, < 2.0.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "5.80.0"
    }
  }
}

# ロックファイルをGitにコミット
git add .terraform.lock.hcl
git commit -m "chore: lock provider versions"

落とし穴3: 循環依存

現象: terraform planがCycle: module.x, module.yを報告。

原因: モジュールAの出力がモジュールBの出力に依存し、モジュールBがモジュールAの出力に依存している。

解決策:

# 誤り: 循環依存
module "vpc" {
  source = "./vpc"
  ecs_security_group_id = module.ecs.security_group_id
}

module "ecs" {
  source = "./ecs"
  subnet_ids = module.vpc.private_subnet_ids
}

# 正しい: 3層に分割、一方向依存
# Layer 1: ネットワーク
module "vpc" {
  source = "./vpc"
}

# Layer 2: セキュリティグループ
module "security_groups" {
  source   = "./security-groups"
  vpc_id   = module.vpc.vpc_id
}

# Layer 3: コンピュート
module "ecs" {
  source             = "./ecs"
  subnet_ids         = module.vpc.private_subnet_ids
  security_group_ids = module.security_groups.app_ids
}

落とし穴4: 機密変数の状態ファイルへの漏洩

現象: terraform showで平文パスワードが見える。状態ファイルに機密情報が含まれている。

原因: sensitive = trueはCLI出力を隠すだけで、状態ファイル内の値は暗号化しない。

解決策:

# オプション1: AWS SSM Parameter Storeの使用
data "aws_ssm_parameter" "db_password" {
  name            = "/app/${var.environment}/db-password"
  with_decryption = true
}

module "rds" {
  source   = "../../modules/rds"
  password = data.aws_ssm_parameter.db_password.value
}

# オプション2: AWS Secrets Managerの使用
data "aws_secretsmanager_secret_version" "db_creds" {
  secret_id = "app/${var.environment}/db-credentials"
}

module "rds" {
  source   = "../../modules/rds"
  password = jsondecode(data.aws_secretsmanager_secret_version.db_creds.secret_string)["password"]
}

落とし穴5: モジュールリファクタリングによるリソース再作成

現象: モジュール名の変更やリソースの移動後、terraform planがリソースの削除と再作成を表示。

原因: Terraformはリソースアドレス（module.vpc.aws_vpc.this）でリソースを識別する。アドレスが変わると、Terraformは新しいリソースとみなす。

解決策:

# リファクタリング前: まず状態を移動
terraform state mv module.vpc module.networking.vpc
terraform state mv module.vpc.aws_vpc.this module.networking.aws_vpc.this

# その後コードを修正
# モジュールファイルを移動
mv modules/vpc modules/networking/vpc

# モジュール参照を更新
# module "vpc" → module "networking_vpc"

# 検証
terraform plan  # 変更なしが表示されるはず

10のよくあるエラートラブルシューティング

1. `Error: Failed to load plugin`

# プラグインキャッシュをクリアして再ダウンロード
rm -rf .terraform/providers
terraform init -upgrade

# ネットワークプロキシの確認
export HTTPS_PROXY=http://proxy.internal:8080
terraform init

2. `Error: Error locking state: Error acquiring the state lock`

# DynamoDBのロックを確認
aws dynamodb scan --table-name terraform-locks

# 他のプロセスが実行中でないことを確認
# ロックが古い場合は強制アンロック
terraform force-unlock <lock-id>

3. `Error: Provider produced inconsistent result after apply`

# Providerのバグ。通常は以下で解決:
# 1. Providerバージョンの更新
terraform init -upgrade

# 2. 既知のProviderバグの場合、lifecycleで変更を無視
resource "aws_instance" "app" {
  lifecycle {
    ignore_changes = [user_data_replace_on_change]
  }
}

4. `Error: Resource already managed by Terraform`

# リソースは状態に存在するがコードから削除されている
# 状態内のリソース一覧
terraform state list

# 状態から削除
terraform state rm aws_instance.old_resource

5. `Error: Module not found`

# モジュールキャッシュをクリア
rm -rf .terraform/modules
terraform init -upgrade

# モジュールソースパスの確認
# ローカルモジュールパスは現在のtfファイルからの相対パス
module "vpc" {
  source = "../../modules/vpc"
}

6. `Error: Invalid for_each argument`

# 誤り: plan時にfor_eachの値が不明
resource "aws_subnet" "private" {
  for_each = toset(module.vpc.private_subnet_cidrs)
}

# 正しい: 既知の値を使用
variable "private_subnets" {
  type = list(string)
}

resource "aws_subnet" "private" {
  for_each = toset(var.private_subnets)
}

7. `Error: Value for unconfigurable attribute`

# 誤り: 読み取り専用属性を設定しようとしている
resource "aws_eip" "nat" {
  instance = aws_instance.nat.id
  domain   = "vpc"
}

# 正しい: Providerドキュメントを確認し、書き込み可能な属性のみ設定
resource "aws_eip" "nat" {
  domain = "vpc"
}

8. `Error: Backend configuration changed`

# バックエンド設定変更後の再初期化
terraform init -migrate-state

# 移行が失敗した場合の手動移行
terraform state pull > state.json
# backend.tfを修正
terraform init
terraform state push state.json

9. `Error: Invalid terraform configuration: No required_providers`

# すべてのモジュールでrequired_providersを宣言する必要がある
terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = ">= 5.0"
    }
  }
}

10. `Error: Incompatible API version`

# ProviderバージョンがTerraformバージョンと非互換
# 互換性の確認
terraform version
terraform providers

# 互換バージョンに更新
terraform {
  required_version = ">= 1.5.0"
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "5.80.0"
    }
  }
}

高度な最適化のヒント

1. Terraform Cloud / Enterprise

# terraform-cloud.tf
terraform {
  cloud {
    organization = "myorg"
    workspaces {
      tags = ["app-infra"]
    }
  }
}

2. Terraformテストフレームワーク

# tests/integration/main.tftest.hcl
run "create_infrastructure" {
  command = apply

  module {
    source = "../../environments/dev"
  }

  variables {
    db_password = "test-password-12345678"
  }
}

run "validate_endpoints" {
  command = apply

  variables {
    api_endpoint = run.create_infrastructure.api_url
  }

  assert {
    condition     = can(http_request.check.status_code == 200)
    error_message = "API endpoint should return 200"
  }
}

3. Infracostによるコスト見積もり

# Infracostでコストを見積もり
infracost breakdown --path=plan.json \
  --format=json \
  --out-file=infracost.json

# PRにコストコメントを追加
infracost comment github --path=infracost.json \
  --behavior=update

4. モジュールドキュメントの自動生成

# terraform-docsのインストール
brew install terraform-docs

# READMEの生成
terraform-docs markdown table ./modules/vpc > ./modules/vpc/README.md

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.92.0
    hooks:
      - id: terraform_fmt
      - id: terraform_validate
      - id: terraform_docs
        args:
          - '--args=--lockfile=false'
      - id: terraform_tflint
      - id: terraform_trivy
      - id: terraform_checkov

比較分析：Terraform vs OpenTofu vs Pulumi vs CDK

次元	Terraform	OpenTofu	Pulumi	CDK
言語	HCL	HCL	TS/Python/Go/C#	TS/Python/Java/C#
ライセンス	BSL 1.1	MPL 2.0	Apache 2.0	Apache 2.0
Provider	3000+	3000+	200+	AWS中心
状態暗号化	S3 KMS	ネイティブ暗号化	Pulumi Cloud	CDK Cloud
テスト	terraform test	terraform test	Mocha/Jest	Jest
GitOps	Atlantis	Atlantis	Pulumi Cloud	CDK Pipelines
学習曲線	低	低	低	中
マルチクラウド	ネイティブ	ネイティブ	ネイティブ	AWS中心
コミュニティ	最大	成長中	成長中	AWSエコシステム
エンタープライズサポート	HashiCorp	Linux Foundation	Pulumi Corp	AWS

意思決定ツリー

チームはHCLに慣れているか？
├── はい → ライセンスコンプライアンスが懸念か？
│        ├── はい → OpenTofu
│        └── いいえ → Terraform
└── いいえ → 主にAWSを使用しているか？
         ├── はい → CDK
         └── いいえ → 汎用プログラミング言語を好むか？
                  ├── はい → Pulumi
                  └── いいえ → Terraform/OpenTofu（HCLは学びやすい）

2026年、Terraform IaCは「やるかやらないか」ではなく「どう良くやるか」の問題

主要な学び

目次

Terraform IaCコア概念

IaC成熟度モデル

Terraformコアワークフロー

2026年のTerraformエコシステムの主要な変化

Pattern 1: モジュール構成設計

3層モジュールアーキテクチャ

ベースモジュール：VPC

構成モジュール：完全なアプリケーションインフラ

モジュールバージョニング

モジュールテスト

Pattern 2: 状態管理

リモートバックエンドアーキテクチャ

S3 + DynamoDBバックエンド設定

バックエンドインフラのブートストラップ

状態レイヤリング

ドリフト検出

Pattern 3: ワークスペース環境分離

ワークスペース vs ディレクトリ分離

推奨アプローチ：ディレクトリ分離 + 共有モジュール

環境設定

変数検証

Pattern 4: OpenTofu移行

移行評価

移行手順

OpenTofu独自機能：暗号化状態

段階的移行戦略

Pattern 5: GitOps統合

Atlantisアーキテクチャ

Atlantisのデプロイ

Atlantisリポジトリ設定

Policy as Code：Sentinel / OPA

5つのよくある落とし穴と解決策

落とし穴1: 状態ファイルの破損

落とし穴2: ProviderバージョンロックによるCI失敗

落とし穴3: 循環依存

落とし穴4: 機密変数の状態ファイルへの漏洩

落とし穴5: モジュールリファクタリングによるリソース再作成

10のよくあるエラートラブルシューティング

1. Error: Failed to load plugin

2. Error: Error locking state: Error acquiring the state lock

3. Error: Provider produced inconsistent result after apply

4. Error: Resource already managed by Terraform

5. Error: Module not found

6. Error: Invalid for_each argument

7. Error: Value for unconfigurable attribute

8. Error: Backend configuration changed

9. Error: Invalid terraform configuration: No required_providers

10. Error: Incompatible API version

高度な最適化のヒント

1. Terraform Cloud / Enterprise

2. Terraformテストフレームワーク

3. Infracostによるコスト見積もり

4. モジュールドキュメントの自動生成

比較分析：Terraform vs OpenTofu vs Pulumi vs CDK

意思決定ツリー

おすすめオンラインツール

1. `Error: Failed to load plugin`

2. `Error: Error locking state: Error acquiring the state lock`

3. `Error: Provider produced inconsistent result after apply`

4. `Error: Resource already managed by Terraform`

5. `Error: Module not found`

6. `Error: Invalid for_each argument`

7. `Error: Value for unconfigurable attribute`

8. `Error: Backend configuration changed`

9. `Error: Invalid terraform configuration: No required_providers`

10. `Error: Incompatible API version`