compute-on-demand-reservations
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCompute Engine On-Demand Reservations
Compute Engine On-Demand 预留
The skill inspects and manages active Google Compute Engine (GCE) On-Demand reservations. It determines whether guaranteed capacity is available, calculates consumption, verifies instance targeting policies, and audits cross-project sharing.
compute-on-demand-reservationscompute-on-demand-reservationsUsage Attribution
使用归属说明
MUST READ: Before executing any , REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.
gcloud必须阅读:在执行任何 、REST API 或 MCP 命令前,您必须阅读并遵循 使用归属说明中的说明。
gcloudPrerequisites, IAM & Billing
前提条件、IAM 与结算
Before querying or managing On-Demand reservations, ensure the environment meets these requirements:
- Project & Region Configuration: Prefer passing and
--project={project_id}directly on each command to avoid overwriting global workstation state, or obtain explicit user confirmation before setting defaults (e.g.,--zone={zone}/us-central1):us-central1-abashgcloud config set project {project_id} gcloud config set compute/region {region} gcloud config set compute/zone {zone} - 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 commands such as or
apt-getwithout explicit user approval; direct the user to the installation guide instead), then authenticate viacurl | bash(for interactive CLI),gcloud auth login(for SDKs), orgcloud auth application-default login(for service accounts).GOOGLE_APPLICATION_CREDENTIALS - IAM Permissions:
- Read-Only Inspection (,
list): Grantdescribe(or custom role withroles/compute.viewerandcompute.reservations.list).compute.reservations.get - Reservation Lifecycle (,
create,update): Grantdelete(or custom role withroles/compute.admin,compute.reservations.create,compute.reservations.resize, andcompute.reservations.update).compute.reservations.delete - Consuming Reservations (): Grant
instances createon the project launching VMs (and on both the host/owner project and the consumer project when consuming a shared reservation).roles/compute.instanceAdmin.v1
- Read-Only Inspection (
- Quota & Organization Policy: Creating an On-Demand reservation immediately consumes regional CPU, GPU, or Local SSD quota. For shared reservations, Compute Engine deducts regional quota in both the host project (at reservation creation) and the consumer project (when VMs launch), and requires the host project to be allowlisted in organization policy .
constraints/compute.sharedReservationsOwnerProjects - Billing & Pricing Warning: On-Demand reservations are billed immediately upon creation at the full On-Demand VM rate whether or not VMs are running and consuming the reservation. Review Compute Engine Pricing, Available Regions and Zones, and Google Cloud Locations (strip suffixes when presenting documentation URLs to human users) before provisioning.
.md.txt
在查询或管理 On-Demand 预留之前,请确保环境满足以下要求:
- 项目与区域配置:优先在每条命令中直接传入 和
--project={project_id},以避免覆盖工作站的全局状态;或者在设置默认值(例如--zone={zone}/us-central1)之前获得用户的明确确认:us-central1-abashgcloud config set project {project_id} gcloud config set compute/region {region} gcloud config set compute/zone {zone} - 结算与 API 启用:确保项目已关联有效的结算账号,并且已启用 Compute Engine API:
bash
gcloud services enable compute.googleapis.com --project={project_id} - Cloud SDK 与身份验证:确保已安装 Google Cloud CLI(未经用户明确许可,绝不要在主机上执行 或
apt-get等安装命令;应引导用户参阅安装指南),然后通过curl | bash(用于交互式 CLI)、gcloud auth login(用于 SDK)或gcloud auth application-default login(用于服务账号)进行身份验证。GOOGLE_APPLICATION_CREDENTIALS - IAM 权限:
- 只读检查(、
list):授予describe(或包含roles/compute.viewer和compute.reservations.list的自定义角色)。compute.reservations.get - 预留生命周期(、
create、update):授予delete(或包含roles/compute.admin、compute.reservations.create、compute.reservations.resize和compute.reservations.update的自定义角色)。compute.reservations.delete - 消耗预留():在启动 VM 的项目上授予
instances create;使用共享预留时,还需在主机/所有者项目和使用方项目上授予此权限。roles/compute.instanceAdmin.v1
- 只读检查(
- 配额与组织策略:创建 On-Demand 预留会立即占用区域的 CPU、GPU 或 Local SSD 配额。对于共享预留,Compute Engine 会同时从主机项目(创建预留时)和使用方项目(启动 VM 时)扣减区域配额,并要求在组织策略 中将主机项目加入允许列表。
constraints/compute.sharedReservationsOwnerProjects - 结算与定价警告:On-Demand 预留在创建后立即按完整的 On-Demand VM 费率计费,无论 VM 是否运行并正在使用预留。配置前请查看 Compute Engine 定价、可用区域和可用区 和 Google Cloud 位置(向用户展示文档 URL 时,移除 后缀)。
.md.txt
Command Syntax & Reference
命令语法与参考
1. List Reservations in a Project / Zone
1. 列出项目或可用区中的预留
bash
gcloud compute reservations list \
--project={project_id} \
[--zones={zone}] \
[--format="table(name,zone.basename(),specificReservation.instanceProperties.machineType.basename(),specificReservation.assuredCount,specificReservation.inUseCount,specificReservation.count,specificReservationRequired,shareSettings.shareType,status)"]bash
gcloud compute reservations list \
--project={project_id} \
[--zones={zone}] \
[--format="table(name,zone.basename(),specificReservation.instanceProperties.machineType.basename(),specificReservation.assuredCount,specificReservation.inUseCount,specificReservation.count,specificReservationRequired,shareSettings.shareType,status)"]2. Inspect Reservation Details & Capacity Metrics
2. 检查预留详情与容量指标
bash
gcloud compute reservations describe {reservation_name} \
--zone={zone} \
--project={project_id}(Note: Dense accelerator reservations backed by leave columns blank in and expose and via .)
aggregateReservationspecificReservation.*listaggregateReservation.totalResourcesaggregateReservation.inUseResourcesdescribebash
gcloud compute reservations describe {reservation_name} \
--zone={zone} \
--project={project_id}(注意:由 支持的密集型 accelerator 预留,其 列在 中会留空;可通过 查看 和 。)
aggregateReservationspecificReservation.*listdescribeaggregateReservation.totalResourcesaggregateReservation.inUseResources3. Create a New On-Demand Reservation
3. 创建新的 On-Demand 预留
[!IMPORTANT] Creating a reservation immediately incurs billing charges. Always obtain explicit human approval before executing.gcloud compute reservations create
bash
gcloud compute reservations create {reservation_name} \
--project={project_id} \
--zone={zone} \
--vm-count={vm_count} \
(--machine-type={machine_type} | --source-instance-template={template_name}) \
[--min-cpu-platform={min_cpu_platform}] \
[--accelerator=count={gpu_count},type={gpu_type}] \
[--local-ssd=interface={nvme|scsi}] \
[--require-specific-reservation] \
[--share-setting=projects --share-with={consumer_project_ids}] # up to 100 consumer projects in the same org (excluding the host project)[!IMPORTANT] 创建预留会立即产生结算费用。执行前,必须始终获得明确的人工批准。gcloud compute reservations create
bash
gcloud compute reservations create {reservation_name} \
--project={project_id} \
--zone={zone} \
--vm-count={vm_count} \
(--machine-type={machine_type} | --source-instance-template={template_name}) \
[--min-cpu-platform={min_cpu_platform}] \
[--accelerator=count={gpu_count},type={gpu_type}] \
[--local-ssd=interface={nvme|scsi}] \
[--require-specific-reservation] \
[--share-setting=projects --share-with={consumer_project_ids}] # up to 100 consumer projects in the same org (excluding the host project)4. Update or Resize an Existing Reservation
4. 更新或调整现有预留
Resizing capacity () and modifying shared consumer projects are mutable in place after obtaining explicit human approval ( and accept up to 100 consumer project IDs or project numbers in the same organization excluding the host project itself, while strictly requires numeric project numbers). Hardware attributes (, , , , , and ) are immutable after creation and require recreating the reservation.
--vm-count--share-with--add-share-with--remove-share-withmachineTypeminCpuPlatformacceleratorlocalSsdzonespecificReservationRequiredbash
gcloud compute reservations update {reservation_name} \
--project={project_id} \
--zone={zone} \
[--vm-count={new_vm_count}] \
[--add-share-with={project_ids_or_numbers} | --remove-share-with={project_numbers}]调整容量大小()和修改共享使用方项目可在获得明确人工批准后原地变更( 和 最多接受同一组织中除主机项目自身以外的 100 个使用方项目 ID 或项目编号,而 则严格要求使用数字项目编号)。硬件属性(、、、、 和 )创建后不可更改,需要重新创建预留。
--vm-count--share-with--add-share-with--remove-share-withmachineTypeminCpuPlatformacceleratorlocalSsdzonespecificReservationRequiredbash
gcloud compute reservations update {reservation_name} \
--project={project_id} \
--zone={zone} \
[--vm-count={new_vm_count}] \
[--add-share-with={project_ids_or_numbers} | --remove-share-with={project_numbers}]5. Delete an Unused On-Demand Reservation (Resource Teardown)
5. 删除未使用的 On-Demand 预留(资源拆除)
To stop ongoing billing for an unused On-Demand reservation, delete it after obtaining explicit human approval (note: deletion fails if the reservation is attached to a resource-based Committed Use Discount where is set—which must be swapped via —or if a targeted reservation with still has ; the command also prompts interactively unless is passed):
commitmentgcloud beta compute commitments update-reservationsspecificReservationRequired: trueinUseCount > 0--quietbash
gcloud compute reservations delete {reservation_name} \
--zone={zone} \
--project={project_id}若要停止未使用的 On-Demand 预留持续产生费用,请在获得明确人工批准后将其删除。请注意:如果该预留与已设置 的基于资源的 Committed Use Discount (CUD) 关联,删除将会失败——必须先通过 进行替换;或者,如果定向预留的 且 ,删除同样会失败;此外,除非传入 ,该命令还会进行交互式提示:
commitmentgcloud beta compute commitments update-reservationsspecificReservationRequired: trueinUseCount > 0--quietbash
gcloud compute reservations delete {reservation_name} \
--zone={zone} \
--project={project_id}Capacity Utilization Analysis
容量利用率分析
When inspecting reservation output, verify that the reservation is or (exclude reservations in or states) and calculate available capacity using the following fields:
statusREADYUPDATINGCREATINGDELETING- : Must be
statusorREADYbefore instances can consume reserved capacity. While a reservation isUPDATING(for example, during a capacity resize or share-setting modification), its already provisioned capacity remains consumable up toUPDATING. OnlyspecificReservation.assuredCountandCREATINGstates block consumption.DELETING - : The number of reserved VM instances currently provisioned and physically backed by Compute Engine hardware. Note that
specificReservation.assuredCountcan be less thanassuredCountwhile a reservation is actively upsizing or if a physical host failure degrades the reservation (specificReservation.count).healthInfo.healthStatus: DEGRADED - : The total requested target number of VM instances in this reservation block.
specificReservation.count - : The number of reserved instances currently consumed by running VMs.
specificReservation.inUseCount - Available Reserved Capacity:
text
Available Capacity = specificReservation.assuredCount - specificReservation.inUseCount
检查预留输出时,请确认预留 为 或 (排除处于 或 状态的预留),并使用以下字段计算可用容量:
statusREADYUPDATINGCREATINGDELETING- :实例能够消耗预留容量前,必须为
status或READY。当预留处于UPDATING状态时(例如调整容量大小或修改共享设置期间),已经预配的容量仍可被消耗,最高不超过UPDATING。只有specificReservation.assuredCount和CREATING状态会阻止消耗。DELETING - :当前已预配并由 Compute Engine 硬件实际承载的预留 VM 实例数量。预留正在扩容时,
specificReservation.assuredCount可能小于assuredCount;物理主机故障导致预留降级(specificReservation.count)时也可能如此。healthInfo.healthStatus: DEGRADED - :此预留块中请求的 VM 实例目标总数。
specificReservation.count - :当前被运行中的 VM 消耗的预留实例数量。
specificReservation.inUseCount - 可用的预留容量:
text
Available Capacity = specificReservation.assuredCount - specificReservation.inUseCount
Health & Consumption Thresholds
健康状态与消耗阈值
- Available (): Provisioned reserved capacity is immediately available. Workloads can launch with 100% provisioning assurance.
> 0 - Exhausted (): Provisioned reserved capacity is fully consumed. New instances matching this specification fall back to unreserved on-demand capacity (if allowed) or fail to launch.
inUseCount >= assuredCount
- 可用():已预配的预留容量可立即使用。工作负载可获得 100% 的预配保证。
> 0 - 已耗尽():已预配的预留容量已完全消耗。新建且规格匹配的实例将回退到未预留的 On-Demand 容量(如果允许),否则将启动失败。
inUseCount >= assuredCount
Reservation Targeting Policies
预留定向策略
Reservations operate under two distinct consumption modes defined by :
specificReservationRequired| Setting | Consumption Mode | Matching Behavior |
|---|---|---|
| Automatic ( | Any newly created |
| Targeted ( | VMs do not consume this capacity unless they match all reserved |
预留具有两种不同的消耗模式,由 定义:
specificReservationRequired| 设置 | 消耗模式 | 匹配行为 |
|---|---|---|
| 自动( | 任何新建的 |
| 定向( | 除非 VM 与预留中的所有 |
Exact Hardware & Property Matching Requirement
硬件与属性必须完全匹配
For a VM to consume a reservation (under either or ), every property below must match the reservation's 100% identically:
ANY_RESERVATIONSPECIFIC_RESERVATIONspecificReservation.instanceProperties- Project and : Same project for
zonereservations, or an authorized consumer project listed inLOCAL, in the exact sameshareSettings.projectMap.zone - : Exact machine type shape.
machineType - : Must match verbatim. If the reservation was created without an explicit CPU platform (
minCpuPlatform), passing"Automatic"on the VM does not match (and vice versa).--min-cpu-platform - : Exact GPU
guestAcceleratorsandacceleratorType(if any).acceleratorCount - : Exact Local SSD partition count and exact storage interface (
localSsdsversusNVME, if any).SCSI - Placement policies: Exact compact placement and
resourcePolicies(if present on the reservation).locationHint - : Must be
provisioningModel(STANDARDVMs never consume On-Demand reservations).SPOT
[!WARNING] Silent Double-Billing Trap: Under(ANY_RESERVATION, the default), if a newly created VM matches--reservation-affinity=anyandzonebut differs on even a single property (such asmachineTypevs.NVMELocal SSD interface orSCSI), Compute Engine silently skips the reservation, launches an unreserved On-Demand VM, and bills for both the idle reservation and the new VM. Creating both the reservation and VMs from the sameminCpuPlatformprevents property drift.--source-instance-template
要让 VM 消耗预留无论是 还是 模式,以下每一项属性都必须与预留的 100% 完全一致:
ANY_RESERVATIONSPECIFIC_RESERVATIONspecificReservation.instanceProperties- 项目与 :对于
zone预留,必须属于同一项目;或者属于LOCAL中列出的已授权使用方项目,并且必须位于完全相同的shareSettings.projectMap。zone - :机器类型规格必须完全一致。
machineType - :必须逐字匹配。如果创建预留时未指定明确的 CPU 平台(
minCpuPlatform),则在 VM 上传入"Automatic"不会匹配,反之亦然。--min-cpu-platform - :GPU 的
guestAccelerators和acceleratorType(如果使用)必须完全一致。acceleratorCount - :Local SSD 分区数量和存储接口必须完全一致(如果使用,接口必须为
localSsds或NVME)。SCSI - 放置策略:如果预留中存在紧凑放置 和
resourcePolicies,必须完全一致。locationHint - :必须为
provisioningModel(STANDARDVM 永远不会消耗 On-Demand 预留)。SPOT
[!WARNING] 静默双重计费陷阱:在(ANY_RESERVATION,默认值)模式下,如果新建 VM 的--reservation-affinity=any和zone匹配,但仅有一个属性不同(例如 Local SSD 接口为machineType而非NVME,或者SCSI不同),Compute Engine 会在无提示的情况下跳过该预留,启动未预留的 On-Demand VM,并对闲置预留和新 VM 同时计费。使用同一个minCpuPlatform创建预留和 VM,可防止属性发生偏移。--source-instance-template
VM Provisioning Best Practices
VM 预配最佳实践
When provisioning VMs, recommend private networking ( paired with IAP TCP forwarding) and a custom least-privilege service account ():
--no-address--service-account- To consume a targeted reservation () during instance creation (note: passing
specificReservationRequired: trueagainst a reservation with--reservation-affinity=specificis rejected by Compute Engine):specificReservationRequired: falsebashgcloud compute instances create {vm_name} \ --project={project_id} \ --zone={zone} \ --machine-type={machine_type} \ --reservation-affinity=specific \ --reservation={reservation_name} \ [--no-address] \ [--service-account={service_account_email}] - To prevent an instance from consuming any reservation:
bash
gcloud compute instances create {vm_name} \ --project={project_id} \ --zone={zone} \ --machine-type={machine_type} \ --reservation-affinity=none \ [--no-address] \ [--service-account={service_account_email}]
预配 VM 时,建议使用私有网络( 配合 IAP TCP 转发)和自定义的最小权限服务账号():
--no-address--service-account- 要在创建实例时消耗定向预留(),请使用以下命令(注意:针对
specificReservationRequired: true的预留传入specificReservationRequired: false会被 Compute Engine 拒绝):--reservation-affinity=specificbashgcloud compute instances create {vm_name} \ --project={project_id} \ --zone={zone} \ --machine-type={machine_type} \ --reservation-affinity=specific \ --reservation={reservation_name} \ [--no-address] \ [--service-account={service_account_email}] - 要防止实例消耗任何预留,请使用以下命令:
bash
gcloud compute instances create {vm_name} \ --project={project_id} \ --zone={zone} \ --machine-type={machine_type} \ --reservation-affinity=none \ [--no-address] \ [--service-account={service_account_email}]
Cross-Project Shared Reservations
跨项目共享预留
Shared reservations allow multiple projects within the same Google Cloud organization to draw from a shared pool of reserved capacity.
- Inspect :
shareSettings- : Reservation is private to the host project.
shareType: LOCAL - : Shared with specific consumer projects keyed under
shareType: SPECIFIC_PROJECTS(mapping each project ID or number toprojectMap).{"projectId": "..."}
- Visibility & CUD Caveats:
- Running in a consumer project never displays shared reservations owned by a host project; always query
gcloud compute reservations list --project={consumer_project_id}(or Cloud Asset Inventory) to inspect--project={host_project_id}andassuredCount.inUseCount - Committed Use Discount (CUD) pricing only covers shared reservation consumers when the host and consumer projects belong to the same Cloud Billing account.
- Running
- Consumer projects consume shared capacity by specifying and referencing the host project in
--project={consumer_project_id}:--reservationbashgcloud compute instances create {vm_name} \ --project={consumer_project_id} \ --zone={zone} \ --machine-type={machine_type} \ --reservation-affinity=specific \ --reservation=projects/{host_project_id}/reservations/{reservation_name} \ [--no-address] \ [--service-account={service_account_email}]
共享预留允许同一 Google Cloud 组织中的多个项目从共享的预留容量池中获取容量。
- 检查 :
shareSettings- :预留仅限主机项目私有。
shareType: LOCAL - :与
shareType: SPECIFIC_PROJECTS中指定的使用方项目共享;projectMap以项目 ID 或编号为键,映射格式为projectMap。{"projectId": "..."}
- 可见性与 CUD 注意事项:
- 在使用方项目中运行 永远不会显示主机项目拥有的共享预留;检查
gcloud compute reservations list --project={consumer_project_id}和assuredCount时,始终应查询inUseCount(或使用 Cloud Asset Inventory)。--project={host_project_id} - 只有当主机项目和使用方项目属于同一个 Cloud Billing account 时,Committed Use Discount (CUD) 定价才涵盖共享预留的使用方。
- 在使用方项目中运行
- 使用方项目通过指定 并在
--project={consumer_project_id}中引用主机项目来消耗共享容量:--reservationbashgcloud compute instances create {vm_name} \ --project={consumer_project_id} \ --zone={zone} \ --machine-type={machine_type} \ --reservation-affinity=specific \ --reservation=projects/{host_project_id}/reservations/{reservation_name} \ [--no-address] \ [--service-account={service_account_email}]
Operational Guardrails & Recommendations
操作护栏与建议
- Human-Approval Guardrail: Never execute mutating commands (,
gcloud compute reservations create,gcloud compute reservations update, orgcloud compute reservations delete) without explicit human approval from the user. Provide copy-pasteable commands and highlight billing implications first.gcloud compute instances create - Compute Engine MCP Server Guardrail: When the Compute Engine MCP server is enabled, inspect the in-session MCP tool schemas before invoking them (in case newer MCP server versions add support); unless verified in the current schema:
- MCP is single-zone only and strips
list_reservationscounts/shape andspecific_reservation(callshare_settingsper reservation or useget_reservation_details).gcloud compute reservations list - No MCP tools exist to create, update, or delete reservations.
- MCP omits
create_instance,reservation_affinity, andmin_cpu_platform(cannot targetlocal_ssdor shared reservations and risks silent unreserved double-billing); fall back toSPECIFIC_RESERVATIONCLI when these parameters are absent from the tool schema.gcloud
- MCP
- Missing Reservation Advisory: When no matching or available reservation exists in the target zone:
- Inform the user that instances launch against unreserved on-demand capacity (subject to stock availability).
- If guaranteed capacity is required, advise creating a new reservation using .
gcloud compute reservations create - If the workload is interruptible or fault-tolerant, suggest evaluating Spot VMs using .
compute-spot-capacity-advice
- Negative Guardrail (No Spot Telemetry for On-Demand): Do not use Spot capacity advice () or emit obtainability scores when inspecting or verifying standard On-Demand reservations. On-Demand reservation checks must inspect concrete reservation status and counts via
gcloud beta compute advice capacity --provisioning-model=SPOTandgcloud compute reservations list.describe
- 人工批准护栏:未经用户明确批准,绝不执行变更命令(、
gcloud compute reservations create、gcloud compute reservations update或gcloud compute reservations delete)。应先提供可直接复制粘贴的命令,并突出说明结算影响。gcloud compute instances create - Compute Engine MCP Server 护栏:启用 Compute Engine MCP server 时,调用工具前应检查当前会话中的 MCP 工具 schema(以应对较新版本可能新增的功能);除非已在当前 schema 中验证,否则:
- MCP 仅支持单个可用区,并且会移除
list_reservations的数量/规格以及specific_reservation(应对每个预留调用share_settings,或使用get_reservation_details)。gcloud compute reservations list - 不存在用于创建、更新或删除预留的 MCP 工具。
- MCP 缺少
create_instance、reservation_affinity和min_cpu_platform(无法定向到local_ssd或共享预留,并可能引发静默的未预留双重计费);当工具 schema 中缺少这些参数时,应改用SPECIFIC_RESERVATIONCLI。gcloud
- MCP
- 预留缺失建议:当目标可用区中不存在匹配或可用的预留时:
- 告知用户实例将使用未预留的 On-Demand 容量启动(受库存可用性限制)。
- 如果需要保证容量,建议使用 创建新预留。
gcloud compute reservations create - 如果工作负载可中断或具备容错能力,建议评估使用 检查 Spot VM。
compute-spot-capacity-advice
- 负向护栏(On-Demand 不使用 Spot 遥测数据):检查或验证标准 On-Demand 预留时,不得使用 Spot 容量建议(),也不得输出可获得性评分。On-Demand 预留检查必须通过
gcloud beta compute advice capacity --provisioning-model=SPOT和gcloud compute reservations list检查具体的预留状态及计数。describe