Modify future reservation requests

Console

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

   Go to Reservations

2. Click the Future reservations tab.

3. In the Name column, click the name of the future reservation request that you want to modify.

   The details page of the selected future reservation request opens.

4. If you want to modify the auto-delete option, description, or name prefix of an approved future reservation, then do one or more of the following:

   • To modify the auto-delete option, in the Auto-created reservations auto-delete time row, click edit Edit, and then do the following:

     1. Specify if you want to enable, disable, or modify the auto-delete option by doing one of the following:

        • To enable the auto-delete option or change the time when Compute Engine automatically deletes the auto-created reservations, do the following:

          1. Click the Enable auto-delete toggle to the on position.

          2. Optional: For Auto-delete time, enter a new date and time when to delete the auto-created reservations. The date and time must be after the end time of the reservation period. If you leave this field empty, then the auto-created reservations are deleted within two hours after the reservation period's end time.

        • Otherwise, click the Enable auto-delete toggle to the off position.

     2. Click Submit.

   • To modify the name prefix, in the Prefix row, click edit Edit, and then do the following:

     1. For Prefix, enter a new name prefix.

     2. Click Submit.

   • To modify the description, in the Description row, click edit Edit, and then do the following:

     1. For Description, enter a new description.

     2. Click Submit.

5. Click edit Edit or edit Edit draft.

   The page to edit the selected future reservation request opens.

6. To modify a future reservation request and submit it to Google Cloud for review, or save the draft request, do one or more of the following:

   • For Prefix, enter a new name prefix for the auto-created reservations provisioned for this future reservation request.

   • For Description, enter a new description.

   • Modify the Start time or End time for your future reservation request. Make sure of the following:

     • The start time can't be later than one year from the date and time at which you submit a future reservation request for review.

     • Specify a recommended value for the start time to ensure that you have sufficient time before your future reservation enters its lock time.

     • Specify a recommended minimum reservation period to increase the likelihood that Google Cloud approves your request after submitting it for review.

   • In the Share type section, you can select either Local or Shared. If you select Shared, you can add or remove projects to share the future reservation request with. You can include up to 100 projects.

   • For Number of VM instances, enter the total count of VMs that you want reserved.

   • If you're modifying a future reservation that wasn't created through an instance template, then, in the Machine configuration section, you can change the following:

     • The machine series and machine type used in the reserved VMs.

     • The GPUs to attach to the reserved VMs.

     • The Local SSD disks and the disk interface type of the reserved VMs.

   • In the Auto-generated reservations auto-delete section, you can enable or disable the automatic deletion of auto-created reservations for your future reservation request.

7. Depending on the procurement status of the future reservation request that you're modifying, do one of the following:

   • If you're modifying a draft future reservation request, then do one of the following:

     • To save your changes, click Save draft.

     • To submit the draft future reservation request to Google Cloud for review, click Submit.

   • Otherwise, click Submit.

If you submit a modification request, then the Reservations page opens. Otherwise, the details page of the future reservation opens.

gcloud

To modify a future reservation request, use the gcloud beta compute future-reservations update command.

gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
    --accelerator=count=NUMBER_OF_ACCELERATORS,type=ACCELERATOR_TYPE \
    --description="DESCRIPTION" \
    --local-ssd=size=375,interface=INTERFACE \
    --machine-type=MACHINE_TYPE \
    --min-cpu-platform=MIN_CPU_PLATFORM \
    --name-prefix=NAME_PREFIX \
    --planning-status=PLANNING_STATUS \
    --share-setting=SHARE_SETTING \
    --share-with=CONSUMER_PROJECT_IDS \
    --start-time=START_TIME \
    --end-time=END_TIME \
    --total-count=TOTAL_COUNT \
    --zone=ZONE

Replace the following:

• FUTURE_RESERVATION_NAME: the name of the future reservation request.

• PLANNING_STATUS: the planning status of the future reservation request. Specify one of the following values:

  • To modify a draft future reservation request without submitting it for review: DRAFT.

  • To submit the future reservation request for review: SUBMITTED.

• ZONE: the zone where the future reservation request is located.

Replace one or more of the following placeholders, or remove them along with their corresponding flags:

