[Terraform] HCL을 처음 만진 날, bootstrap 삽질기

bootstrap/versions.tf

terraform {
  # use_lockfile 이 GA 된 첫 버전
  required_version = ">= 1.11"

  required_providers {
    aws = {
      source = "hashicorp/aws"
      # aws_iam_openid_connect_provider 의 thumbprint_list 가 optional 이 된
      # 버전은 v5.81.0 (2024-12) — 그 미만에서는 생략 시 검증 에러가 난다.
      version = ">= 5.81"
    }
  }
}

provider "aws" {
  region = "ap-northeast-2"
}

bootstrap/variables.tf

variable "github_org" {
  description = "GitHub 조직 이름. OIDC sub 조건(repo:<org>/<repo>)의 기준이 된다."
  type        = string
}

variable "github_repo" {
  description = "IaC 저장소 이름. 조직 소유 저장소여야 한다."
  type        = string
  default     = "team-infra"
}

variable "state_bucket_name" {
  description = <<-EOT
    Terraform state 버킷 이름. S3 버킷 이름은 전역 유일해야 한다.
    변경 시 bootstrap/backend.tf 와 platform/backend.tf 의
    bucket 값도 함께 바꿀 것 (backend 블록은 변수를 못 쓴다).
  EOT
  type        = string
  default     = "team-tfstate"
}

variable "permissions_boundary_arn" {
  description = <<-EOT
    CI 롤에 붙일 권한 경계 정책 ARN.
    팀 IAM 설계상 "새로 생성되는 IAM 개체에 경계 강제"가 걸려 있다면
    이 값 없이는 CreateRole 자체가 거부될 수 있다. 예:
      arn:aws:iam::<ACCOUNT_ID>:policy/<경계정책이름>
  EOT
  type        = string
  default     = null
}

variable "plan_role_policy_arns" {
  description = "plan 롤에 붙일 관리형 정책 (읽기 전용)"
  type        = list(string)
  default     = ["arn:aws:iam::aws:policy/ReadOnlyAccess"]
}

variable "apply_role_policy_arns" {
  description = <<-EOT
    apply 롤에 붙일 관리형 정책. 기본값(PowerUser + IAMFull)은 사실상
    관리자 수준의 임시 구성이다. 반드시 권한 경계와 함께 쓰고,
    "FullAccess -> 최소권한 리팩터링" 목록에 이 롤을 등재해 축소한다.
  EOT
  type        = list(string)
  default = [
    "arn:aws:iam::aws:policy/PowerUserAccess",
    "arn:aws:iam::aws:policy/IAMFullAccess",
  ]
}

bootstrap/main.tf

# 원격 state 버킷 세트
# DynamoDB 없음 — 잠금은 backend 의 use_lockfile(S3 조건부 쓰기)이 담당한다.

resource "aws_s3_bucket" "tfstate" {
  bucket = var.state_bucket_name

  lifecycle {
    # state 버킷이 destroy 에 쓸려 나가는 사고 방지
    prevent_destroy = true
  }
}

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

  versioning_configuration {
    status = "Enabled"
  }
}

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

  rule {
    apply_server_side_encryption_by_default {
      sse_algorithm = "AES256"
    }
  }
}

resource "aws_s3_bucket_public_access_block" "tfstate" {
  bucket                  = aws_s3_bucket.tfstate.id
  block_public_acls       = true
  block_public_policy     = true
  ignore_public_acls      = true
  restrict_public_buckets = true
}

# .tflock 은 잠글 때 생성되고 풀 때 삭제된다. 버저닝 버킷에서 "삭제"는
# delete marker + noncurrent 버전을 남기므로, 치우는 규칙이 없으면
# plan/apply 마다 쓰레기가 쌓인다.
resource "aws_s3_bucket_lifecycle_configuration" "tfstate" {
  bucket     = aws_s3_bucket.tfstate.id
  depends_on = [aws_s3_bucket_versioning.tfstate]

  rule {
    id     = "expire-noncurrent"
    status = "Enabled"

    filter {}

    # 과거 state 복구 가능 창 = 30일
    noncurrent_version_expiration {
      noncurrent_days = 30
    }

    expiration {
      expired_object_delete_marker = true
    }

    abort_incomplete_multipart_upload {
      days_after_initiation = 7
    }
  }
}

