Update instance properties

---

You can use a single request from the Google Cloud CLI or the Compute Engine API to update multiple instance properties and optionally restart the instance if necessary. The update method handles the logic for validating the updated instance properties and ensuring that the necessary resources are available to complete the update successfully. If the request includes invalid properties or if the requested resources are not available, the request returns an error and makes no changes to your instance. This protects the instance from partial updates and protects the instance from being stopped and unable to access resources to start up again.

Before you begin

• If you haven't already, then set up authentication. Authentication is the process by which your identity is verified for access to Google Cloud services and APIs. To run code or samples from a local development environment, you can authenticate to Compute Engine by selecting one of the following options:
  

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. Install the Google Cloud CLI, then initialize it by running the following command:

     gcloud init

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
  2. Set a default region and zone.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

Restrictions

• Instance update requests through the gcloud CLI or the Compute Engine API do not support PATCH semantics. The instance resource in the update request must include all of the properties of the instance. Properties that are missing from the instance configuration in your update request are considered to be deleted from the instance.
• You can update only a specific list of properties.
• Changing instances to and from sole tenancy is not supported.
• You can change an instance from one reservation to another, but you cannot attach or detach an instance to a reservation using the update process.
• If the instance has a local SSD attached, you cannot update properties that require the instance to restart. You must delete and then recreate the instance. Make sure that you migrate your critical data from the local SSD to a persistent disk or to another VM before deleting the VM.
• If an instance uses resources that are available only in the beta Compute Engine API, you must use the correct version of the instances.update method to update those properties. For example, if you create an instance using the beta Compute Engine API and configure the instance with a resource that only the beta API recognizes, you must also use the beta version of the instances.update method to update those resources. The v1 version of the instances.update method does not recognize the beta resources that your instance uses, so it deletes those beta resources from the instance configuration during the update process. This also applies to resources in the alpha API.

Permissions

You must have the compute.instances.update permission to update instances. This permission is included in several existing Identity and Access Management (IAM) roles. You must also have permission to use the resources that you want to modify on the instance. For example, to add a disk to an instance you must have the following permissions:

• The compute.instances.update permission on the instance that you want to update.
• Either compute.disks.use permission for an existing disk or compute.disks.create on a project where you want to create a new disk.

Best practices

To ensure that the instance update interface works most effectively for you, use the following best practices:

• If possible, consistently use the same version of the Compute Engine API to create, set, and update instances. This ensures that you can update and modify any instance resources if they are available only in one version of the API.
• Although you can use the instances.update method to update instances in a managed instance group (MIG), for most situations it is better to change the instance template of the group and roll that update out to the MIG instead.

Properties that you can update

You can change only a specific set of instance properties through the update method. Updates to some properties require the instance to restart. To prevent accidental restarts on your instances, your request must define what action is allowed to be taken on your instances. Your request can specify one of the following actions:

• NO_EFFECT: The update request checks to see if the request is valid and if the resources are available, but it does not execute the update. Use this to test commands without initiating any actual updates.
• REFRESH: The update request runs only if the modified instance properties don't require the instance to restart. The request returns an INFEASIBLE error if the request is valid but a restart is required.
• RESTART: If the update requires the instance to restart, the system will restart your instance.

Properties that require RESTART to update:

• disks - Boot disks
  • disks.deviceName - All disks
• displayDevice
• enableNestedVirtualization
• guestAccelerators
• machineType
• minCpuPlatform
• networkPerformanceConfig
• performanceMonitoringUnit
• reservationAffinity
• resourcePolicies
• scheduling
• serviceAccounts
• shieldedInstanceConfig
• threadsPerCore
• visibleCoreCount

Properties that require only REFRESH to update:

• canIpForward
• deletionProtection
• description
• disks - Non-boot disk properties, excluding deviceName
• labels
• metadata
• nodeAffinities
• tags

Update instance properties

Update your instances using the following steps:

1. Export the existing instance configuration properties.
2. Modify the properties of the instance configuration.
3. Run a test request by specifying NO_EFFECT as the most disruptive action. The response indicates invalid fields in the instance configuration and indicates the action required to apply the changes.
4. If the configuration is acceptable, request an instance update and specify the most disruptive action that is acceptable for your instance update.

The system starts the update process only if your request meets the following requirements:

• The instance fingerprint property in your request must match the fingerprint of the instance that you are updating. This prevents simultaneous update requests on the same instance from overwriting each other.
• The properties in your update request must be valid.
• The resources that you requested must be available.
• If the properties in your request require the instance to restart, your request must specify RESTART as an allowed action.

If the requirements are met, the system starts the instance update process. Otherwise, the system makes no changes to your existing instance or its configuration.

You can initiate updates using either the gcloud CLI or the Compute Engine API.

