gcloud-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gcloud CLI

Overview

概述

Operate the

gcloud

CLI as a safe, effective cloud assistant. Read cloud state freely for debugging and exploration. Always ask the user before any create, update, or delete operation. This is non-negotiable.

安全、高效地将

gcloud

CLI用作云助手。可自由读取云状态以进行调试和探索。在执行任何创建、更新或删除操作前，必须先询问用户。这是不可协商的要求。

When to use

适用场景

When running any
```
gcloud
```
command
When debugging GCP resources (reading logs, describing instances, checking IAM)
When creating, updating, or deleting cloud resources
When authenticating to Google Cloud
When exploring what resources exist in a project
When the user asks about their GCP environment

Do NOT use when:

Managing GCP infrastructure with Terraform (use terraform/IaC skills instead)
Working with Firebase CLI (
```
firebase
```
commands)
Using Google Cloud client libraries in application code (not CLI operations)

运行任何
```
gcloud
```
命令时
调试GCP资源时（读取日志、描述实例、检查IAM）
创建、更新或删除云资源时
向Google Cloud进行身份验证时
探索项目中存在哪些资源时
用户询问其GCP环境相关问题时

不适用场景：

使用Terraform管理GCP基础设施时（请改用terraform/IaC相关技能）
使用Firebase CLI（
```
firebase
```
命令）时
在应用代码中使用Google Cloud客户端库时（非CLI操作）

Workflow

工作流程

1. Verify context

1. 验证上下文

Before running any

gcloud

command, check the current authentication and project context. Wrong project is the #1 cause of gcloud disasters.

bash

gcloud auth list
gcloud config get-value project
gcloud config get-value account

If not authenticated, guide the user through the appropriate auth flow (see Authentication section below). If the active project looks wrong, confirm with the user before proceeding.

在运行任何

gcloud

命令前，请检查当前的身份验证和项目上下文。选错项目是导致gcloud操作灾难的头号原因。

bash

gcloud auth list
gcloud config get-value project
gcloud config get-value account

如果未通过身份验证，请引导用户完成相应的认证流程（见下文身份验证部分）。如果当前激活的项目看起来有误，请在继续前与用户确认。

2. Classify the operation

2. 分类操作类型

Every

gcloud

command falls into one of two categories:

Category	Verbs	Action
Read-only	`list` , `describe` , `get-iam-policy` , `logs read` , `info` , `operations list`	Execute immediately. No confirmation needed.
Mutating	`create` , `delete` , `update` , `deploy` , `set-iam-policy` , `add-iam-policy-binding` , `remove-iam-policy-binding` , `ssh` , `scp` , `start` , `stop` , `resize`	Show command + impact, ask user for approval.

When uncertain whether a command mutates state, treat it as mutating.

每个

gcloud

命令都属于以下两类之一：

类别	动词	操作方式
只读操作	`list` , `describe` , `get-iam-policy` , `logs read` , `info` , `operations list`	立即执行，无需确认。
变更操作	`create` , `delete` , `update` , `deploy` , `set-iam-policy` , `add-iam-policy-binding` , `remove-iam-policy-binding` , `ssh` , `scp` , `start` , `stop` , `resize`	展示命令及其影响，请求用户批准。

如果不确定命令是否会变更状态，请将其视为变更操作。

3. Discover the right command

3. 查找正确的命令

For unfamiliar services or subcommands, use the built-in help system:

bash

undefined

对于不熟悉的服务或子命令，请使用内置帮助系统：

bash

undefined

Find available command groups

查找可用的命令组

gcloud --help

Explore a service

探索某个服务

gcloud compute --help

Find subcommands

查找子命令

gcloud compute instances --help

Get flags for a specific command

获取特定命令的参数

gcloud compute instances create --help


Always verify flag names via `--help` rather than guessing. Flags change across
gcloud versions and services.

gcloud compute instances create --help


请始终通过`--help`验证参数名称，而非猜测。参数会随gcloud版本和服务不同而变化。

4. Execute read-only commands freely

4. 自由执行只读命令

Run read commands without asking. These are safe and help gather context:

bash

undefined

无需询问即可运行只读命令，这些操作是安全的，有助于收集上下文信息：

bash

undefined

List resources

列出资源

gcloud compute instances list --format="table(name,zone,status)"

Describe a specific resource

描述特定资源

gcloud compute instances describe my-instance --zone=us-central1-a

Read logs

读取日志

gcloud logging read "resource.type=gce_instance" --limit=50 --format=json

Check IAM

检查IAM

gcloud projects get-iam-policy my-project --format=json


Use `--format` to control output: `json` for parsing, `table` for readability,
`value` for scripting.

gcloud projects get-iam-policy my-project --format=json


