gcloud

gcloud 480+

gcloud(Google Cloud CLI), gsutil, bq 명령어 빠른 참조 — 인증, 프로젝트 / IAM, Compute / GKE / BigQuery / Cloud Storage, 설정, Cloud Build / Deploy — 자주 쓰는 옵션과 실전 예시까지 함께 정리했습니다.

명령어 48개

도움말

gcloud --version

gcloud, gsutil, bq 버전과 핵심 라이브러리를 출력합니다.

gcloud --version
gcloud help

최상위 도움말과 전체 명령 그룹 목록을 표시합니다.

gcloud help
gcloud help <cmd>

모든 gcloud 명령의 플래그 + 예시를 표시합니다(경로 구분자는 공백).

gcloud help compute instances create
gcloud topic <topic>

심층 문서를 읽습니다: `configurations`, `projections`, `filters`, `offline` 등.

configurations; projections; filters; offline; access-control

gcloud topic filters

인증

gcloud init

최초 실행 마법사 — 로그인, 프로젝트 선택, 기본 region / zone 선택.

gcloud init
gcloud auth login

사용자 자격 증명으로 gcloud가 GCP에 접근하도록 인가합니다(브라우저 OAuth 흐름).

--no-launch-browser; --no-activate

gcloud auth login --no-launch-browser
gcloud auth application-default login

Application Default Credentials 설정 — 클라이언트 라이브러리(Python / Node / Go)가 사용합니다.

--scopes <scope1,scope2>; --no-launch-browser

gcloud auth application-default login
gcloud auth activate-service-account --key-file <key.json>

다운로드한 JSON 키 파일을 사용해 서비스 계정을 활성화합니다.

gcloud auth activate-service-account [email protected] --key-file=ci.json
gcloud auth list

자격 증명이 있는 모든 계정을 나열합니다.

--format=yaml; --filter

gcloud auth list
gcloud auth revoke

한 계정 또는 모든 계정의 자격 증명을 취소합니다.

<account>; --all

gcloud auth revoke --all

프로젝트

gcloud config get-value project

현재 활성 프로젝트를 출력합니다.

gcloud config get-value project
gcloud config set project <id>

활성 프로젝트를 설정합니다.

gcloud config set project my-gcp-project
gcloud projects list

접근할 수 있는 모든 프로젝트를 나열합니다.

--format='table(projectId,name,projectNumber)'; --limit

gcloud projects list --format='table(projectId,name)'

설정

gcloud config configurations list

저장된 모든 설정(명명된 프로파일)을 나열합니다.

--format=yaml

gcloud config configurations list
gcloud config configurations create <name>

새 명명 설정을 만듭니다.

--no-activate

gcloud config configurations create dev --no-activate
gcloud config configurations activate <name>

기존 설정으로 전환합니다.

gcloud config configurations activate prod
CLOUDSDK_ACTIVE_CONFIG_NAME=<name> gcloud ...

영구 설정을 수정하지 않고 설정을 사용합니다(CI / 스크립트).

CLOUDSDK_ACTIVE_CONFIG_NAME=prod gcloud compute instances list
gcloud config set compute/region <region>

속성별 기본값(region / zone / project / account)을 설정합니다.

compute/region; compute/zone; container/cluster; compute/region us-central1

gcloud config set compute/region us-central1

출력

gcloud <cmd> --format=<fmt>

출력 형식을 선택합니다: `json`, `yaml`, `table`, `csv`, `value`, `default`.

json; yaml; table; csv; value; default; get(<expr>):label

gcloud compute instances list --format='table(name,zone.basename(),machineType.basename())'
gcloud <cmd> --filter='<expr>'

서버 측 필터 — 표현식 신택스는 `gcloud topic filters` 참조.

name=foo; zone:us-*; status:RUNNING

gcloud compute instances list --filter='zone:us-central1-a AND labels.env=prod'
gcloud <cmd> --limit <N>

결과 개수를 제한합니다(그렇지 않으면 서버 측 페이징은 무제한).

gcloud compute instances list --limit=20

IAM

gcloud iam service-accounts list

활성 프로젝트의 모든 서비스 계정을 나열합니다.

--project; --format=json; --limit

gcloud iam service-accounts list
gcloud iam service-accounts keys create <file.json> --iam-account <sa>

