This document explains how to create shared reservations, which are reservations
shared across multiple projects, and manage which projects in your organization
can consume the shared reservations.
A shared reservation can be used by the project that hosts the reservation
(owner project) and by the projects the reservation is shared with (consumer
projects). Use shared reservations if your organization has multiple projects
that need virtual machine (VM) instances with the same properties reserved.
By using shared reservations, you can improve the utilization of your
reservations and reduce the number of reservations that you need to create and
manage. 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 (CUDs). 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 only be used by a single project, see
Create a reservation for a single project
.
Before you begin
Required roles
To get the permissions that you need to create shared reservations,
ask your administrator to grant you the
following IAM roles:
For more information about granting roles, see
Manage access
.
These predefined roles contain
the permissions required to create shared reservations. To see the exact permissions that are
required, expand the
Required permissions
section:
Required permissions
The following permissions are required to create shared reservations:
-
compute.reservations.create
on the project
-
To view organization policies:
orgpolicy.policy.get
on the organization
-
To edit organization policies:
orgpolicy.policy.set
on the organization
-
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
.
Best practices
When creating shared reservations, the following best practices are recommended.
By following them, you can help optimize the manageability and utilization of
shared reservations in your organization.
-
Have the owner project create the shared reservation but not consume it.
- To spread spendings across projects, it's recommended to only have
consumer projects consume a shared reservation. The owner project should
only be used to create the shared reservation.
- The owner project must have sufficient quota for twice the resources
to reserve. For more information, see
Additional requirements for shared reservations
.
-
Minimize the number of projects in your organization that you allow to
create shared reservations. You can control this through the Shared
Reservations Owner Projects
(
compute.sharedReservationsOwnerProjects
) organization policy
constraint.
- You can only list the reservations created by each project. This means
that shared reservations are only listed in the owner project—you
cannot list the reservations shared with each project or list all shared
reservations in each organization—so having only a few owner
projects makes it easier to monitor and manage your shared
reservations.
- Limit the sharing of a shared reservation to a few projects only to
manage the quota of your reserved resources more easily.
- For more information, see
Allow and restrict projects from
creating and modifying shared reservations
.
-
Minimize the number of separate shared reservations with identical VM
properties.
- An organization can have up to 100 shared reservations for each unique
combination of
VM
properties
. As a result, minimizing the number of shared reservations
with identical VM properties that you create helps mitigate this
limit.
- Having fewer shared reservations improves manageability.
-
Only share reservations between projects with the same Cloud Billing
account.
- Limit each shared reservation to only be shared with consumer projects
that have the same Cloud Billing account as the owner project.
This makes it easier for you to see if a reservation was consumed and how
it was billed.
- If you enabled
CUD sharing
and you're eligible to receive CUDs at the
Cloud Billing account level, then, to maximize the CUDs you
receive for your consumed reservations, limit your shared reservations to
that commitment's Cloud Billing account. Doing this lets you
maintain consistent billing across projects that create and consume shared
reservations.
-
For future reservation requests, carefully review the total count of VMs
that you request.
- If you are creating a
future
reservation request
, ensure that you request a
total count
of
VMs that accounts for all of the following:
- All matching reserved VMs that will already exist at the future
date.
- All matching unreserved VMs that will already exist at the future
date.
- Any matching unused on-demand reservations that will already exist
at the future date.
- The increase in usage that you want to reserve at the future
date.
For example, suppose you need 10 additional VMs at the future date and
you'll already have the following resources at the future date:
- 40 matching reserved VMs
- 50 matching unreserved VMs
or
- 40 matching reserved VMs
- 50 matching unused on-demand reservations
Because your existing usage at the future date already adds up to 90
matching VMs and reservations, and you need an additional ten VMs, you
must specify a total count of
100
in your future reservation
request.
For more information, see
Count and provision reserved resources
.
Allow and restrict projects from creating and modifying shared reservations
By default, no projects are allowed to create or modify shared reservations
in an organization. Add projects to the
Shared Reservations Owner Projects
(
compute.sharedReservationsOwnerProjects
) organization policy constraint
to allow them to create and modify shared reservations. For more information
about organization policy constraints, see
Introduction to the Organization Policy Service
.
Use the following steps to view and edit the
Shared Reservations Owner Projects
(
compute.sharedReservationsOwnerProjects
)
organization policy constraint.
View the shared reservations organization policy constraint
To see which projects are allowed to create and modify shared reservations,
use the Google Cloud console or gcloud CLI.
gcloud
To see which projects the
compute.sharedReservationsOwnerProjects
constraint allows to create and modify shared reservations:
Download the policy for your organization as a file named
policy.yaml
,
using the
gcloud resource-manager org-policies describe
command
:
gcloud resource-manager org-policies describe compute.sharedReservationsOwnerProjects --organization=
ORGANIZATION_ID
> policy.yaml
Replace
ORGANIZATION_ID
with the
organization ID
of your organization.
Use a text editor to open the
policy.yaml
file and view the
compute.sharedReservationsOwnerProjects
constraint. The projects
that are allowed to create and modify shared reservations are listed
under its
allowedValues
:
...
constraint: constraints/compute.sharedReservationsOwnerProjects
listPolicy:
allowedValues:
- projects/
PROJECT_NUMBER_1
- projects/
PROJECT_NUMBER_2
- projects/
PROJECT_NUMBER_3
...
where
PROJECT_NUMBER_1
,
PROJECT_NUMBER_2
, and
PROJECT_NUMBER_3
are the
project numbers
of the only projects in your organization that are allowed to
create shared reservations.
Optional: Delete the
policy.yaml
file.
If you are using a Linux or macOS terminal, use the following command:
rm policy.yaml
If you are using a Windows terminal, use the following command:
del policy.yaml
Edit the shared reservations organization policy constraint
To edit which projects are allowed to create and modify shared reservations,
use the Google Cloud console or gcloud CLI.
gcloud
To edit which projects the
compute.sharedReservationsOwnerProjects
constraint allows to create and modify shared reservations,
use one of the following methods:
To
grant permission to a single project
to create and modify
shared reservations, use the
gcloud resource-manager org-policies allow
command
.
You can repeat this command for each project that you want to grant
this permission to.
gcloud resource-manager org-policies allow compute.sharedReservationsOwnerProjects projects/
PROJECT_NUMBER
\
--organization=
ORGANIZATION_ID
Replace the following:
- PROJECT_NUMBER
: the
project number
(not project ID) of a project in your organization that you want to
allow to create and modify shared reservations.
- ORGANIZATION_ID
: the
organization ID
of your organization.
To
grant or revoke the permissions for multiple projects
to
create and modify shared reservations, replace the organization
policy constraint:
To download the policy for your organization as a file named
policy.yaml
,
use the
gcloud resource-manager org-policies describe
command
:
gcloud resource-manager org-policies describe compute.sharedReservationsOwnerProjects --organization=
ORGANIZATION_ID
> policy.yaml
Replace
ORGANIZATION_ID
with the
organization ID
of your organization.
Use a text editor to modify the
policy.yaml
file so that the
compute.sharedReservationsOwnerProjects
constraint lists all of the
projects that you want to be allowed to create and modify shared
reservations under its
allowedValues
.
- For each project that you want to grant the permission to create
and modify shared reservations, add the project in a new line under
allowedValues
.
- For each project that you want to revoke the permission to create
and modify shared reservations, delete the line for that project.
When you are finished, make sure the
policy.yaml
file looks
similar to the following:
...
constraint: constraints/compute.sharedReservationsOwnerProjects
listPolicy:
allowedValues:
- projects/
PROJECT_NUMBER_1
- projects/
PROJECT_NUMBER_2
- projects/
PROJECT_NUMBER_3
...
where
PROJECT_NUMBER_1
,
PROJECT_NUMBER_2
, and
PROJECT_NUMBER_3
are the
project numbers
(not project IDs) of all of the projects in your organization that
you want to be allowed to create and modify shared reservations.
Save the
policy.yaml
file and close the text editor.
To update the policy for your organization with your changes, use the
gcloud resource-manager org-policies set-policy
command
:
gcloud resource-manager org-policies set-policy --organization=
ORGANIZATION_ID
policy.yaml
Replace
ORGANIZATION_ID
with the
organization ID
of your organization.
Optional: Delete the
policy.yaml
file.
If you are using a Linux or macOS terminal, use the following command:
rm policy.yaml
If you are using a Windows terminal, use the following command:
del policy.yaml
You might need to wait a few minutes for the edit to take effect.
Create a shared reservation
This section explains how to create shared reservations. After you create a
shared reservation, it can be modified only by the owner project, but the
resources for a shared reservation can be consumed by the owner project or any
consumer projects.
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 shared 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. However, because templates are
project-specific, you can't use the same template to create VMs that can
consume the reservation outside of the project that created the reservation.
For the projects the reservation is shared with, you must create similar
templates in those projects or create VMs by specifying properties directly.
Specify properties directly
This section explains how to directly define the properties of a shared
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:
Specify an instance template
To create a shared reservation by specifying an instance template, you can use
the Google Cloud console, gcloud CLI, or REST.
Console
To create a shared reservation by specifying an instance template, do the
following:
In the Google Cloud console, go to the
Reservations
page.
Go to Reservations
The
Reservations
page appears.
Click
add_box
Create reservation
.
The
Create a reservation
page appears.
In the
Name
field, enter a name for your reservation.
Select the
Region
and
Zone
where you want to reserve resources.
In the
Share type
section, do the following:
To specify a shared reservation, click
Shared
.
Click
add
Add projects
, and
then select the projects from the current project's organization
that you want to share the reservation with.
In the
Use with VM instance
section, select one of the following
options:
To allow matching VM instances to automatically use this
reservation, click
Use reservation automatically
(default).
To consume this reservation's resources only when creating matching
VMs that specifically target this reservation by name, click
Select specific reservation
.
In the
Number of VM instances
field, enter the number of VMs that
you want to reserve.
In the
Machine configuration
section, do the following:
To specify the properties of your VMs from an existing
instance template
, select
Use instance template
.
In the
Instance template
field, select the instance template of
your choice. If you select a regional instance template, you can
only reserve resources within the region of the instance template.
In the
Auto-delete
section, you can enable the auto-delete option
to let Compute Engine automatically delete the reservation at
a specific date and time. Automatically deleting reservations can be
useful to avoid unnecessary charges when you stop consuming the
reservation.
To create the reservation, click
Create
.
Creating the shared reservation might take some time to complete. This
action redirects you to the
Reservations
page.
gcloud
To create a shared reservation by specifying an instance template, use the
gcloud compute reservations create
command
.
To create a shared reservation by specifying an instance template without
any optional flags, run the following command:
gcloud compute reservations create
RESERVATION_NAME
\
--project=
PROJECT_ID
\
--share-setting=projects \
--share-with=
CONSUMER_PROJECT_IDS
\
--source-instance-template=projects/
PROJECT_ID
/
LOCATION
/instanceTemplates/
INSTANCE_TEMPLATE_NAME
\
--vm-count=
NUMBER_OF_VMS
\
--zone=
ZONE
Replace the following:
RESERVATION_NAME
: the name of the reservation to
create.
PROJECT_ID
: the ID of the project where you want to
reserve resources and where the instance template exists.
CONSUMER_PROJECT_IDS
: a comma-separated list of
IDs of projects
that can consume this reservation—for example,
project-1,project-2
. You can include up to 100 consumer projects.
These projects must be in the same organization as the owner project.
Don't include the owner project. By default, it is already allowed to
consume the reservation.
LOCATION
: the location of the instance template.
Specify one of the following values:
For a global instance template:
global
.
For a regional instance template:
regions/
REGION
.
Replace
REGION
with the region where the instance
template is located. If you specify a regional instance template,
you can only reserve VMs within the region of the instance template.
INSTANCE_TEMPLATE_NAME
: the name of an existing
instance template. If you specify an instance template, you can't
override any of its properties when creating the reservation. Otherwise,
you encounter
errors
.
NUMBER_OF_VMS
: the number of VMs to reserve.
ZONE
: the zone in which to reserve resources.
For example, to create a reservation by specifying a global instance
template in zone
us-central1-a
, share the reservation with projects
project-1
and
project-2
, and reserve ten VMs that each use an N2
predefined machine type with 4 vCPUs, run the following command:
gcloud compute reservations create my-reservation \
--project=example-project \
--share-setting=projects \
--share-with=project-1,project-2 \
--source-instance-template=projects/example-project/global/example-instance-template \
--vm-count=10 \
--zone=us-central1-a
Optionally, you can do one or more of the following:
To specify that only VMs that
specifically target this reservation
can consume it, include the
--require-specific-reservation
flag.
gcloud compute reservations create example-reservation \
--require-specific-reservation
\
...
To enable Compute Engine to
automatically delete the reservation
,
select one of the following methods:
To delete the reservation at a specific date and time, use the
gcloud beta compute reservations create
command
and include the
--delete-at-time
flag.
gcloud beta compute reservations create reservation-example \
--delete-at-time=
DELETE_AT_TIME
\
...
Replace
DELETE_AT_TIME
with a date and time
formatted as an
RFC 3339 timestamp
, which
must be as follows:
YYYY-MM-DD
T
HH:MM:SS
OFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit
year, 2-digit month, and a 2-digit day of the month, separated
by hyphens (
-
).
HH:MM:SS
: a time formatted as a 2-digit hour
using a 24-hour time, 2-digit minutes, and 2-digit seconds,
separated by colons (
:
).
OFFSET
: the time zone formatted as an offset
of
Coordinated Universal Time (UTC)
.
For example, to use the Pacific Standard Time (PST), specify
-08:00
. Alternatively, to use no offset, specify
Z
.
To delete the reservation after a specific duration, use the
gcloud beta compute reservations create
command
and include the
--delete-after-duration
flag.
gcloud beta compute reservations create reservation-example \
--delete-after-duration=
DELETE_AFTER_DURATION
\
...
Replace
DELETE_AFTER_DURATION
with a duration in
days, hours, minutes, or seconds. For example, specify
30m
for 30
minutes, or
1d2h3m4s
for 1 day, 2 hours, 3 minutes, and 4 seconds.
REST
To create a shared reservation by specifying an instance template, make a
POST
request to the
reservations.insert
method
.
For example, to create a shared reservation by specifying an instance
template without any optional fields and share the reservation with two
consumer projects, make the following
POST
request:
POST https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/
ZONE
/reservations
{
"name": "
RESERVATION_NAME
",
"shareSettings": {
"shareType": "SPECIFIC_PROJECTS",
"projectMap": {
"
CONSUMER_PROJECT_ID_1
": {
"projectId": "
CONSUMER_PROJECT_ID_1
"
},
"
CONSUMER_PROJECT_ID_2
": {
"projectId": "
CONSUMER_PROJECT_ID_2
"
}
}
},
"specificReservation": {
"count": "
NUMBER_OF_VMS
",
"sourceInstanceTemplate": "projects/
PROJECT_ID
/
LOCATION
/instanceTemplates/
INSTANCE_TEMPLATE_NAME
"
}
}
Replace the following:
PROJECT_ID
: the ID of the project where you want to
reserve resources and where the instance template exists.
ZONE
: the zone in which to reserve resources.
RESERVATION_NAME
: the name of the reservation to
create.
CONSUMER_PROJECT_ID_1
and
CONSUMER_PROJECT_ID_2
: the
IDs of projects
that can consume this reservation. You can include up to 100 consumer
projects. These projects must be in the same organization as the owner
project. Don't include the owner project. By default, it is already
allowed to consume the reservation.
NUMBER_OF_VMS
: the number of VMs to reserve.
LOCATION
: the location of the instance template.
Specify one of the following values:
For a global instance template:
global
.
For a regional instance template:
regions/
REGION
.
Replace
REGION
with the region where the instance
template is located. If you specify a regional instance template,
you can only reserve VMs within the region of the instance template.
INSTANCE_TEMPLATE_NAME
: the name of an existing
instance template. If you specify an instance template, you can't
override any of its properties when creating the reservation. Otherwise,
you encounter
errors
.
For example, to create a reservation for ten VMs in zone
us-central1-a
by
specifying a global instance template, and share the reservation with
projects
project-1
and
project-2
, make the following
POST
request:
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "my-reservation",
"shareSettings": {
"shareType": "SPECIFIC_PROJECTS",
"projectMap": {
"project-1": {
"projectId": "project-1"
},
"project-2": {
"projectId": "project-2"
}
}
},
"specificReservation": {
"count": "10",
"sourceInstanceTemplate": "projects/example-project/global/instanceTemplates/example-instance-template"
}
}
Optionally, you can do one or more of the following:
To specify that only VMs that
specifically target this reservation
can consume it, include the
specificReservationRequired
field in the
request body and set it to
true
.
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"specificReservationRequired": true
,
...
}
To enable Compute Engine to
automatically delete the reservation
,
select one of the following methods:
To delete the reservation at a specific date and time, make a
POST
request to the
beta.reservations.insert
method
.
In the request body, include the
deleteAtTime
field.
POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"deleteAtTime": "
DELETE_AT_TIME
"
,
...
}
Replace
DELETE_AT_TIME
with a date and time formatted
as an
RFC 3339 timestamp
, which
must be as follows:
YYYY-MM-DD
T
HH:MM:SS
OFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit
year, 2-digit month, and a 2-digit day of the month, separated
by hyphens (
-
).
HH:MM:SS
: a time formatted as a 2-digit hour
using a 24-hour time, 2-digit minutes, and 2-digit seconds,
separated by colons (
:
).
OFFSET
: the time zone formatted as an offset
of
Coordinated Universal Time (UTC)
.
For example, to use the Pacific Standard Time (PST), specify
-08:00
. Alternatively, to use no offset, specify
Z
.
To delete the reservation after a specific duration, make a
POST
request to the
beta.reservations.insert
method
.
In the request body, include the
deleteAfterDuration
field.
POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"deleteAfterDuration": {
"seconds": "
DELETE_AFTER_DURATION
"
}
,
...
}
Replace
DELETE_AFTER_DURATION
with a duration in
seconds. For example, specify
86400
for 86,400 seconds (1 day).
Specify VM properties directly
To create a shared reservation by specifying properties directly, use the
Google Cloud console, gcloud CLI, Terraform, or REST.
Console
To create a shared reservation, do the following:
In the Google Cloud console, go to the
Reservations
page.
Go to Reservations
The
Reservations
page appears.
Click
add_box
Create reservation
.
The
Create a reservation
page appears.
In the
Name
field, enter a name for your reservation.
Select the
Region
and
Zone
where you want to reserve resources.
In the
Share type
section, do the following:
To specify a shared reservation, click
Shared
.
Click
add
Add projects
, and
then select the projects from the current project's organization
that you want to share the reservation with.
In the
Use with VM instance
section, select one of the following
options:
To allow matching VMs to automatically consume this reservation,
click
Use reservation automatically
(default).
To consume this reservation's resources only when creating matching
VMs that specifically target this reservation by name, click
Select specific reservation
.
In the
Number of VM instances
field, enter the number of VMs that
you want to reserve.
In the
Machine configuration
section, select
Specify machine type
, and then specify the following:
In the
Machine family
,
Series
, and
Machine type
fields, select a machine family, series, and machine type.
Optional: To specify a minimum CPU platform and/or GPUs, do the
following:
To expand the
CPU Platform and GPU
section, click the
expand_more
expander
arrow.
Optional: To specify a minimum CPU platform, in the
CPU Plaform
list, select an option.
Optional: To add GPUs, click
add
Add GPU
. Then, in
the
GPU type
and
Number of GPUs
fields, select the
type and number of GPUs for each VM.
Optional: To add Local SSDs, do the following:
In the
Number of disks
field, select the number of Local
SSDs for each VM.
In the
Interface type
field, select the interface for the
Local SSDs.
In the
Auto-delete
section, you can enable the auto-delete option
to let Compute Engine automatically delete the reservation at
a specific date and time. Automatically deleting reservations can be
useful to avoid unnecessary charges when you stop consuming the
reservation.
To create the reservation, click
Create
.
Creating the shared reservation might take some time to complete. This
action redirects you to the
Reservations
page.
gcloud
To create a shared reservation, use the
gcloud compute reservations create
command
.
To create a shared reservation without any optional flags, run the following
command:
gcloud compute reservations create
RESERVATION_NAME
\
--machine-type=
MACHINE_TYPE
\
--project=
PROJECT_ID
\
--share-setting=projects \
--share-with=
CONSUMER_PROJECT_IDS
\
--vm-count=
NUMBER_OF_VMS
\
--zone=
ZONE
Replace the following:
RESERVATION_NAME
: the name of the reservation to
create.
MACHINE_TYPE
: a
machine type
to use for each VM.
Specify one of the following values:
For a predefined machine type:
MACHINE_FAMILY
-standard-
CPUS
.
For a custom machine type:
MACHINE_FAMILY
-custom-
CPUS
-
MEMORY
.
Before specifying a custom machine type, review the
limitations
for VMs with custom machine types.
Replace the following:
MACHINE_FAMILY
: the machine family.
CPUS
: the number of vCPUs.
MEMORY
: the total memory for a reserved VM.
Memory must be a multiple of 256 MB and must be supplied in MB.
For example, to specify an N2 custom machine type with 4 vCPUs and
5 GB of memory, which is 5,120 MB, specify
n2-custom-4-5120
.
PROJECT_ID
: the ID of the project where you want to
reserve resources.
CONSUMER_PROJECT_IDS
: a comma-separated list of
IDs of projects
that can consume this reservation—for example,
project-1,project-2
. You can include up to 100 consumer projects.
These projects must be in the same organization as the owner project.
Don't include the owner project. By default, it is already allowed to
consume the reservation.
NUMBER_OF_VMS
: the number of VMs to reserve.
ZONE
: the zone in which to reserve resources.
For example, to create a reservation for ten VMs in zone
us-central1-a
by
specifying a global instance template, and share the reservation with
projects
project-1
and
project-2
, run the following command:
gcloud compute reservations create my-reservation \
--machine-type=n2-standard-4 \
--project=example-project \
--share-setting=projects \
--share-with=project-1,project-2 \
--vm-count=10 \
--zone=us-central1-a
Optionally, you can do one or more of the following:
To add
graphics processing units (GPUs)
to each
reserved VM, include the
--accelerator
flag.
gcloud compute reservations create my-reservation \
--accelerator=count=
NUMBER_OF_ACCELERATORS
,type=
ACCELERATOR_TYPE
...
Replace the following:
Make sure that the machine type you specify in the reservation supports
the types of GPUs you specify and that
the GPU is available in the zone
where you want to reserve resources. Otherwise, creating the reservation
fails.
To add one or more
Local SSDs
to each
reserved VM, include one or more
--local-ssd
flags. You can specify up
to 24 Local SSDs. Each Local SSD is 375 GB.
For example, to specify two Local SSDs when creating a reservation,
include two
--local-ssd
flags.
gcloud compute reservations create my-reservation \
--local-ssd=size=375,interface=
INTERFACE_1
\
--local-ssd=size=375,interface=
INTERFACE_2
\
...
Replace
INTERFACE_1
and
INTERFACE_2
with the type of interface you want each
Local SSD to use. Specify one of the following values:
Make sure that the machine type you specify for the reserved VMs
supports the chosen disk interfaces. Otherwise, creating the reservation
fails. For more information, see how to
choose a disk interface
.
To have the reserved VMs use a specific
minimum CPU platform
instead of the zone's default CPU platform, include the
--min-cpu-platform
flag.
gcloud compute reservations create my-reservation \
--min-cpu-platform="
MIN_CPU_PLATFORM
"
\
...
Replace
MIN_CPU_PLATFORM
with a minimum CPU platform.
To make sure that a CPU platform is available in the zone where you're
reserving resources,
view the available CPU platforms by zone
.
To specify that only VMs that
specifically target this reservation
can consume it, include the
--require-specific-reservation
flag.
gcloud compute reservations create example-reservation \
--require-specific-reservation
\
...
To enable Compute Engine to
automatically delete the reservation
,
select one of the following methods:
To delete the reservation at a specific date and time, use the
gcloud beta compute reservations create
command
and include the
--delete-at-time
flag.
gcloud beta compute reservations create reservation-example \
--delete-at-time=
DELETE_AT_TIME
\
...
Replace
DELETE_AT_TIME
with a date and time
formatted as an
RFC 3339 timestamp
, which
must be as follows:
YYYY-MM-DD
T
HH:MM:SS
OFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit
year, 2-digit month, and a 2-digit day of the month, separated
by hyphens (
-
).
HH:MM:SS
: a time formatted as a 2-digit hour
using a 24-hour time, 2-digit minutes, and 2-digit seconds,
separated by colons (
:
).
OFFSET
: the time zone formatted as an offset
of
Coordinated Universal Time (UTC)
.
For example, to use the Pacific Standard Time (PST), specify
-08:00
. Alternatively, to use no offset, specify
Z
.
To delete the reservation after a specific duration, use the
gcloud beta compute reservations create
command
and include the
--delete-after-duration
flag.
gcloud beta compute reservations create reservation-example \
--delete-after-duration=
DELETE_AFTER_DURATION
\
...
Replace
DELETE_AFTER_DURATION
with a duration in
days, hours, minutes, or seconds. For example, specify
30m
for 30
minutes, or
1d2h3m4s
for 1 day, 2 hours, 3 minutes, and 4 seconds.
REST
To create a shared reservation, make a
POST
request to the
reservations.insert
method
.
For example, to create a shared reservation without any optional fields and
share the reservation with two consumer projects, make the following
POST
request:
POST https://compute.googleapis.com/compute/v1/projects/
PROJECT_ID
/zones/
ZONE
/reservations
{
"name": "
RESERVATION_NAME
",
"shareSettings": {
"shareType": "SPECIFIC_PROJECTS",
"projectMap": {
"
CONSUMER_PROJECT_ID_1
": {
"projectId": "
CONSUMER_PROJECT_ID_1
"
},
"
CONSUMER_PROJECT_ID_2
": {
"projectId": "
CONSUMER_PROJECT_ID_2
"
}
}
},
"specificReservation": {
"count": "
NUMBER_OF_VMS
",
"instanceProperties": {
"machineType": "
MACHINE_TYPE
",
}
}
}
Replace the following:
PROJECT_ID
: the ID of the project where you want to
reserve resources.
ZONE
: the zone in which to reserve resources.
RESERVATION_NAME
: the name of the reservation to
create.
CONSUMER_PROJECT_ID_1
and
CONSUMER_PROJECT_ID_2
: the
IDs of projects
that can consume this reservation. You can include up to 100 consumer
projects. These projects must be in the same organization as the owner
project. Don't include the owner project. By default, it is already
allowed to consume the reservation.
NUMBER_OF_VMS
: the number of VMs to reserve.
MACHINE_TYPE
: a
machine type
to use for each VM.
Specify one of the following values:
For a predefined machine type:
MACHINE_FAMILY
-standard-
CPUS
.
For a custom machine type:
MACHINE_FAMILY
-custom-
CPUS
-
MEMORY
.
Before specifying a custom machine type, review the
limitations
for VMs with custom machine types.
Replace the following:
MACHINE_FAMILY
: the machine family.
CPUS
: the number of vCPUs.
MEMORY
: the total memory for a reserved VM.
Memory must be a multiple of 256 MB and must be supplied in MB.
For example, to specify an N2 custom machine type with 4 vCPUs and
5 GB of memory, which is 5,120 MB, specify
n2-custom-4-5120
.
For example, to create a reservation by specifying a global instance
template in zone
us-central1-a
, share the reservation with projects
project-1
and
project-2
, and reserve ten VMs that each use an N2
predefined machine type with 4 vCPUs, make the following
POST
request:
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "my-reservation",
"shareSettings": {
"shareType": "SPECIFIC_PROJECTS",
"projectMap": {
"project-1": {
"projectId": "project-1"
},
"project-2": {
"projectId": "project-2"
}
}
},
"specificReservation": {
"count": "10",
"instanceProperties": {
"machineType": "n2-standard-4",
}
}
}
Optionally, you can do one or more of the following:
To add
graphics processing units (GPUs)
to each
reserved VM, include the
guestAccelerators
field in the request body.
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"specificReservation": {
"instanceProperties": {
"guestAccelerators": [
{
"acceleratorCount":
NUMBER_OF_ACCELERATORS
,
"acceleratorType": "
ACCELERATOR_TYPE
"
}
]
,
...
},
...
}
}
Replace the following:
Make sure that the machine type you specify in the reservation supports
the types of GPUs you specify and that
the GPU is available in the zone
where you want to reserve resources. Otherwise, creating the reservation
fails.
To add one or more
Local SSDs
to each
reserved VM, include the
localSsds
field in the request body. You can
specify up to 24 Local SSDs. Each Local SSD is 375 GB.
For example, to specify two Local SSDs when creating a reservation,
specify the following:
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"specificReservation": {
"instanceProperties": {
"localSsds": [
{
"diskSizeGb": "375",
"interface": "
INTERFACE_1
"
},
{
"diskSizeGb": "375",
"interface": "
INTERFACE_2
"
}
]
,
...
},
...
}
}
Replace
INTERFACE_1
and
INTERFACE_2
with the type of interface you want each
Local SSD to use. Specify one of the following values:
Make sure that the machine type you specify for the reserved VMs
supports the chosen disk interfaces. Otherwise, creating the reservation
fails. For more information, see how to
choose a disk interface
.
To have the reserved VMs use a specific
minimum CPU platform
instead of the zone's default CPU platform, include the
minCpuPlatform
field in the request body.
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"specificReservation": {
"instanceProperties": {
"minCpuPlatform": "
MIN_CPU_PLATFORM
",
...
},
...
}
}
Replace
MIN_CPU_PLATFORM
with a minimum CPU platform.
To make sure that a CPU platform is available in the zone where you're
reserving resources,
view the available CPU platforms by zone
.
To specify that only VMs that
specifically target this reservation
can consume it, include the
specificReservationRequired
field in the
request body and set it to
true
.
POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"specificReservationRequired": true
,
...
}
To enable Compute Engine to
automatically delete the reservation
,
select one of the following methods:
To delete the reservation at a specific date and time, make a
POST
request to the
beta.reservations.insert
method
.
In the request body, include the
deleteAtTime
field.
POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"deleteAtTime": "
DELETE_AT_TIME
"
,
...
}
Replace
DELETE_AT_TIME
with a date and time
formatted as an
RFC 3339 timestamp
, which
must be as follows:
YYYY-MM-DD
T
HH:MM:SS
OFFSET
Replace the following:
YYYY-MM-DD
: a date formatted as a 4-digit
year, 2-digit month, and a 2-digit day of the month, separated
by hyphens (
-
).
HH:MM:SS
: a time formatted as a 2-digit hour
using a 24-hour time, 2-digit minutes, and 2-digit seconds,
separated by colons (
:
).
OFFSET
: the time zone formatted as an offset
of
Coordinated Universal Time (UTC)
.
For example, to use the Pacific Standard Time (PST), specify
-08:00
. Alternatively, to use no offset, specify
Z
.
To delete the reservation after a specific duration, make a
POST
request to the
beta.reservations.insert
method
.
In the request body, include the
deleteAfterDuration
field.
POST https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/reservations
{
"name": "example-reservation",
"deleteAfterDuration": {
"seconds": "
DELETE_AFTER_DURATION
"
}
,
...
}
Replace
DELETE_AFTER_DURATION
with a duration in
seconds. For example, specify
86400
for 86,400 seconds (1 day).
Troubleshooting
Learn how to
troubleshoot reservation creation
.
What's next