⚡

GoogleCloudSDK(gcloudCLI)技能Skill gcloud

本技能提供了使用 Google Cloud SDK (gcloud CLI) 的全面指南，用于安装配置、认证授权、管理项目和资源、部署应用到 GCP 服务如 Compute Engine、GKE、App Engine 和 Cloud Storage，以及编写自动化脚本和集成 CI/CD 流水线。关键词：gcloud CLI, Google Cloud SDK, 云管理, 命令行工具, 自动化, 部署, 认证, GCP, DevOps, 云计算。

GCP 0 次安装 0 次浏览 更新于 3/18/2026

name: gcloud description: 实现 Google Cloud SDK (gcloud CLI) 的指南 - 一个用于管理 Google Cloud 资源的命令行工具。在安装/配置 gcloud、与 Google Cloud 认证、管理项目/配置、部署应用程序、使用 Compute Engine/GKE/App Engine/Cloud Storage、编写 gcloud 操作脚本、实施 CI/CD 流水线或故障排除 Google Cloud 部署时使用。

Google Cloud SDK (gcloud) 技能

全面指南，用于使用 Google Cloud SDK (gcloud CLI) - 主要命令行界面，用于与 Google Cloud Platform 服务交互、管理资源和自动化云操作。

何时使用此技能

在以下情况下使用此技能：

  • 安装和配置 Google Cloud SDK
  • 与 Google Cloud 认证（用户账户、服务账户、ADC）
  • 初始化 gcloud 并设置项目/配置
  • 管理多个 Google Cloud 项目和环境
  • 部署应用到 GCP（Compute Engine、GKE、App Engine、Cloud Run）
  • 使用 Cloud Storage、数据库和其他 GCP 服务
  • 编写 gcloud 命令脚本以进行自动化和 CI/CD 流水线
  • 故障排除认证、授权或部署问题
  • 优化 gcloud 命令性能和输出格式
  • 实施云操作的安全最佳实践

核心概念

gcloud CLI

架构：

  • 命令结构： gcloud + [发布级别] + 组件 + 实体 + 操作 + [参数] + [标志]
  • 发布级别： alpha、beta、GA（通用可用性）
  • 组件： compute、container、app、sql、iam、config、auth、storage 等
  • 全局标志： --project、--format、--filter、--quiet、--verbosity

关键特性：

  • 100 多个 Google Cloud 服务的统一 CLI
  • 所有服务的一致命令模式
  • 丰富的输出格式（JSON、YAML、CSV、表格）
  • 内置过滤和服务器端查询优化
  • 用于自动化的交互式和非交互式模式

认证 vs 授权

认证（你是谁）：

  • 用户账户（开发人员、管理员）
  • 服务账户（应用程序、自动化）
  • 应用程序默认凭证（ADC）
  • OAuth 2.0、API 密钥、工作负载/工作身份联盟

授权（你能做什么）：

  • IAM 角色和权限
  • 服务账户模拟
  • 资源级访问控制

配置管理

命名配置：

  • 用于不同环境的多个配置配置文件
  • 每个配置存储：账户、项目、区域、区域和其他属性
  • 即时切换配置

属性：

  • 7 个类别中的 50 多个可配置属性
  • 优先级：CLI 标志 > 环境变量 > 配置文件 > 默认值

I. 安装与设置

A. 安装方法

Linux（存档安装）

# 下载（选择架构）
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-linux-x86_64.tar.gz

# 提取
tar -xf google-cloud-cli-linux-x86_64.tar.gz

# 安装
./google-cloud-sdk/install.sh

# 初始化
./google-cloud-sdk/bin/gcloud init

Debian/Ubuntu（包管理器）

# 添加仓库
echo "deb [signed-by=/usr/share/keyrings/cloud.google.gpg] https://packages.cloud.google.com/apt cloud-sdk main" | sudo tee -a /etc/apt/sources.list.d/google-cloud-sdk.list

# 导入密钥
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key --keyring /usr/share/keyrings/cloud.google.gpg add -

# 安装
sudo apt-get update && sudo apt-get install google-cloud-cli

macOS

# 下载安装程序
curl -O https://dl.google.com/dl/cloudsdk/channels/rapid/downloads/google-cloud-cli-darwin-arm.tar.gz