gcloud

1. Use the instances export command to export the existing instance properties:

   gcloud compute instances export INSTANCE_NAME \
       --project PROJECT_ID \
       --zone ZONE \
       --destination=FILE_PATH
   

   Replace the following:

   • INSTANCE_NAME: the name for the instance that you want to export.
   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • FILE_PATH: the output path where you want to save the instance configuration file on your local workstation.

2. Use a text editor to modify one or more properties in the exported instance configuration file. To learn which properties you can update, see the list of updatable properties. For example, to change the machine type of the instance, change the machineType property:

   ⋮
   machineType: https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE
   ⋮
   

   Replace the following:

   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • MACHINE_TYPE: the machine type of the instance. For example, n1-standard-2.

3. Use the instances update-from-file command to run a test update of the target instance. Specify the --most-disruptive-allowed-action=NO_EFFECT flag. The response identifies misconfigured properties and indicates whether a RESTART or REFRESH action is required to apply the update.

   gcloud compute instances update-from-file INSTANCE_NAME \
       --project PROJECT_ID \
       --zone ZONE \
       --source=FILE_PATH \
       --most-disruptive-allowed-action NO_EFFECT
   

   Replace the following:

   • INSTANCE_NAME: the name for the instance you want to export.
   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • FILE_PATH: the path to the modified instance configuration file on your local workstation.

4. Use the instances update-from-file command to update the target instance. If you are updating a property that requires the instance to restart, include the --most-disruptive-allowed-action=RESTART flag. If the properties do not require a restart, specify the --most-disruptive-allowed-action=REFRESH flag. To learn which properties require a restart, see the updatable properties list.

   gcloud compute instances update-from-file INSTANCE_NAME \
       --project PROJECT_ID \
       --zone ZONE \
       --source=FILE_PATH \
       --most-disruptive-allowed-action ALLOWED_ACTION
   

   Replace the following:

   • INSTANCE_NAME: the name for the instance you want to export.
   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • FILE_PATH: the path to the modified instance configuration file on your local workstation.
   • ALLOWED_ACTION: defines how disruptive the update can be. Specify RESTART to allow for a full restart of the instance. Specify REFRESH to update the instance only if the modified properties do not require the instance to restart.

If the update request is valid and the required resources are available, the instance update process begins. You can monitor the status of this operation by viewing the audit logs. If the update requires a restart and your command allows for a RESTART, the instance restarts to apply the changes.

REST

1. Use the instances.get method in the Compute Engine API to export the existing instance properties:

   GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME
   

   Replace the following:

   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • INSTANCE_NAME: the name for the instance you want to export.

   This request returns an instance resource definition.

2. In the response, modify the instance resource properties. To learn which properties are updatable, see the updatable properties list. For example, to change the machine type of the instance, change the machineType property. You can change multiple properties.

   {
     ⋮
     "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/MACHINE_TYPE",
     ⋮
   }
   

   Replace the following:

   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • MACHINE_TYPE: the machine type of the instance. For example, n1-standard-2.

3. Use the instances.update method in the Compute Engine API and specify most_disruptive_allowed_action=NO_EFFECT to run a test update of the target instance. The response identifies misconfigured properties and indicates if a RESTART or REFRESH action is required to apply the update.

   PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=NO_EFFECT
   
   {
     ⋮
     "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
     ⋮
   }
   

   Replace the following:

   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • INSTANCE_NAME: the name for the instance you want to export.

4. Use the instances.update method in the Compute Engine API to update the target instance. If you are updating a property that requires an instance restart, include the ?most_disruptive_allowed_action=RESTART query parameter to indicate that the instance can be restarted during the update. If the properties do not require a restart, specify the ?most_disruptive_allowed_action=REFRESH query parameter. To learn which properties require a restart, see the updatable properties list. Include the full body for the instance resource that you modified. In the following example, the body changes the machine type to n1-standard-2:

   PUT https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/INSTANCE_NAME?most_disruptive_allowed_action=ALLOWED_ACTION
   
   {
     ⋮
     "machineType": "https://www.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/machineTypes/n1-standard-2",
     ⋮
   }
   

   Replace the following:

   • PROJECT_ID: the project ID for this request.
   • ZONE: the zone for this instance.
   • INSTANCE_NAME: the name for the instance you want to export.
   • ALLOWED_ACTION: defines how disruptive the update can be. Specify RESTART to allow for a full restart of the instance. Specify REFRESH to update the instance only if the modified properties do not require the instance to restart.

If the update request is valid and the required resources are available, the instance update process begins. You can monitor the status of this operation by viewing the audit logs. If the update requires a restart and your command allows for a RESTART, the instance restarts to apply the changes.

What's next

• Check the instance's status.
• Learn how to reserve resources in a specific zone.