Create a reservation for a single project


This document explains how to create a single-project reservation, which can be consumed only by virtual machine (VM) instances in the same project. To learn more about reservations, see Reservations of Compute Engine zonal resources.

For other methods of creating reservations, see instead the following pages:

  • If you have any 1-year or 3-years commitments in the current project, then your reserved resources automatically receive any applicable committed use discounts. You can also create and attach a reservation to a commitment when you purchase the commitment. To learn more, see Attach reservations to commitments.

  • To create a reservation that can be used by multiple projects, see Create a shared reservation.

Before you begin

Required roles

To get the permissions that you need to create single-project reservations, ask your administrator to grant you the Compute Admin (roles/compute.admin) IAM role on the project. For more information about granting roles, see Manage access.

This predefined role contains the permissions required to create single-project reservations. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to create single-project reservations:

  • compute.reservations.create on the project
  • To specify an instance template: compute.instanceTemplates.useReadOnly on the instance template

You might also be able to get these permissions with custom roles or other predefined roles.

Create a single-project reservation

This section explains how to create single-project reservations.

To consume a reservation, a VM must have properties that exactly match that reservation. To specify the properties of the VMs that you want to reserve, select one of the following sections in this document:

By default, a reservation can be automatically consumed by any VMs with properties that match it. If you want to control reservation consumption, do one or more of the following:

Additionally, you can specify a compact placement policy when creating a reservation. A compact placement policy specifies that VMs should be located as close to each other as possible to reduce network latency.

Specify an instance template

To create a single-project reservation by specifying an instance template, use the Google Cloud console, gcloud CLI, or Compute Engine API.

If you want to specify a compact placement policy in the reservation's instance template, you must use the gcloud CLI or Compute Engine API.

Console

To create a single-project reservation from an instance template, follow these steps:

  1. In the Google Cloud console, go to the Reservations page.

    Go to Reservations

    The Reservations page appears.

  2. Click Create reservation.

    The Create a reservation page appears.

  3. In the Name field, enter a name for your reservation.

  4. Select the Region and Zone where you want to reserve resources.

  5. In the Share type section, click Local (default).

  6. In the Use with VM instance section, select one of the following options:

    • To allow matching VMs to automatically use this reservation, click Use reservation automatically (default).

    • To use this reservation's resources only when creating matching VMs that specifically target this reservation by name, click Select specific reservation.

  7. In the Number of VM instances field, enter the number of VM instances that you want to reserve.

  8. In the Machine configuration section, do the following:

    1. To specify the properties of your VMs from an existing instance template, select Use instance template.

    2. In the Instance template field, select the instance template of your choice.

  9. To create the reservation, click Create.

    Creating the single-project reservation might take some time to complete. This action redirects you to the Reservations page.

gcloud

To create a single-project reservation from an instance template, use the gcloud compute reservations create command with the --source-instance-template flag.

gcloud compute reservations create RESERVATION_NAME \
    --project=PROJECT_ID \
    --source-instance-template=INSTANCE_TEMPLATE_NAME \
    --vm-count=NUMBER_OF_VMS \
    --zone=ZONE

Replace the following:

  • RESERVATION_NAME: the name of the reservation to create.

  • PROJECT_ID: Optional. The project ID of the project that you want to reserve resources for. If the --project flag is omitted, the current project is used.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template. Learn how to create and list instance templates.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • ZONE: the zone in which to reserve resources.

If you want to indicate that only VMs that explicitly target this reservation can use it, add the --require-specific-reservation flag. To learn more about targeted consumption of reservations, see How reservations work.

For example, to create a single-project reservation from an instance template that can only be used when this reservation is specifically targeted, run the following command:

gcloud compute reservations create my-instance-template-reservation \
    --project=example-project \
    --source-instance-template=example-instance-template \
    --vm-count=10 \
    --zone=us-central1-a \
    --require-specific-reservation

API

To create a single-project reservation from an instance template, make a POST request by using the reservations.insert method. In the request body, include the following parameters:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

{
  "name": "RESERVATION_NAME",
  "specificReservation": {
    "count": "NUMBER_OF_VMS",
    "sourceInstanceTemplate": "projects/PROJECT_ID/global/instanceTemplates/INSTANCE_TEMPLATE_NAME"
  }
}

Replace the following:

  • PROJECT_ID: the project ID of the project that you want to reserve resources for.

  • ZONE: the zone in which to reserve resources.

  • RESERVATION_NAME: the name of the reservation to create.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • INSTANCE_TEMPLATE_NAME: the name of an existing instance template. Learn how to create and list instance templates.

If you want to indicate that only VMs that explicitly target this reservation can use it, add the specificReservationRequired field and set it to true. To learn more about targeted consumption of reservations, see How reservations work.

