반응형

시리즈: gcloud CLI 자동화 운영 플레이북 (총 11편) | 4회

gcloud configurations로 프로젝트와 환경을 실수 없이 전환하는 법

여러분, 프로덕션 프로젝트에서 작업하는 줄 알았는데 개발 프로젝트였던 적 있지 않아요? 아니면 반대로, 테스트인 줄 알았는데 프로덕션이었던 경험은요? configuration 분리가 이 문제를 구조적으로 해결해줘요.

Summary

  • configuration은 gcloud 속성(프로젝트, 계정, 리전, 존)을 “이름 붙인 묶음”으로 관리하는 장치야
  • default는 절대 건드리지 말고, 목적별로 새 configuration을 만드는 게 가장 안전해
  • CI/자동화에서는 CLOUDSDK_ACTIVE_CONFIG_NAME 환경변수로 configuration을 강제 지정해야 해
  • direnv 같은 도구와 조합하면 디렉토리 이동만으로 프로젝트 전환이 자동화돼

이 글의 대상

  • gcloud를 쓰고 있지만 프로젝트 전환 시 실수가 잦은 개발자
  • 개발/스테이징/프로덕션 환경을 CLI로 안전하게 오가야 하는 SRE/플랫폼 엔지니어
  • CI 파이프라인에서 gcloud 구성이 꼬여서 장애를 겪은 적 있는 DevOps 담당자

목차

  1. configuration이란 무엇이고 어디에 저장되는가
  2. 핵심 원칙: default는 보존하고 목적별로 분리하라
  3. 프로젝트별 configuration 실전 예시
  4. 환경별 분리: dev/staging/prod를 안전하게 오가기
  5. 역할별 분리: 같은 프로젝트, 다른 권한
  6. CI 안정성: CLOUDSDK_ACTIVE_CONFIG_NAME으로 비대화형 강제
  7. direnv로 디렉토리 기반 자동 전환 만들기
  8. configuration 관련 필수 명령 총정리
  9. 실패 케이스와 트러블슈팅

1. configuration이란 무엇이고 어디에 저장되는가

결론부터 말하면, configuration은 gcloud 속성의 “이름 붙인 프로필”이야.

gcloud를 처음 설치하고 gcloud init을 실행하면 default라는 configuration이 만들어져. 여기에 프로젝트 ID, 계정, 리전, 존 같은 속성이 저장되는 거지.

저장 위치

OS 경로
Linux/macOS ~/.config/gcloud/
Windows %APPDATA%\gcloud\

이 디렉토리 안에 configurations/ 폴더가 있고, 각 configuration은 config_[이름] 파일로 저장돼. 예를 들어 config_default, config_proj-abc 이런 식이야.

# 현재 configuration 확인
gcloud config configurations list

출력 예시:

NAME       IS_ACTIVE  ACCOUNT              PROJECT          COMPUTE_DEFAULT_ZONE  COMPUTE_DEFAULT_REGION
default    True       user@example.com     my-default-proj  asia-northeast3-a     asia-northeast3

여기서 중요한 건 IS_ACTIVE 컬럼이야. 현재 어떤 configuration이 활성 상태인지 한눈에 보여주거든.

2. 핵심 원칙: default는 보존하고 목적별로 분리하라

이게 이 글에서 가장 중요한 내용이야. 한 줄로 요약하면:

default configuration은 건드리지 말고, 프로젝트/환경/역할별로 새 configuration을 만들어라.

왜 그런지 설명할게. default를 직접 수정하면서 쓰면 이런 일이 벌어져:

상황 위험
gcloud config set project prod-project 후 잊어버림 테스트 명령이 프로덕션에서 실행됨
리전을 바꾼 뒤 원래 값을 모름 엉뚱한 리전에 리소스 생성
CI에서 default를 쓰는 스크립트가 로컬 default에 의존 환경에 따라 동작이 달라짐

반면에 목적별로 configuration을 분리하면:

장점 효과
전환이 명시적 activate 명령으로만 전환되니까 실수가 줄어
설정이 독립적 한 configuration을 바꿔도 다른 건 영향 없어
검증이 쉬워 gcloud config list로 현재 상태를 즉시 확인 가능
CI와 분리 환경변수로 CI 전용 configuration을 강제할 수 있어

3. 프로젝트별 configuration 실전 예시

가장 흔한 패턴이야. 프로젝트마다 configuration을 만드는 거지.

3단계로 끝나는 프로젝트 configuration 생성

# 1단계: configuration 생성
gcloud config configurations create proj-payment

# 2단계: 활성화 (생성 시 자동 활성화되기도 해)
gcloud config configurations activate proj-payment

# 3단계: 속성 설정
gcloud config set project payment-service-prod
gcloud config set account ops-team@example.com
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone asia-northeast3-a

이걸 팀에서 운영하는 프로젝트가 3개라면 이렇게 돼:

# 결제 서비스
gcloud config configurations create proj-payment
gcloud config configurations activate proj-payment
gcloud config set project payment-service-prod
gcloud config set compute/region asia-northeast3

# 사용자 서비스
gcloud config configurations create proj-user
gcloud config configurations activate proj-user
gcloud config set project user-service-prod
gcloud config set compute/region us-central1

# 데이터 파이프라인
gcloud config configurations create proj-data
gcloud config configurations activate proj-data
gcloud config set project data-pipeline-prod
gcloud config set compute/region asia-northeast3

전환은 간단해:

# 결제 서비스로 전환
gcloud config configurations activate proj-payment

# 현재 상태 확인 (습관처럼 하자)
gcloud config list

4. 환경별 분리: dev/staging/prod를 안전하게 오가기

같은 서비스라도 환경(dev/staging/prod)별로 프로젝트가 다른 경우가 많지? 이럴 때 환경별 configuration이 빛을 발해.

# 개발 환경
gcloud config configurations create env-dev
gcloud config configurations activate env-dev
gcloud config set project myapp-dev-12345
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone asia-northeast3-a

# 스테이징 환경
gcloud config configurations create env-staging
gcloud config configurations activate env-staging
gcloud config set project myapp-staging-67890
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone asia-northeast3-a

# 프로덕션 환경
gcloud config configurations create env-prod
gcloud config configurations activate env-prod
gcloud config set project myapp-prod-11111
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone asia-northeast3-a

전환 없이 단건 실행하기

매번 activate하기 귀찮다면 --configuration 플래그를 쓰면 돼:

# 현재 dev가 활성이지만, prod에서 한 건만 조회
gcloud compute instances list --configuration=env-prod

이건 활성 configuration을 바꾸지 않고 해당 configuration의 속성으로 한 번만 실행하는 거야. 실수로 전환을 깜빡하는 걸 막아주니까 아주 유용해.

5. 역할별 분리: 같은 프로젝트, 다른 권한

같은 프로젝트에서도 “읽기 전용” 작업과 “관리자” 작업을 구분해야 할 때가 있어. 예를 들어:

# 읽기 전용 (일상 조회)
gcloud config configurations create role-viewer
gcloud config configurations activate role-viewer
gcloud config set project myapp-prod-11111
gcloud config set account readonly-user@example.com

# 관리자 (변경 작업)
gcloud config configurations create role-admin
gcloud config configurations activate role-admin
gcloud config set project myapp-prod-11111
gcloud config set account admin-user@example.com

이렇게 하면 일상적인 조회는 role-viewer로 하다가, 실제 변경이 필요할 때만 role-admin으로 전환하는 습관이 생겨. “최소 권한 원칙”을 configuration 단위로 실천하는 거지.

6. CI 안정성: CLOUDSDK_ACTIVE_CONFIG_NAME으로 비대화형 강제