使用`--format`控制输出格式：`json`用于解析，`table`用于可读性，`value`用于脚本编写。

5. Confirm before mutating

5. 变更操作前需确认

For ANY create, update, or delete operation:

State what will happen — describe the resource, the action, and the project/region it affects
Show the exact command — the user should see precisely what will run
Ask for explicit approval — do not proceed without a clear "yes"

Example confirmation flow:

I'm going to create a new Compute Engine instance in project
my-project
:
bash
gcloud compute instances create web-server-1 \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=debian-11 \
  --image-project=debian-cloud
This will create a billable VM in
us-central1-a
. Shall I proceed?

Never use

--quiet

on destructive commands unless the user explicitly requests it. The

--quiet

flag suppresses confirmation prompts that are a safety net.

对于任何创建、更新或删除操作：

说明操作内容 — 描述资源、操作类型及其影响的项目/区域
展示确切命令 — 用户应能看到将执行的具体命令
请求明确批准 — 未获得明确的“是”回复前不要继续

示例确认流程：

我将在项目
my-project
中创建一个新的Compute Engine实例：
bash
gcloud compute instances create web-server-1 \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=debian-11 \
  --image-project=debian-cloud
这将在
us-central1-a
区域创建一个可计费的VM。是否继续？

除非用户明确要求，否则请勿在破坏性命令中使用

--quiet

参数。

--quiet

参数会抑制作为安全保障的确认提示。

6. Verify the result

6. 验证操作结果

After any mutating operation, run a corresponding read command to confirm:

bash

undefined

完成任何变更操作后，请运行相应的只读命令确认结果：

bash

undefined

After creating an instance

创建实例后

gcloud compute instances describe web-server-1 --zone=us-central1-a --format="table(name,status,networkInterfaces[0].accessConfigs[0].natIP)"

After deploying to Cloud Run

部署到Cloud Run后

gcloud run services describe my-service --region=us-central1 --format="table(status.url,status.conditions.status)"

After updating IAM

更新IAM后

gcloud projects get-iam-policy my-project --flatten="bindings[].members" --filter="bindings.members:user@example.com"

undefined

gcloud projects get-iam-policy my-project --flatten="bindings[].members" --filter="bindings.members:user@example.com"

undefined

Authentication

身份验证

Choose the auth flow based on context:

Context	Command	Notes
Local development (interactive)	`gcloud auth login`	Opens browser, stores user credentials
Application Default Credentials	`gcloud auth application-default login`	For apps using Google client libraries locally
Service account (CI/scripts)	`gcloud auth activate-service-account --key-file=KEY.json`	Use only when workload identity is unavailable
Workload Identity (production)	No `gcloud` auth needed	Preferred for GKE, Cloud Run, Cloud Functions — no keys to manage
Impersonation	`gcloud auth login --update-adc` then use `--impersonate-service-account=SA@PROJECT.iam.gserviceaccount.com`	Test SA permissions without downloading keys

Recommendations:

For local dev:

gcloud auth login

gcloud auth application-default login

For CI/CD: Workload Identity Federation (no keys). Fall back to service account keys only if WIF is not available.
For production workloads: Always use Workload Identity. Never store keys.

After authenticating, always set the project:

bash

gcloud config set project PROJECT_ID

根据上下文选择认证流程：

上下文	命令	说明
本地开发（交互式）	`gcloud auth login`	打开浏览器，存储用户凭证
应用默认凭证	`gcloud auth application-default login`	供本地使用Google客户端库的应用使用
服务账号（CI/脚本）	`gcloud auth activate-service-account --key-file=KEY.json`	仅当工作负载身份不可用时使用
工作负载身份（生产环境）	无需 `gcloud` 认证命令	推荐用于GKE、Cloud Run、Cloud Functions — 无需管理密钥
模拟身份	`gcloud auth login --update-adc` 然后使用 `--impersonate-service-account=SA@PROJECT.iam.gserviceaccount.com`	无需下载密钥即可测试服务账号权限

建议：

本地开发：

gcloud auth login

gcloud auth application-default login

CI/CD：工作负载身份联合（无密钥）。仅当WIF不可用时才回退到服务账号密钥。
生产工作负载：始终使用工作负载身份。切勿存储密钥。

完成身份验证后，请始终设置项目：

bash

gcloud config set project PROJECT_ID

Common service patterns

常见服务操作模式

For detailed command patterns per service, see references/command-patterns.md.

Quick overview of the most common operations:

Service	Read	Mutate
Compute Engine	`gcloud compute instances list/describe`	`gcloud compute instances create/delete/start/stop`
Cloud Run	`gcloud run services list/describe`	`gcloud run deploy` , `gcloud run services delete`
Cloud Functions	`gcloud functions list/describe/logs read`	`gcloud functions deploy/delete`
GKE	`gcloud container clusters list/describe`	`gcloud container clusters create/delete/resize`
IAM	`gcloud projects get-iam-policy`	`gcloud projects add-iam-policy-binding`
Cloud Storage	`gcloud storage ls/cat`	`gcloud storage cp/rm/mv`
Cloud SQL	`gcloud sql instances list/describe`	`gcloud sql instances create/delete/patch`
Pub/Sub	`gcloud pubsub topics list` , `subscriptions list`	`gcloud pubsub topics create/delete`
Logging	`gcloud logging read`	`gcloud logging write` (rare)
Networking	`gcloud compute networks list/describe`	`gcloud compute networks create/delete`

有关各服务的详细命令模式，请参阅references/command-patterns.md。

最常见操作的快速概览：

服务	只读操作	变更操作
Compute Engine	`gcloud compute instances list/describe`	`gcloud compute instances create/delete/start/stop`
Cloud Run	`gcloud run services list/describe`	`gcloud run deploy` , `gcloud run services delete`
Cloud Functions	`gcloud functions list/describe/logs read`	`gcloud functions deploy/delete`
GKE	`gcloud container clusters list/describe`	`gcloud container clusters create/delete/resize`
IAM	`gcloud projects get-iam-policy`	`gcloud projects add-iam-policy-binding`
Cloud Storage	`gcloud storage ls/cat`	`gcloud storage cp/rm/mv`
Cloud SQL	`gcloud sql instances list/describe`	`gcloud sql instances create/delete/patch`
Pub/Sub	`gcloud pubsub topics list` , `subscriptions list`	`gcloud pubsub topics create/delete`
Logging	`gcloud logging read`	`gcloud logging write` （罕见）
网络	`gcloud compute networks list/describe`	`gcloud compute networks create/delete`

Checklist

检查清单

Verified current auth and project context
Classified operation as read-only or mutating
Used
```
--help
```
to discover unfamiliar commands/flags
Executed read-only commands without blocking on confirmation
Showed exact command and impact before any mutating operation
Got explicit user approval before mutating
Did NOT use
```
--quiet
```
on destructive commands without user request
Verified result with a read command after mutation
Used appropriate
```
--format
```
flag for output readability

已验证当前的认证和项目上下文
已将操作分类为只读或变更类型
使用
```
--help
```
查找不熟悉的命令/参数
无需等待确认即可执行只读命令
在执行任何变更操作前展示确切命令及其影响
在变更前获得用户明确批准
未在未获得用户请求的情况下对破坏性命令使用
```
--quiet
```
参数
变更后使用只读命令验证结果
使用了合适的
```
--format
```
参数以提升输出可读性

Examples

示例

Example: Debug why a Cloud Run service is failing

User asks: "My Cloud Run service

api-server

us-east1

is returning 503s, help me debug."

Agent response (executes all reads freely, no confirmation needed):

bash

undefined

示例：调试Cloud Run服务失败的原因

用户提问：“我在

us-east1

区域的Cloud Run服务

api-server

返回503错误，帮我调试。”

助手回复（可自由执行所有只读操作，无需确认）：

bash

undefined

Check service status

检查服务状态

gcloud run services describe api-server --region=us-east1 --format="yaml(status)"

Check recent revisions

检查最近的版本

gcloud run revisions list --service=api-server --region=us-east1 --format="table(name,active,status)"

Read logs for errors

读取错误日志

gcloud logging read 'resource.type="cloud_run_revision" AND resource.labels.service_name="api-server" AND severity>=ERROR' --limit=20 --format=json

Check if the container image exists

检查容器镜像是否存在

gcloud run revisions describe REVISION_NAME --region=us-east1 --format="value(image)"


All of these are read-only. Run them immediately and analyze the results.

**Example: Create a new instance (mutating)**

User asks: "Create an e2-medium instance called web-1 in us-central1-a."

Agent response:

> I'll create a Compute Engine instance in project `current-project`:
>
> ```bash
> gcloud compute instances create web-1 \
>   --zone=us-central1-a \
>   --machine-type=e2-medium \
>   --image-family=debian-11 \
>   --image-project=debian-cloud
> ```
>
> This will create a billable e2-medium VM. Shall I proceed?

After user confirms, run the command, then verify:

```bash
gcloud compute instances describe web-1 --zone=us-central1-a --format="table(name,status,machineType,networkInterfaces[0].accessConfigs[0].natIP)"

gcloud run revisions describe REVISION_NAME --region=us-east1 --format="value(image)"


这些均为只读操作，可立即执行并分析结果。

**示例：创建新实例（变更操作）**

用户提问：“在us-central1-a区域创建一个名为web-1的e2-medium实例。”

助手回复：

> 我将在项目`current-project`中创建一个Compute Engine实例：
>
> ```bash
> gcloud compute instances create web-1 \
>   --zone=us-central1-a \
>   --machine-type=e2-medium \
>   --image-family=debian-11 \
>   --image-project=debian-cloud
> ```
>
> 这将创建一个可计费的e2-medium虚拟机。是否继续？

用户确认后，执行命令，然后验证：

```bash
gcloud compute instances describe web-1 --zone=us-central1-a --format="table(name,status,machineType,networkInterfaces[0].accessConfigs[0].natIP)"

