Terraform 상태 관리와 모듈 설계 실전 가이드: Remote Backend·State Locking·모듈화 패턴과 Drift Detection

{
  "version": 4,
  "terraform_version": "1.10.3",
  "serial": 42,
  "lineage": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "outputs": {
    "vpc_id": {
      "value": "vpc-0abc123def456789",
      "type": "string"
    }
  },
  "resources": [
    {
      "mode": "managed",
      "type": "aws_vpc",
      "name": "main",
      "provider": "provider[\"registry.terraform.io/hashicorp/aws\"]",
      "instances": [
        {
          "schema_version": 1,
          "attributes": {
            "id": "vpc-0abc123def456789",
            "cidr_block": "10.0.0.0/16",
            "tags": {
              "Name": "production-vpc"
            }
          }
        }
      ]
    }
  ]
}

# backend-bootstrap/main.tf
resource "aws_s3_bucket" "terraform_state" {
  bucket = "my-company-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_dynamodb_table" "terraform_locks" {
  name         = "terraform-state-locks"
  billing_mode = "PAY_PER_REQUEST"
  hash_key     = "LockID"

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

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

# terraform block
terraform {
  required_version = ">= 1.10.0"

  backend "s3" {
    bucket         = "my-company-terraform-state"
    key            = "production/network/terraform.tfstate"
    region         = "ap-northeast-2"
    encrypt        = true
    kms_key_id     = "arn:aws:kms:ap-northeast-2:123456789012:key/abcd-1234"
    dynamodb_table = "terraform-state-locks"
  }
}

terraform {
  backend "s3" {
    bucket       = "my-company-terraform-state"
    key          = "production/network/terraform.tfstate"
    region       = "ap-northeast-2"
    encrypt      = true
    use_lockfile = true
  }
}

terraform {
  backend "gcs" {
    bucket = "my-company-terraform-state"
    prefix = "production/network"
  }
}

terraform {
  cloud {
    organization = "my-company"

    workspaces {
      name = "production-network"
    }
  }
}

Error: Error acquiring the state lock
Lock Info:
  ID:        a1b2c3d4-e5f6-7890
  Path:      my-company-terraform-state/production/network/terraform.tfstate
  Operation: OperationTypeApply
  Who:       user@hostname
  Version:   1.10.3
  Created:   2026-03-11 09:15:30.123456 +0000 UTC

# 잠금 강제 해제 (반드시 다른 작업이 실행 중이 아닌지 확인 후)
terraform force-unlock a1b2c3d4-e5f6-7890

modules/
  vpc/
    main.tf          # 리소스 정의
    variables.tf     # 입력 변수
    outputs.tf       # 출력 값
    versions.tf      # 프로바이더 및 Terraform 버전 제약
    README.md        # 모듈 사용 문서
    examples/
      simple/
        main.tf
      complete/
        main.tf
    tests/
      vpc_test.go    # Terratest 기반 테스트

# environments/production/main.tf
module "vpc" {
  source  = "../../modules/vpc"
  name    = "production"
  cidr    = "10.0.0.0/16"
  azs     = ["ap-northeast-2a", "ap-northeast-2b", "ap-northeast-2c"]
}

module "security_groups" {
  source = "../../modules/security-groups"
  vpc_id = module.vpc.vpc_id
  environment = "production"
}

module "eks" {
  source             = "../../modules/eks"
  cluster_name       = "production-cluster"
  vpc_id             = module.vpc.vpc_id
  subnet_ids         = module.vpc.private_subnet_ids
  security_group_ids = [module.security_groups.eks_sg_id]
}

module "rds" {
  source             = "../../modules/rds"
  identifier         = "production-db"
  vpc_id             = module.vpc.vpc_id
  subnet_ids         = module.vpc.database_subnet_ids
  security_group_ids = [module.security_groups.rds_sg_id]
}

# modules/web-application/main.tf
# 내부에서 VPC, ALB, ECS, RDS 모듈을 조합
module "vpc" {
  source = "../vpc"
  cidr   = var.vpc_cidr
}

module "alb" {
  source    = "../alb"
  vpc_id    = module.vpc.vpc_id
  subnet_ids = module.vpc.public_subnet_ids
}

module "ecs" {
  source       = "../ecs"
  cluster_name = var.app_name
  vpc_id       = module.vpc.vpc_id
  alb_arn      = module.alb.alb_arn
}

# 소비자는 간단하게 사용
# environments/production/main.tf
module "web_app" {
  source   = "../../modules/web-application"
  app_name = "my-web-app"
  vpc_cidr = "10.0.0.0/16"
}

module "vpc" {
  source  = "app.terraform.io/my-company/vpc/aws"
  version = "~> 3.2.0"

  name = "production"
  cidr = "10.0.0.0/16"
}

# 상태만 새로고침하여 drift 확인 (인프라 변경 없음)
terraform plan -refresh-only

# 상세 출력으로 변경 사항 확인
terraform plan -refresh-only -detailed-exitcode
# 종료 코드: 0 = 변경 없음, 1 = 오류, 2 = drift 감지

#!/bin/bash
# drift-detection.sh
set -euo pipefail

SLACK_WEBHOOK_URL="https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX"

echo "Running drift detection..."
terraform init -backend=true -input=false

# -detailed-exitcode: 종료 코드 2는 변경 사항 존재
if terraform plan -refresh-only -detailed-exitcode -input=false > plan_output.txt 2>&1; then
  echo "No drift detected."
  exit 0
fi

EXIT_CODE=$?

if [ "$EXIT_CODE" -eq 2 ]; then
  echo "Drift detected! Sending notification..."
  DRIFT_SUMMARY=$(grep -E "^  #|^  ~|^  -|^  \+" plan_output.txt | head -20)

  curl -X POST "$SLACK_WEBHOOK_URL" \
    -H 'Content-Type: application/json' \
    -d "{\"text\": \"Drift detected in production infrastructure:\n\`\`\`\n${DRIFT_SUMMARY}\n\`\`\`\"}"
  exit 2
else
  echo "Error running terraform plan"
  exit 1
fi

# 1. backend 설정 추가 후
terraform init -migrate-state

# 2. 마이그레이션 확인 프롬프트에 yes 입력
# 3. 로컬 상태 파일 삭제
rm terraform.tfstate terraform.tfstate.backup

# 리소스 이름 변경
terraform state mv aws_instance.old_name aws_instance.new_name

# 모듈로 이동
terraform state mv aws_vpc.main module.network.aws_vpc.main

# 다른 상태 파일로 이동
terraform state mv -state-out=other.tfstate aws_s3_bucket.data aws_s3_bucket.data

# 기존 리소스를 Terraform 관리 하에 둠
terraform import aws_instance.web i-1234567890abcdef0

# 모듈 내 리소스 import
terraform import module.vpc.aws_vpc.main vpc-0abc123def456789

import {
  to = aws_instance.web
  id = "i-1234567890abcdef0"
}

moved {
  from = aws_instance.old_name
  to   = aws_instance.new_name
}

moved {
  from = aws_vpc.main
  to   = module.network.aws_vpc.main
}

output "database_password" {
  value     = aws_db_instance.main.password
  sensitive = true
}

environments/
  production/
    network/          # VPC, 서브넷, NAT GW (인프라팀)
    security/         # IAM, KMS, Security Group (보안팀)
    database/         # RDS, ElastiCache (DBA팀)
    application/      # ECS, Lambda, API GW (개발팀)
    monitoring/       # CloudWatch, Datadog (SRE팀)
  staging/
    ...

data "terraform_remote_state" "network" {
  backend = "s3"
  config = {
    bucket = "my-company-terraform-state"
    key    = "production/network/terraform.tfstate"
    region = "ap-northeast-2"
  }
}

resource "aws_instance" "web" {
  subnet_id = data.terraform_remote_state.network.outputs.private_subnet_ids[0]
}

# 1. S3 버전 관리에서 이전 버전 복원
aws s3api list-object-versions \
  --bucket my-company-terraform-state \
  --prefix production/network/terraform.tfstate

# 2. 정상적인 이전 버전을 다운로드
aws s3api get-object \
  --bucket my-company-terraform-state \
  --key production/network/terraform.tfstate \
  --version-id "VERSION_ID_HERE" \
  restored-state.tfstate

# 3. 상태 파일 검증
terraform show restored-state.tfstate

# 4. 복원된 상태 파일 업로드
aws s3 cp restored-state.tfstate \
  s3://my-company-terraform-state/production/network/terraform.tfstate

# 5. refresh로 최신 상태 동기화
terraform apply -refresh-only

# 1. 실제로 다른 작업이 실행 중인지 확인
# DynamoDB에서 잠금 항목 조회
aws dynamodb get-item \
  --table-name terraform-state-locks \
  --key '{"LockID": {"S": "my-company-terraform-state/production/network/terraform.tfstate"}}'

# 2. 잠금 소유자와 시간 확인 후 강제 해제
terraform force-unlock LOCK_ID_HERE

# 3. 상태 무결성 확인
terraform plan

# 1. 현재 원격 상태 다운로드
terraform state pull > remote-state.json

# 2. serial 번호 확인
python3 -c "import json; print(json.load(open('remote-state.json'))['serial'])"

# 3. refresh로 상태 동기화
terraform apply -refresh-only

# 4. 변경 사항 재적용
terraform plan
terraform apply