• To enable Compute Engine to automatically delete the auto-created reservations after the end time of the reservation period, do one of the following:

  • To delete the reservations within two hours after the end time (default), include the --auto-delete-auto-created-reservations flag.

    gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
        --auto-delete-auto-created-reservations \
        --planning-status=PLANNING_STATUS \
        --zone=ZONE
    

  • To delete the auto-created reservations at a specific time after the end time of the reservation period, include the --auto-delete-auto-created-reservations and --auto-created-reservations-delete-time flags.

    gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
        --auto-created-reservations-delete-time=AUTO_CREATED_RESERVATIONS_DELETE_TIME \
        --auto-delete-auto-created-reservations \
        --planning-status=PLANNING_STATUS \
        --zone=ZONE
    

    Replace AUTO_CREATED_RESERVATIONS_DELETE_TIME with a date and time formatted as an RFC 3339 timestamp.

  • To delete the auto-created reservations after a specific duration after the end time of the reservation period, include the --auto-delete-auto-created-reservations and --auto-created-reservations-duration flags.

    gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
        --auto-created-reservations-duration=DURATION_BEFORE_DELETE \
        --auto-delete-auto-created-reservations \
        --planning-status=PLANNING_STATUS \
        --zone=ZONE
    

    Replace DURATION_BEFORE_DELETE 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.

• To disable Compute Engine from automatically deleting the auto-created reservations provisioned for this future reservation request, include the --no-auto-delete-auto-created-reservations flag.

  gcloud beta compute future-reservations update FUTURE_RESERVATION_NAME \
      --no-auto-delete-auto-created-reservations \
      --planning-status=PLANNING_STATUS \
      --zone=ZONE
  

• To add or remove GPUs attached to reserved N1 VMs, or update the GPU type, do one of the following:

  • To change the number and type of GPUs, replace the following:

    • NUMBER_OF_ACCELERATORS: the number of GPUs to add per reserved VM.

    • ACCELERATOR_TYPE: the type of GPU to add to the reserved VMs. Ensure that the GPU is available in the zone where the future reservation request is located. Otherwise, modifying the request fails.

  • To remove all GPUs attached to reserved N1 VMs, replace the --accelerator flag with the --clear-accelerator flag.

• DESCRIPTION: A new description for your future reservation request.

• To add or remove Local SSD disks from your reserved VMs, or edit the Local SSD disk interface type, do one of the following:

  • To add Local SSD disks or edit the disk interface type, replace the INTERFACE with one of the following values:

    • If your boot disk image has optimized NVMe drivers: nvme.

    • Otherwise: scsi.

    Include the --local-ssd flag for as many Local SSD disks that you want to add. You can specify a maximum of 24 Local SSD disks.

  • To remove all Local SSD disks attached to the reserved VMs, remove all --local-ssd flags and include the --clear-local-ssd flag.

• MACHINE_TYPE: The new machine type to use for each reserved VM. If you change the machine type, then ensure to also specify a recommended minimum reservation period for the new machine series. Otherwise, Google Cloud is likely to to decline your modification request.

• MINIMUM_CPU_PLATFORM: A new minimum CPU platform to use for each reserved VM.

• NAME_PREFIX: A new name prefix for the auto-created reservations provisioned for your future reservation request.

• SHARE_SETTING: A new share type for your future reservation request. Specify one of the following values:

  • For a single-project future reservation request: local. To avoid errors, you must also replace the --share-with flag with the --clear-share-settings flag.

  • For a shared future reservation request: projects. To avoid errors, you must also specify at least one consumer project in the --share-with flag.

• CONSUMER_PROJECT_IDS: A comma-separated list of IDs of projects that you want to share your future reservation request with—for example, project-1,project-2. You can specify up to 100 consumer projects.

• START_TIME: The new start time of the reservation period formatted as an RFC 3339 timestamp. The start time can't be later than one year from the date and time at which you submit the modification request for review. To have sufficient time to optionally cancel, delete, or modify a future reservation after it's approved and before it enters its lock time, specify a recommended start time.

• END_TIME: The new end time of the reservation period formatted as an RFC 3339 timestamp. The reservation period must last at least 24 hours. Alternatively, you can replace the --end-time flag with the --duration=END_DURATION flag. Replace END_DURATION with the duration of the reservation period in seconds. To increase the likelihood that Google Cloud approves a future reservation request after you submit it for review, specify a recommended reservation period.

• TOTAL_COUNT: The new total number of VMs that you want reserved for the period, VM configuration, and project(s) specified in your future reservation request. If you want to increase the total count, than ensure that you have sufficient quota for the resources that you're reserving. Otherwise, Google Cloud declines your modification request.

