Reserve capacity from actual or forecasted usage

This document explains how to generate Google Cloud CLI commands to create future reservation requests based on the actual or forecasted usage of the virtual machine (VM) instances in your project or organization.

Future reservations are useful to secure capacity up to 1 year in advance for forecasted spikes. When using Capacity Planner, you can generate gcloud CLI commands to create future reservation requests that specify a total count of VMs based on the actual or forecasted usage of selected machine types. If you create future reservation requests and Google Cloud approves them, Compute Engine automatically creates (auto-creates) reservations with the reserved capacity on the date you specified. Then, you can start consuming the auto-created reservations by creating VMs with matching properties.

Before you begin

Install the Google Cloud CLI.
To initialize the gcloud CLI, run the following command:
```
gcloud init
```
Note: You can run the gcloud CLI in the Google Cloud console without installing the Google Cloud CLI. To run the gcloud CLI in the Google Cloud console, use Cloud Shell.
If you can't access Capacity Planner in the Google Cloud console, your project or organization might not be eligible to access and use Capacity Planner. To enable your project or organization to use Capacity Planner, contact your Technical Account Manager or the Sales team.
If you haven't already:

Review how future reservation requests work.
Review how to create single-project or shared future reservation requests.

Required roles

To get the permissions that you need to generate gcloud CLI commands to create future reservation requests, ask your administrator to grant you the following IAM roles:

To access and view Capacity Planner: Capacity Planner Viewer (roles/capacityplanner.viewer) on the project or organization
To create future reservation requests: Compute Admin (roles/compute.admin) on the owner project

For more information about granting roles, see Manage access.

These predefined roles contain the permissions required to generate gcloud CLI commands to create future reservation requests. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to generate gcloud CLI commands to create future reservation requests:

To create future reservation requests: compute.futureReservations.create on the owner project
To let Compute Engine auto-create reservations: compute.reservations.create on the owner project
To view the forecasted usage of your VMs: capacityplanner.forecasts.list on the project or organization
To view the actual usage of your VMs: capacityplanner.usageHistories.list on the project or organization
To summarize the actual usage of your VMs: capacityplanner.usageHistories.summarize on the project or organization

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

Limitations

The following limitations apply when you generate gcloud CLI commands to create future reservation requests:

You can only generate gcloud CLI commands to create future reservation requests by specifying properties directly.
You can only generate gcloud CLI commands with the following reservation periods:
- The time for the start time and end time of a reservation period can only specify a time offset from Coordinated Universal Time (UTC) of +00:00.
- The end time of a reservation period can only be up to 6 months from the current date. If you need a longer reservation period, you must manually edit the generated gcloud CLI commands.

Generate future reservation requests

You can generate a gcloud CLI command for each machine type that you select in the Usage and forecast by machine type table. If you select more than one machine type, all the generated gcloud CLI commands have matching values for the following future reservation properties:

Auto-delete option
Name prefix
Reservation period
Share type^*

^* If you generate gcloud CLI commands to create shared future reservations requests, all the commands specify matching consumer projects.

By default, every generated gcloud CLI command specifies a DRAFT planning status. After you generate the gcloud CLI commands, you can edit one or more of their fields according to your needs. For example, you can change the machine type and zone to increase the chances that Google Cloud approves your future reservation request.

The following sections explain how to generate the gcloud CLI commands to create future reservation requests, edit the generated commands, and then run them in the gcloud CLI.

Generate gcloud CLI commands

To generate gcloud CLI commands to create future reservation requests using the Google Cloud console, do the following:

In the Google Cloud console navigation menu, go to Capacity Planner.

Go to Capacity Planner
Optional: To change project or organization, in the project picker at the top of the page, select a project or organization.
Click the Virtual machine tab (default).
In the Machine family list, select one of the following options:
- To select a single machine family only, select one of the available machine families.
- To select all machine families, select All.
In the Location list, select a region or zone.
In the Usage percentile list, select a VM usage data percentile.
In the Forecast prediction interval list, select a prediction interval.
In the Usage and forecast by Machine Types section, do the following:
1. In the Usage month list, select the month in which you want the reservation period of your future reservation requests to start.
2. In the Forecast start date list, select the start date of your forecast. By default, the start date is set to the first day of the next calendar month.
  
  The start time of the future reservation requests' reservation period is set to the forecast start date.
3. In the Forecast end date list, select the end date of your forecast. By default, the end date is set to the last day of the month of the next calendar month.
  
  The end time of the future reservation requests' reservation period is set to the forecast end date.
4. In the table, select the machine types you want to specify in the future reservation requests. If you select more than one machine type, Capacity Planner generates separate gcloud CLI commands for every machine type that you select.
Click Generate future-reservation gcloud commands.

The Generate gcloud commands for future reservations pane appears.
In the Name field, enter a name for the future reservation requests that you want to create. By default, the value is set to ID-DATE-TIME and consists of the following elements:
- ID is the ID of the project or organization. To view your organization ID, see Getting your organization resource ID in the Resource Manager documentation.
- DATE is the current date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month.
- TIME is the current time formatted as a 2-digit hour that uses a 24-hour time and a 2-digit minutes in UTC+00:00.
If you create more than one future reservation request, the pregenerated names are NAME-1, NAME-2, and so on, up to the number of future reservation requests that you're creating.
In the Name prefix field, enter a name prefix for the future reservation requests.
In the Description field, enter a description for the future reservation requests. If you omit this field, the value is set to "*Auto-generated from Capacity Planner*". Otherwise, the *Auto-generated from Capacity Planner* suffix is attached at the end of your description.
In the Start time field, enter a time with no UTC offset for the start time of the reservation period. By default, the value is set to midnight UTC (00:00).
In the End time field, enter a time with no UTC offset for the end time of the reservation period. By default, the value is set to midnight UTC (00:00).
In the Total count section, do the following:
1. In the Usage list, select one of the following options:
  - For upper bound usage, select Upper bound - P75 forecast.
  - For median usage, select Median - P50 forecast.
  - For lower bound usage, select Lower bound - P25 forecast.
  - For the average NTH percentile usage, select Average NTH percentile usage.
    
    Where NTH is the 50th, 75th, or 99th percentile usage you selected in the previous steps.