bootstrap/oidc.tf

resource "aws_iam_openid_connect_provider" "github" {
  url            = "<https://token.actions.githubusercontent.com>"
  client_id_list = ["sts.amazonaws.com"]
  # thumbprint_list 생략: 2023-07부터 AWS가 신뢰 CA 라이브러리로 검증하며
  # provider 5.81+ 에서 optional.
}

# ---- plan 롤: 이 레포의 모든 sub(브랜치·태그·PR)에서 assume 가능 ----

data "aws_iam_policy_document" "plan_trust" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }

    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }

    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:${var.github_org}/${var.github_repo}:*"]
    }
  }
}

resource "aws_iam_role" "plan" {
  name                 = "github-actions-plan"
  assume_role_policy   = data.aws_iam_policy_document.plan_trust.json
  permissions_boundary = var.permissions_boundary_arn
  # IAM description 은 ASCII/Latin-1 만 허용 (한글 불가)
  description = "GitHub Actions PR plan only (read + state access)"
}

# ---- apply 롤: 보호된 main 브랜치에서만 assume 가능 ----

data "aws_iam_policy_document" "apply_trust" {
  statement {
    actions = ["sts:AssumeRoleWithWebIdentity"]

    principals {
      type        = "Federated"
      identifiers = [aws_iam_openid_connect_provider.github.arn]
    }

    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:aud"
      values   = ["sts.amazonaws.com"]
    }

    condition {
      test     = "StringEquals"
      variable = "token.actions.githubusercontent.com:sub"
      values   = ["repo:${var.github_org}/${var.github_repo}:ref:refs/heads/main"]
    }
  }
}

resource "aws_iam_role" "apply" {
  name                 = "github-actions-apply"
  assume_role_policy   = data.aws_iam_policy_document.apply_trust.json
  permissions_boundary = var.permissions_boundary_arn
  description = "GitHub Actions main-branch apply only. Least-privilege refactoring target."
}

# ---- state 버킷 접근 (두 롤 공통) ----
# plan 도 기본 동작으로 state 잠금을 잡으므로 두 롤 모두 필요하다.
# use_lockfile 은 락 파일(.tflock) 삭제 때문에 s3:DeleteObject 가 추가로 필요하다.
# 버킷/* 로 뭉치지 않고 state 키와 락 키를 분리한다 — state 객체에는
# Delete 를 주지 않고, Delete 는 .tflock 에만 허용한다.
# 루트 모듈이 늘면 이 목록에 키를 추가할 것.

locals {
  tfstate_keys = [
    "bootstrap/terraform.tfstate",
    "platform/terraform.tfstate",
  ]
}

data "aws_iam_policy_document" "tfstate_access" {
  statement {
    sid       = "ListStateBucket"
    actions   = ["s3:ListBucket"]
    resources = [aws_s3_bucket.tfstate.arn]
  }

  statement {
    sid = "ReadWriteState"
    actions = [
      "s3:GetObject",
      "s3:PutObject",
    ]
    resources = [for k in local.tfstate_keys : "${aws_s3_bucket.tfstate.arn}/${k}"]
  }

  statement {
    sid = "ManageLockFile"
    actions = [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject",
    ]
    resources = [for k in local.tfstate_keys : "${aws_s3_bucket.tfstate.arn}/${k}.tflock"]
  }
}

resource "aws_iam_policy" "tfstate_access" {
  name        = "team-tfstate-access"
  description = "Terraform remote state + .tflock access"
  policy      = data.aws_iam_policy_document.tfstate_access.json
}

resource "aws_iam_role_policy_attachment" "plan_state" {
  role       = aws_iam_role.plan.name
  policy_arn = aws_iam_policy.tfstate_access.arn
}

