Back to Details

gcloud

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

gcloud — Google Cloud Platform CLI

gcloud — Google Cloud Platform CLI

Command-line interface for managing Google Cloud resources. Covers 
gcloud
, 
gcloud storage
(replaces 
gsutil
), and 
bq
(BigQuery).
用于管理Google Cloud资源的命令行界面。涵盖
gcloud
、
gcloud storage
（替代
gsutil
）和
bq
（BigQuery）。

Platform Notes (Windows + Git Bash)

平台注意事项（Windows + Git Bash）

  • Install: 
    scoop install gcloud
    (preferred) or 
    GoogleCloudSDKInstaller.exe
  • If installed via scoop, 
    gcloud components install
    may not work — use scoop to manage
  • Config: 
    %APPDATA%/gcloud/
    (PowerShell) or 
    ~/.config/gcloud/
    (Git Bash)
  • Service account keys: store in 
    $TEMP
    or project 
    .secrets/
    , never commit
  • Python: gcloud requires Python; scoop install handles this automatically
  • 安装：
    scoop install gcloud
    （推荐）或
    GoogleCloudSDKInstaller.exe
  • 若通过scoop安装，
    gcloud components install
    可能无法正常工作——请使用scoop进行管理
  • 配置路径：
    %APPDATA%/gcloud/
    （PowerShell）或
    ~/.config/gcloud/
    （Git Bash）
  • 服务账号密钥：存储在
    $TEMP
    或项目
    .secrets/
    目录下，绝对不要提交到版本库
  • Python：gcloud依赖Python；scoop安装会自动处理此需求

⚠️ Path Translation Gotcha

⚠️ 路径转换陷阱

Git Bash auto-translates 
/
-prefixed args, breaking some gcloud commands:
bash
undefined
Git Bash会自动转换以
/
开头的参数，导致部分gcloud命令失效：
bash
undefined

FIX — disable MSYS path conversion:

修复方法 — 禁用MSYS路径转换：

export MSYS_NO_PATHCONV=1
export MSYS_NO_PATHCONV=1

Or per-command:

或针对单个命令：

MSYS_NO_PATHCONV=1 gcloud projects add-iam-policy-binding my-project ...

> **⚠️ Cost**: Commands that create resources (instances, clusters, databases) incur
> GCP charges. Always confirm project and region before creating.
MSYS_NO_PATHCONV=1 gcloud projects add-iam-policy-binding my-project ...

> **⚠️ 成本提示**：创建资源（实例、集群、数据库）的命令会产生GCP费用。创建前请务必确认项目和区域。

Agent Safety Model

Agent安全模型

