시리즈: gcloud CLI 자동화 운영 플레이북 (총 11편) | 5회
프로젝트부터 IAM까지, gcloud로 조직 운영을 자동화하는 6단계 프로비저닝
새 프로젝트를 만들 때마다 콘솔에서 클릭하고, API 활성화하고, IAM 권한 주고… 매번 같은 작업을 반복하고 있다면 이 글이 답이에요. 프로젝트 생성부터 IAM 바인딩까지 6단계를 코드화하면 실수도 줄고 온보딩 속도도 빨라져요.
Summary
- 프로젝트는 비용과 권한이 만나는 경계야 – 생성 절차를 코드화하지 않으면 거버넌스가 무너져
- 표준 프로비저닝은 “폴더 배치 -> 프로젝트 생성 -> 태그/라벨 -> 빌링 연결 -> IAM -> API enable” 6단계로 고정해
- 태그는 “통제(정책 집행)”용이고 라벨은 “분류(비용/검색)”용이야 – 이걸 헷갈리면 거버넌스 설계가 꼬여
- IAM은 기본 역할(Owner/Editor) 대신 최소권한 + 그룹 기반 + 조건부로 설계하는 게 정석이야
이 글의 대상
- 새 프로젝트를 수작업으로 만들고 있어서 표준화가 필요한 플랫폼 엔지니어
- 태그와 라벨의 차이를 명확히 이해하고 거버넌스에 적용하고 싶은 보안/운영 담당자
- IAM 권한을 “일단 Owner 줘” 식으로 운영하다가 감사에서 지적받은 경험이 있는 팀 리더
목차
- 프로젝트 = 비용 + 권한의 경계
- 표준 프로비저닝 6단계 워크플로우
- Step 1~2: 폴더 배치와 프로젝트 생성
- Step 3: 태그 vs 라벨 – 통제와 분류를 구분하라
- Step 4: 빌링 연결
- Step 5: IAM – 최소권한, 그룹 기반, 조건부
- Step 6: API enablement 파일 관리
- 전체 프로비저닝 스크립트 예시
- 실패 케이스와 트러블슈팅
1. 프로젝트 = 비용 + 권한의 경계
결론부터 말하면, Google Cloud에서 프로젝트는 단순한 “폴더”가 아니야. 비용(Billing)과 권한(IAM)이 만나는 핵심 경계선이야.
조직 계층 구조
Organization (회사)
├── Folder (부서/팀/환경)
│ ├── Project (개발)
│ ├── Project (스테이징)
│ └── Project (프로덕션)
└── Folder (인프라)
├── Project (네트워크)
└── Project (보안/KMS)
| 레벨 | 역할 | 핵심 |
|---|---|---|
| Organization | 최상위 정책 단위 | 조직정책(Org Policy) 적용 |
| Folder | 부서/팀/환경 그룹핑 | IAM 상속, 정책 범위 제한 |
| Project | 리소스/비용/권한의 실체 | 청구 계정 연결, API 활성화, IAM 바인딩 |
프로젝트를 제대로 설계하지 않으면 이런 문제가 생겨:
- 비용 혼선: 개발과 운영 비용이 섞여서 팀별 비용 추적 불가
- 권한 범람: “일단 Editor 줘”가 프로덕션 데이터 삭제로 이어짐
- 환경 오염: 테스트 데이터가 프로덕션 프로젝트에 들어감
그래서 프로젝트 생성 절차를 코드화하는 게 중요해. 수작업으로 콘솔에서 만들면 매번 설정이 달라지거든.
2. 표준 프로비저닝 6단계 워크플로우
모든 새 프로젝트는 이 순서를 따르는 게 좋아:
| 단계 | 작업 | 왜 이 순서인지 |
|---|---|---|
| 1 | 폴더 배치 | 프로젝트가 들어갈 위치를 먼저 정해야 IAM 상속이 정해져 |
| 2 | 프로젝트 생성 | 폴더 아래에 프로젝트를 만들어 |
| 3 | 태그/라벨 적용 | 생성 즉시 거버넌스 메타데이터를 붙여야 추적 가능 |
| 4 | 빌링 연결 | 빌링이 없으면 유료 API나 리소스를 쓸 수 없어 |
| 5 | IAM 바인딩 | 그룹 기반 최소권한으로 초기 접근 설정 |
| 6 | API enable | 필요한 서비스만 정확하게 활성화 |
이 순서를 뒤바꾸면 문제가 생겨. 예를 들어 빌링 연결 없이 API를 enable하려 하면 실패하거든.
3. Step 1~2: 폴더 배치와 프로젝트 생성
폴더 생성
# 조직 아래에 폴더 생성
gcloud resource-manager folders create \
--display-name="infra-prod" \
--organization=ORGANIZATION_ID
# 기존 폴더 아래에 하위 폴더 생성
gcloud resource-manager folders create \
--display-name="payment-team" \
--folder=PARENT_FOLDER_ID
프로젝트 생성
# 폴더 하위에 프로젝트 생성
gcloud projects create my-payment-prod \
--folder=FOLDER_ID \
--name="Payment Service Production"
# 조직 직접 하위에 프로젝트 생성 (태그 동시 부여)
gcloud projects create my-payment-prod \
--organization=ORGANIZATION_ID \
--tags=ORG_ID/environment=production
프로젝트 ID 규칙 (놓치면 재생성해야 돼)
| 규칙 | 설명 |
|---|---|
| 길이 | 6~30자 |
| 문자 | 소문자, 숫자, 하이픈만 허용 |
| 시작 | 소문자로 시작해야 해 |
| 변경 | 프로젝트 ID는 한 번 정하면 변경 불가 |
| 재사용 | 삭제된 프로젝트의 ID도 일정 기간 재사용 불가 |
네이밍 규칙을 팀에서 먼저 합의하는 게 정말 중요해. 예:
[팀]-[서비스]-[환경]->payment-api-prod
검증
# 프로젝트 정보 확인
gcloud projects describe my-payment-prod
# 프로젝트 목록에서 확인
gcloud projects list --filter="projectId:my-payment*"
4. Step 3: 태그 vs 라벨 – 통제와 분류를 구분하라
이 구분을 제대로 이해해야 거버넌스 설계가 깔끔해져. 많은 사람이 헷갈리는 부분이야.
한 줄 요약
| 구분 | 태그 (Tag) | 라벨 (Label) |
|---|---|---|
| 목적 | 통제 (정책 집행) | 분류 (비용/검색) |
| 관리 범위 | 조직 수준 | 리소스/프로젝트 수준 |
| IAM 연동 | IAM Conditions에서 사용 가능 | 불가 |
| 조직정책 연동 | 가능 | 불가 |
| 비용 리포트 | 가능 | 가능 (주로 이 용도) |
| 생성 주체 | 조직 관리자가 키/값 정의 | 리소스 소유자가 자유롭게 |
태그 – 정책 집행의 핵심 도구
# 1. 태그 키 생성 (조직 관리자)
gcloud resource-manager tags keys create environment \
--parent=organizations/ORG_ID
# 2. 태그 값 생성
gcloud resource-manager tags values create production \
--parent=tagKeys/TAG_KEY_ID
gcloud resource-manager tags values create development \
--parent=tagKeys/TAG_KEY_ID
# 3. 프로젝트에 태그 바인딩
gcloud resource-manager tags bindings create \
--tag-value=ORG_ID/environment/production \
--parent=//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER
# 4. 바인딩 확인
gcloud resource-manager tags bindings list \
--parent=//cloudresourcemanager.googleapis.com/projects/PROJECT_NUMBER
태그의 진짜 힘은 IAM Conditions와 조직정책에서 발휘돼. 예를 들어 “environment=production 태그가 붙은 리소스에만 compute.admin 권한을 줘”라는 조건을 걸 수 있어.
라벨 – 비용 추적과 검색의 도구
# 프로젝트에 라벨 추가
gcloud projects update my-payment-prod \
--update-labels=team=payment,cost-center=cc-1234,owner=jayden
# 라벨로 리소스 필터링
gcloud compute instances list --filter="labels.team=payment"
# 빌링 리포트에서 라벨별 비용 확인 가능
운영 팁
- 태그는 생성 단계에서 바로 부여해야 해. 나중에 하면 빈 기간이 생겨서 정책 적용이 안 될 수 있어
- 라벨은 팀 표준 키를 미리 정해둬.
team,env,cost-center,owner같은 필수 라벨 목록을 만들어 놓는 거지 - 태그/라벨이 비용 리포트에 반영되기까지 지연이 있을 수 있어. “바로 안 보인다”고 당황하지 마
5. Step 4: 빌링 연결
# 빌링 계정 연결 (beta 명령)
gcloud beta billing projects link my-payment-prod \
--billing-account=BILLING_ACCOUNT_ID
# 연결 확인
gcloud beta billing projects describe my-payment-prod
빌링 연결이 안 되면 유료 API enable이 실패하고, 리소스 생성도 거부돼. 반드시 API enable 전에 해야 해.
6. Step 5: IAM – 최소권한, 그룹 기반, 조건부
IAM 설계는 프로젝트 운영의 핵심이야. 세 가지 원칙을 기억하자.
원칙 1: 기본 역할은 쓰지 마
| 역할 유형 | 예시 | 권장 여부 |
|---|---|---|
| 기본 역할 | Owner, Editor, Viewer | 비추천 (너무 넓어) |
| 사전정의 역할 | roles/compute.admin, roles/storage.objectViewer | 추천 |
| 커스텀 역할 | 직접 권한 조합 | 세밀한 통제 필요 시 |
# 나쁜 예: Editor 역할 부여 (절대 하지 마)
# gcloud projects add-iam-policy-binding my-project --member='user:someone@example.com' --role='roles/editor'
# 좋은 예: 필요한 역할만 부여
gcloud projects add-iam-policy-binding my-payment-prod \
--member='group:payment-devs@example.com' \
--role='roles/compute.viewer'
원칙 2: 그룹 기반으로 부여해
개인 사용자에게 역할을 주면 입사/퇴사/팀 이동 때마다 일일이 바꿔야 해. 그룹에 주면 그룹 멤버만 관리하면 돼.
# 개발팀 그룹에 Compute 관리 권한
gcloud projects add-iam-policy-binding my-payment-prod \
--member='group:payment-devs@example.com' \
--role='roles/compute.admin'
# 운영팀 그룹에 모니터링 권한
gcloud projects add-iam-policy-binding my-payment-prod \
--member='group:payment-ops@example.com' \
--role='roles/monitoring.viewer'
# 서비스계정에 스토리지 권한
gcloud projects add-iam-policy-binding my-payment-prod \
--member='serviceAccount:payment-app@my-payment-prod.iam.gserviceaccount.com' \
--role='roles/storage.objectAdmin'
원칙 3: 조건부 접근 제어 (IAM Conditions)
태그와 결합하면 엄청 강력해져.
# 예시 1: 프로덕션 태그가 붙은 리소스에만 Compute Admin 허용
gcloud resource-manager folders add-iam-policy-binding $FOLDER_ID \
--member='group:infra@company.com' \
--role='roles/compute.admin' \
--condition-title='prod-only' \
--condition-description='Grant Compute Admin only for resources tagged env=prod' \
--condition-expression='resource.matchTag("ORG_ID/environment", "production")'
# 예시 2: 근무시간에만 접근 허용 (외부 계약자용)
gcloud projects add-iam-policy-binding my-payment-prod \
--member='user:contractor@example.com' \
--role='roles/viewer' \
--condition-title='business-hours' \
--condition-description='Access only during business hours' \
--condition-expression='request.time.getHours("Asia/Seoul") >= 9 && request.time.getHours("Asia/Seoul") < 18 && request.time.getDayOfWeek("Asia/Seoul") >= 1 && request.time.getDayOfWeek("Asia/Seoul") <= 5'
IAM 정책 검증
# 전체 IAM 정책 확인
gcloud projects get-iam-policy my-payment-prod --format=json
# 특정 바인딩만 보기 (조건부 포함)
gcloud projects get-iam-policy my-payment-prod \
--flatten="bindings[]" \
--format="json(bindings)"
7. Step 6: API enablement 파일 관리
“API not enabled” 에러는 실무에서 정말 자주 터져. 이걸 근절하는 가장 좋은 방법은 필요 API 목록을 파일로 관리하는 거야.
API 목록 파일 만들기
# apis.txt (서비스별 필요 API 목록)
compute.googleapis.com
container.googleapis.com
run.googleapis.com
cloudbuild.googleapis.com
secretmanager.googleapis.com
cloudkms.googleapis.com
logging.googleapis.com
monitoring.googleapis.com
일괄 활성화 스크립트
#!/bin/bash
PROJECT_ID="my-payment-prod"
API_FILE="apis.txt"
echo "=== API 활성화 시작: $PROJECT_ID ==="
while IFS= read -r api; do
# 빈 줄과 주석 건너뛰기
[[ -z "$api" || "$api" == \#* ]] && continue
echo "활성화 중: $api"
gcloud services enable "$api" --project="$PROJECT_ID" --quiet
done < "$API_FILE"
echo "=== 활성화 완료. 검증 중... ==="
gcloud services list --project="$PROJECT_ID" --enabled --format="table(NAME)"
여러 API 한 번에 활성화 (빠른 방법)
# 공백으로 구분해서 한 번에 여러 개 enable
gcloud services enable \
compute.googleapis.com \
container.googleapis.com \
run.googleapis.com \
--project=my-payment-prod \
--async
# --async를 붙이면 백그라운드에서 처리돼서 더 빨라
현재 활성 API 확인
# 활성화된 API 목록
gcloud services list --project=my-payment-prod --enabled
# 특정 API가 활성화돼 있는지 확인
gcloud services list --project=my-payment-prod --enabled --filter="NAME:compute"
8. 전체 프로비저닝 스크립트 예시
6단계를 하나의 스크립트로 묶으면 이렇게 돼:
#!/bin/bash
set -euo pipefail
# === 변수 정의 ===
PROJECT_ID="payment-api-prod"
PROJECT_NAME="Payment API Production"
FOLDER_ID="123456789012"
BILLING_ACCOUNT="01ABCD-234EFG-567HIJ"
ORG_ID="987654321"
REGION="asia-northeast3"
echo "=== Step 1~2: 프로젝트 생성 ==="
gcloud projects create "$PROJECT_ID" \
--folder="$FOLDER_ID" \
--name="$PROJECT_NAME" \
--quiet
echo "=== Step 3: 태그/라벨 적용 ==="
# 라벨
gcloud projects update "$PROJECT_ID" \
--update-labels=team=payment,env=prod,cost-center=cc-pay-001
# 태그 바인딩 (프로젝트 번호 필요)
PROJECT_NUMBER=$(gcloud projects describe "$PROJECT_ID" --format='value(projectNumber)')
gcloud resource-manager tags bindings create \
--tag-value="$ORG_ID/environment/production" \
--parent="//cloudresourcemanager.googleapis.com/projects/$PROJECT_NUMBER" \
--quiet
echo "=== Step 4: 빌링 연결 ==="
gcloud beta billing projects link "$PROJECT_ID" \
--billing-account="$BILLING_ACCOUNT"
echo "=== Step 5: IAM 바인딩 ==="
# 개발팀 그룹
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member='group:payment-devs@company.com' \
--role='roles/compute.viewer' --quiet
# 운영팀 그룹
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member='group:payment-ops@company.com' \
--role='roles/compute.admin' --quiet
# 서비스계정 생성 및 권한
gcloud iam service-accounts create payment-app-sa \
--display-name="Payment App Service Account" \
--project="$PROJECT_ID"
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
--member="serviceAccount:payment-app-sa@${PROJECT_ID}.iam.gserviceaccount.com" \
--role='roles/storage.objectAdmin' --quiet
echo "=== Step 6: API 활성화 ==="
gcloud services enable \
compute.googleapis.com \
container.googleapis.com \
run.googleapis.com \
secretmanager.googleapis.com \
--project="$PROJECT_ID" --quiet
echo "=== 검증 ==="
echo "--- 프로젝트 정보 ---"
gcloud projects describe "$PROJECT_ID"
echo "--- IAM 정책 ---"
gcloud projects get-iam-policy "$PROJECT_ID" \
--format="table(bindings.role, bindings.members)"
echo "--- 활성 API ---"
gcloud services list --project="$PROJECT_ID" --enabled \
--format="table(NAME)"
echo "=== 프로비저닝 완료! ==="
이 스크립트를 팀 저장소에 두고, 새 프로젝트가 필요할 때마다 변수만 바꿔서 실행하면 돼. 매번 일관된 설정이 보장되니까 사고가 줄어들어.
9. 실패 케이스와 트러블슈팅
실패 1: “API not enabled” 에러
ERROR: (gcloud.compute.instances.create) PERMISSION_DENIED:
Compute Engine API has not been used in project 123456 before or it is disabled.
원인: 해당 프로젝트에서 Compute Engine API가 활성화되지 않았어.
해결:
gcloud services enable compute.googleapis.com --project=my-project-id
예방: 프로비저닝 스크립트에 필요한 API를 모두 포함시켜놓는 게 최선이야.
실패 2: 빌링 없이 API enable 시도
ERROR: (gcloud.services.enable) FAILED_PRECONDITION:
Billing account for project '123456' is not found.
원인: 빌링 계정이 연결되지 않은 상태에서 유료 API를 활성화하려 했어.
해결: 빌링 먼저 연결 -> API enable 순서를 지켜.
실패 3: 프로젝트 ID 규칙 위반
ERROR: (gcloud.projects.create) INVALID_ARGUMENT:
Request contains an invalid argument.
원인: 프로젝트 ID에 대문자, 밑줄, 특수문자가 들어갔거나 30자를 초과했어.
규칙: 소문자+숫자+하이픈, 6~30자, 소문자로 시작.
실패 4: IAM 바인딩 시 조건식 오류
ERROR: (gcloud.projects.add-iam-policy-binding) INVALID_ARGUMENT:
Condition expression is not valid.
원인: --condition-expression의 CEL(Common Expression Language) 문법 오류야.
해결: 조건식을 테스트할 때는 간단한 조건부터 시작해서 점진적으로 복잡하게 만들어가. 문법 참고는 IAM Conditions 개요 문서에서 확인해.
실패 5: 조직 쿼터 초과
ERROR: (gcloud.projects.create) RESOURCE_EXHAUSTED:
Quota exceeded for quota group 'ProjectMutationGroup'.
원인: 조직에 허용된 프로젝트 수 한도에 도달했어.
해결: Google Cloud 콘솔에서 쿼터 증가를 요청하거나, 사용하지 않는 프로젝트를 정리해.
핵심 정리
1. 프로젝트는 비용과 권한의 경계야 -- 생성 절차를 코드화해서 일관성을 보장해야 해
2. 표준 프로비저닝 6단계(폴더->프로젝트->태그/라벨->빌링->IAM->API)를 순서대로 지켜
3. 태그는 통제(IAM Conditions, 조직정책), 라벨은 분류(비용, 검색) -- 이 구분이 거버넌스의 기초야
4. IAM은 기본 역할(Owner/Editor) 대신 사전정의 역할을 그룹 기반으로 부여하고, 필요하면 조건부를 걸어
FAQ
Q. 프로젝트 ID와 프로젝트 이름(name)은 뭐가 달라?
A. 프로젝트 ID는 전 세계적으로 고유한 식별자이고 한 번 정하면 변경 불가해. 프로젝트 이름은 표시용이고 언제든 바꿀 수 있어. API 호출이나 CLI에서는 항상 프로젝트 ID를 사용해.
Q. 태그를 꼭 써야 해? 라벨만으로 충분하지 않아?
A. 비용 추적과 리소스 검색만 필요하면 라벨로 충분해. 하지만 “특정 환경의 리소스에만 IAM 권한을 제한”하거나 “조직정책으로 특정 태그 없는 리소스 생성을 차단”하려면 태그가 필수야. 조직이 커질수록 태그의 가치가 올라가.
Q. 프로젝트별 API 목록은 어떻게 관리하는 게 좋아?
A. 서비스 유형별로 API 목록 파일을 만들어 Git으로 관리하는 게 가장 좋아. 예를 들어 apis-web-service.txt, apis-data-pipeline.txt 이런 식으로. 새 프로젝트를 만들 때 해당 유형의 파일로 일괄 enable하면 돼.
Q. IAM Conditions의 조건식이 틀리면 접근이 완전히 차단돼?
A. 맞아, 조건식이 잘못되면 의도치 않게 접근이 차단될 수 있어. 그래서 조건부 바인딩을 추가하기 전에 반드시 테스트 프로젝트에서 먼저 검증하고, 기존 비조건부 바인딩은 유지한 상태에서 점진적으로 전환하는 게 안전해.
Q. 서비스계정은 프로젝트마다 따로 만들어야 해?
A. 원칙적으로는 서비스 단위(마이크로서비스/워크로드)로 서비스계정을 분리하는 게 최소권한 원칙에 맞아. 하나의 서비스계정을 여러 프로젝트에서 공유하면 권한이 불필요하게 넓어질 수 있어.
Q. gcloud로 IAM 역할을 부여할 때 기존 바인딩이 삭제돼?
A. add-iam-policy-binding은 기존 바인딩을 유지하면서 새로운 바인딩을 추가해. 삭제하려면 remove-iam-policy-binding을 써야 해. 하지만 set-iam-policy는 전체 정책을 덮어쓰니까 조심해야 해.
Q. 폴더(Folder) 없이 프로젝트를 조직 바로 아래에 만들어도 돼?
A. 기술적으로는 가능하지만 비추천이야. 폴더가 없으면 프로젝트가 많아질 때 IAM 관리가 힘들어지고, 조직정책을 환경별로 다르게 적용하기 어려워져. 최소한 환경(dev/staging/prod)별로 폴더를 두는 게 좋아.
Q. 태그 바인딩에서 왜 프로젝트 번호(number)를 쓰지 프로젝트 ID가 아니야?
A. 태그 바인딩의 --parent는 Cloud Resource Manager의 리소스 경로를 사용하는데, 이 경로에는 프로젝트 번호가 들어가. 프로젝트 번호는 gcloud projects describe PROJECT_ID --format='value(projectNumber)'로 확인할 수 있어.
Q. 빌링 계정 연결 권한은 누구한테 있어?
A. roles/billing.projectManager 역할이 필요해. 보통 조직의 빌링 관리자가 이 권한을 가지고 있고, 프로비저닝을 자동화하는 서비스계정에도 이 역할을 부여해야 해.
참고 자료 (References)
데이터 출처
| 출처 | 설명 | 링크 |
|---|---|---|
| Google Cloud 공식 문서 | 프로젝트 생성 및 관리 | 프로젝트 생성/관리 |
| Google Cloud 공식 문서 | Tags 생성 및 관리 | Tags 생성/관리 |
| Google Cloud 공식 문서 | IAM Conditions 개요 | IAM Conditions |
| Google Cloud 공식 문서 | 서비스 활성화/비활성화 | services enable |
| Google Cloud 공식 문서 | IAM 문서 | IAM 가이드 |
| Google Cloud 공식 문서 | 서비스계정 생성 | 서비스계정 생성 |
| Google Cloud 공식 문서 | 보안 베스트프랙티스 | 보안 BP |
| Google Cloud 공식 문서 | 조직정책 - 서비스계정 제한 | SA 제한 Org Policy |
핵심 인용
“Use predefined roles instead of basic roles to follow the principle of least privilege.” — Google Cloud 보안 베스트프랙티스
다음 편 예고
[6편] 네트워킹과 컴퓨트 플레이북: VPC, GCE, GKE, Cloud Run 실전 운영
- “검증 명령”이 “생성 명령”보다 중요한 이유를 VPC/방화벽 사례로 보여줄게요
- 외부 IP 없는 VM을 IAP SSH로 안전하게 접속하는 표준 구성
- Cloud Run의 --no-traffic + 트래픽 분할로 무중단 배포를 구현하는 실전 패턴