compute-on-demand-reservations

name: compute-on-demand-reservationsmetadata:   version: "1.0.0"  category: Computedescription: >-  Inspects, verifies, and manages Google Compute Engine (GCE) On-Demand reservations  and analyzes consumed versus available reserved capacity. Use when checking active  reservation capacity, determining whether reserved VMs are available or exhausted,  verifying reservation targeting (automatic versus specific reservation), or sharing  reservations across projects. Don't use for Spot capacity advice (use  compute-spot-capacity-advice) or future calendar bookings (use compute-future-reservations).

Compute Engine On-Demand Reservations

The compute-on-demand-reservations 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.

Usage Attribution

MUST READ: Before executing any gcloud, REST API, or MCP command, you MUST read and follow the instructions in Usage Attribution.

---

Prerequisites, IAM & Billing

Before querying or managing On-Demand reservations, ensure the environment meets these requirements:

1. Project & Region Configuration: Prefer passing --project={project_id} and --zone={zone} directly on each command to avoid overwriting global workstation state, or obtain explicit user confirmation before setting defaults (e.g., us-central1 / us-central1-a):

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

2. Billing & API Enablement: Ensure the project has an active billing account attached and the Compute Engine API is enabled:

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

3. Cloud SDK & Authentication: Ensure the Google Cloud CLI is installed (never execute unprompted host installation commands such as apt-get or curl | bash 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).
4. IAM Permissions:
   • Read-Only Inspection (list, describe): Grant roles/compute.viewer (or custom role with compute.reservations.list and compute.reservations.get).
   • Reservation Lifecycle (create, update, delete): Grant roles/compute.admin (or custom role with compute.reservations.create, compute.reservations.resize, compute.reservations.update, and compute.reservations.delete).
   • Consuming Reservations (instances create): Grant roles/compute.instanceAdmin.v1 on the project launching VMs (and on both the host/owner project and the consumer project when consuming a shared reservation).
5. 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.
6. 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 .md.txt suffixes when presenting documentation URLs to human users) before provisioning.

---

Command Syntax & Reference

1. List Reservations in a Project / Zone

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

gcloud compute reservations describe {reservation_name} \
  --zone={zone} \
  --project={project_id}

(Note: Dense accelerator reservations backed by aggregateReservation leave specificReservation.* columns blank in list and expose aggregateReservation.totalResources and aggregateReservation.inUseResources via describe.)

3. Create a New On-Demand Reservation

[!IMPORTANT] Creating a reservation immediately incurs billing charges. Always obtain explicit human approval before executing gcloud compute reservations create.

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

Resizing capacity (--vm-count) and modifying shared consumer projects are mutable in place after obtaining explicit human approval (--share-with and --add-share-with accept up to 100 consumer project IDs or project numbers in the same organization excluding the host project itself, while --remove-share-with strictly requires numeric project numbers). Hardware attributes (machineType, minCpuPlatform, accelerator, localSsd, zone, and specificReservationRequired) are immutable after creation and require recreating the reservation.

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)

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 commitment is set—which must be swapped via gcloud beta compute commitments update-reservations—or if a targeted reservation with specificReservationRequired: true still has inUseCount > 0; the command also prompts interactively unless --quiet is passed):

gcloud compute reservations delete {reservation_name} \
  --zone={zone} \
  --project={project_id}

---

Capacity Utilization Analysis

When inspecting reservation output, verify that the reservation status is READY or UPDATING (exclude reservations in CREATING or DELETING states) and calculate available capacity using the following fields:

• status: Must be READY or UPDATING before instances can consume reserved capacity. While a reservation is UPDATING (for example, during a capacity resize or share-setting modification), its already provisioned capacity remains consumable up to specificReservation.assuredCount. Only CREATING and DELETING states block consumption.
• specificReservation.assuredCount: The number of reserved VM instances currently provisioned and physically backed by Compute Engine hardware. Note that assuredCount can be less than specificReservation.count while a reservation is actively upsizing or if a physical host failure degrades the reservation (healthInfo.healthStatus: DEGRADED).
• specificReservation.count: The total requested target number of VM instances in this reservation block.
• specificReservation.inUseCount: The number of reserved instances currently consumed by running VMs.
• Available Reserved Capacity:

  Available Capacity = specificReservation.assuredCount - specificReservation.inUseCount
  

