Reserve capacity from actual or forecasted usage

Private preview

This product is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products are available "as is" and might have limited support. For more information, see the launch stage descriptions.

This document explains how to generate Google Cloud CLI commands to create future reservation requests based on the actual or forecasted usage of the following Compute Engine resources in your Google Cloud project, folder, or organization:

• Virtual machine (VM) instances

• GPUs

Future reservations are useful to secure capacity up to one 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 or GPU types. If you create future reservation requests and Google Cloud approves them, then Compute Engine automatically reserves the requested resources on the date you specified. For more information, see How Compute Engine provisions reserved resources.

Before you begin

1. Install the Google Cloud CLI.

2. 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.
3. If you can't access Capacity Planner in the Google Cloud console, then your organization might not be eligible to access and use Capacity Planner. To request access, contact your Technical Account Manager (TAM) or the Sales team.
4. If you haven't already, then see the following:
• How future reservation requests work.
• 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, folder, 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 to projects, folders, and organizations.

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 or GPUs: capacityplanner.forecasts.list on the project, folder, or organization
• To view the actual usage of your VMs or GPUs: capacityplanner.usageHistories.list on the project, folder, or organization
• To summarize the actual usage of your VMs or GPUs: capacityplanner.usageHistories.summarize on the project, folder, or organization

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

Limitations

When generating gcloud CLI commands to create future reservation requests, the following limitations apply:

• 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, then 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, then all the generated gcloud CLI commands have matching values for the following future reservation properties:

• Auto-delete option

• Name prefix

• Reservation period

• Share type

  Note: If you generate gcloud CLI commands to create shared future reservations requests, then all the commands also specify matching consumer projects.

By default, every generated gcloud CLI command specifies a draft planning status. You can optionally edit one or more fields in the generated commands based on your needs. For example, you can change the machine type and zone to increase the likelihood that Google Cloud approves your future reservation requests.

The following sections explain how to do the following:

1. Select the Compute Engine resources to create future reservation requests for

2. Generate the gcloud CLI commands to create future reservation requests

3. Edit the generated gcloud CLI commands

4. Create future reservation requests

Select the Compute Engine resources

To select the gcloud CLI resources to create future reservation requests for, do the following:

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

   Go to Capacity planner

2. Optional: To change project, folder, or organization, in the project picker at the top of the page, select a project, folder, or organization.

3. Select one of the following Compute Engine resources:

   • To create future reservation requests based on your VMs' usage, do the following:

     1. Click the Virtual machine tab, if it's not already selected.

     2. For Machine family, 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.

          

   • To create future reservation requests based on your GPUs' usage, do the following:

     1. Click the GPU tab.

     2. For GPU type, select one of the following options:

        • To select a single GPU type only, select one of the available GPU types.

        • To select all GPU types, select All.

          

4. For Location, select a region or zone.

5. For Usage percentile, select a VM usage data percentile.

6. For Forecast prediction interval, select a prediction interval.

7. In the Usage and forecast by machine types table, do the following:

   1. For Usage month, select the month in which you want the reservation period of your future reservation requests to start.

   2. For Forecast start date, 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. For Forecast end date, 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, then Capacity Planner generates separate gcloud CLI commands for every machine type that you select.

8. Click Generate future-reservation gcloud commands.

Generate gcloud CLI commands

In the Generate gcloud commands for future reservations pane, you can generate gcloud CLI commands to create future reservation requests by doing the following:

1. For Name, enter a name for the future reservation requests that you want to create. By default, the value is set to ID-DATE-TIME, which consists of the following:

   • ID: the ID of your project, folder, or organization.

   • DATE: the current date formatted as a 4-digit year, 2-digit month, and a 2-digit day of the month.

   • TIME: 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, then the pre-generated names are NAME-1, NAME-2, and so on, up to the number of future reservation requests that you're creating.

2. For Name prefix, enter a name prefix for the future reservation requests.

3. For Description, enter a description for the future reservation requests. If you omit this field, then 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.

4. For Start time, 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).

5. For End time, 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).

6. In the Total count section, do the following:

   1. For Usage, 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. For Operator, 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. For Value percentage, enter a percentage to increase or decrease the selected usage and, consequently, the total count of VMs specified in the generated gcloud CLI commands.

7. 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, then all the auto-created reservations are deleted at the specified deletion time regardless if they're fully consumed or not.

     1. Select Yes.

     2. For Time, specify a date and time time with no UTC offset when Compute Engine can automatically delete the auto-created reservations.

   • Otherwise, select No (default).

8. Click Continue.

9. 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, for Total VM count, enter the new total count.

   2. For Owner project, specify the owner project for the future reservation requests. If you're generating gcloud CLI commands when viewing Capacity Planner in a project, then you can only set your current project as the owner project.

      Note: If you want to create shared future reservation requests, then Google Cloud recommends selecting an owner project that won't consume the reserved capacity. For more information, see the best practices for shared reservations.

   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. For Share type, select Project.

        2. For Share with, 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, for Share type, select Local (default).

   4. To specify a different minimum CPU platform and local SSD interface, for Min CPU Platform and Local SSD interface, 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, then those types are automatically selected and you can't select other options.

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

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

After generating gcloud CLI commands in the previous section, you can optionally edit the generated commands to ensure that the future reservation requests' reservation periods specify the following:

• A recommended value for the start time. Otherwise, you might lack the time to optionally cancel, delete, or modify the future reservation requests after Google Cloud approves them.

• A recommended value for the duration. Otherwise, Google Cloud might be less likely to approve your future reservation requests.

Additionally, make sure that your reservation periods don'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 requests fails. For more information, see Overlapping reservation periods.

To edit the generated gcloud CLI commands, do the following:

1. In the Future Reservation details section, edit one or more flags in the generated gcloud CLI commands according to your needs. For a full list of flags that you can specify, see how to create a single-project or shared future reservation request.

2. When you've finalized your changes, click Copy, and then store the gcloud CLI commands somewhere. You need them in the following section.

3. Click Close.

Create future reservation requests

To create future reservation requests, do the following:

1. In Cloud Shell or a command line of your choice, run the commands that you generated and, in case, edited in the previous sections.

   For example, the output for creating two future reservation requests 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].
   

2. If you created a draft future reservation request in the previous step, then 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 view future reservation requests.

• Learn how to consume the automatically created reservations that Compute Engine provisions for a future reservation.

• Learn how to cancel or delete future reservation requests.