Updating instance properties

You can use a single request from the gcloud command-line tool 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

Restrictions

  • Instance update requests through the gcloud tool 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 an instance to restart. You must stop the instance, update the instance's properties, and restart the instance manually.
  • 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 do not 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:

  • reservation_affinity
  • disk - Boot disks
  • display_device
  • guest_accelerator
  • machine_type
  • min_cpu_platform
  • scheduling
  • service_account
  • shielded_instance_config

Properties that require only REFRESH to update:

  • deletion_protection
  • description
  • disk - Non-boot disks
  • labels
  • metadata
  • tags

Updating 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 tool 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.

API

  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/update?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:

    • 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.
  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/update?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:

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