resource "aws_iam_role_policy_attachment" "apply_state" {
  role       = aws_iam_role.apply.name
  policy_arn = aws_iam_policy.tfstate_access.arn
}

# ---- plan 롤 읽기 가드 ----

data "aws_iam_policy_document" "plan_read_guard" {
  statement {
    sid    = "DenyObjectReadExceptState"
    effect = "Deny"
    actions = [
      "s3:GetObject",
      "s3:GetObjectVersion",
    ]
    not_resources = ["${aws_s3_bucket.tfstate.arn}/*"]
  }
}

resource "aws_iam_role_policy" "plan_read_guard" {
  name   = "read-guard"
  role   = aws_iam_role.plan.id
  policy = data.aws_iam_policy_document.plan_read_guard.json
}

# ---- apply 롤 자기 수정 차단 ----
# bootstrap 을 사람이 돌리는 것만으로는 self-modification 이 막히지 않는다.
# apply 롤에는 IAMFullAccess(iam:*) 가 붙어 있으므로, CI 자격 증명이
# 탈취되면 자기 trust policy·경계·정책을 바꿔 권한 상승이 가능하다.

data "aws_iam_policy_document" "apply_self_protect" {
  statement {
    sid    = "DenyCiRoleModification"
    effect = "Deny"
    actions = [
      "iam:UpdateAssumeRolePolicy",
      "iam:UpdateRole",
      "iam:UpdateRoleDescription",
      "iam:DeleteRole",
      "iam:PutRolePermissionsBoundary",
      "iam:DeleteRolePermissionsBoundary",
      "iam:AttachRolePolicy",
      "iam:DetachRolePolicy",
      "iam:PutRolePolicy",
      "iam:DeleteRolePolicy",
    ]
    resources = [
      aws_iam_role.plan.arn,
      aws_iam_role.apply.arn,
    ]
  }

  statement {
    sid    = "DenyTrustAnchorTampering"
    effect = "Deny"
    actions = [
      "iam:DeleteOpenIDConnectProvider",
      "iam:UpdateOpenIDConnectProviderThumbprint",
      "iam:AddClientIDToOpenIDConnectProvider",
      "iam:RemoveClientIDFromOpenIDConnectProvider",
    ]
    resources = [aws_iam_openid_connect_provider.github.arn]
  }

  statement {
    sid    = "DenyGuardPolicyTampering"
    effect = "Deny"
    actions = [
      "iam:CreatePolicyVersion",
      "iam:DeletePolicy",
      "iam:DeletePolicyVersion",
      "iam:SetDefaultPolicyVersion",
    ]
    # 경계 정책 자체의 내용 변경도 권한 상승 경로다.
    resources = compact([
      aws_iam_policy.tfstate_access.arn,
      var.permissions_boundary_arn,
    ])
  }
}

resource "aws_iam_role_policy" "apply_self_protect" {
  name   = "self-protect"
  role   = aws_iam_role.apply.id
  policy = data.aws_iam_policy_document.apply_self_protect.json
}

resource "aws_iam_role_policy_attachment" "plan_managed" {
  for_each   = toset(var.plan_role_policy_arns)
  role       = aws_iam_role.plan.name
  policy_arn = each.value
}

resource "aws_iam_role_policy_attachment" "apply_managed" {
  for_each   = toset(var.apply_role_policy_arns)
  role       = aws_iam_role.apply.name
  policy_arn = each.value
}

bootstrap/outputs.tf

output "oidc_provider_arn" {
  description = "GitHub OIDC 자격 증명 공급자 ARN"
  value       = aws_iam_openid_connect_provider.github.arn
}

output "plan_role_arn" {
  description = "GitHub 저장소 Variables 에 AWS_PLAN_ROLE_ARN 으로 등록"
  value       = aws_iam_role.plan.arn
}

output "apply_role_arn" {
  description = "GitHub 저장소 Variables 에 AWS_APPLY_ROLE_ARN 으로 등록"
  value       = aws_iam_role.apply.arn
}

