compute-spot-capacity-advice

Compute Engine Spot 容量建议

compute-spot-capacity-advice 技能可提供遥测数据和架构指导，帮助在提交创建请求前评估 Google Compute Engine（GCE）Spot VM 的可获取性。

Spot VM 在闲置计算容量上运行，可能会被抢占。评估容量可获取性有助于工作负载减少配置失败、避免资源短缺，并选择最佳机器系列、分布形态和区域。

说明

Spot Capacity Advice 通过 Compute Engine Beta API（compute.beta.AdviceService.Capacity、POST /compute/beta/projects/{project}/regions/{region}/advice/capacity）提供，无需将项目加入允许名单。务必通过 gcloud beta 发布渠道调用它（gcloud beta compute advice capacity）——即使 gcloud compute advice capacity 出现在 --help 中，也绝不可省略 beta，因为 v1 后端会拒绝 SPOT。Flex-start Capacity Advice（--provisioning-model=FLEX_START）目前处于 Private Preview 阶段；对于未明确加入允许名单的公开工作负载，务必使用 --provisioning-model=SPOT。

使用归因

务必阅读：执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读并遵循使用归因中的说明。

---

前提条件与 IAM 要求

查询 Spot 容量建议之前，请确保环境满足以下要求：

1. 项目和区域配置：优先在每条命令中直接传入 --project={project_id} 和 --region={region}，以避免覆盖工作站的全局状态；或者在设置默认值（例如 us-central1）之前征得用户明确同意：

   gcloud config set project {project_id}
   gcloud config set compute/region {region}
   

2. 结算和 API 启用：确保项目关联了有效的结算账号，并已启用 Compute Engine API：

   gcloud services enable compute.googleapis.com --project={project_id}
   

3. Cloud SDK 和身份验证：确保已安装 Google Cloud CLI（未经用户明确批准，绝不可擅自在主机上执行安装或修改组件的命令，例如 apt-get、管道式 Shell 安装脚本或 gcloud components install beta；应引导用户参阅安装指南），然后通过 gcloud auth login（用于交互式 CLI）、gcloud auth application-default login（用于 SDK）或 GOOGLE_APPLICATION_CREDENTIALS（用于服务账号）进行身份验证。
4. IAM 权限：遵循最小权限原则，授予 roles/compute.viewer（或包含 compute.advice.capacity 权限的自定义角色）。
5. 价格和位置：查询容量建议免费，但已配置的 Spot VM 会按动态 Spot 费率计费。请参阅 Compute Engine 定价、可用区域和可用区和 Google Cloud 位置（向用户展示文档网址时，请移除 .md.txt 后缀）。

---

命令语法和参考

使用 gcloud beta compute advice capacity 查询容量建议：

gcloud beta compute advice capacity \
  --project={project_id} \
  --region={region} \
  --provisioning-model=SPOT \
  --size={vm_count} \
  --target-distribution-shape={target_shape} \
  (--instance-selection-machine-types={machine_types} | --instance-selection="name={selection_name},machine-type={machine_type_1},machine-type={machine_type_2}") \
  [--zones={zone_1},{zone_2}]

标志参考与 CLI 限制

如需查看完整的标志定义，请参阅 gcloud beta compute advice capacity 参考文档。构造命令时，请遵循以下不易察觉的 CLI 限制：

• --region 与 --zones：指定 --zones 时会自动推断 --region。
• --size 范围：每次查询接受 1 到 1000 个 VM。
• --target-distribution-shape：必须指定跨可用区的放置偏好（any-single-zone、any 或 balanced）。
• 实例选择与不支持的标志：在整个请求中，最多指定 5 种机器类型，可使用单个 --instance-selection-machine-types 标志、单个 --instance-selection 标志（gcloud 每条命令仅支持一个 --instance-selection 标志），或 --instance-flexibility-policy（最多指定 10 个命名选择）。请勿在 CLI 中传递 --max-run-duration、--accelerator-topology、rank、min-cpu-platform、minCpuPlatform 或 disks。

---

输出解读：分数与建议

该命令会返回一个或多个包含放置分片和评估分数的建议（如果该区域没有候选可用区支持所请求的机器系列，则返回 {}；区域库存不足时仍会返回建议，其中 obtainability: 0.1，且 estimatedUptime: 60s），如下方示例输出所示：

# Example output
recommendations:
- scores:
    obtainability: 0.9
    estimatedUptime: 3600s
  shards:
  - instanceCount: 100
    machineType: n2-standard-32
    provisioningModel: SPOT
    zone: https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a

分数评估标准