For example, consider a draft shared future reservation request named fr-03 and located in zone us-central1-a. Suppose that you want to modify this shared future reservation request by making the following changes:

• Convert the request into a single-project future reservation request.

• Disable the auto-delete option.

• Reserve 100 VMs.

• Submit the future reservation request to Google Cloud for review.

To modify fr-03, run the following command:

gcloud beta compute future-reservations update fr-03 \
    --clear-share-settings \
    --no-auto-delete-auto-created-reservations \
    --planning-status=SUBMITTED \
    --share-setting=local \
    --total-count=100 \
    --zone=us-central1-a

REST

To modify a future reservation request, make a PATCH request to the beta.futureReservations.update method.

PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=UPDATE_FIELDS

{
  "autoDeleteAutoCreatedReservations": "AUTO_DELETE_AUTO_CREATED_RESERVATIONS",
  "description": "DESCRIPTION",
  "name": "FUTURE_RESERVATION_NAME",
  "namePrefix": "NAME_PREFIX",
  "planningStatus": "PLANNING_STATUS",
  "shareSettings": {
    "projects": [
      "CONSUMER_PROJECT_ID_1",
      "CONSUMER_PROJECT_ID_2"
    ],
    "shareType": "SHARE_TYPE"
  },
  "specificSkuProperties": {
    "instanceProperties": {
      "guestAccelerators": [
        {
          "acceleratorCount": NUMBER_OF_ACCELERATORS,
          "acceleratorType": "ACCELERATOR_TYPE"
        }
      ],
      "localSsds": [
        {
          "diskSizeGb": "375",
          "interface": "INTERFACE_1"
        },
        {
          "diskSizeGb": "375",
          "interface": "INTERFACE_2"
        }
      ],
      "machineType": "MACHINE_TYPE",
      "minCpuPlatform": "MINIMUM_CPU_PLATFORM"
    },
    "totalCount": "TOTAL_COUNT"
  },
  "timeWindow": {
    "endTime": "END_TIME",
    "startTime": "START_TIME"
  }
}

Replace the following:

• PROJECT_ID: the ID of the project where the future reservation request is located.

• ZONE: the zone where the future reservation request is located.

• FUTURE_RESERVATION_NAME: the name of the future reservation request.

• UPDATE_FIELDS: a comma-separated list of fields to update in the request body. You must encode each comma as %2C. If you specify a field in the updateMask query parameter and in the request body, then this updates the value of the field. Otherwise, if you specify the field only in the updateMask query parameter, then this deletes the field.

  For example, to update the autoDeleteAutoCreatedReservations, totalCount, and endTime fields in your future reservation request, specify the following:

  autoDeleteAutoCreatedReservations%2CspecificSkuProperties.totalCount%2CtimeWindow.endTime
  

• PLANNING_STATUS: the planning status of the future reservation request. Specify one of the following values:

  • To modify a draft future reservation request without submitting it for review: DRAFT.

  • To submit the modification request for review: SUBMITTED.

Replace one or more of the following placeholders, or remove them along with their corresponding fields:

• AUTO_DELETE_AUTO_CREATED_RESERVATIONS: If you set this field to true, then Compute Engine automatically deletes the auto-created reservations provisioned for your future reservation request. By default, the deletion is within two hours after the reservation period's end time. To change this, do one of the following:

  • To delete the auto-created reservations at a specific time after the end time of your reservation period, set the autoDeleteAutoCreatedReservations to true and specify the autoCreatedReservationsDeleteTime field.

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDeleteTime%2CplanningStatus
    
    {
      "autoDeleteAutoCreatedReservations": "true",
      "autoCreatedReservationsDeleteTime": "DELETE_TIME",
      "name": "FUTURE_RESERVATION_NAME",
      "planningStatus": "PLANNING_STATUS"
    }
    

    Replace DELETE_TIME with a date and time when Compute Engine deletes reservations. The date and time must be formatted as an RFC 3339 timestamp.

  • To delete the auto-created reservations after a specific duration from the start time of the reservation period, set the autoDeleteAutoCreatedReservations to true and specify the autoCreatedReservationsDuration field.

    PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=autoDeleteAutoCreatedReservations%2CautoCreatedReservationsDuration%2CplanningStatus
    
    {
      "autoDeleteAutoCreatedReservations": "true",
      "autoCreatedReservationsDuration": {
        "seconds": "DURATION_BEFORE_DELETE"
      },
      "name": "FUTURE_RESERVATION_NAME",
      "planningStatus": "PLANNING_STATUS"
    }
    

    Replace DURATION_BEFORE_DELETE with a duration in seconds. For example, specify 604800 for 604,800 seconds (7 days).

