GCP 全新项目启动 Runbook（gcloud 命令流程）¶

日期：2026-07-31 ｜范围：从建项目到跑起 Flex Start GPU/TPU 再到清理

一份从零建 GCP 项目、启用 API、配 IAM、跑起 Flex Start GPU/TPU、最后清理的完整 gcloud 流程。Flex Start / L4 部分已实测验证。

阶段 0：认证与 gcloud 初始化¶

# 首次使用：登录并初始化
gcloud auth login

# 应用默认凭据（供 SDK / 客户端库使用，如 python、terraform）
gcloud auth application-default login

# 确认当前身份
gcloud auth list

已登录过则可跳过，用 gcloud config set account <[email protected]> 切换身份。
CI / 自动化场景用服务账号：gcloud auth activate-service-account --key-file=key.json。

阶段 1：项目创建与基础配置¶

# 变量（按需修改）
PROJECT_ID="my-new-proj-$(date +%s)"       # 全局唯一，小写/数字/连字符
BILLING_ID="XXXXXX-XXXXXX-XXXXXX"          # gcloud billing accounts list 查
REGION="us-central1"
ZONE="us-central1-a"

# 1. 创建项目
gcloud projects create "$PROJECT_ID" --name="$PROJECT_ID"

# 2. 关联结算账号（不关联无法用付费资源）
gcloud billing accounts list --format='value(name,displayName,open)'
gcloud billing projects link "$PROJECT_ID" --billing-account="$BILLING_ID"

# 3. 设为默认项目/区域
gcloud config set project "$PROJECT_ID"
gcloud config set compute/region "$REGION"
gcloud config set compute/zone "$ZONE"

display-name ≠ project ID

项目显示名和真实 project ID 不是一回事。若只知道显示名，用下面反查真实 ID：

gcloud projects list --filter="name:显示名" --format='value(projectId)'

阶段 2：启用所需 API¶

# 一次性批量启用（按需增删）
gcloud services enable \
  compute.googleapis.com \
  aiplatform.googleapis.com \
  container.googleapis.com \
  storage.googleapis.com \
  iam.googleapis.com \
  cloudresourcemanager.googleapis.com \
  logging.googleapis.com \
  monitoring.googleapis.com \
  --project="$PROJECT_ID"

# 确认已启用
gcloud services list --enabled --project="$PROJECT_ID" --format='value(config.name)'

阶段 3：IAM / 服务账号（可选但推荐）¶

SA_NAME="workload-sa"
SA_EMAIL="${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com"

# 建 SA
gcloud iam service-accounts create "$SA_NAME" \
  --display-name="Workload SA" --project="$PROJECT_ID"

# 授权（示例：compute + storage + aiplatform）
for ROLE in roles/compute.admin roles/storage.admin roles/aiplatform.user; do
  gcloud projects add-iam-policy-binding "$PROJECT_ID" \
    --member="serviceAccount:${SA_EMAIL}" --role="$ROLE" --condition=None
done

跨项目 Vertex 调用

SA 需在目标项目上具备 roles/aiplatform.admin + roles/serviceusage.serviceUsageConsumer，否则会 403。

阶段 4：网络（默认网络通常够用，需自定义时）¶

# 若项目无 default 网络，建一个自动子网 VPC
gcloud compute networks create default --subnet-mode=auto --project="$PROJECT_ID"

# 放行 SSH / 内部流量
gcloud compute firewall-rules create allow-ssh \
  --network=default --allow=tcp:22 --source-ranges=0.0.0.0/0 --project="$PROJECT_ID"
gcloud compute firewall-rules create allow-internal \
  --network=default --allow=tcp,udp,icmp --source-ranges=10.128.0.0/9 --project="$PROJECT_ID"

阶段 5：配额检查（开机前必看）¶

# GPU 配额（Flex Start 走 PREEMPTIBLE_* 配额）
gcloud compute regions describe "$REGION" --project="$PROJECT_ID" \
  --format="table(quotas.filter('metric:L4').metric, quotas.limit, quotas.usage)" 2>/dev/null

Flex Start 的配额映射

Flex Start L4 → PREEMPTIBLE_NVIDIA_L4_GPUS
常规 L4 → NVIDIA_L4_GPUS

更可靠的方式是直接 REST：GET https://compute.googleapis.com/compute/v1/projects/$PID/regions/$REGION，读 quotas 数组。

阶段 6A：启动 Flex Start GPU（g2 / L4，已实测）¶

gcloud compute instances create flex-l4-test \
  --project="$PROJECT_ID" \
  --zone="$ZONE" \
  --machine-type=g2-standard-4 \
  --provisioning-model=FLEX_START \
  --instance-termination-action=DELETE \
  --max-run-duration=1800s \
  --maintenance-policy=TERMINATE \
  --no-restart-on-failure \
  --image-family=common-cu124 --image-project=deeplearning-platform-release \
  --boot-disk-size=200GB

GPU 启动的四个坑

GPU 机器必须 --maintenance-policy=TERMINATE（默认 MIGRATE 会直接报错）。
GA track 用 --maintenance-policy，不是 --on-host-maintenance（那是 alpha/beta）。
boot disk 建议 ≥200GB，否则有 I/O 性能告警。
跑 CUDA 用 common-cu124 镜像（自带驱动）；纯测试可用 debian-12。

Flex Start 是 DWS 排队供应：实测 us-central1-a 约 20 秒起，但高峰期可能排队。

# 轮询状态
gcloud compute instances describe flex-l4-test --zone="$ZONE" --project="$PROJECT_ID" \
  --format='value(status,scheduling.provisioningModel,guestAccelerators[0].acceleratorType)'

阶段 6B：启动 Flex Start TPU（GKE node pool，参考）¶

绝对规则

任何 node pool 删除都必须获得明确批准，Flex Start 尤甚——TPU 释放后需要重新排队，删除操作一旦开始无法取消。

gcloud container node-pools create flex-v6e-pool \
  --cluster=YOUR_CLUSTER --location="$REGION" --project="$PROJECT_ID" \
  --node-locations="$ZONE" \
  --machine-type=ct6e-standard-4t \
  --flex-start --enable-autoscaling --num-nodes=0 --max-nodes=2 \
  --disk-size=1000GB   # v6e 默认 100GB，GCS FUSE 缓存需 1TB+

TPU 拓扑要点：v6e 仅 2D（8×8 = 64 chips），v5p/v7x 为 3D。

阶段 7：清理（避免计费）¶

# 删单机（Flex Start 到期会自动删，手动删更保险）
gcloud compute instances delete flex-l4-test --zone="$ZONE" --project="$PROJECT_ID" --quiet

# 确认无残留计费资源
gcloud compute instances list --project="$PROJECT_ID"
gcloud compute disks list --project="$PROJECT_ID"

常用排障¶

现象	原因 / 处理
`PERMISSION_DENIED` 调用 API	未启用对应 API，或身份缺角色；见阶段 2 / 3
`Project 'X' not found or permission denied (210002)`	用了 display-name 当 ID；反查真实 projectId
`onHostMaintenance must be TERMINATE`	GPU 机型加 `--maintenance-policy=TERMINATE`
`unrecognized arguments: --on-host-maintenance`	GA track 用 `--maintenance-policy`
Flex Start 一直 PROVISIONING	DWS 排队中；换区或稍等，us-central1/us-east4 的 L4 最稳