You can use a single request from theGoogle Cloud CLI or theCompute Engine APIto update multiple instance properties and optionallyrestart the instance if necessary. The update method handles the logic forvalidating the updated instance properties and ensuring that the necessaryresources are available to complete the update successfully. If the requestincludes invalid properties or if the requested resources are not available,the request returns an error and makes no changes to your instance. Thisprotects the instance from partial updates and protects the instance frombeing stopped and unable to access resources to start up again.

To update the network interfaces (networkInterfaces) of an instance,see insteadUpdate the network interfaces for an instance.

To add or remove Dynamic Network Interfaces from an instance, use the followingprocedures instead of updating the instance properties:

• Delete Dynamic NICs from an instance
• Add Dynamic NICs to an instance

Before you begin

• If you haven't already, set upauthentication. Authentication verifies your identity 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. After installation,initialize the Google Cloud CLI by running the following command:

     gcloudinit

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

     Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud 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. After installation,initialize the Google Cloud CLI by running the following command:

  gcloudinit

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  Note: If you installed the gcloud CLI previously, make sure you have the latest version by runninggcloud components update.

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

Restrictions

• Instance update requests through the gcloud CLI orthe Compute Engine API don't supportPATCH semantics. Theinstance resource in the update request must include all of the propertiesof the instance. Properties that are missing from the instance configurationin your update request are considered to be deleted from the instance.
• You can update only aspecific 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 cannotattach or detach an instance to a reservation using the update process.
• If the instance has Local SSD disks attached, you can't update properties thatrequire the instance to restart while the instance is running. You can deleteand then recreate the instance, orstop the instance, update theproperties,and then restart it.
• You can update thenetworkInterfaces property of an instance, but you can'tadd virtual NICs (vNICs) to or remove vNICs from an instance.
• If an instance uses resources that are available only in the betaCompute Engine API, you must use the correct version of theinstances.update method to update those properties. For example, if youcreate an instance using the beta Compute Engine API and configurethe instance with a resource that only the beta API recognizes, you mustalso use the beta version of theinstances.update method to update thoseresources. The v1 version of theinstances.update methoddoesn't recognize the beta resources that your instance uses, so it deletesthose beta resources from the instance configuration during the updateprocess. This behavior also applies to resources in the alpha API.

Permissions

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

• Thecompute.instances.update permission on the instance that you want toupdate.
• Eithercompute.disks.use permission for an existing disk orcompute.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 theCompute Engine API to create, set, and update instances. Thisensures that you can update and modify any instance resources if they areavailable only in one version of the API.
• Although you can use theinstances.update method to update instances in amanaged instance group (MIG),for most situations it is better to change theinstance template of the group androll that update out to the MIGinstead.
• If updating a resource that is used by the instance, use the command to updatethat resource instance of updating the instance properties, for example:
  • You can modify disks with thedisks.update method
  • To change the network used by the instance, you can use theinstances.updateNetworkInterface method, which doesn't requirestopping the instance.

Properties that you can update

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

• NO_EFFECT: the update request checks to see if the request is valid andif the resources are available, but it doesn't execute the update. Use thisaction to test commands without initiating any actual updates.
• REFRESH: the update request runs only if the modified instanceproperties don't require the instance to restart. The request returns anINFEASIBLE error if the request is valid but a restart is required.
• RESTART: if the update requires the instance to restart, then the systemwill restart your instance.

The following properties require a restart (RESTART) to update:

• disks: boot disks, including all disks (disks.deviceName)
• displayDevice
• enableNestedVirtualization
• guestAccelerators
• machineType
• minCpuPlatform
• networkInterfaces
• networkPerformanceConfig
• performanceMonitoringUnit
• reservationAffinity: You can only update how the instance consumesreservations (reservationAffinity.consumeReservationType) as follows:
  • From consuming any matching reservation (ANY_RESERVATION) to not consumingreservations (NO_RESERVATION)
  • From not consuming reservations (NO_RESERVATION) to consuming any matchingreservations (ANY_RESERVATION)
• resourcePolicies
• scheduling
• serviceAccounts
• shieldedInstanceConfig
• threadsPerCore
• visibleCoreCount

The following properties only require a refresh (REFRESH) to update:

• canIpForward
• deletionProtection
• description
• disks: non-boot disk properties, excludingdeviceName
• 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 specifyingNO_EFFECT as the most disruptive action.The response indicates invalid fields in the instance configuration andindicates the action required to apply the changes.
4. If the configuration is acceptable, request an instance update and specifythe most disruptive action that is acceptable for your instance update.

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

• The instancefingerprint property in your request must match thefingerprint of the instance that you are updating. This preventssimultaneous update requests on the same instance from overwritingeach 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, yourrequest must specifyRESTART 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 itsconfiguration.

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

What's next

• Check the instance'sstate.
• Learn how toreserve resources in aspecific zone.
• Learn how toUpdate the network interfaces for an instance.