본문으로 건너뛰기

GCP 커스텀 IAM Role (name: Terraform)

개요​

이 문서는 Terraform을 사용하여 Google Cloud Platform (GCP) 프로젝트 내에 커스텀 IAM 역할을 생성하고 관리하는 방법을 설명합니다. 커스텀 역할을 사용하면 사전 정의된 역할보다 세분화된 권한 제어가 가능하여 최소 권한 원칙을 효과적으로 구현할 수 있습니다.

DTA-WIDE 시스템에서는 Terraform을 사용하여 인프라 변경을 자동화하고 있으며, Terraform 실행 주체(예: 서비스 계정)에 필요한 최소한의 권한을 부여하기 위해 이 커스텀 역할을 사용합니다.

구성 및 아키텍처​

  • 역할 ID: TerraformRole (프로젝트 내 고유 ID)
  • 역할 이름: Terraform (GCP 콘솔에 표시되는 이름)
  • 관리 수준: 프로젝트 (패턴: dta-cloud-de-[dev|stage|prod])
  • 관리 도구: Terraform, Terragrunt
  • 형상 관리: Git (이 저장소)

Terraform을 통한 인프라 관리​

구현 요소​

커스텀 IAM 역할을 Terraform으로 관리하기 위해 다음 요소를 사용합니다:

  1. Terraform 모듈: 재사용 가능한 google_project_iam_custom_role 리소스 정의 (/infrastructure/terraform/modules/iam/)
  2. Terragrunt 구성: 환경별(dev, stage, prod) 설정값 관리 (/infrastructure/terragrunt/[dev|stage|prod]/iam/)

Terraform 모듈 구조 (/infrastructure/terraform/modules/iam/main.tf)​

variable "project_id" {
  description = "The GCP project ID where the custom role will be created."
  type        = string
}

resource "google_project_iam_custom_role" "terraform_role" {
  project     = var.project_id
  role_id     = "TerraformRole"
  title       = "Terraform"
  description = "Custom role for Terraform service account with necessary permissions."
  stage       = "GA" # 일반 안정화 버전
  permissions = [
    # --- (241개의 권한 목록) ---
    "certificatemanager.certmapentries.create",
    "certificatemanager.certmapentries.delete",
    # ... (중략) ...
    "storage.objects.list"
    # --- (권한 목록 끝) ---
  ]
}

  • project_id: 역할을 생성할 GCP 프로젝트 ID (Terragrunt에서 환경별로 주입)
  • role_id: 커스텀 역할의 고유 ID
  • title: GCP 콘솔에 표시될 역할 이름
  • description: 역할에 대한 설명
  • stage: 역할의 출시 단계 (GA, BETA, ALPHA 등)
  • permissions: 역할에 부여할 권한 목록

환경별 Terragrunt 구성​

각 환경(dev, stage, prod)에서 IAM 모듈을 사용하기 위한 Terragrunt 설정입니다. 환경별 프로젝트 ID가 inputs 블록을 통해 Terraform 모듈에 전달됩니다.

  • Dev: /infrastructure/terragrunt/dev/iam/terragrunt.hcl 
    include {
      path = find_in_parent_folders()
    }

    terraform {
      source = "../../../terraform/modules/iam"
    }

    inputs = {
      project_id = "dta-cloud-de-dev"
    }
  • Stage: /infrastructure/terragrunt/stage/iam/terragrunt.hcl 
    include {
      path = find_in_parent_folders()
    }

    terraform {
      source = "../../../terraform/modules/iam"
    }

    inputs = {
      project_id = "dta-cloud-de-stage"
    }
  • Prod: /infrastructure/terragrunt/prod/iam/terragrunt.hcl 
    include {
      path = find_in_parent_folders()
    }

    terraform {
      source = "../../../terraform/modules/iam"
    }

    inputs = {
      project_id = "dta-cloud-de-prod" # 실제 프로덕션 프로젝트 ID 확인 필요
    }

배포 방법​

사전 요구 사항​

  1. 대상 환경의 GCP 프로젝트(dta-cloud-de-[dev|stage|prod])가 존재해야 합니다.
  2. 각 프로젝트에서 IAM API (iam.googleapis.com)가 활성화되어 있어야 합니다.
  3. Terraform 및 Terragrunt가 로컬 또는 CI/CD 환경에 설치되어 있어야 합니다.
  4. 배포를 실행하는 주체(사용자 또는 서비스 계정)는 대상 프로젝트에 대한 roles/iam.roleAdmin 또는 커스텀 역할을 생성/수정할 수 있는 충분한 권한을 가지고 있어야 합니다.

배포 단계​

각 환경별 디렉토리로 이동하여 다음 명령어를 실행합니다.

  • Dev 환경: 
    cd infrastructure/terragrunt/dev/iam
    terragrunt init
    terragrunt plan
    terragrunt apply # 확인 후 실행
  • Stage 환경: 
    cd infrastructure/terragrunt/stage/iam
    terragrunt init
    terragrunt plan
    terragrunt apply # 확인 후 실행
  • Prod 환경: (변경 관리 절차 준수) 
    cd infrastructure/terragrunt/prod/iam
    terragrunt init
    terragrunt plan -out=iam-prod-plan.tfplan
    # 계획 검토 및 승인 후
    terragrunt apply iam-prod-plan.tfplan

보안 설정​

  • 최소 권한 원칙: 이 커스텀 역할은 Terraform이 인프라를 관리하는 데 필요한 최소한의 권한만 포함하도록 설계되었습니다. 불필요한 권한은 제거해야 합니다.
  • 정기 검토: 역할에 부여된 권한 목록은 주기적으로 검토하여 필요한 권한만 유지되고 있는지 확인해야 합니다. 특히 GCP 서비스 변경이나 Terraform 프로바이더 업데이트 시 검토가 필요합니다.
  • 역할 사용 제한: 이 역할은 Terraform 실행을 위한 서비스 계정 등 명확한 목적을 가진 주체에게만 부여되어야 합니다.

모범 사례​

  • 권한 설명 추가: 각 권한 또는 권한 그룹에 대해 주석을 추가하여 왜 해당 권한이 필요한지 명확히 합니다.
  • 모듈화 유지: IAM 역할 정의를 별도의 모듈로 관리하여 재사용성과 유지보수성을 높입니다.
  • 변경 관리: 프로덕션 환경의 역할 변경은 terragrunt plan 결과를 검토하고 승인하는 절차를 거칩니다.
  • 버전 관리: 모든 변경 사항은 Git을 통해 버전 관리됩니다.

문제 해결​

  • Permission Denied 오류: terragrunt apply 실행 시 권한 부족 오류가 발생하면, 배포 주체에게 해당 환경 프로젝트에 필요한 권한(예: roles/iam.roleAdmin)이 있는지 확인하거나, Terraform 모듈 내 permissions 목록에 누락된 권한이 있는지 확인합니다.
  • 역할 업데이트 실패: 역할 업데이트 시 충돌이 발생하면 GCP 콘솔에서 직접 수정된 사항이 있는지 확인하고 Terraform 상태와 동기화해야 할 수 있습니다 (terraform import 또는 수동 조정).

변경 이력​

버전날짜작성자변경 내용
0.1.02025-03-27bok@weltcorp.com커스텀 IAM 역할 문서 초기 생성
0.2.02025-03-29(Gemini)bigquery.md 형식 적용, dev/stage 환경 구성 추가, 프로젝트 ID 패턴 명시