完整定义请参阅查看 Spot VM 的可用性：scores.obtainability（范围为 0.0 到 1.0，以离散档位输出，例如 0.9、0.5 和 0.1）以及 scores.estimatedUptime（3600s、600s 或 60s）。将 obtainability >= 0.7 视为可获取性较高，0.4–0.69 视为可获取性中等（使用灵活的机器类型或多可用区放置），将 < 0.4 视为库存不足风险较高（不要建议立即部署完整批次；请采用以下架构缓解措施）。将 scores.estimatedUptime 解读为被抢占前的最短预期运行时间：3600s（60 分钟，适用于容错批处理工作负载）、600s（10 分钟，仅适用于短时任务或频繁检查点）以及 60s（1 分钟，被抢占风险高——请检查其他位置、机器类型或预配模式）。

---

架构缓解措施与最佳实践

容量受限时（obtainability < 0.4，或者该区域没有可用的机器系列时返回空 {}）：

1. 扩大分布范围：
   • 将 --target-distribution-shape=any-single-zone 改为 --target-distribution-shape=any（或 balanced），以便 Compute Engine 在该区域的所有可用区分布实例。
2. 提高实例灵活性：
   • 使用 --instance-selection 或 --instance-selection-machine-types，在同一代中添加替代机器形状（例如 n2-standard-32、n2-standard-48），或跨系列添加（例如 c2-standard-30、c3-standard-44）。请注意，创建实例或模板时，Gen 4 及更新系列（例如 c4*、n4*、m4*、h4d*、a4* 和 a3-ultragpu-8g）需要使用 Hyperdisk 启动卷，而非 pd-* 磁盘；对于新发布的机器系列，请通过 gcloud compute machine-types describe 或官方机器系列文档确认支持的磁盘类型。
3. 区域回退方案：
   • 评估网络延迟或计费特征相近的邻近区域（例如从 us-central1 回退到 us-east4、us-west1 或 us-east1）。
4. 加速器、SKU 和可用区限制：
   • gcloud beta compute advice capacity 通过集成加速器的机器类型（例如 g2-standard-*、a2-highgpu-*、a3-highgpu-*、a3-megagpu-*）评估 GPU 容量，并默认包含 AI 可用区（用户应确认项目已启用 AI 可用区）。请勿传入 --accelerator-topology，并将 --instance-selection 严格限制为 name 和 machine-type（请勿在 gcloud CLI 中传入 rank、min-cpu-platform、disks 或来宾加速器标志；带有外接来宾 GPU 的 n1-* VM，以及使用非默认 Local SSD 的机器类型，仅在 Beta REST API 中通过 instanceFlexibilityPolicy.instanceSelections.{selection_name} 下的 guestAccelerators 和 disks 受支持；每块 Local SSD 磁盘须对应一个 type: SCRATCH 条目）。
   • 不受支持的 Spot SKU、免费套餐和 Day-0 不可变性：Spot VM 不支持 a4x-* 或裸机（*-metal）形状；Spot e2-micro VM 不符合 Google Cloud 免费套餐额度资格；现有 STANDARD VM 无法通过 set-scheduling 原地转换为 SPOT（需要重新创建 VM）。
   • 不支持 TPU 可用性：advice.capacity API 不支持查看 Cloud TPU 的可用性。对于 TPU 容量规划和日历预留，请使用 compute-future-reservations（gcloud compute advice calendar-mode）。
5. 配额与余量免责声明：
   • 可获取性评分反映的是数据中心的物理容量，而非项目配额分配情况。预配前请核实区域 Spot CPU/GPU 配额（通过 gcloud compute regions describe {region}、gcloud compute project-info describe 或 Google Cloud 控制台的“配额”页面）。即使物理容量可用性很高，项目配额不足时尝试启动实例仍会在运行时失败。
6. 只读建议、强化型 VM 默认设置与 MCP 防护措施：
   • 容量建议严格来说是只读建议工具。未经用户明确批准，切勿执行会修改状态的命令（例如 gcloud compute instances create 或 gcloud compute instances delete）；应改为提供可直接复制粘贴的命令。
   • 为 Spot VM 生成 gcloud compute instances create 命令时，建议使用私有网络（将 --no-address 与 IAP TCP 转发配合使用）、自定义的最小权限服务账号（--service-account），以及 --instance-termination-action=DELETE（以免 Spot 抢占后启动磁盘仍继续计费）。提醒用户在工作负载完成后删除临时 Spot VM（gcloud compute instances delete {vm_name} --zone={zone}；除非传入 --quiet，否则命令会交互式提示）。
   • Compute Engine MCP create_instance 防护措施：调用前请检查会话中 MCP create_instance 工具的架构（以防较新版本的 MCP 服务增加了相关支持）；除非已在当前架构中确认，否则 MCP create_instance 会省略 provisioning_model（静默预配全价 STANDARD VM）、硬编码 global/networks/default，且无法设置自定义服务账号——请始终改用 gcloud compute instances create --provisioning-model=SPOT。