gcloud CLI 사용법: 터미널에서 Google Cloud 다루기

Google Cloud Console에서 VM 하나 만들려고 브라우저를 열고, 프로젝트를 전환하려고 또 클릭하고, 배포 상태를 확인하려고 다시 페이지를 새로고침하고… 이런 경험 없으신가요?

gcloud는 Google Cloud의 공식 CLI 도구입니다. Compute Engine, Cloud Storage, Cloud Run, BigQuery 같은 주요 서비스를 터미널 명령어 하나로 다룰 수 있어서 브라우저 없이도 클라우드 리소스를 관리할 수 있는데요. 셸 스크립트나 CI/CD 파이프라인에서도 그대로 쓸 수 있어서 자동화에도 딱입니다.

gcloud CLI란?

gcloud는 Google Cloud SDK에 포함된 명령줄 도구입니다. Google Cloud의 거의 모든 서비스를 터미널에서 제어할 수 있고, Google Cloud를 다루는 개발자라면 사실상 필수 도구라고 할 수 있습니다.

Google Cloud SDK에는 gcloud 외에도 몇 가지 도구가 함께 들어 있습니다. gsutil은 Cloud Storage 전용 명령어인데 gcloud storage 명령어로 점차 대체되고 있고, bq는 BigQuery 전용 CLI입니다. gcloud가 대부분의 서비스를 커버하기 때문에 보통은 gcloud만 알아도 충분합니다.

명령어 구조가 꽤 직관적입니다. gcloud [서비스] [리소스] [동작] 패턴을 따르기 때문에 서비스 이름과 하고 싶은 동작만 알면 대충 감으로 명령어를 유추해볼 수 있습니다.

gcloud compute instances list      # Compute Engine VM 목록
gcloud run services list           # Cloud Run 서비스 목록
gcloud storage buckets list        # Cloud Storage 버킷 목록

설치

macOS에서는 Homebrew로 설치하는 게 가장 간단합니다.

brew install google-cloud-sdk

Homebrew로 설치하면 업데이트도 brew upgrade google-cloud-sdk로 관리할 수 있어서 편합니다.

공식 설치 스크립트를 사용하는 방법도 있습니다.

curl https://sdk.cloud.google.com | bash

이 방법은 홈 디렉토리에 SDK를 설치하고 셸 설정 파일에 PATH를 자동으로 추가해줍니다. 설치 후 새 터미널을 열거나 source ~/.zshrc를 실행하면 gcloud 명령어를 쓸 수 있습니다.

Linux에서는 패키지 매니저로도 설치할 수 있습니다.

# Debian/Ubuntu
sudo apt-get install google-cloud-cli

# RHEL/CentOS/Fedora
sudo yum install google-cloud-cli

설치가 끝나면 버전을 확인해봅시다.

gcloud version

SDK를 최신 버전으로 업데이트하고 싶을 때는 이 명령어를 사용합니다.

gcloud components update

초기 설정

설치 후 가장 먼저 할 일은 gcloud init입니다. 인증부터 기본 프로젝트, 리전 설정까지 대화형으로 안내해줍니다.

gcloud init

실행하면 브라우저가 열리면서 구글 계정으로 로그인하라고 안내하는데요. 로그인을 마치면 터미널로 돌아와서 기본 프로젝트와 기본 리전/존을 선택하게 됩니다.

이미 초기 설정을 했는데 계정만 바꾸고 싶다면 auth login을 따로 실행할 수도 있습니다.

gcloud auth login

여기서 한 가지 헷갈리는 게 있는데요. gcloud auth login과 gcloud auth application-default login은 다릅니다.

gcloud auth login은 gcloud CLI 자체가 사용할 인증 정보를 설정하는 거고, gcloud auth application-default login은 로컬에서 실행하는 애플리케이션 코드가 Google Cloud API를 호출할 때 사용할 인증 정보를 설정하는 겁니다.

# gcloud CLI용 인증
gcloud auth login

# 로컬 애플리케이션 코드용 인증 (ADC)
gcloud auth application-default login

예를 들어 Python에서 google-cloud-storage 라이브러리로 Cloud Storage에 접근하는 코드를 로컬에서 테스트하려면 application-default login으로 인증해야 합니다. 이 인증 정보를 Application Default Credentials(ADC)라고 부르는데, Google Cloud 클라이언트 라이브러리가 자동으로 찾아서 사용합니다.

현재 어떤 계정으로 인증되어 있는지는 이렇게 확인합니다.

gcloud auth list

프로젝트 관리

Google Cloud에서는 모든 리소스가 프로젝트 단위로 묶입니다. 여러 프로젝트를 오가며 작업하는 일이 많기 때문에 프로젝트 관련 명령어는 자주 쓰게 됩니다.