CI/CD 파이프라인에서는 대화형(interactive) 명령을 쓸 수 없어. gcloud config configurations activate는 대화형 명령이 아니긴 하지만, 환경변수로 강제하는 게 훨씬 안정적이야.

환경변수로 configuration 고정하기

# CI 스크립트 시작 부분에서
export CLOUDSDK_ACTIVE_CONFIG_NAME=ci-deploy

# 이후 모든 gcloud 명령은 ci-deploy configuration을 사용
gcloud compute instances list  # ci-deploy의 project/region 사용

CI 파이프라인 예시 (GitHub Actions)

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      CLOUDSDK_ACTIVE_CONFIG_NAME: ci-prod-deploy
    steps:
      - name: gcloud 인증
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ secrets.WIF_PROVIDER }}
          service_account: ${{ secrets.SA_EMAIL }}

      - name: configuration 생성 및 설정
        run: |
          gcloud config configurations create ci-prod-deploy || true
          gcloud config set project ${{ secrets.PROD_PROJECT }}
          gcloud config set compute/region asia-northeast3

      - name: 배포
        run: |
          gcloud run deploy myservice --image=gcr.io/${{ secrets.PROD_PROJECT }}/myapp:${{ github.sha }}

왜 환경변수가 더 안전한가

방식 장점 단점
activate 명령 직관적 이전 상태에 의존, 병렬 실행 시 충돌 가능
CLOUDSDK_ACTIVE_CONFIG_NAME 프로세스 격리, 병렬 안전 환경변수 관리가 필요
--configuration 플래그 명령 단위 격리 매번 붙여야 해서 번거로움

CI에서는 환경변수 방식이 가장 안정적이야. 특히 여러 파이프라인이 동시에 돌아갈 때, 환경변수는 프로세스별로 격리되니까 서로 간섭하지 않거든.

7. direnv로 디렉토리 기반 자동 전환 만들기

이건 좀 고급 팁인데, 정말 편해. direnv를 쓰면 디렉토리를 이동할 때 자동으로 configuration이 전환돼.

설정 방법

# 1. direnv 설치
# macOS
brew install direnv

# Linux (apt)
sudo apt install direnv

# 2. 쉘에 direnv hook 추가 (~/.bashrc 또는 ~/.zshrc)
eval "$(direnv hook bash)"  # bash
eval "$(direnv hook zsh)"   # zsh

# 3. 프로젝트 디렉토리에 .envrc 생성
cd ~/projects/payment-service
echo 'export CLOUDSDK_ACTIVE_CONFIG_NAME=proj-payment' > .envrc
direnv allow

cd ~/projects/data-pipeline
echo 'export CLOUDSDK_ACTIVE_CONFIG_NAME=proj-data' > .envrc
direnv allow

이제 cd ~/projects/payment-service만 하면 자동으로 proj-payment configuration이 활성화돼. 디렉토리를 벗어나면 원래 상태로 돌아가고.

프로덕션 프로젝트에서 실수로 테스트 명령을 날리는 사고를 이것만으로도 크게 줄일 수 있어.

8. configuration 관련 필수 명령 총정리

작업 명령
목록 보기 gcloud config configurations list
생성 gcloud config configurations create NAME
활성화 gcloud config configurations activate NAME
삭제 gcloud config configurations delete NAME
속성 설정 gcloud config set SECTION/PROPERTY VALUE
속성 해제 gcloud config unset SECTION/PROPERTY
현재 구성 보기 gcloud config list
단건 실행 gcloud COMMAND --configuration=NAME
환경변수 강제 export CLOUDSDK_ACTIVE_CONFIG_NAME=NAME

자주 설정하는 속성들

# 프로젝트
gcloud config set project PROJECT_ID

# 계정
gcloud config set account USER@EXAMPLE.COM

# 리전/존
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone asia-northeast3-a

# 서비스계정 임시 위임 (키리스 운영)
gcloud config set auth/impersonate_service_account SA_EMAIL

9. 실패 케이스와 트러블슈팅

실패 1: “configuration already exists” 에러