For example, to create a single-project reservation from an instance template that can only be used when this reservation is specifically targeted, make the following POST request:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations

{
  "name": "my-instance-template-reservation",
  "specificReservation": {
    "count": "10",
    "sourceInstanceTemplate": "projects/example-project/global/instanceTemplates/example-instance-template"
  },
  "specificReservationRequired": true
}

After you create a reservation, to see its details and if any instances have consumed the reservation, you can view the details of the reservation.

Specify properties directly

To create a single-project reservation by specifying properties directly, use the Google Cloud console, gcloud CLI, Compute Engine API, or Terraform.

If you want to specify a compact placement policy in your reservation, you must use the gcloud CLI or Compute Engine API.

Console

To create a single-project reservation, follow these steps:

  1. In the Google Cloud console, go to the Reservations page.

    Go to Reservations

    The Reservations page appears.

  2. Click Create reservation.

    The Create a reservation page appears.

  3. In the Name field, enter a name for your reservation.

  4. Select the Region and Zone where you want to reserve resources.

  5. In the Share type section, click Local (default).

  6. In the Use with VM instance section, select one of the following options:

    • To allow matching VMs to automatically use this reservation, click Use reservation automatically (default).

    • To use this reservation's resources only when creating matching VMs that specifically target this reservation by name, click Select specific reservation.

  7. In the Number of VM instances field, enter the number of VM instances that you want to reserve.

  8. In the Machine configuration section, select Specify machine type, and then specify the following:

    1. In the Machine family, Series, and Machine type fields, select a machine family, series, and machine type.

    2. Optional: To specify a minimum CPU platform and/or GPUs, do the following:

      1. To expand the CPU Platform and GPU section, click the expander arrow.

      2. Optional: To specify a minimum CPU platform, in the CPU Platform list, select an option.

      3. Optional: To add GPUs, click Add GPU. Then, in the GPU type and Number of GPUs fields, select the type and number of GPUs for each VM.

    3. Optional: To add local SSDs, do the following:

      1. In the Number of disks field, select the number of local SSDs for each VM.

      2. In the Interface type field, select the interface for the local SSDs.

  9. To create the reservation, click Create.

    Creating the single-project reservation might take some time to complete. This action redirects you to the Reservations page.

gcloud

To create a single-project reservation, use the gcloud compute reservations create command.

gcloud compute reservations create RESERVATION_NAME \
    --machine-type=MACHINE_TYPE \
    --min-cpu-platform MINIMUM_CPU_PLATFORM \
    --vm-count=NUMBER_OF_VMS \
    --accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE \
    --local-ssd=size=375,interface=INTERFACE_1 \
    --local-ssd=size=375,interface=INTERFACE_2 \
    --zone=ZONE \
    --project=PROJECT_ID

Replace the following:

  • RESERVATION_NAME: the name of the reservation to create.

  • MACHINE_TYPE: a predefined or custom machine type.

    • For predefined machine types, use the format MACHINE_FAMILY-standard-CPUS; for example, n2-standard-4.

    • For custom machine types, use the format MACHINE_FAMILY-custom-CPUS-MEMORY; for example n2-custom-4-5120. For a full list of restrictions, read the specifications for custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.

    • CPUS: the number of vCPUs.

    • MEMORY: the total memory for a reserved instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.

  • MINIMUM_CPU_PLATFORM: the minimum CPU to use for each instance.

  • NUMBER_OF_VMS: the number of VMs to reserve.

  • NUMBER_OF_ACCELERATORS: the number of GPUs to add, per instance.

  • ACCELERATOR_TYPE: the type of accelerator.

  • INTERFACE_1 and INTERFACE_2: the type of interface you want the local SSDs for each instance to use. Valid options are: scsi and nvme. Each local SSD is 375 GB. Repeat the --local-ssd flag for each local SSD that you want to add, up to 24 local SSDs per instance.

  • ZONE: the zone in which to reserve resources.

  • PROJECT_ID: Optional. the project ID of the project that you want to reserve resources for. If the --project flag is omitted, the current project is used.

If you want to indicate that only VMs that explicitly target this reservation can use it, or if your instance template specifies a compact placement policy, add the --require-specific-reservation flag. To learn more about targeted consumption of reservations, see How reservations work.

For example, to create a reservation that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves ten N2 machines, each with 4 Intel Haswell (or more recent) vCPUs, 10 GB of memory, 2 V100 GPUs, and a 375 GB local SSD:

gcloud compute reservations create my-reservation \
    --machine-type=n2-standard-4 \
    --vm-count=10 \
    --accelerator=count=2,type=nvidia-tesla-v100 \
    --local-ssd=size=375,interface=scsi \
    --require-specific-reservation \
    --resource-policies=policy=COMPACT_PLACEMENT_POLICY_NAME \
    --zone=us-central1-a