# 提取并安装
tar -xf google-cloud-cli-darwin-arm.tar.gz
./google-cloud-sdk/install.sh

Windows

# 从 https://cloud.google.com/sdk/docs/install 下载安装程序
# 运行 GoogleCloudSDKInstaller.exe
# 按照安装向导操作

B. 初始化

# 交互式设置（推荐首次使用）
gcloud init

# 它做什么：
# 1. 打开浏览器进行 OAuth 认证
# 2. 选择或创建项目
# 3. 设置默认配置（区域、区域）
# 4. 存储凭证

# 非交互式（CI/CD 环境）
gcloud auth activate-service-account --key-file=key.json
gcloud config set project PROJECT_ID
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

C. 组件

# 列出可用组件
gcloud components list

# 安装额外组件
gcloud components install kubectl        # Kubernetes CLI
gcloud components install app-engine-python  # App Engine
gcloud components install cloud-sql-proxy    # Cloud SQL 代理
gcloud components install pubsub-emulator    # Pub/Sub 模拟器

# 更新所有组件
gcloud components update

# 移除组件
gcloud components remove COMPONENT_ID

核心组件（默认安装）：

  • gcloud - 主 CLI
  • gsutil - Cloud Storage 工具
  • bq - BigQuery CLI
  • core - 核心库

II. 认证与授权

A. 认证方法

1. 用户账户（OAuth 2.0）

# 使用浏览器登录
gcloud auth login

# 无浏览器登录（远程/无头）
gcloud auth login --no-browser

# 使用特定账户登录
gcloud auth login user@example.com

# 列出已认证账户
gcloud auth list

# 切换活动账户
gcloud config set account user@example.com

# 撤销凭证
gcloud auth revoke user@example.com

2. 服务账户

# 使用密钥文件激活服务账户
gcloud auth activate-service-account SA_EMAIL --key-file=path/to/key.json

# 创建服务账户
gcloud iam service-accounts create SA_NAME \
  --display-name="服务账户显示名称"

# 创建并下载密钥
gcloud iam service-accounts keys create key.json \
  --iam-account=SA_EMAIL

# 授予 IAM 角色
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/compute.admin"

3. 应用程序默认凭证（ADC）

# 为客户端库设置 ADC
gcloud auth application-default login

# 使用服务账户模拟设置 ADC
gcloud auth application-default login \
  --impersonate-service-account=SA_EMAIL

# 撤销 ADC
gcloud auth application-default revoke

# ADC 搜索顺序：
# 1. GOOGLE_APPLICATION_CREDENTIALS 环境变量
# 2. ~/.config/gcloud/application_default_credentials.json
# 3. 元数据服务器（在 GCP 资源上）

4. 服务账户模拟（推荐用于生产）

# 为单个命令模拟
gcloud compute instances list \
  --impersonate-service-account=SA_EMAIL

# 设置默认模拟
gcloud config set auth/impersonate_service_account SA_EMAIL

# 验证模拟
gcloud config get-value auth/impersonate_service_account

# 清除模拟
gcloud config unset auth/impersonate_service_account

为什么模拟？

  • 短期临时凭证（无持久密钥风险）
  • 无需分发服务账户密钥
  • 集中权限管理
  • 易于审计和轮换

B. 配置配置文件

创建和管理配置

# 创建新配置
gcloud config configurations create dev

# 列出所有配置
gcloud config configurations list

# 激活配置
gcloud config configurations activate dev

# 为单个命令切换配置
gcloud compute instances list --configuration=prod

# 设置属性
gcloud config set project my-project-dev
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

# 查看所有属性
gcloud config list

# 取消设置属性
gcloud config unset compute/zone

# 删除配置
gcloud config configurations delete dev

多环境模式

# 开发环境
gcloud config configurations create dev
gcloud config set project my-project-dev
gcloud config set account dev@example.com
gcloud config set compute/region us-central1

# 暂存环境
gcloud config configurations create staging
gcloud config set project my-project-staging
gcloud config set auth/impersonate_service_account staging-sa@project.iam.gserviceaccount.com

# 生产环境
gcloud config configurations create prod
gcloud config set project my-project-prod
gcloud config set auth/impersonate_service_account prod-sa@project.iam.gserviceaccount.com