Common mistakes

常见错误

Mistake	Fix
Running mutating commands without checking active project	Always run `gcloud config get-value project` first
Guessing flag names instead of checking `--help`	Use `gcloud <command> --help` to verify flags
Using `--quiet` on delete commands by default	Only use `--quiet` when user explicitly requests it
Not verifying mutations after execution	Run a corresponding `describe` or `list` command
Using service account keys in production	Use Workload Identity Federation instead
Forgetting `--format` flag, getting unreadable output	Use `--format=json` for parsing, `--format=table(...)` for display
Running `gcloud auth login` in CI environments	Use `gcloud auth activate-service-account` or Workload Identity
Not specifying `--zone` or `--region`	Always include location flags to avoid interactive prompts
Assuming `gcloud` is installed/authenticated	Verify with `gcloud --version` and `gcloud auth list` first
Deleting resources without confirming the project context	Double-check project with user before any delete

错误	修复方法
未检查当前项目就执行变更命令	始终先运行 `gcloud config get-value project`
猜测参数名称而非查看 `--help`	使用 `gcloud <command> --help` 验证参数
默认在删除命令中使用 `--quiet` 参数	仅在用户明确要求时才使用 `--quiet`
变更操作后未验证结果	运行相应的 `describe` 或 `list` 命令
在生产环境中使用服务账号密钥	改用工作负载身份联合
忘记使用 `--format` 参数，导致输出难以阅读	使用 `--format=json` 用于解析， `--format=table(...)` 用于展示
在CI环境中运行 `gcloud auth login`	使用 `gcloud auth activate-service-account` 或工作负载身份
未指定 `--zone` 或 `--region` 参数	始终包含位置参数以避免交互式提示
假设 `gcloud` 已安装并完成认证	先通过 `gcloud --version` 和 `gcloud auth list` 验证
未确认项目上下文就删除资源	在执行任何删除操作前与用户再次确认项目

Quick reference

快速参考

Operation	Command
Check auth	`gcloud auth list`
Check project	`gcloud config get-value project`
Switch project	`gcloud config set project PROJECT_ID`
List all services	`gcloud services list --enabled`
Discover commands	`gcloud <group> --help`
Format as JSON	`--format=json`
Format as table	`--format="table(field1,field2)"`
Filter results	`--filter="name:prefix-*"`
Limit output	`--limit=N`
All regions/zones	`gcloud compute regions list` / `gcloud compute zones list`

操作	命令
检查认证状态	`gcloud auth list`
检查当前项目	`gcloud config get-value project`
切换项目	`gcloud config set project PROJECT_ID`
列出所有已启用服务	`gcloud services list --enabled`
查找命令	`gcloud <group> --help`
格式化为JSON	`--format=json`
格式化为表格	`--format="table(field1,field2)"`
过滤结果	`--filter="name:prefix-*"`
限制输出数量	`--limit=N`
所有区域/可用区	`gcloud compute regions list` / `gcloud compute zones list`

Key principles

核心原则

Read freely, write cautiously — Read operations are safe and should run immediately to gather context. Every mutating operation requires explicit user approval, no exceptions.
Verify context first — Always confirm the active project and account before running commands. A command in the wrong project can cause real damage.
Discover, don't guess — Use
```
--help
```
to find correct subcommands and flags. Guessing leads to errors or worse, valid-but-wrong commands.
Verify after mutation — Always run a read command after any create, update, or delete to confirm the change took effect.
Prefer keyless auth — Workload Identity Federation for production,
```
gcloud auth login
```
for local dev. Service account keys are a last resort.

自由读取，谨慎变更 — 只读操作是安全的，应立即执行以收集上下文。所有变更操作都需要用户明确批准，无一例外。
先验证上下文 — 运行命令前始终确认当前激活的项目和账号。在错误的项目中执行命令可能会造成实际损失。
主动查找，而非猜测 — 使用
```
--help
```
查找正确的子命令和参数。猜测会导致错误，甚至执行有效但错误的命令。
变更后验证结果 — 在任何创建、更新或删除操作后，始终运行只读命令以确认变更已生效。
优先使用无密钥认证 — 生产环境使用工作负载身份联合，本地开发使用
```
gcloud auth login
```
。服务账号密钥是最后的选择。