지금 어떤 프로젝트가 기본으로 잡혀 있는지 보려면 이렇게 하면 됩니다.

gcloud config get-value project

프로젝트를 전환할 때는 config set을 씁니다.

gcloud config set project my-project-id

내가 접근할 수 있는 프로젝트 목록을 보려면 projects list를 쓰면 됩니다.

gcloud projects list

프로젝트가 많으면 --filter와 --format 플래그를 알아두면 좋습니다.

# 이름에 "prod"가 포함된 프로젝트만 필터링
gcloud projects list --filter="name:prod"

# 프로젝트 ID만 깔끔하게 출력
gcloud projects list --format="value(projectId)"

--format 플래그는 거의 모든 gcloud 명령어에서 쓸 수 있는데요. json, yaml, table, csv, value 같은 형식을 지정할 수 있어서 스크립트에서 출력을 파싱할 때 편합니다.

Compute Engine 다루기

Compute Engine은 Google Cloud의 가상 머신(VM) 서비스입니다. VM 인스턴스의 생성, 조회, 시작/중지, 삭제를 전부 터미널에서 할 수 있습니다.

현재 프로젝트의 VM 인스턴스 목록부터 뽑아봅시다.

gcloud compute instances list

새 VM을 만들어볼까요?

gcloud compute instances create my-vm \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=debian-12 \
  --image-project=debian-cloud

VM에 SSH로 접속하는 것도 한 줄이면 됩니다. SSH 키 설정이나 IP 주소를 따로 알 필요 없이 인스턴스 이름만 넣으면 알아서 연결해줍니다.

gcloud compute ssh my-vm --zone=us-central1-a

인스턴스를 중지하거나 다시 시작하는 것도 간단하고요.

# VM 중지
gcloud compute instances stop my-vm --zone=us-central1-a

# VM 시작
gcloud compute instances start my-vm --zone=us-central1-a

Cloud Storage 다루기

Cloud Storage는 Google Cloud의 객체 스토리지 서비스입니다. gcloud storage 명령어로 버킷 생성부터 파일 업로드/다운로드까지 전부 다룰 수 있습니다.

내 버킷이 뭐가 있는지 보려면요.

gcloud storage buckets list

새 버킷은 이렇게 만듭니다.

gcloud storage buckets create gs://my-bucket-name --location=us-central1

파일을 업로드하거나 다운로드하는 건 cp 명령어입니다. 로컬 파일 시스템처럼 cp로 복사하면 됩니다.

# 로컬 파일을 버킷에 업로드
gcloud storage cp ./report.pdf gs://my-bucket-name/

# 버킷에서 로컬로 다운로드
gcloud storage cp gs://my-bucket-name/report.pdf ./

# 디렉토리 전체를 재귀적으로 업로드
gcloud storage cp -r ./data/ gs://my-bucket-name/data/

버킷 안의 파일 목록을 보려면 ls 명령어를 사용합니다.

gcloud storage ls gs://my-bucket-name/

예전에는 gsutil 명령어를 따로 써야 했는데, 이제는 gcloud storage로 통합되고 있어서 gcloud 하나만 기억하면 됩니다.

Cloud Run 배포하기

Cloud Run은 컨테이너를 서버리스로 실행하는 서비스인데요. gcloud run deploy 한 줄이면 소스 코드에서 바로 배포할 수 있습니다.

gcloud run deploy my-service \
  --source=. \
  --region=us-central1 \
  --allow-unauthenticated

--source=.를 지정하면 현재 디렉토리의 소스 코드를 Cloud Build로 빌드한 뒤 자동으로 배포해줍니다. Dockerfile이 있으면 그걸 사용하고, 없으면 Google Cloud의 빌드팩이 언어를 감지해서 알아서 빌드합니다.

이미 빌드된 컨테이너 이미지를 배포하려면 --image 플래그를 사용합니다.

gcloud run deploy my-service \
  --image=gcr.io/my-project/my-image:latest \
  --region=us-central1

배포된 서비스 목록은 services list로 볼 수 있고요.

gcloud run services list

환경 변수를 설정하거나 메모리 제한을 조정하는 것도 deploy에서 바로 됩니다.

gcloud run deploy my-service \
  --source=. \
  --region=us-central1 \
  --set-env-vars="DB_HOST=10.0.0.1,APP_ENV=production" \
  --memory=512Mi

구성 프로필 관리하기

회사 프로젝트와 개인 프로젝트를 번갈아 작업한다면 구성 프로필(configurations)이 유용합니다. 프로젝트, 계정, 리전 같은 설정을 프로필별로 저장해두고 한 번에 전환할 수 있거든요.