# 切换环境
gcloud config configurations activate dev
gcloud config configurations activate prod

III. 常见工作流

A. 项目管理

# 列出项目
gcloud projects list

# 创建项目
gcloud projects create PROJECT_ID --name="项目名称"

# 设置活动项目
gcloud config set project PROJECT_ID

# 获取当前项目
gcloud config get-value project

# 启用 API
gcloud services enable compute.googleapis.com
gcloud services enable container.googleapis.com

# 列出已启用 API
gcloud services list

# 描述项目
gcloud projects describe PROJECT_ID

B. Compute Engine

# 列出实例
gcloud compute instances list

# 创建实例
gcloud compute instances create my-instance \
  --zone=us-central1-a \
  --machine-type=e2-medium \
  --image-family=debian-11 \
  --image-project=debian-cloud \
  --boot-disk-size=10GB

# SSH 进入实例
gcloud compute ssh my-instance --zone=us-central1-a

# 复制文件
gcloud compute scp local-file.txt my-instance:~/remote-file.txt \
  --zone=us-central1-a

# 停止实例
gcloud compute instances stop my-instance --zone=us-central1-a

# 删除实例
gcloud compute instances delete my-instance --zone=us-central1-a

C. Google Kubernetes Engine (GKE)

# 创建集群
gcloud container clusters create my-cluster \
  --zone=us-central1-a \
  --num-nodes=3 \
  --machine-type=e2-medium

# 获取集群凭证
gcloud container clusters get-credentials my-cluster --zone=us-central1-a

# 列出集群
gcloud container clusters list

# 调整集群大小
gcloud container clusters resize my-cluster \
  --num-nodes=5 \
  --zone=us-central1-a

# 删除集群
gcloud container clusters delete my-cluster --zone=us-central1-a

D. Cloud Storage

# 创建桶
gsutil mb gs://my-bucket-name

# 上传文件
gsutil cp local-file.txt gs://my-bucket-name/

# 下载文件
gsutil cp gs://my-bucket-name/file.txt ./

# 列出桶内容
gsutil ls gs://my-bucket-name/

# 同步目录
gsutil rsync -r ./local-dir gs://my-bucket-name/remote-dir

# 设置桶权限
gsutil iam ch user:user@example.com:objectViewer gs://my-bucket-name

# 删除桶
gsutil rm -r gs://my-bucket-name

E. App Engine

# 部署应用程序
gcloud app deploy app.yaml

# 查看应用程序
gcloud app browse

# 查看日志
gcloud app logs tail

# 列出版本
gcloud app versions list

# 删除版本
gcloud app versions delete VERSION_ID

# 设置流量分割
gcloud app services set-traffic SERVICE \
  --splits v1=0.5,v2=0.5

F. Cloud Run

# 部署容器
gcloud run deploy my-service \
  --image=gcr.io/PROJECT_ID/my-image:tag \
  --platform=managed \
  --region=us-central1 \
  --allow-unauthenticated

# 列出服务
gcloud run services list

# 描述服务
gcloud run services describe my-service --region=us-central1

# 删除服务
gcloud run services delete my-service --region=us-central1

IV. 脚本编写与自动化

A. 输出格式

# JSON（推荐用于脚本编写）
gcloud compute instances list --format=json

# YAML
gcloud compute instances list --format=yaml

# CSV
gcloud compute instances list --format="csv(name,zone,status)"

# 表格（默认）
gcloud compute instances list --format=table

# 值（单个字段提取）
gcloud config get-value project --format="value()"

# 自定义格式
gcloud compute instances list \
  --format="table(name,zone,machineType,status)"

B. 过滤

# 服务器端过滤（更高效）
gcloud compute instances list --filter="zone:us-central1-a"
gcloud compute instances list --filter="status=RUNNING"
gcloud compute instances list --filter="name~^web-.*"

# 多条件
gcloud compute instances list \
  --filter="zone:us-central1 AND status=RUNNING"

# 否定
gcloud compute instances list --filter="NOT status=TERMINATED"

# 复杂表达式
gcloud compute instances list \
  --filter="(status=RUNNING OR status=STOPPING) AND zone:us-central1"

C. 错误处理

#!/bin/bash

# 简单错误检查
if ! gcloud compute instances create my-instance; then
  echo "创建实例失败"
  exit 1