서비스 계정의 JSON 키를 만듭니다 — ADC를 지원하지 않는 툴에 필요합니다.

--iam-account <sa>; --key-file-type json

gcloud iam service-accounts keys create ci.json --iam-account [email protected]
gcloud projects add-iam-policy-binding <project> --member='user:<email>' --role='roles/<role>'

프로젝트 레벨에서 멤버에게 역할을 부여합니다.

--member=user:foo@bar / serviceAccount:foo / group:bar / domain:bar; --role=roles/owner

gcloud projects add-iam-policy-binding my-proj --member='user:[email protected]' --role='roles/viewer'

Compute Engine

gcloud compute instances list

모든 VM을 zone, 머신 타입, 상태와 함께 나열합니다.

--project; --filter; --format=table; --limit

gcloud compute instances list --format='table(name,zone,machineType,status)'
gcloud compute instances create <name> --zone <z> --machine-type <t>

기본 이미지(Debian 12)로 VM을 만듭니다.

--zone; --machine-type; --image-family; --image-project; --preemptible; --tags; --labels; --metadata; --service-account; --scopes

gcloud compute instances create vm-dev --zone=us-central1-a --machine-type=e2-medium --image-family=debian-12
gcloud compute ssh <vm> --zone <z>

VM에 SSH 세션을 엽니다(`~/.ssh/google_compute_engine`에 키 자동 생성 / 보관).

--zone; --ssh-key-file; --command <cmd>; --tunnel-through-iap; --internal-ip

gcloud compute ssh vm-dev --zone=us-central1-a --command 'docker ps'
gcloud compute instances delete <vm> --zone <z>

VM을 삭제합니다(디스크 포함 / 제외).

--zone; --delete-disks=all / data / boot

gcloud compute instances delete vm-dev --zone=us-central1-a --delete-disks=all
gcloud compute disks list

모든 영구 디스크를 나열합니다.

--filter='zone:us-*'; --format=table

gcloud compute disks list --format='table(name,sizeGb,zone,status)'
gcloud compute snapshots create <name> --source-disk <disk>

백업 또는 복제를 위해 영구 디스크의 스냅샷을 만듭니다.

--source-disk <name>; --source-disk-zone; --description

gcloud compute snapshots create snap-2026-08-25 --source-disk=data-disk --source-disk-zone=us-central1-a

GKE

gcloud container clusters list

모든 GKE 클러스터를 나열합니다.

--region; --format=table; --limit

gcloud container clusters list --format='table(name,zone,masterVersion,status)'
gcloud container clusters get-credentials <name> --region <r>

클러스터의 kubeconfig을 `~/.kube/config`에 병합하고 컨텍스트를 전환합니다.

--region; --zone; --project; --internal-ip

gcloud container clusters get-credentials my-cluster --region=us-central1
gcloud container clusters create <name> --num-nodes=1

Autopilot 또는 Standard GKE 클러스터를 만듭니다.

--num-nodes; --machine-type; --region; --enable-autoscaling; --enable-autorepair; --cluster-version; --release-channel rapid|regular|stable

gcloud container clusters create my-cluster --region=us-central1 --num-nodes=3 --enable-autoscaling --min-nodes=1 --max-nodes=5

Cloud Storage

gsutil ls

버키트 / 객체를 나열합니다(별칭: `gcloud storage ls`).

-r; -l; -h; gs://; -d (디렉터리만 나열)

gsutil ls gs://my-bucket/data/
gsutil cp <local> gs://<bucket>/<key>

객체를 업로드 또는 복사합니다. 디렉터리 재귀 복사에는 `-r`.

-r; -m 병렬; -c cache-control 보존; -p ACL 보존; -n no-clobber; -z <fmt> 업로드 시 압축

gsutil cp -r ./dist gs://my-bucket/app/
gsutil rsync -r <src> <dst>

양방향 디렉터리 동기화(병렬, 빠름). 소스 / 대상은 로컬 또는 `gs://`.

-r; -d 추가 파일 삭제; -c 체크섬 비교; -n dry-run; -x exclude

gsutil rsync -r -d ./build gs://my-bucket/build
gcloud storage buckets create gs://<name> --location <loc>

지정한 location / class로 새 Cloud Storage 버킷을 만듭니다.

--location; --default-storage-class; --uniform-bucket-level-access; --public-access-prevention