• DESCRIPTION: A new description for the future reservation request.

• NAME_PREFIX: A new name prefix for the auto-created reservations provisioned for your future reservation request.

• CONSUMER_PROJECT_ID_1 and CONSUMER_PROJECT_ID_2: The IDs of projects that you want to share your future reservation request with. The projects must be in the same organization as the owner project. You can specify up to 100 consumer projects.

• SHARE_TYPE: A new share type for your future reservation request. Do one of the following:

  • To specify a single-project future reservation request, do the following:

    • Specify LOCAL.

    • Remove the shareSettings.projects field.

  • To specify a shared future reservation request, do the following:

    • Specify SPECIFIC_PROJECTS.

    • Specify at least one consumer project in the shareSettings.projects field. The consumer projects must be in the same organization as the owner project. You can specify up to 100 consumer projects.

• To change the number and type of GPUs to attach to your reserved N1 VMs, replace the following:

  • NUMBER_OF_ACCELERATORS: the number of GPUs to add per reserved VM.

  • ACCELERATOR_TYPE: the type of GPU to add to the reserved VMs. Ensure that the GPU is available in the zone where the future reservation request is located. Otherwise, modifying the request fails.

• INTERFACE_1 and INTERFACE_2: The type of disk interface type for the Local SSD disks attached to each reserved VM. Specify one of the following values:

  • If your boot disk image has optimized NVMe drivers: NVME.

  • Otherwise: SCSI.

    You can specify a maximum of 24 Local SSD disks.

• MACHINE_TYPE: The new machine type to use for each reserved VM. If you change the machine type, then ensure to also specify a recommended minimum reservation period. for the new machine series. Otherwise, Google Cloud is less likely to approve your modification request.

• MINIMUM_CPU_PLATFORM: A new minimum CPU platform to use for each reserved VM.

• TOTAL_COUNT: The new total number of VMs that you want reserved for the period, VM configuration, and project(s) specified in this future reservation request. If you want to increase the total count, than ensure that you have sufficient quota for the resources that you're reserving. Otherwise, Google Cloud declines your modification request.

• START_TIME: The new start time of the reservation period formatted as an RFC 3339 timestamp. The start time can't be later than one year from the date and time at which you submit the modification request for review. To have sufficient time to optionally cancel, delete, or modify a future reservation after it's approved and before it enters its lock time, specify a recommended start time.

• END_TIME: The new end time of the reservation period formatted as an RFC 3339 timestamp. The reservation period must last at least 24 hours. Alternatively, you can replace the endTime field with the duration field to specify a specific duration from the start time of the reservation period:

  PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/futureReservations/FUTURE_RESERVATION_NAME?updateMask=timeWindow.duration%2CplanningStatus
  
  {
    "name": "FUTURE_RESERVATION_NAME",
    "planningStatus": "PLANNING_STATUS",
    "timeWindow": {
      "duration": {
        "seconds": "END_DURATION"
      }
    }
  }
  

  Replace END_DURATION with a duration in seconds. For example, specify 1209600 for 1,209,600 seconds (14 days). To increase the likelihood that Google Cloud approves a future reservation request after you submit it for review, specify a recommended reservation period.

For example, consider a draft shared future reservation request named fr-03 and located in zone us-central1-a. Suppose that you want to modify this shared future reservation request by making the following changes:

• Convert the request into a single-project future reservation request.

• Disable the auto-delete option.

• Reserve 100 VMs.

• Submit the future reservation request to Google Cloud for review.

To modify fr-03, make a PATCH request as follows:

PATCH https://compute.googleapis.com/compute/beta/projects/example-project/zones/us-central1-a/futureReservations/fr-03?updateMask=autoDeleteAutoCreatedReservations%2CplanningStatus%2CshareSettings.shareType%2CspecificSkuProperties.totalCount

{
  "autoDeleteAutoCreatedReservations": false,
  "name": "fr-03",
  "planningStatus": "SUBMITTED",
  "shareSettings": {
    "shareType": "LOCAL"
  },
  "specificSkuProperties": {
    "totalCount": "100"
  }
}