fi

# 捕获退出代码
gcloud compute instances describe my-instance
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  echo "实例未找到或发生错误"
  exit $EXIT_CODE
fi

# 捕获 stderr
ERROR_OUTPUT=$(gcloud compute instances create my-instance 2>&1)
if [ $? -ne 0 ]; then
  echo "错误：$ERROR_OUTPUT"
  exit 1
fi

# 创建前验证（幂等模式）
if ! gcloud compute instances describe my-instance &>/dev/null; then
  gcloud compute instances create my-instance
else
  echo "实例已存在，跳过创建"
fi

D. 重试逻辑

#!/bin/bash

MAX_RETRIES=5
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
  if gcloud compute instances create my-instance; then
    echo "实例创建成功"
    exit 0
  else
    echo "尝试 $i 失败，${RETRY_DELAY}s 后重试..."
    sleep $RETRY_DELAY
    RETRY_DELAY=$((RETRY_DELAY * 2))  # 指数回退
  fi
done

echo "$MAX_RETRIES 次尝试后失败"
exit 1

E. 批量操作

#!/bin/bash

# 并行实例创建
INSTANCES=("web-1" "web-2" "web-3")

for instance in "${INSTANCES[@]}"; do
  gcloud compute instances create "$instance" \
    --zone=us-central1-a \
    --machine-type=e2-medium \
    --async  # 在后台运行
done

# 等待所有操作完成
gcloud compute operations list --filter="status=RUNNING" \
  --format="value(name)" | while read op; do
  gcloud compute operations wait "$op" --zone=us-central1-a
done

echo "所有实例已创建"

F. CI/CD 集成

GitHub Actions

name: 部署到 GCP

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - id: auth
        uses: google-github-actions/auth@v1
        with:
          credentials_json: ${{ secrets.GCP_SA_KEY }}

      - name: 设置 Cloud SDK
        uses: google-github-actions/setup-gcloud@v1

      - name: 部署到 Cloud Run
        run: |
          gcloud run deploy my-service \
            --image=gcr.io/${{ secrets.GCP_PROJECT_ID }}/my-image:${{ github.sha }} \
            --region=us-central1 \
            --platform=managed

GitLab CI

deploy:
  image: google/cloud-sdk:alpine
  script:
    - echo $GCP_SA_KEY | base64 -d > key.json
    - gcloud auth activate-service-account --key-file=key.json
    - gcloud config set project $GCP_PROJECT_ID
    - gcloud app deploy
  only:
    - main

V. 最佳实践

A. 安全

1. 永不提交凭证

# 添加到 .gitignore
echo "key.json" >> .gitignore
echo ".config/gcloud/" >> .gitignore
echo "application_default_credentials.json" >> .gitignore

2. 使用服务账户模拟

# 优先模拟而非密钥文件
gcloud config set auth/impersonate_service_account SA_EMAIL

# 不推荐：gcloud auth activate-service-account --key-file=key.json

3. 最小权限原则

# 授予最小必需角色
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member="serviceAccount:SA_EMAIL" \
  --role="roles/compute.instanceAdmin.v1"  # 特定角色，非 "owner"

4. 定期轮换密钥

# 创建新密钥
gcloud iam service-accounts keys create new-key.json \
  --iam-account=SA_EMAIL

# 删除旧密钥
gcloud iam service-accounts keys delete KEY_ID \
  --iam-account=SA_EMAIL

B. 性能

1. 使用服务器端过滤

# 好：在服务器上过滤
gcloud compute instances list --filter="zone:us-central1"

# 差：本地使用 grep 过滤
gcloud compute instances list | grep us-central1

2. 限制输出

# 只获取所需内容
gcloud compute instances list --limit=10

# 仅投影所需字段
gcloud compute instances list --format="value(name,zone)"

3. 批量操作

# 使用 --async 进行并行操作
gcloud compute instances create instance-1 --async
gcloud compute instances create instance-2 --async
gcloud compute instances create instance-3 --async

C. 可维护性

1. 使用命名配置

# 分离开发/暂存/生产配置
gcloud config configurations create dev
gcloud config configurations create prod

2. 记录命令

#!/bin/bash
# 目的：部署应用到 Cloud Run
# 用法：./deploy.sh [环境]
# 示例：./deploy.sh production