gcloud storage buckets create gs://my-bucket --location=us-central1 --uniform-bucket-level-access

BigQuery

bq query --use_legacy_sql=false 'SELECT ...'

BigQuery에 대해 임시 SQL 쿼리를 실행합니다.

--use_legacy_sql=false; --max_rows; --destination_table; --parameter; --format=json

bq query --use_legacy_sql=false 'SELECT COUNT(*) FROM `bigquery-public-data.samples.shakespeare`'
bq show --format=pretty <project>:<dataset>

프로젝트 / 데이터셋 / 테이블 / 작업의 메타데이터를 표시합니다.

--format=pretty; --schema; --view

bq show my-proj:my_dataset
bq load --source_format=CSV --autodetect <dataset>.<table> <file>

로컬 CSV/JSON/Parquet 파일을 BigQuery 테이블에 대량 로드합니다.

--source_format=CSV|JSON|PARQUET|AVRO|NEWLINE_DELIMITED_JSON; --autodetect; --replace; --skip_leading_rows=1

bq load --source_format=CSV --autodetect --skip_leading_rows=1 my_dataset.users users.csv

Cloud Build

gcloud builds submit --tag gcr.io/<proj>/<img>

기본 Cloud Build 설정으로 현재 디렉터리에서 컨테이너를 빌드합니다.

--tag; --config <file>; --machine-type; --timeout; --gcs-source-staging-dir; --no-source-image-upload

gcloud builds submit --tag gcr.io/my-proj/app:v1 .

Cloud Deploy

gcloud app deploy <yaml>

App Engine 표준 / 플렉스에 배포합니다.

--image-url; --version; --promote; --stop-previous-version

gcloud app deploy app.yaml --promote

Pub/Sub

gcloud pubsub topics publish <topic> --message '<msg>'

단일 메시지를 게시합니다 — 임시 테스트에 유용합니다.

--message; --attributes; --ordering-key

gcloud pubsub topics publish my-topic --message 'hello' --attributes=k=v
gcloud pubsub subscriptions pull <sub> --limit <N> --auto-ack

구독에서 N개 메시지를 가져오고(자동 확인) — sanity check에 좋습니다.

--limit; --auto-ack; --format=json

gcloud pubsub subscriptions pull my-sub --limit=5 --auto-ack

배포 / 롤백

gcloud components update

gcloud 자체와 설치된 모든 구성 요소를 최신 릴리스로 업데이트합니다.

gcloud components update
gcloud components install <name>

옵션 gcloud 구성 요소(kubectl, bq, gsutil, app-engine-python 등)를 설치합니다.

<name>

gcloud components install kubectl

진단

gcloud info

gcloud 환경을 출력합니다: python 버전, 설치 위치, 활성 설정.

--run-diagnostics; --log-level=debug

gcloud info
gcloud feedback

환경 정보가 미리 채워진 상태로 공개 gcloud 이슈 트래커를 브라우저에서 엽니다.

--log-level=debug

gcloud feedback

관련 명령어 치트시트

Google Cloud CLI 소개

Google Cloud CLI(gcloud)는 Google Cloud Platform(GCP) 서비스를 관리하기 위한 Google의 공식 CLI 도구입니다. 한 설치 프로그램에 세 바이너리가 포함됩니다: `gcloud`(리소스 관리, IAM, App Engine, Cloud SQL, GKE, Compute Engine), `gsutil`(Cloud Storage, 원래 구식 `gsutil` 독립 CLI에서 유래), `bq`(BigQuery). 현재 안정 라인은 gcloud 480+(2025년 8월 시대)입니다. gcloud는 리소스-그룹 패턴을 따릅니다: `gcloud <group> <resource> <verb>` — 예: `gcloud compute instances list`, `gcloud iam service-accounts keys create`. 인증은 인터랙티브 `gcloud auth login`, 서비스 계정 키, 그리고 Application Default Credentials(ADC)를 통한 `gcloud auth application-default login`을 지원합니다 — 후자는 Terraform, Python, Node.js SDK의 표준 자격 증명 소스입니다. gcloud는 Apache 2.0 라이선스이며, 명시적인 `gcloud app deploy`, `gcloud builds submit` 등을 제외하고는 코드를 어디에도 업로드하지 않습니다.

치트시트 버전 1.0.0