Where COMPACT_PLACEMENT_POLICY_NAME is the name of an existing compact placement policy. Learn how to create and describe compact placement policies.

If you don't want to specify a compact placement policy in a reservation, omit the --resource-policies flag.

API

To create a single-project reservation, make a POST request by using the reservations.insert method. In the request body, include the following parameters:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/reservations

{
  "name": "RESERVATION_NAME",
  "specificReservation": {
    "count": "NUMBER_OF_VMS",
    "instanceProperties": {
      "machineType": "MACHINE_TYPE",
      "minCpuPlatform": "MINIMUM_CPU_PLATFORM",
      "guestAccelerators": [
        {
          "acceleratorCount": "NUMBER_OF_ACCELERATORS",
          "acceleratorType": "ACCELERATOR_TYPE"
        }
      ],
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "INTERFACE_1"
        },
        {
          "diskSizeGb": "375",
          "interface": "INTERFACE_2"
        }
      ]
    }
  }
}

Replace the following:

  • PROJECT_ID: the project ID of the project that you want to reserve resources for.
  • ZONE: the zone in which to reserve resources.
  • RESERVATION_NAME: the name of the reservation to create.
  • NUMBER_OF_VMS: the quantity of VMs to reserve.
  • MACHINE_TYPE: a predefined or custom machine type.

    • For predefined machine types, use the format MACHINE_FAMILY-standard-CPUS; for example, n2-standard-4.
    • For custom machine types, use the format MACHINE_FAMILY-custom-CPUS-MEMORY; for example n2-custom-4-5120. For a full list of restrictions, read the specifications for custom machine types.

    Replace the following:

    • MACHINE_FAMILY: the family of machine types; for example, specify n2 for N2 VMs.
    • CPUS: the number of vCPUs.
    • MEMORY: the total memory for a reserved instance. Memory must be a multiple of 256 MB and must be supplied in MB; for example, to create an N2 VM with 4 vCPUs and 5 GB of memory, which is 5120 MB, use n2-custom-4-5120.
  • MINIMUM_CPU_PLATFORM: the minimum CPU to use for each instance.

  • NUMBER_OF_ACCELERATORS: the number of GPUs to add, per instance.

  • ACCELERATOR_TYPE: the type of accelerator.

  • INTERFACE_1 and INTERFACE_2: the type of interface you want the local SSDs for each instance to use. Valid options are: scsi and nvme. Each local SSD is 375 GB. Repeat the localSsds.diskSizeGb and localSsds.interface fields for each local SSD that you want to add, up to 24 local SSDs per instance.

If you want to indicate that only VMs that explicitly target this reservation can use it, or if your instance template specifies a compact placement policy, add the specificReservationRequired field and set it to true. To learn more about targeted consumption of reservations, see How reservations work.

For example, to create a reservation that can only be used when this reservation is specifically targeted, use a command similar to the following. This example reserves 10 N2 machines, each with 4 Intel Haswell (or more recent) vCPUs, 10 GB of memory, 2 V100 GPUs, and a 375 GB local SSD:

POST https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/reservations

{
  "name": "reservation-1",
  "specificReservation":
  {
    "count": "10",
    "instanceProperties":
    {
      "machineType": "n2-standard-4",
      "minCpuPlatform": "Intel Haswell",
      "guestAccelerators":
      [
        {
          "acceleratorCount": 2,
          "acceleratorType": "nvidia-tesla-v100"
        }
      ],
      "localSsds":
      [
        {
          "diskSizeGb": "375",
          "interface": "SCSI"
        }
      ]
    }
  },
  "resourcePolicies": {
    "Placement" : "projects/my-project/regions/us-central1/resourcePolicies/COMPACT_PLACEMENT_POLICY_NAME"
  },
  "specificReservationRequired": true,
}

Where COMPACT_PLACEMENT_POLICY_NAME is the name of an existing compact placement policy. Learn how to create and describe compact placement policies.

If you don't want to specify a compact placement policy in a reservation, omit the resourcePolicies field.

Terraform

To create a single-project reservation, use the google_compute_reservation Terraform resource. To specify a reservation for a single project, omit the share_settings block (default) or set the share_type field to LOCAL.


resource "google_compute_reservation" "gce_reservation_local" {
  name = "gce-reservation-local"
  zone = "us-central1-c"

  share_settings {
    share_type = "LOCAL"
  }

  specific_reservation {
    count = 1
    instance_properties {
      machine_type = "n2-standard-2"
    }
  }
}

For more information about how to use Terraform, see Using Terraform with Google Cloud.

After you create a reservation, to see its details and if any instances have consumed the reservation, you can view the details of the reservation.

Troubleshooting

Learn how to troubleshoot reservation creation.

What's next