ERROR: (gcloud.config.configurations.create) The configuration [proj-abc] already exists.

원인: 같은 이름의 configuration이 이미 있어.

해결:

# 기존 configuration 확인
gcloud config configurations list

# 기존 걸 쓰거나 삭제 후 재생성
gcloud config configurations delete proj-abc
gcloud config configurations create proj-abc

실패 2: 전환했는데 프로젝트가 안 바뀐 것 같은 경우

원인: --project 플래그가 configuration보다 우선해. 또는 CLOUDSDK_CORE_PROJECT 환경변수가 남아있을 수 있어.

진단 순서:

# 1. 현재 활성 configuration 확인
gcloud config configurations list

# 2. 현재 속성 확인
gcloud config list

# 3. 환경변수 확인
echo $CLOUDSDK_CORE_PROJECT
echo $CLOUDSDK_ACTIVE_CONFIG_NAME

gcloud 속성 우선순위 (높은 순서대로):

우선순위 방법
1 (최고) 명령 플래그 (–project, –region 등)
2 환경변수 (CLOUDSDK_CORE_PROJECT 등)
3 활성 configuration의 속성 값

실패 3: CI에서 configuration이 없다는 에러

ERROR: (gcloud.config.configurations.activate) The configuration [ci-deploy] does not exist.

원인: CI 환경은 매번 새로 시작하니까 이전에 만든 configuration이 없어.

해결: CI 스크립트 시작 부분에서 configuration을 항상 새로 만들어:

gcloud config configurations create ci-deploy 2>/dev/null || true
gcloud config configurations activate ci-deploy
gcloud config set project $PROJECT_ID

2>/dev/null || true는 이미 존재할 때 에러를 무시하는 패턴이야.

핵심 정리

1. configuration은 gcloud 속성(프로젝트/계정/리전)의 이름 붙인 묶음이고, ~/.config/gcloud에 저장돼
2. default는 보존하고, 프로젝트/환경/역할별로 configuration을 분리하는 게 사고 방지의 핵심이야
3. CI에서는 CLOUDSDK_ACTIVE_CONFIG_NAME 환경변수로 configuration을 강제 지정해야 안전해
4. direnv와 조합하면 디렉토리 이동만으로 프로젝트/환경 전환이 자동화돼

FAQ

Q. configuration과 프로젝트는 1:1 관계야?

A. 아니, 꼭 그럴 필요는 없어. 같은 프로젝트에 대해 역할별로 여러 configuration을 만들 수도 있고, 반대로 여러 프로젝트를 하나의 configuration에 담을 수도 있어(비추천이지만). 핵심은 “작업 맥락”에 맞게 분리하는 거야.

Q. configuration을 만들면 자동으로 activate되나?

A. gcloud 버전에 따라 다를 수 있는데, 보통 생성 시 자동 활성화돼. 확실하게 하려면 create 후에 activate를 명시적으로 실행하는 게 좋아.

Q. 이미 default에 속성을 다 설정해버렸는데 어떡해?

A. 걱정하지 마. default의 현재 속성을 확인한 뒤(gcloud config list), 새 configuration을 만들어서 같은 속성을 옮기면 돼. 그리고 default는 최소한의 속성(또는 빈 상태)으로 두는 게 좋아.

Q. configuration 간에 인증(계정)도 따로 관리돼?

A. configuration에 account 속성을 다르게 설정할 수 있어. 하지만 실제 인증 토큰은 gcloud auth login으로 별도 관리돼. configuration의 account는 “이 configuration을 쓸 때 어떤 인증된 계정을 기본으로 할지” 지정하는 거지, 인증 자체를 하는 건 아니야.

Q. CLOUDSDK_ACTIVE_CONFIG_NAME과 –configuration 플래그 중 뭐가 우선이야?

A. --configuration 플래그가 환경변수보다 우선해. 즉, 환경변수로 ci-deploy를 지정했어도 --configuration=other를 붙이면 other로 실행돼. 우선순위: 플래그 > 환경변수 > 마지막 activate 상태.

