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.

Note: After you create a reservation, you are charged for the reserved resources, even if they are not used, until you delete the reservation. If you delete a reservation but don't delete the instances that were using the reserved resources, the resources still incur charges. For more information, see Billing.

Before you begin

• If you want to use the command-line examples in this guide, do the following:
  1. Install or update to the latest version of the Google Cloud CLI.
  2. Set a default region and zone.
• If you want to use the API examples in this guide, set up API access.
• Review the requirements and restrictions for reservations.

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:

• Recommended: Specify an instance template

  This section explains how to use an instance template to define the properties of a reservation. By using an instance template, you can define the properties of a reservation and the VMs that can consume the reservation in the same place.

• Specify properties directly

  This section explains how to directly define the properties of a reservation. This method requires you to manually ensure that the properties of your VMs and reservations match exactly—any mismatched properties prevent consumption.

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:

• Create a reservation that can only be consumed by VMs that specifically target it, as explained in the following sections in this document. Then, configure VMs to consume that specific reservation.

• Configure VMs that can't consume any reservations.

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.

Caution: Make sure of the following:

• Create your reservation in the same region and zone as the resources within the instance template. Any regional or zonal resources that are specified in an instance template—such as a machine type or a disk—restrict the use of the template to the locations where those resources exist. For example, if your instance template specifies an existing disk in the us-central1-a zone, then you must create your reservation in the same zone. Otherwise, creating the reservation or the VMs that can consume the reservation fails.

  To check if an existing template specifies any resources that bind the template to a specific region or zone, describe the instance template and look for references to regional or zonal resources inside of it.

• If the instance template specifies a compact placement policy, make sure that the template also specifies a supported machine type for compact placement policies. Attempting to create a reservation by specifying an instance template with an unsupported machine type causes errors.

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.

  Note: If you specify an instance template using the --source-instance-template, you must omit any flag that specifies VM properties. Attempting to override an instance template's properties causes the command to fail.

  Additionally, if an instance template specifies a compact placement policy, make sure of the following:

  • You must omit the --resource-policies flag.
  • You must specify the --require-specific-reservation flag. This indicates that only VMs that that explicitly target this reservation can consume it.

• 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.

  Note: If you specify an instance template in the request body, you can't specify VM properties using the instanceProperties field. Attempting to override an instance template's properties causes the POST request to fail.

  Additionally, if an instance template specifies a compact placement policy, make sure of the following:

  • You must omit the resourcePolicies field.
  • You must specify the "specificReservationRequired": true field. This indicates that only VMs that that explicitly target this reservation can consume it.

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.

Note: If you specify a compact placement policy when creating a reservation, you must specify a supported machine type for compact placement policies. Attempting to specify an unsupported machine type causes errors.

For more information about reservations that specify compact placement policies, see their requirements and restrictions.

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.

Note: If you specify a compact placement policy when creating a reservation, you must specify a supported machine type for compact placement policies. Attempting to specify an unsupported machine type causes errors.

For more information about reservations that specify compact placement policies, see their requirements and restrictions.

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.

compute/reservation/main.tf

View on GitHub Feedback

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

• Learn how to view your reservations
• Learn how to attach reservations to commitments.
• Learn how to consume reservations.