2. In the Operator list, select one of the following comparison operators:
  - To increase the selected usage value by the percentage in the next field, select (+) Increase (default).
  - To decrease the selected usage value by the percentage in the next field, select (-) Decrease.
3. In the Value percentage field, enter a percentage to increase or decrease the selected usage and, consequently, the total count of VMs specified in the generated gcloud CLI commands.
In the Auto-delete reservations section, do one of the following:
- To automatically delete the auto-created reservations after the end time of the reservation period, follow these steps:
  
  Caution: If you enable the auto-delete option, all the auto-created reservations are deleted at the specified deletion time regardless if they're fully consumed or not.
  1. Select Yes.
  2. In the Time field, specify a date and time time with no UTC offset when Compute Engine can automatically delete the auto-created reservations.
- Otherwise, select No (default).
Click Continue.
In the Additional configurations for future reservations section, do the following:
1. Optional: To modify the total count of VMs specified in the generated gcloud CLI commands, in the Total VM count field, enter the new total count.
2. In the Owning project field, specify the owner project for the future reservation requests. If you're generating gcloud CLI commands when viewing Capacity Planner in a project, you can only set your current project as the owner project.
  
  Note: If you want to create shared future reservation requests, Google Cloud recommends to select an owner project that won't consume the reserved capacity. For more information, see Best practices in the Compute Engine reservations documentation.
3. To specify the share type of your future reservation requests, do one of the following:
  - To create shared future reservation requests, do the following:
    1. In the Share type field, select Project.
    2. In the Share with field, select the projects you want to share the future reservation requests with. By default, Capacity Planner shows the projects with the highest historical usage for the selected machine types. To add other projects within your organization, do the following:
      1. Click Add other projects.
      2. In the Add other projects dialog, enter a comma-separated list of project IDs, and then click Add to list.
  - To create single-project future reservation requests, in the Share type field, select Local (default).
4. To specify a different minimum CPU platform and local SSD interface, in the Min CPU Platform and Local SSD interface field, select one of the available options. By default, the option with highest percentage distribution usage in the past 30 days is selected.
  
  Note: If the selected machine types have used only one type of minimum CPU platform or local SSD interface in the past 30 days, those types are automatically selected and you can't select other options.

Click Generate.

The output is similar to the following example:

gcloud beta compute future-reservations create example-fr-1 \
    --total-count=10 \
    --machine-type=n1-standard-1 \
    --min-cpu-platform='' \
    --start-time=2023-12-01T00:00:00.000Z \
    --end-time=2023-12-30T00:00:00.000Z \
    --name-prefix=fr \
    --description="*Auto-generated from Capacity Planner*" \
    --planning-status=DRAFT \
    --zone=us-central1-c \
    --share-setting=local \
    --no-auto-delete-auto-created-reservations

gcloud beta compute future-reservations create example-fr-2 \
    --total-count=3 \
    --machine-type=n1-standard-1 \
    --min-cpu-platform='' \
    --start-time=2023-12-01T00:00:00.000Z \
    --end-time=2023-12-30T00:00:00.000Z \
    --name-prefix=fr \
    --description="*Auto-generated from Capacity Planner*" \
    --planning-status=DRAFT \
    --zone=us-central1-f \
    --share-setting=local \
    --no-auto-delete-auto-created-reservations

Optional: To edit one or more of the properties you specified in the previous steps and that apply to all the generated gcloud CLI commands, click Edit, and then repeat one or more of the previous steps to edit your preferred properties.

Edit the generated gcloud CLI commands

To edit the generated gcloud CLI commands using the Google Cloud console, do the following:

In the Future Reservation details section, edit one or more flags in the generated gcloud CLI commands to create future reservation requests. For a full list of flags that you can specify, see how to create a single-project or shared future reservation request.
Caution: Before creating a future reservation request, make sure that its reservation period specifies the following:
- A recommended value for the start time. Otherwise, you might lack the time to optionally cancel, delete, or modify the future reservation request after Google Cloud approves it.
- A recommended value for the duration. Otherwise, Google Cloud might be less likely to approve your future reservation request.
Additionally, make sure that your reservation period doesn't overlap with the reservation period of an existing future reservation request with matching VM properties and zone, and that was created in or is shared with your current project. Otherwise, creating the future reservation request fails.
When you've finalized your changes, click Copy, and then store the gcloud CLI commands somewhere. You need them in the following section.
Click Close.

Create future reservation requests

To create future reservation requests using the gcloud CLI, do the following:

Run the commands you generated in the previous sections.

The output is similar to the following:

Created [https://www.googleapis.com/compute/beta/projects/example-project/zones/us-central1-c/futureReservations/example-fr-1].
Created [https://www.googleapis.com/compute/beta/projects/example-project/zones/us-central1-f/futureReservations/example-fr-2].

If you created a future reservation request using the --planning-status=DRAFT flag in the previous step (default), you must submit the draft future reservation request to Google Cloud for approval by doing one of the following:
- If you want to change one or more properties before submitting the request, then modify the draft future reservation request.
- Otherwise, submit the draft future reservation request for review.

What's next

Learn how to modify, cancel, or delete future reservation requests.
Learn how to consume the automatically created reservations that Compute Engine provisions for a future reservation.