Q. Windows에서도 direnv를 쓸 수 있어?

A. direnv는 주로 Linux/macOS에서 쓰이지만, Windows에서도 WSL(Windows Subsystem for Linux)을 사용하면 동일하게 쓸 수 있어. PowerShell 네이티브로는 비슷한 효과를 $PROFILE에 디렉토리 체크 로직을 넣어서 구현할 수 있지.

Q. configuration이 너무 많아지면 관리가 힘들지 않아?

A. 맞아, 그래서 네이밍 규칙이 중요해. [유형]-[이름] 패턴을 추천해. 예: proj-payment, env-prod, role-admin. 그리고 안 쓰는 configuration은 주기적으로 정리(delete)하는 습관을 들이는 게 좋아.

Q. configuration 설정을 팀원들과 공유할 수 있어?

A. configuration 파일 자체를 공유하기보다는 configuration을 만드는 스크립트를 공유하는 게 훨씬 나아. 예를 들어 setup-configs.sh를 팀 저장소에 두고, 온보딩 시 실행하게 하는 거지. 이렇게 하면 팀 표준을 코드로 관리할 수 있어.

Q. gcloud init을 다시 실행하면 기존 configuration이 날아가?

A. gcloud init은 기본적으로 현재 활성 configuration을 재설정하거나 새 configuration을 만드는 옵션을 줘. 기존 configuration이 삭제되진 않으니 걱정하지 마. 다만 --console-only 같은 플래그 없이 실행하면 브라우저가 열리는 대화형 플로우가 진행돼.

참고 자료 (References)

데이터 출처

출처 설명 링크
Google Cloud 공식 문서 configurations 관리 가이드 configurations 관리
Google Cloud 공식 문서 gcloud CLI 인증 가이드 Authorize the gcloud CLI
Google Cloud 공식 문서 gcloud config 레퍼런스 gcloud config
Google Cloud 공식 문서 스크립팅 gcloud 가이드 Scripting gcloud
direnv 공식 디렉토리별 환경변수 관리 도구 direnv.net

핵심 인용

“Named configurations allow you to maintain multiple sets of gcloud properties, such as account, project, and compute region/zone, and switch between them.” — Google Cloud CLI configurations 관리 문서

다음 편 예고

[5편] 조직 운영 자동화: 프로젝트, API, IAM을 코드로 프로비저닝하기
- 프로젝트가 왜 “비용+권한의 경계”인지, 생성 절차를 어떻게 코드화하는지 알아봐요
- API enablement를 파일로 관리해서 “API not enabled” 에러를 근절하는 방법
- 태그 vs 라벨의 차이를 제대로 이해하고, IAM 최소권한 원칙을 gcloud로 구현하는 실전 예시

반응형

'AI' 카테고리의 다른 글

VPC부터 Cloud Run까지, gcloud로 네트워크와 컴퓨트를 검증 가능하게 운영하는 법 — gcloud CLI 자동화 운영 플레이북 6/11  (0) 2026.03.12
프로젝트부터 IAM까지, gcloud로 조직 운영을 자동화하는 6단계 프로비저닝 — gcloud CLI 자동화 운영 플레이북 5/11  (0) 2026.03.12
gcloud 인증 체계 완전 정복: 사용자, 서비스계정, ADC 분리로 온보딩 장애를 없애는 법 — gcloud CLI 자동화 운영 플레이북 3/11  (0) 2026.03.12
gcloud CLI 로컬 설치 표준과 버전 정책으로 팀 온보딩 실패를 줄이는 법 — gcloud CLI 자동화 운영 플레이북 2/11  (0) 2026.03.12
gcloud CLI 도입이 팀 생산성의 전환점이 되는 이유와 실전 전략 — gcloud CLI 자동화 운영 플레이북 1/11  (0) 2026.03.12

티스토리툴바