Operations classified by risk. Follow this model for all gcloud commands.
LevelGateExamples
READProceed autonomously
list
, 
describe
, 
get
, 
logs read
, 
config list
, 
gcloud storage ls
WRITEConfirm with user; note cost if billable
create
, 
deploy
, 
update
, 
enable
, 
gcloud storage cp
(upload)
DESTRUCTIVEAlways confirm; show what's affected
delete
, 
rm
, 
gsutil rm -r
, 
bq rm -r
, 
rsync -d
, IAM removal
EXPENSIVEConfirm + state approximate costGKE clusters ($70+/mo), SQL instances ($8-400/mo), VMs (~$5-2k/mo)
SECURITYConfirm + explain impact
--allow-unauthenticated
, firewall rules, IAM owner/editor grants
FORBIDDENRefuse; escalate to human
gcloud iam service-accounts keys create
, 
gcloud projects delete
, passwords in CLI args
Rules:
  • Never combine 
    --quiet
    with destructive operations     — it suppresses the only safety gate
  • Never put passwords/secrets as command-line arguments — visible in process list & shell history
  • Always use 
    --format=json
     for machine-parseable output (agents can't reliably parse tables)
  • When in doubt, treat as DESTRUCTIVE
操作按风险等级分类。所有gcloud命令均需遵循此模型。
等级管控要求示例
只读可自主执行
list
、
describe
、
get
、
logs read
、
config list
、
gcloud storage ls
写入需与用户确认；若产生费用需注明
create
、
deploy
、
update
、
enable
、
gcloud storage cp
（上传）
破坏性必须确认；展示受影响的内容
delete
、
rm
、
gsutil rm -r
、
bq rm -r
、
rsync -d
、IAM权限移除
高成本确认并说明大致费用GKE集群（约70美元/月起）、SQL实例（约8-400美元/月）、虚拟机（约5-2000美元/月）
安全相关确认并解释影响
--allow-unauthenticated
、防火墙规则、IAM所有者/编辑者权限授予
禁止操作拒绝执行；升级至人工处理
gcloud iam service-accounts keys create
、
gcloud projects delete
、在CLI参数中传入密码
规则:
  • 绝不要将
    --quiet
    与破坏性操作结合使用    ——它会屏蔽所有安全提示，包括删除确认
  • 绝不要将密码/密钥作为命令行参数传入——会在进程列表和Shell历史中暴露
  • **始终使用
    --format=json
    **以获得机器可解析的输出（Agent无法可靠解析表格格式）
  • 存疑时，按破坏性操作处理

Command Structure

命令结构

text
gcloud [RELEASE_LEVEL] COMPONENT ENTITY OPERATION [ARGS] [FLAGS]
Key global flags: 
--project
, 
--format
, 
--filter
, 
--limit
, 
--quiet
, 
--verbosity
, 
--async
text
gcloud [RELEASE_LEVEL] COMPONENT ENTITY OPERATION [ARGS] [FLAGS]
关键全局标志：
--project
、
--format
、
--filter
、
--limit
、
--quiet
、
--verbosity
、
--async

Service Reference

服务参考

ServiceFileKey Commands
Auth & Configauth.mdLogin, ADC, impersonation, config profiles
IAM & Projectsiam.mdProjects, APIs, service accounts, Secret Manager
Compute & Networkingcompute.mdVMs, SSH, firewall, VPC, DNS, static IPs
Serverlessserverless.mdCloud Run, Functions, App Engine, Scheduler, Tasks
Storage & Artifactsstorage.mdgcloud storage, Artifact Registry
Datadata.mdCloud SQL, BigQuery (bq), Pub/Sub
Automation & CI/CDautomation.mdScripting, output formats, filtering, GitHub Actions, operations
Read the per-service file for full command reference.
服务文件核心命令
身份验证与配置auth.md登录、ADC、身份模拟、配置文件
IAM与项目iam.md项目、API、服务账号、Secret Manager
计算与网络compute.md虚拟机、SSH、防火墙、VPC、DNS、静态IP
无服务器serverless.mdCloud Run、Functions、App Engine、Scheduler、Tasks
存储与制品storage.mdgcloud storage、Artifact Registry
数据服务data.mdCloud SQL、BigQuery（bq）、Pub/Sub
自动化与CI/CDautomation.md脚本编写、输出格式、过滤、GitHub Actions、操作管理
详细命令参考请查看各服务对应的文件。

Pre-Flight Checks

预检查步骤

Before working with any GCP service:
bash
undefined
在使用任何GCP服务前：
bash
undefined

1. Correct project?

1. 是否为正确的项目？

gcloud config get-value project
gcloud config get-value project

2. Default region set?

2. 是否设置了默认区域？

gcloud config get-value compute/region
gcloud config get-value compute/region

3. Required API enabled? (most APIs are disabled by default)

3. 所需API是否已启用？（大多数API默认处于禁用状态）

gcloud services list --filter="name:run.googleapis.com" --format="value(name)" | grep -q run ||
gcloud services enable run.googleapis.com
gcloud services list --filter="name:run.googleapis.com" --format="value(name)" | grep -q run ||
gcloud services enable run.googleapis.com

4. Billing enabled?

4. 是否已启用计费？

gcloud billing projects describe $(gcloud config get-value project) --format="value(billingEnabled)"

**If you hit `PERMISSION_DENIED: ... API has not been enabled`**, enable the API
mentioned in the error and retry.
gcloud billing projects describe $(gcloud config get-value project) --format="value(billingEnabled)"

**若遇到`PERMISSION_DENIED: ... API has not been enabled`错误**，请启用错误信息中提及的API并重试。

Troubleshooting

问题排查

ProblemDiagnosisFix
Auth failure
gcloud auth list
gcloud auth login
or check key file
Permission deniedCheck IAM (see iam.md)Grant correct role
API not enabledError message says which API
gcloud services enable API_NAME
Quota exceeded
gcloud compute project-info describe
Request increase in Console
Wrong project
gcloud config get-value project
gcloud config set project X
Wrong region
gcloud config get-value compute/region
Set correct region; related resources must match
Config confusion
gcloud config configurations list
Check active config, override with 
--project
Slow commandsLarge result setUse 
--filter
, 
--limit
, 
--format=value
bash
undefined
问题诊断方法修复方案
身份验证失败
gcloud auth list
gcloud auth login
或检查密钥文件
权限不足查看IAM配置（参考iam.md）授予正确的角色
API未启用错误信息会指明具体API
gcloud services enable API_NAME
配额超限
gcloud compute project-info describe
在控制台申请配额提升
项目错误
gcloud config get-value project
gcloud config set project X
区域错误
gcloud config get-value compute/region
设置正确的区域；相关资源需匹配区域
配置混乱
gcloud config configurations list
检查活跃配置，使用
--project
参数覆盖
命令执行缓慢结果集过大使用
--filter
、
--limit
、
--format=value
参数
bash
undefined

Debug mode

调试模式

gcloud compute instances list --verbosity=debug
gcloud compute instances list --verbosity=debug

Full environment info

完整环境信息

gcloud info
undefined
gcloud info
undefined

Quick Reference

快速参考

TaskCommand
Login
gcloud auth login
Set project
gcloud config set project PROJECT_ID
Current project
gcloud config get-value project
Enable API
gcloud services enable API.googleapis.com
List anything
gcloud COMPONENT list --format=json
Describe anything
gcloud COMPONENT describe NAME --format=json
JSON output
--format=json
Single value
--format="value(field)"
Filter
--filter="field=value"
Quiet ⚠️
--quiet
— suppresses ALL prompts including delete confirmations
Help
gcloud COMPONENT --help
任务命令
登录
gcloud auth login
设置项目
gcloud config set project PROJECT_ID
当前项目
gcloud config get-value project
启用API
gcloud services enable API.googleapis.com
列出所有资源
gcloud COMPONENT list --format=json
描述资源
gcloud COMPONENT describe NAME --format=json
JSON输出
--format=json
提取单个值
--format="value(field)"
过滤
--filter="field=value"
静默模式 ⚠️
--quiet
— 屏蔽所有提示，包括删除确认
帮助
gcloud COMPONENT --help