compute-spot-capacity-advice

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Compute Engine Spot Capacity Advice

Compute Engine Spot 容量建议

The

compute-spot-capacity-advice

skill provides telemetry and architectural guidance to assess the obtainability of Google Compute Engine (GCE) Spot VMs before submitting creation requests.

Spot VMs run on spare compute capacity and are subject to preemption. Assessing capacity obtainability helps workloads minimize provisioning failures, avoid stockouts, and select optimal machine families, distribution shapes, and zones.

[!NOTE] Spot Capacity Advice is served on the Compute Engine Beta API (
compute.beta.AdviceService.Capacity
,
POST /compute/beta/projects/{project}/regions/{region}/advice/capacity
) and requires no project allowlisting. Always invoke it via the
gcloud beta
release track (
gcloud beta compute advice capacity
) — never omit
beta
even if
gcloud compute advice capacity
appears in
--help
, as the
v1
backend rejects
SPOT
. Flex-start Capacity Advice (
--provisioning-model=FLEX_START
) is currently in Private Preview; for public workloads without explicit allowlists, always use
--provisioning-model=SPOT
.

compute-spot-capacity-advice

skill 提供遥测数据和架构指导，用于在提交创建请求之前评估 Google Compute Engine (GCE) Spot VM 的可获得性。

Spot VM 运行在闲置计算容量上，并且可能被抢占。评估容量可获得性有助于工作负载减少置备失败、避免缺货，并选择最优的 machine family、distribution shape 和 zone。

[!NOTE] Spot Capacity Advice 通过 Compute Engine Beta API (
compute.beta.AdviceService.Capacity
,
POST /compute/beta/projects/{project}/regions/{region}/advice/capacity
) 提供服务，且无需将项目加入 allowlist。务必通过
gcloud beta
发布通道 (
gcloud beta compute advice capacity
) 调用——即使
--help
中显示
gcloud compute advice capacity
，也绝不能省略
beta
，因为
v1
后端会拒绝
SPOT
。Flex-start Capacity Advice (
--provisioning-model=FLEX_START
) 目前处于 Private Preview；对于未明确加入 allowlist 的公开工作负载，始终使用
--provisioning-model=SPOT
。

Usage Attribution

使用归属说明（Usage Attribution）

MUST READ: Before executing any

gcloud

, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.

必须阅读：在执行任何

gcloud

、REST API 或 MCP 命令之前，你必须阅读并遵循使用归属说明中的指示。

Prerequisites & IAM Requirements

前提条件与 IAM 要求

Before querying Spot capacity advice, ensure the environment meets these requirements:

Project & Region Configuration: Prefer passing
```
--project={project_id}
```
and
```
--region={region}
```
directly on each command to avoid overwriting global workstation state, or obtain explicit user confirmation before setting defaults (e.g.,
```
us-central1
```
):
bash
```
gcloud config set project {project_id}
gcloud config set compute/region {region}
```
Billing & API Enablement: Ensure the project has an active billing account attached and the Compute Engine API is enabled:
bash
```
gcloud services enable compute.googleapis.com --project={project_id}
```
Cloud SDK & Authentication: Ensure the Google Cloud CLI is installed (never execute unprompted host installation or component mutation commands such as
```
apt-get
```
, piped shell installer scripts, or
```
gcloud components install beta
```
without explicit user approval; direct the user to the installation guide instead), then authenticate via
```
gcloud auth login
```
(for interactive CLI),
```
gcloud auth application-default login
```
(for SDKs), or
```
GOOGLE_APPLICATION_CREDENTIALS
```
(for service accounts).
IAM Permissions: Grant
```
roles/compute.viewer
```
(or a custom role containing the
```
compute.advice.capacity
```
permission) following the principle of least privilege.
Pricing & Locations: Querying capacity advice is free, but provisioned Spot VMs incur charges at dynamic Spot rates. Review Compute Engine Pricing, Available Regions and Zones, and Google Cloud Locations (strip
```
.md.txt
```
suffixes when presenting documentation URLs to human users).

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