Health & Consumption Thresholds

• Available (> 0): Provisioned reserved capacity is immediately available. Workloads can launch with 100% provisioning assurance.
• Exhausted (inUseCount >= assuredCount): Provisioned reserved capacity is fully consumed. New instances matching this specification fall back to unreserved on-demand capacity (if allowed) or fail to launch.

---

Reservation Targeting Policies

Reservations operate under two distinct consumption modes defined by specificReservationRequired:

Exact Hardware & Property Matching Requirement

For a VM to consume a reservation (under either ANY_RESERVATION or SPECIFIC_RESERVATION), every property below must match the reservation's specificReservation.instanceProperties 100% identically:

• Project and zone: Same project for LOCAL reservations, or an authorized consumer project listed in shareSettings.projectMap, in the exact same zone.
• machineType: Exact machine type shape.
• minCpuPlatform: Must match verbatim. If the reservation was created without an explicit CPU platform ("Automatic"), passing --min-cpu-platform on the VM does not match (and vice versa).
• guestAccelerators: Exact GPU acceleratorType and acceleratorCount (if any).
• localSsds: Exact Local SSD partition count and exact storage interface (NVME versus SCSI, if any).
• Placement policies: Exact compact placement resourcePolicies and locationHint (if present on the reservation).
• provisioningModel: Must be STANDARD (SPOT VMs never consume On-Demand reservations).

[!WARNING] Silent Double-Billing Trap: Under ANY_RESERVATION (--reservation-affinity=any, the default), if a newly created VM matches zone and machineType but differs on even a single property (such as NVME vs. SCSI Local SSD interface or minCpuPlatform), 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 same --source-instance-template prevents property drift.

VM Provisioning Best Practices

When provisioning VMs, recommend private networking (--no-address paired with IAP TCP forwarding) and a custom least-privilege service account (--service-account):

• To consume a targeted reservation (specificReservationRequired: true) during instance creation (note: passing --reservation-affinity=specific against a reservation with specificReservationRequired: false is rejected by Compute Engine):

  gcloud 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:

  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:
  • shareType: LOCAL: Reservation is private to the host project.
  • shareType: SPECIFIC_PROJECTS: Shared with specific consumer projects keyed under projectMap (mapping each project ID or number to {"projectId": "..."}).
• Visibility & CUD Caveats:
  • Running gcloud compute reservations list --project={consumer_project_id} in a consumer project never displays shared reservations owned by a host project; always query --project={host_project_id} (or Cloud Asset Inventory) to inspect assuredCount and inUseCount.
  • Committed Use Discount (CUD) pricing only covers shared reservation consumers when the host and consumer projects belong to the same Cloud Billing account.
• Consumer projects consume shared capacity by specifying --project={consumer_project_id} and referencing the host project in --reservation:

  gcloud 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, gcloud compute reservations delete, or gcloud compute instances create) without explicit human approval from the user. Provide copy-pasteable commands and highlight billing implications first.
• 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 list_reservations is single-zone only and strips specific_reservation counts/shape and share_settings (call get_reservation_details per reservation or use gcloud compute reservations list).
  • No MCP tools exist to create, update, or delete reservations.
  • MCP create_instance omits reservation_affinity, min_cpu_platform, and local_ssd (cannot target SPECIFIC_RESERVATION or shared reservations and risks silent unreserved double-billing); fall back to gcloud CLI when these parameters are absent from the tool schema.
• 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 (gcloud beta compute advice capacity --provisioning-model=SPOT) 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 compute reservations list and describe.