output "state_bucket" {
  description = "원격 state 버킷 이름"
  value       = aws_s3_bucket.tfstate.id
}

bootstrap/backend.tf

terraform {
  backend "s3" {
    bucket       = "team-tfstate"
    key          = "bootstrap/terraform.tfstate"
    region       = "ap-northeast-2"
    use_lockfile = true
    encrypt      = true
  }
}

bootstrap/example.tfvars

github_org               = "<your-org>"
github_repo              = "team-infra"
state_bucket_name        = "team-tfstate"
permissions_boundary_arn = "arn:aws:iam::<ACCOUNT_ID>:policy/<경계정책이름>"

.github/workflows/terraform-plan.yml

name: terraform plan

on:
  pull_request:
    paths:
      - "platform/**"

permissions:
  id-token: write # OIDC 토큰 발급에 필수
  contents: read
  pull-requests: write # plan 결과를 PR 코멘트로 남기기 위해 필요

jobs:
  plan:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: platform
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_PLAN_ROLE_ARN }}
          aws-region: ap-northeast-2

      - uses: hashicorp/setup-terraform@v3

      - name: fmt check (repo 전체)
        working-directory: .
        run: terraform fmt -check -recursive

      - name: init
        run: terraform init

      - name: validate
        run: terraform validate

      - name: plan
        id: plan
        run: terraform plan -no-color -lock-timeout=60s
        continue-on-error: true

      - name: comment plan on PR
        uses: actions/github-script@v7
        env:
          PLAN_STDOUT: ${{ steps.plan.outputs.stdout }}
          PLAN_STDERR: ${{ steps.plan.outputs.stderr }}
        with:
          script: |
            const marker = '<!-- terraform-plan-platform -->';
            const ok = '${{ steps.plan.outcome }}' === 'success';

            // 코멘트 최대 길이(65536자) 초과 대비
            let output = ok ? process.env.PLAN_STDOUT : process.env.PLAN_STDERR;
            const LIMIT = 60000;
            if (output.length > LIMIT) {
              output = output.slice(0, LIMIT)
                + '\n... (출력이 잘렸습니다. 전체는 Actions 로그 참고)';
            }

            const body = [
              marker,
              `## platform terraform plan ${ok ? '✅' : '❌ 실패'}`,
              '',
              '<details><summary>plan 출력 펼치기</summary>',
              '',
              '```',
              output,
              '```',
              '',
              '</details>',
              '',
              `*commit ${context.sha.slice(0, 7)} ·`
                + ` [실행 로그](${context.serverUrl}/${context.repo.owner}/`
                + `${context.repo.repo}/actions/runs/${context.runId})*`,
            ].join('\n');

            const { data: comments } = await github.rest.issues.listComments({
              ...context.repo,
              issue_number: context.issue.number,
              per_page: 100,
            });
            const existing = comments.find(c => c.body.startsWith(marker));
            if (existing) {
              await github.rest.issues.updateComment({
                ...context.repo, comment_id: existing.id, body,
              });
            } else {
              await github.rest.issues.createComment({
                ...context.repo, issue_number: context.issue.number, body,
              });
            }

      - name: fail if plan failed
        if: steps.plan.outcome == 'failure'
        run: exit 1

.github/workflows/terraform-apply.yml

name: terraform apply

on:
  push:
    branches: [main]
    paths:
      - "platform/**"

permissions:
  id-token: write
  contents: read

concurrency:
  group: terraform-apply-platform # 같은 대상의 apply 중복 실행 방지
  cancel-in-progress: false

jobs:
  apply:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: platform
    steps:
      - uses: actions/checkout@v4

      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ vars.AWS_APPLY_ROLE_ARN }}
          aws-region: ap-northeast-2

      - uses: hashicorp/setup-terraform@v3

      - name: init
        run: terraform init

      - name: apply
        run: terraform apply -auto-approve -lock-timeout=60s