# gcloud CLI 설치·초기 설정 가이드 (Windows)

> 작성: 2026-09-16 KST · 갱신: 2026-09-16 (설치 완료)
> 이 머신(JUNOWIN11)에 gcloud CLI가 **설치되었습니다** (Google Cloud SDK 585.0.0, winget으로 설치). 아직 로그인·프로젝트 설정은 하지 않은 상태입니다. 이 문서는 설치와 초기 설정(인증·프로젝트)까지의 단계별 가이드입니다.

## 한눈에 보기

| 항목 | 값 |
|------|-----|
| 도구 | 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` |

## 1. 설치

로그인·동의가 필요한 다운로드/설치는 사용자가 직접 진행합니다. 아래 셋 중 하나를 선택하세요.

### 방법 A — 공식 설치 관리자 (권장)

1. 다운로드: <https://cloud.google.com/sdk/docs/install#windows>
2. `GoogleCloudSDKInstaller.exe` 실행 → 안내에 따라 설치
3. 설치 마지막 단계에서 **"Run gcloud init"** 체크 유지 (바로 초기화로 이어짐)
4. 새 PowerShell 창을 열어 PATH 반영 확인

설치 관리자는 번들 Python을 함께 넣으므로 별도 Python이 없어도 됩니다.

### 방법 B — Chocolatey

```powershell
choco install gcloudsdk -y
```

### 방법 C — Scoop

```powershell
scoop bucket add extras
scoop install gcloud
```

### 설치 확인

```powershell
gcloud version
```

`gcloud`가 인식되지 않으면 새 터미널을 열거나(환경변수 재로딩), 아래 경로가 PATH에 있는지 확인합니다.

- 공식 설치 관리자 기본 경로: `%LOCALAPPDATA%\Google\Cloud SDK\google-cloud-sdk\bin`

## 2. 초기화 (`gcloud init`)

```powershell
gcloud init
```

대화형으로 다음을 순서대로 진행합니다.

1. 브라우저가 열리며 Google 계정 로그인·권한 동의 (사용자가 직접 승인)
2. 사용할 **프로젝트** 선택 또는 새로 생성
3. (선택) 기본 **region/zone** 지정

로그인 브라우저 창은 사용자가 직접 승인해야 합니다. 헤드리스/원격 환경이면 다음을 사용합니다.

```powershell
gcloud init --console-only
# 또는 로그인만
gcloud auth login --no-launch-browser
```

## 3. 인증 (Authentication)

### 사용자 계정 로그인

```powershell
gcloud auth login
```

### 애플리케이션 기본 자격증명 (ADC)

로컬에서 실행하는 앱/SDK가 GCP API를 호출할 때 사용합니다.

```powershell
gcloud auth application-default login
```

### 서비스 계정 키 (자동화·서버용)

```powershell
gcloud auth activate-service-account --key-file="C:\path\to\key.json"
```

> 보안: 서비스 계정 키(JSON)는 비밀정보입니다. 저장소에 커밋하지 말고, 권한은 최소화하세요.

## 4. 프로젝트·기본값 설정

```powershell
# 현재 계정으로 접근 가능한 프로젝트 목록
gcloud projects list

# 기본 프로젝트 지정
gcloud config set project <PROJECT_ID>

# 기본 region/zone
gcloud config set compute/region asia-northeast3
gcloud config set compute/zone  asia-northeast3-a
```

`asia-northeast3` = 서울 리전.

## 5. 설정 확인·전환

```powershell
# 현재 활성 설정 확인
gcloud config list
gcloud auth list

# 여러 환경(계정·프로젝트) 프로필 관리
gcloud config configurations list
gcloud config configurations create work
gcloud config configurations activate work
```

## 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)

| 항목 | 경로 |
|------|------|
| 설정·프로필 | `%APPDATA%\gcloud\` |
| 활성 설정 | `%APPDATA%\gcloud\configurations\config_default` |
| ADC 자격증명 | `%APPDATA%\gcloud\application_default_credentials.json` |
| 로그 | `%APPDATA%\gcloud\logs\` |

## 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 현황(계정·프로젝트·기본 리전)을 별도 "현황" 페이지로 정리해 드립니다.

```powershell
gcloud version
gcloud config list
gcloud auth list
```