项目与 Region 配置：优先在每条命令中直接传入
```
--project={project_id}
```
和
```
--region={region}
```
，以避免覆盖工作站上的全局状态；或者，在设置默认值（例如
```
us-central1
```
）之前取得用户的明确确认：
bash
```
gcloud config set project {project_id}
gcloud config set compute/region {region}
```
结算与 API 启用：确保项目已关联有效的结算账号，并且 Compute Engine API 已启用：
bash
```
gcloud services enable compute.googleapis.com --project={project_id}
```
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
```
（用于服务账号）进行身份验证。
IAM 权限：按照最小权限原则授予
```
roles/compute.viewer
```
（或包含
```
compute.advice.capacity
```
权限的自定义角色）。
定价与位置：查询容量建议是免费的，但已置备的 Spot VM 会按动态 Spot 价格计费。请查阅 Compute Engine Pricing、Available Regions and Zones 和 Google Cloud Locations（在向用户展示文档 URL 时，移除
```
.md.txt
```
后缀）。

Command Syntax & Reference

命令语法与参考

Query capacity advice using

gcloud beta compute advice capacity

bash

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}]

使用

gcloud beta compute advice capacity

查询容量建议：

bash

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}]

Flag Reference & CLI Constraints

Flag 参考与 CLI 约束

For complete flag definitions, refer to the

gcloud beta compute advice capacity

reference documentation. When constructing commands, apply these non-obvious CLI constraints:

--region
vs.
--zones
:
```
--region
```
is automatically inferred when
```
--zones
```
is specified.
--size
Bounds: Accepts
```
1
```
to
```
1000
```
VMs per query.

--target-distribution-shape
: Required placement preference across zones (

any-single-zone

any

, or

balanced

Instance Selection & Unsupported Flags: Specify up to
```
5
```
machine types total across the request using a single
```
--instance-selection-machine-types
```
flag, a single
```
--instance-selection
```
flag (
```
gcloud
```
supports only one
```
--instance-selection
```
flag per command), or
```
--instance-flexibility-policy
```
(up to
```
10
```
named selections). Do not pass
```
--max-run-duration
```
,
```
--accelerator-topology
```
,
```
rank
```
,
```
min-cpu-platform
```
,
```
minCpuPlatform
```
, or
```
disks
```
on the CLI.

有关完整的 flag 定义，请参阅

gcloud beta compute advice capacity

参考文档。构建命令时，请遵循以下不易察觉的 CLI 约束：

--region
与
--zones
：指定
```
--zones
```
时会自动推断
```
--region
```
。
--size
范围：每次查询可接受
```
1
```
到
```
1000
```
台 VM。
--target-distribution-shape
：必填，用于指定跨 zone 的放置偏好（
```
any-single-zone
```
、
```
any
```
或
```
balanced
```
）。
Instance Selection 与不支持的 Flags：每条请求可通过单个
```
--instance-selection-machine-types
```
flag、单个
```
--instance-selection
```
flag（
```
gcloud
```
每条命令仅支持一个
```
--instance-selection
```
flag），或
```
--instance-flexibility-policy
```
指定最多
```
5
```
种 machine type（最后一种方式最多支持
```
10
```
个命名 selection）。不要在 CLI 中传入
```
--max-run-duration
```
、
```
--accelerator-topology
```
、
```
rank
```
、
```
min-cpu-platform
```
、
```
minCpuPlatform
```
或
```
disks
```
。

Output Interpretation: Scores & Recommendations

输出解读：分数与建议

The command returns one or more recommendations containing placement shards and evaluation scores (or

{}

if zero candidate zones in the region support the requested machine series; regional stockouts still return a recommendation with

obtainability: 0.1

and

estimatedUptime: 60s

), as shown in the following example output:

yaml

undefined

命令会返回一个或多个 recommendation，其中包含 placement shard 和评估分数（如果该 region 内没有任何候选 zone 支持所请求的 machine series，则返回

{}

；即使发生 region 级缺货，仍会返回一条 recommendation，其中

obtainability: 0.1

且

estimatedUptime: 60s

），示例如下：

yaml

undefined

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

undefined

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

undefined

Score Evaluation Rubric

分数评估标准

Refer to View the availability of Spot VMs for full definitions of

scores.obtainability

(

0.0

1.0

, emitted in discrete buckets such as

0.9

0.5

, and

0.1

) and

scores.estimatedUptime

(

3600s

600s

, or

60s

). Treat

obtainability >= 0.7

as strongly obtainable,

0.4

–

0.69

as moderately obtainable (use flexible machine types or multi-zone placement), and

< 0.4

as high stockout risk (do not advise immediate full-batch deployment; apply the architectural mitigations below). Interpret

scores.estimatedUptime

as the minimum expected runtime before preemption:

3600s

(60 minutes, suitable for fault-tolerant batch workloads),

600s

(10 minutes, suitable only for short tasks or frequent checkpointing), and

60s

(1 minute, high preemption risk—check another location, machine type, or provisioning model).

有关

scores.obtainability

（范围为

0.0

到

1.0

，以

0.9

、

0.5

、

0.1

等离散档位输出）和

scores.estimatedUptime

（

3600s

、

600s

或

60s

）的完整定义，请参阅查看 Spot VM 的可用性。将

obtainability >= 0.7

视为具有较高可获得性，将

0.4

–

0.69

视为具有中等可获得性（应使用灵活的 machine type 或多 zone 放置），并将

< 0.4

视为存在较高缺货风险（不建议立即部署完整批次；应采用下述架构缓解措施）。将

scores.estimatedUptime

解读为被抢占前的最短预期运行时长：

3600s

（60 分钟，适合容错型批处理工作负载）、

600s

（10 分钟，仅适合短任务或频繁创建 checkpoint 的任务），以及

60s

（1 分钟，存在较高的抢占风险——应检查其他位置、machine type 或 provisioning model）。

Architectural Mitigation & Best Practices

架构缓解措施与最佳实践

When capacity is constrained (

obtainability

< 0.4

or empty

{}

returned when the machine series is unavailable in the region):

Broaden Distribution Shape:
- Switch from
```
--target-distribution-shape=any-single-zone
```
  to
```
--target-distribution-shape=any
```
  (or
```
balanced
```
  ) so Compute Engine can distribute instances across all available zones in the region.
Inject Instance Flexibility:
- Add alternative machine shapes within the same generation (e.g.,
```
n2-standard-32
```
  ,
```
n2-standard-48
```
  ) or across families (e.g.,
```
c2-standard-30
```
  ,
```
c3-standard-44
```
  ) using
```
--instance-selection
```
  or
```
--instance-selection-machine-types
```
  (note that Gen 4+ families such as
```
c4*
```
  ,
```
n4*
```
  ,
```
m4*
```
  ,
```
h4d*
```
  ,
```
a4*
```
  , and
```
a3-ultragpu-8g
```
  require Hyperdisk boot volumes rather than
```
pd-*
```
  disks when creating instances or templates; for newly released machine series, verify supported disk types via
```
gcloud compute machine-types describe
```
  or the official machine family documentation).
Regional Fallbacks:
- Evaluate adjacent regions with similar network latency or billing characteristics (e.g., fallback from
```
us-central1
```
  to
```
us-east4
```
  ,
```
us-west1
```
  , or
```
us-east1
```
  ).
Accelerator, SKU & Zone Limitations:
- ```
gcloud beta compute advice capacity
```
  evaluates GPU capacity via integrated accelerator machine types (such as
```
g2-standard-*
```
  ,
```
a2-highgpu-*
```
  ,
```
a3-highgpu-*
```
  ,
```
a3-megagpu-*
```
  ) and includes AI zones by default (users should confirm that AI zones are enabled for their project). Do not pass
```
--accelerator-topology
```
  , and restrict
```
--instance-selection
```
  strictly to
```
name
```
  and
```
machine-type
```
  (do not pass
```
rank
```
  ,
```
min-cpu-platform
```
  ,
```
disks
```
  , or guest accelerator flags on the
```
gcloud
```
  CLI;
```
n1-*
```
  VMs with attached guest GPUs and machine types with non-default Local SSDs are supported only on the Beta REST API under
```
instanceFlexibilityPolicy.instanceSelections.{selection_name}
```
  via
```
guestAccelerators
```
  and
```
disks
```
  with one
```
type: SCRATCH
```
  entry per Local SSD disk).
- Unsupported Spot SKUs, Free Tier & Day-0 Immutability: Spot VMs do not support
```
a4x-*
```
  or bare metal (
```
*-metal
```
  ) shapes, Spot
```
e2-micro
```
  VMs do not qualify for the Google Cloud Free Tier allowance, and existing
```
STANDARD
```
  VMs cannot be converted in place to
```
SPOT
```
  via
```
set-scheduling
```
  (requires recreating the VM).
- No TPU Availability Support: The
```
advice.capacity
```
  API does not support viewing the availability of Cloud TPUs. For TPU capacity planning and calendar bookings, use
```
compute-future-reservations
```
  (
```
gcloud compute advice calendar-mode
```
  ).
Quota & Headroom Disclaimer:
- Obtainability scores reflect physical datacenter capacity, not project quota allocation. Verify regional Spot CPU/GPU quota (via
```
gcloud compute regions describe {region}
```
  ,
```
gcloud compute project-info describe
```
  , or the Google Cloud Console Quotas page) before provisioning. Attempting to launch instances without sufficient project quota will fail at runtime despite high physical capacity availability.
Read-Only Advisory, Hardened VM Defaults & MCP Guardrail:
- Capacity advice is strictly a read-only advisory tool. Never execute mutating commands (such as
```
gcloud compute instances create
```
  or
```
gcloud compute instances delete
```
  ) without explicit human approval from the user; provide copy-pasteable commands instead.
- When generating
```
gcloud compute instances create
```
  commands for Spot VMs, recommend private networking (
```
--no-address
```
  paired with IAP TCP forwarding), a custom least-privilege service account (
```
--service-account
```
  ), and
```
--instance-termination-action=DELETE
```
  (so boot disks do not continue billing after Spot preemption). Remind users to delete temporary Spot VMs (
```
gcloud compute instances delete {vm_name} --zone={zone}
```
  , which prompts interactively unless
```
--quiet
```
  is passed) when workloads finish.
- Compute Engine MCP
  create_instance
  Guardrail: Inspect the in-session MCP
```
create_instance
```
  tool schema before invoking it (in case newer MCP server versions add support); unless verified in the current schema, MCP
```
create_instance
```
  omits
```
provisioning_model
```
  (silently provisioning full-price
```
STANDARD
```
  VMs), hardcodes
```
global/networks/default
```
  , and cannot set custom service accounts — always use
```
gcloud compute instances create --provisioning-model=SPOT
```
  instead.

当容量受限（

obtainability

< 0.4

，或 machine series 在该 region 不可用时返回空

{}

）：

扩展 Distribution Shape：
- 将
```
--target-distribution-shape=any-single-zone
```
  切换为
```
--target-distribution-shape=any
```
  （或
```
balanced
```
  ），使 Compute Engine 可以在该 region 的所有可用 zone 之间分配实例。
引入 Instance Flexibility：
- 使用
```
--instance-selection
```
  或
```
--instance-selection-machine-types
```
  ，在同一 generation 内添加替代 machine shape（例如
```
n2-standard-32
```
  、
```
n2-standard-48
```
  ），或跨 family 添加替代 shape（例如
```
c2-standard-30
```
  、
```
c3-standard-44
```
  ）（注意，在创建 instance 或 template 时，Gen 4+ family，例如
```
c4*
```
  、
```
n4*
```
  、
```
m4*
```
  、
```
h4d*
```
  、
```
a4*
```
  和
```
a3-ultragpu-8g
```
  ，要求使用 Hyperdisk boot volume，而不是
```
pd-*
```
  disk；对于新发布的 machine series，请通过
```
gcloud compute machine-types describe
```
  或官方 machine family 文档验证支持的 disk 类型）。
Region Fallback：
- 评估网络延迟或计费特征相近的相邻 region（例如，从
```
us-central1
```
  fallback 至
```
us-east4
```
  、
```
us-west1
```
  或
```
us-east1
```
  ）。
Accelerator、SKU 与 Zone 限制：
- ```
gcloud beta compute advice capacity
```
  通过集成 accelerator 的 machine type（例如
```
g2-standard-*
```
  、
```
a2-highgpu-*
```
  、
```
a3-highgpu-*
```
  、
```
a3-megagpu-*
```
  ）评估 GPU 容量，并默认纳入 AI zone（用户应确认其项目已启用 AI zone）。不要传入
```
--accelerator-topology
```
  ；在 gcloud CLI 上，
```
--instance-selection
```
  必须严格限定为
```
name
```
  和
```
machine-type
```
  （不要传入
```
rank
```
  、
```
min-cpu-platform
```
  、
```
disks
```
  或 guest accelerator flag；挂载 guest GPU 的
```
n1-*
```
  VM，以及使用非默认 Local SSD 的 machine type，仅可通过 Beta REST API 的
```
instanceFlexibilityPolicy.instanceSelections.{selection_name}
```
  使用
```
guestAccelerators
```
  和
```
disks
```
  支持，其中每个 Local SSD disk 对应一个
```
type: SCRATCH
```
  条目）。
- 不支持的 Spot SKU、Free Tier 与 Day-0 不可变性：Spot VM 不支持
```
a4x-*
```
  或裸金属（
```
*-metal
```
  ）shape；Spot
```
e2-micro
```
  VM 不计入 Google Cloud Free Tier 配额；现有
```
STANDARD
```
  VM 无法通过
```
set-scheduling
```
  就地转换为
```
SPOT
```
  （必须重新创建 VM）。
- 不支持 TPU 可用性查询：
```
advice.capacity
```
  API 不支持查看 Cloud TPU 的可用性。如需规划 TPU 容量或进行日历预订，请使用
```
compute-future-reservations
```
  （
```
gcloud compute advice calendar-mode
```
  ）。
Quota 与 Headroom 免责声明：
- 可获得性分数反映物理数据中心容量，而非项目 quota 分配。置备之前，请验证 region 的 Spot CPU/GPU quota（可通过
```
gcloud compute regions describe {region}
```
  、
```
gcloud compute project-info describe
```
  或 Google Cloud Console 的 Quotas 页面检查）。即使物理容量可用率很高，若项目 quota 不足，启动 instance 仍会在运行时失败。
只读建议、VM 安全加固默认设置与 MCP Guardrail：
- Capacity advice 是严格只读的 advisory tool。未经用户明确批准，绝不要执行 mutation command（例如
```
gcloud compute instances create
```
  或
```
gcloud compute instances delete
```
  ）；应改为提供可直接复制粘贴的命令。
- 为 Spot VM 生成
```
gcloud compute instances create
```
  命令时，建议使用 private networking（
```
--no-address
```
  与 IAP TCP forwarding 搭配）、自定义最小权限 service account（
```
--service-account
```
  ），并设置
```
--instance-termination-action=DELETE
```
  （从而避免 Spot 被抢占后 boot disk 继续计费）。提醒用户在工作负载完成后删除临时 Spot VM（
```
gcloud compute instances delete {vm_name} --zone={zone}
```
  ；除非传入
```
--quiet
```
  ，否则该命令会进行交互式确认）。
- Compute Engine MCP
  create_instance
  Guardrail：调用当前会话中的 MCP
```
create_instance
```
  tool schema 前，请先检查该 schema（以防较新的 MCP server 版本新增相关支持）；除非已验证当前 schema 支持这些能力，否则 MCP
```
create_instance
```
  会省略
```
provisioning_model
```
  （从而静默置备全价
```
STANDARD
```
  VM）、硬编码
```
global/networks/default
```
  ，并且无法设置自定义 service account——始终改用
```
gcloud compute instances create --provisioning-model=SPOT
```
  。