GCP 서비스 계정 생성 및 관리 가이드
이 문서는 Terraform과 Terragrunt를 사용하여 Google Cloud Platform(GCP)에서 서비스 계정을 생성하고 관리하는 방법을 설명합니다.
개요
서비스 계정은 GCP에서 애플리케이션이 리소스에 안전하게 접근할 수 있도록 하는 특별한 유형의 계정입니다. DTA-WIDE 프로젝트에서는 다양한 서비스 구성 요소가 각자의 권한으로 GCP 리소스에 접근할 수 있도록 서비스 계정을 사용합니다.
디렉토리 구조
infrastructure/
├── terraform/
│ └── modules/
│ ├── iam_service_account/ # 서비스 계정 생성 모듈
│ └── iam_service_account_roles/ # 기존 서비스 계정에 역할 부여 모듈
└── terragrunt/
├── root.hcl # 공통 설정
├── dev/
│ └── iam/
│ ├── bigquery_sa/ # BigQuery 서비스 계정 생성
│ └── terraform_service_account/ # Terraform 서비스 계정 역할 부여
├── stage/
│ └── iam/
│ └── (유사한 구조)
└── prod/
└── iam/
└── (유사한 구조)
모듈 설명
1. iam_service_account 모듈
이 모듈은 GCP 서비스 계정을 생성하고, 필요에 따라 역할을 부여하고 키를 생성하는 기능을 제공합니다.
주요 기능:
- 서비스 계정 생성
- 생성된 서비스 계정에 역할 부여
- 선택적으로 서비스 계정 키 생성
입력 변수
| 변수 이름 | 설명 | 타입 | 필수 | 기본값 |
|---|---|---|---|---|
project_id | GCP 프로젝트 ID | string | 예 | - |
account_id | 생성할 서비스 계정의 ID | string | 예 | - |
display_name | 서비스 계정의 표시 이름 | string | 예 | - |
description | 서비스 계정에 대한 설명 | string | 아니오 | "" |
roles | 서비스 계정에 부여할 역할 목록 | list(string) | 아니오 | [] |
create_key | 서비스 계정 키를 생성할지 여부 | bool | 아니오 | false |
key_algorithm | 키 생성 알고리즘 | string | 아니오 | "KEY_ALG_RSA_2048" |
public_key_type | 공개 키 유형 | string | 아니오 | "TYPE_X509_PEM_FILE" |
private_key_type | 개인 키 유형 | string | 아니오 | "TYPE_GOOGLE_CREDENTIALS_FILE" |
출력 값
| 이름 | 설명 |
|---|---|
service_account_id | 생성된 서비스 계정의 고유 ID |
service_account_email | 생성된 서비스 계정의 이메일 주소 |
service_account_name | 생성된 서비스 계정의 리소스 이름 |
key_id | 생성된 서비스 계정 키의 ID (키를 생성한 경우에만) |
key | 생성된 서비스 계정 키 (base64 인코딩된 JSON 형식, 키를 생성한 경우에만) |
2. iam_service_account_roles 모듈
이 모듈은 기존에 생성된 서비스 계정에 역할을 부여하는 기능만 제공합니다. 서비스 계정이 이미 존재해야 합니다.
사용 예시
서비스 계정 생성 및 권한 부여
새로운 서비스 계정을 생성하고 필요한 역할을 부여하려면:
-
서비스 계정을 위한 디렉토리 생성:
mkdir -p infrastructure/terragrunt/dev/iam/my_service_account -
Terragrunt 설정 파일 생성:
# infrastructure/terragrunt/dev/iam/my_service_account/terragrunt.hcl
include {
path = find_in_parent_folders("root.hcl")
}
terraform {
source = "../../../../terraform/modules/iam_service_account"
}
inputs = {
project_id = "dta-cloud-de-dev"
account_id = "my-service"
display_name = "My Service Account"
description = "내 애플리케이션을 위한 서비스 계정"
roles = [
"roles/storage.objectViewer",
"roles/pubsub.subscriber"
]
} -
서비스 계정 생성:
cd infrastructure/terragrunt/dev/iam/my_service_account
terragrunt init
terragrunt plan # 변경 사항 확인
terragrunt apply # 확인 후 적용
서비스 계정 키 생성
서비스 계정을 생성하면서 동시에 키를 생성하려면:
# infrastructure/terragrunt/dev/iam/my_service_account/terragrunt.hcl
include {
path = find_in_parent_folders("root.hcl")
}
terraform {
source = "../../../../terraform/modules/iam_service_account"
}
inputs = {
project_id = "dta-cloud-de-dev"
account_id = "my-service"
display_name = "My Service Account"
description = "내 애플리케이션을 위한 서비스 계정"
roles = [
"roles/storage.objectViewer",
"roles/pubsub.subscriber"
]
# 키 생성 활성화
create_key = true
}
그런 다음 Terragrunt 출력에서 key 값을 가져와 사용할 수 있습니다:
terragrunt output -raw key > my-service-key.json
# 주의: 이 파일은 민감한 정보를 포함하므로 안전하게 관리해야 합니다!
서비스 계정 관리 모범 사례
- 최소 권한 원칙: 서비스 계정에는 필요한 최소한의 권한만 부여합니다.
- 환경별 분리: 개발, 스테이징, 프로덕션 환경마다 별도의 서비스 계정을 사용합니다.
- 키 관리: 서비스 계정 키는 안전하게 관리하고, 가능하면 GCP의 워크로드 아이덴티티 페더레이션이나 메타데이터 서버를 활용합니다.
- 정기적 검토: 서비스 계정 권한을 정기적으로 검토하여 불필요한 권한을 제거합니다.
- 명명 규칙: 서비스 계정 ID에 용도를 명확히 나타내는 명명 규칙을 사용합니다. 예:
bigquery-processor,pubsub-subscriber등
문제 해결
서비스 계정 생성 실패
- 프로젝트 ID가 올바른지 확인하세요.
- 서비스 계정 ID가 중복되지 않았는지 확인하세요.
- 서비스 계정 ID 명명 규칙을 준수하는지 확인하세요 (6-30자, 소문자, 숫자, 하이픈만 가능).
역할 부여 실패
- IAM API가 활성화되어 있는지 확인하세요.
- 권한이 있는지 확인하세요 (보통
roles/iam.serviceAccountAdmin필요).
키 생성 실패
- 프로젝트당 서비스 계정 키 수 제한을 초과하지 않았는지 확인하세요.
- 키 생성 권한이 있는지 확인하세요.