gcloud CLI 설치·초기 설정
작성: 2026-09-16 KST · 갱신: 2026-09-16 (설치 완료) 이 머신(JUNOWIN11)에 gcloud CLI가 설치되었습니다 (Google Cloud SDK 585.0.0, winget으로 설치). 아직 로그인·프로젝트 설정은 하지 않은 상태입니다. 이 문서는 설치와 초기 설정(인증·프로젝트)까지의 단계별 가이드입니다.
한눈에 보기
Section titled “한눈에 보기”| 항목 | 값 |
|---|---|
| 도구 | Google Cloud CLI (gcloud, 구 Cloud SDK) |
| 현재 상태 | 설치됨 — SDK 585.0.0 (core 2026.09.11, bq 2.1.38, gsutil 5.37) |
| 설치 방식 | winget install --id Google.CloudSDK -e (이 머신 적용) |
| 설치 경로 | C:\Program Files (x86)\Google\Cloud SDK\google-cloud-sdk\bin |
| 인증 상태 | 미로그인 (활성 계정·프로젝트 없음) — 아래 3~4단계 필요 |
| 인증 방식 | 사용자 계정(gcloud auth login) 또는 서비스 계정 키 |
| 기본 설정 파일 | %APPDATA%\gcloud\ (config, 자격증명 캐시) |
| 설치 확인 | gcloud version, gcloud config list |
로그인·동의가 필요한 다운로드/설치는 사용자가 직접 진행합니다. 아래 셋 중 하나를 선택하세요.
방법 A — 공식 설치 관리자 (권장)
Section titled “방법 A — 공식 설치 관리자 (권장)”- 다운로드: https://cloud.google.com/sdk/docs/install#windows
GoogleCloudSDKInstaller.exe실행 → 안내에 따라 설치- 설치 마지막 단계에서 “Run gcloud init” 체크 유지 (바로 초기화로 이어짐)
- 새 PowerShell 창을 열어 PATH 반영 확인
설치 관리자는 번들 Python을 함께 넣으므로 별도 Python이 없어도 됩니다.
방법 B — Chocolatey
Section titled “방법 B — Chocolatey”choco install gcloudsdk -y방법 C — Scoop
Section titled “방법 C — Scoop”scoop bucket add extrasscoop install gcloudgcloud versiongcloud가 인식되지 않으면 새 터미널을 열거나(환경변수 재로딩), 아래 경로가 PATH에 있는지 확인합니다.
- 공식 설치 관리자 기본 경로:
%LOCALAPPDATA%\Google\Cloud SDK\google-cloud-sdk\bin
2. 초기화 (gcloud init)
Section titled “2. 초기화 (gcloud init)”gcloud init대화형으로 다음을 순서대로 진행합니다.
- 브라우저가 열리며 Google 계정 로그인·권한 동의 (사용자가 직접 승인)
- 사용할 프로젝트 선택 또는 새로 생성
- (선택) 기본 region/zone 지정
로그인 브라우저 창은 사용자가 직접 승인해야 합니다. 헤드리스/원격 환경이면 다음을 사용합니다.
gcloud init --console-only# 또는 로그인만gcloud auth login --no-launch-browser3. 인증 (Authentication)
Section titled “3. 인증 (Authentication)”사용자 계정 로그인
Section titled “사용자 계정 로그인”gcloud auth login애플리케이션 기본 자격증명 (ADC)
Section titled “애플리케이션 기본 자격증명 (ADC)”로컬에서 실행하는 앱/SDK가 GCP API를 호출할 때 사용합니다.
gcloud auth application-default login서비스 계정 키 (자동화·서버용)
Section titled “서비스 계정 키 (자동화·서버용)”gcloud auth activate-service-account --key-file="C:\path\to\key.json"보안: 서비스 계정 키(JSON)는 비밀정보입니다. 저장소에 커밋하지 말고, 권한은 최소화하세요.
4. 프로젝트·기본값 설정
Section titled “4. 프로젝트·기본값 설정”# 현재 계정으로 접근 가능한 프로젝트 목록gcloud projects list
# 기본 프로젝트 지정gcloud config set project <PROJECT_ID>
# 기본 region/zonegcloud config set compute/region asia-northeast3gcloud config set compute/zone asia-northeast3-aasia-northeast3 = 서울 리전.
5. 설정 확인·전환
Section titled “5. 설정 확인·전환”# 현재 활성 설정 확인gcloud config listgcloud auth list
# 여러 환경(계정·프로젝트) 프로필 관리gcloud config configurations listgcloud config configurations create workgcloud config configurations activate work6. 자주 쓰는 명령 요약
Section titled “6. 자주 쓰는 명령 요약”| 목적 | 명령 |
|---|---|
| 버전·구성 요소 | gcloud version / gcloud components list |
| 구성 요소 업데이트 | gcloud components update |
| 로그인 상태 | gcloud auth list |
| 현재 설정 | gcloud config list |
| 프로젝트 변경 | gcloud config set project <ID> |
| Compute 인스턴스 목록 | gcloud compute instances list |
| Storage 버킷 목록 | gcloud storage buckets list |
| Cloud Run 배포 | gcloud run deploy <SERVICE> --source . |
| 로그 보기 | gcloud logging read "resource.type=..." --limit 20 |
7. 설정 파일 위치 (Windows)
Section titled “7. 설정 파일 위치 (Windows)”| 항목 | 경로 |
|---|---|
| 설정·프로필 | %APPDATA%\gcloud\ |
| 활성 설정 | %APPDATA%\gcloud\configurations\config_default |
| ADC 자격증명 | %APPDATA%\gcloud\application_default_credentials.json |
| 로그 | %APPDATA%\gcloud\logs\ |
8. 문제 해결
Section titled “8. 문제 해결”gcloud를 찾을 수 없음: 새 터미널을 열거나, 위bin경로를 PATH에 추가. 설치 관리자로 재설치 시 “Add gcloud to PATH” 옵션 확인.- 로그인 브라우저가 안 열림:
gcloud auth login --no-launch-browser로 출력된 URL을 수동으로 열어 코드 붙여넣기. - 프록시 환경:
gcloud config set proxy/type http,proxy/address,proxy/port설정. - 권한 오류(403): 해당 계정에 필요한 IAM 역할이 있는지, 올바른 프로젝트가 활성인지 확인.
설치·로그인을 마친 뒤 아래 출력을 공유해 주시면, 이 머신의 실제 gcloud 현황(계정·프로젝트·기본 리전)을 별도 “현황” 페이지로 정리해 드립니다.
gcloud versiongcloud config listgcloud auth list