새 프로필을 만들어 봅시다.

gcloud config configurations create work
gcloud config set project work-project-id
gcloud config set account work@company.com
gcloud config set compute/region us-central1

개인 프로젝트용 프로필도 하나 만들어두면 편합니다.

gcloud config configurations create personal
gcloud config set project personal-project-id
gcloud config set account me@gmail.com
gcloud config set compute/region asia-northeast3

프로필 간 전환은 activate 한 줄이면 됩니다.

gcloud config configurations activate work

현재 어떤 프로필이 활성화되어 있고, 어떤 설정이 들어 있는지 확인하려면 list 명령어를 씁니다.

gcloud config configurations list

특정 명령어를 실행할 때만 다른 프로필을 사용하고 싶다면 --configuration 플래그를 붙이면 됩니다.

gcloud compute instances list --configuration=personal

자주 쓰는 플래그

gcloud에는 대부분의 명령어에서 공통으로 쓸 수 있는 플래그가 몇 가지 있는데요. 알아두면 작업 효율이 확 올라갑니다.

--format 플래그로 출력 형식을 바꿀 수 있습니다. JSON으로 출력하면 jq와 조합해서 원하는 데이터만 뽑아낼 수 있고, value로 출력하면 셸 스크립트에서 변수에 바로 담기 좋습니다.

# JSON 형식으로 출력
gcloud compute instances list --format=json

# 특정 필드만 추출
gcloud compute instances list --format="value(name, zone)"

# 테이블에 원하는 컬럼만 표시
gcloud compute instances list --format="table(name, zone, status)"

--filter 플래그로 결과를 필터링할 수 있습니다.

# 실행 중인 VM만 필터링
gcloud compute instances list --filter="status=RUNNING"

# 이름이 "web"으로 시작하는 인스턴스
gcloud compute instances list --filter="name~^web"

--quiet (또는 -q) 플래그는 확인 프롬프트를 건너뛰는데, 스크립트에서 자동화할 때 자주 씁니다.

gcloud compute instances delete my-vm --zone=us-central1-a --quiet

명령어를 실행하기 전에 무슨 일이 일어나는지 미리 보고 싶다면 --dry-run을 지원하는 명령어도 있고, --log-http 플래그를 붙이면 실제 HTTP 요청과 응답을 볼 수 있어서 디버깅할 때 쓸만합니다.

실용적인 활용 팁

gcloud 명령어가 기억나지 않을 때는 --help 플래그를 적극 활용하면 좋습니다. 어떤 수준에서든 --help를 붙이면 해당 명령어 그룹의 하위 명령어와 옵션을 보여줍니다.

gcloud --help                    # 최상위 도움말
gcloud compute --help            # Compute Engine 관련 명령어
gcloud compute instances --help  # VM 인스턴스 관련 명령어

대화형으로 명령어를 찾고 싶다면 gcloud interactive를 사용해보세요. 자동 완성과 인라인 도움말을 제공하는 대화형 셸이 열립니다.

gcloud interactive

특정 서비스의 API를 활성화해야 할 때도 터미널에서 바로 할 수 있습니다. 웹 콘솔에서 “API 사용 설정” 버튼을 찾아다닐 필요 없이 명령어 한 줄이면 됩니다.

# Cloud Run API 활성화
gcloud services enable run.googleapis.com

# 여러 API를 한 번에 활성화
gcloud services enable run.googleapis.com cloudbuild.googleapis.com

프로젝트의 현재 설정 상태를 한눈에 보고 싶을 때는 info 명령어가 있습니다.

gcloud info

현재 계정, 프로젝트, 설치 경로, SDK 버전 등을 한꺼번에 보여줘서 뭔가 안 될 때 환경을 점검하기 딱 좋습니다.

마치며

gcloud는 Google Cloud를 다루는 개발자라면 반드시 익혀야 할 도구입니다. 명령어 구조가 gcloud [서비스] [리소스] [동작] 패턴으로 일관되어 있어서 하나의 서비스에 익숙해지면 다른 서비스도 비슷하게 다룰 수 있거든요.

구성 프로필로 여러 프로젝트를 깔끔하게 전환할 수 있고, --format과 --filter 플래그로 출력을 원하는 대로 가공할 수 있어서 자동화 스크립트 짤 때도 편합니다.

구글 API 인증이 처음이라면 OAuth 2.0으로 구글 API 호출하기도 참고하세요. Google Workspace 서비스를 터미널에서 다루고 싶다면 Google Workspace CLI도 함께 살펴보시면 좋습니다. 더 자세한 내용은 Google Cloud SDK 공식 문서에서 확인하실 수 있습니다.