ENV=${1:-staging}
gcloud config configurations activate "$ENV"
gcloud run deploy my-service --image=gcr.io/project/image:latest

3. 使用环境变量

# 使脚本可移植
PROJECT_ID=${GCP_PROJECT_ID:-default-project}
REGION=${GCP_REGION:-us-central1}

gcloud config set project "$PROJECT_ID"
gcloud config set compute/region "$REGION"

D. 监控与日志

# 启用审计日志
gcloud logging read "resource.type=gce_instance" \
  --limit=10 \
  --format=json

# 跟踪命令历史
gcloud info --show-log

# 调试的详细输出
gcloud compute instances create my-instance --verbosity=debug

VI. 故障排除

常见问题

1. 认证失败

# 检查当前认证
gcloud auth list

# 验证凭证
gcloud auth application-default print-access-token

# 重新认证
gcloud auth login
gcloud auth application-default login

2. 权限被拒绝

# 检查 IAM 权限
gcloud projects get-iam-policy PROJECT_ID \
  --flatten="bindings[].members" \
  --filter="bindings.members:user@example.com"

# 检查服务账户权限
gcloud iam service-accounts get-iam-policy SA_EMAIL

3. 配额超出

# 检查配额使用
gcloud compute project-info describe --project=PROJECT_ID

# 通过 Cloud Console 请求配额增加

4. 网络问题

# 检查连接性
gcloud info

# 使用代理
gcloud config set proxy/type http
gcloud config set proxy/address PROXY_HOST
gcloud config set proxy/port PROXY_PORT

5. 配置问题

# 查看当前配置
gcloud config list

# 重置配置
gcloud config configurations delete default
gcloud init

VII. 快速参考

基本命令

任务 命令
初始化 gcloud gcloud init
登录 gcloud auth login
设置项目 gcloud config set project PROJECT_ID
列出资源 gcloud [服务] list
描述资源 gcloud [服务] describe RESOURCE
创建资源 gcloud [服务] create RESOURCE
删除资源 gcloud [服务] delete RESOURCE
获取帮助 gcloud [服务] --help
查看配置 gcloud config configurations list
切换配置 gcloud config configurations activate CONFIG

全局标志

标志 目的 示例
--project 覆盖项目 --project=my-project
--format 输出格式 --format=json
--filter 服务器端过滤器 --filter="status=RUNNING"
--limit 限制结果 --limit=10
--quiet 抑制提示 --quiet
--verbosity 日志级别 --verbosity=debug
--async 不等待 --async

常见属性

# 核心
gcloud config set project PROJECT_ID
gcloud config set account EMAIL
gcloud config set disable_usage_reporting true

# 计算
gcloud config set compute/region us-central1
gcloud config set compute/zone us-central1-a

# 容器
gcloud config set container/cluster CLUSTER_NAME

# App Engine
gcloud config set app/cloud_build_timeout 1200

VIII. 资源

官方文档

工具

最佳实践总结

  1. 认证： 使用服务账户模拟而非密钥文件
  2. 配置： 使用命名配置处理多环境
  3. 安全： 授予最小 IAM 权限，定期轮换密钥
  4. 性能： 使用服务器端过滤，批量操作使用 --async
  5. 脚本编写： 输出 JSON 格式，实施错误处理和重试
  6. 自动化： 使用环境变量，操作前验证
  7. 监控： 启用 Cloud Audit Logs，跟踪命令历史
  8. 维护： 保持 SDK 更新，彻底记录脚本

常见用例

多环境部署

  • 分离开发/暂存/生产配置
  • 每个环境使用服务账户模拟
  • 通过 CI/CD 自动部署

基础设施即代码

  • 使用 gcloud 在 shell 脚本中创建资源
  • 将配置导出为 YAML/JSON
  • 版本控制基础设施命令

数据管道自动化

  • 计划的 BigQuery 作业
  • Cloud Storage 文件传输
  • Pub/Sub 消息处理

安全合规

  • 所有操作的审计日志
  • 加密静态和传输中数据
  • 定期密钥轮换和访问审查

此技能提供了全面的 gcloud CLI 知识，用于实现 Google Cloud 解决方案，从基本认证到高级自动化工作流。始终参考官方文档以获取最新特性和服务特定细节。