Updates an instance only if the necessary resources are available. This method can update only a specific set of instance properties. See Updating a running instance for a list of updatable instance properties.

Scopes

You will need authorization for at least one of the following scopes to make a valid call:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/compute

If unset, the scope for this method defaults to https://www.googleapis.com/auth/cloud-platform. You can set the scope for this method like this: compute1 --scope <scope> instances update ...

Required Scalar Arguments

  • <project> (string)
    • Project ID for this request.
  • <zone> (string)
    • The name of the zone for this request.
  • <instance> (string)
    • Name of the instance resource to update.

Required Request Value

The request value is a data-structure with various fields. Each field may be a simple scalar or another data-structure. In the latter case it is advised to set the field-cursor to the data-structure's field to specify values more concisely.

For example, a structure like this:

Instance:
  advanced-machine-features:
    enable-nested-virtualization: boolean
    enable-uefi-networking: boolean
    threads-per-core: integer
  can-ip-forward: boolean
  confidential-instance-config:
    enable-confidential-compute: boolean
  cpu-platform: string
  creation-timestamp: string
  deletion-protection: boolean
  description: string
  display-device:
    enable-display: boolean
  fingerprint: string
  hostname: string
  id: string
  kind: string
  label-fingerprint: string
  labels: { string: string }
  last-start-timestamp: string
  last-stop-timestamp: string
  last-suspended-timestamp: string
  machine-type: string
  metadata:
    fingerprint: string
    kind: string
  min-cpu-platform: string
  name: string
  network-performance-config:
    total-egress-bandwidth-tier: string
  params:
    resource-manager-tags: { string: string }
  private-ipv6-google-access: string
  reservation-affinity:
    consume-reservation-type: string
    key: string
    values: [string]
  resource-policies: [string]
  satisfies-pzs: boolean
  scheduling:
    automatic-restart: boolean
    instance-termination-action: string
    location-hint: string
    min-node-cpus: integer
    on-host-maintenance: string
    preemptible: boolean
    provisioning-model: string
  self-link: string
  shielded-instance-config:
    enable-integrity-monitoring: boolean
    enable-secure-boot: boolean
    enable-vtpm: boolean
  shielded-instance-integrity-policy:
    update-auto-learn-policy: boolean
  source-machine-image: string
  source-machine-image-encryption-key:
    kms-key-name: string
    kms-key-service-account: string
    raw-key: string
    rsa-encrypted-key: string
    sha256: string
  start-restricted: boolean
  status: string
  status-message: string
  tags:
    fingerprint: string
    items: [string]
  zone: string

can be set completely with the following arguments which are assumed to be executed in the given order. Note how the cursor position is adjusted to the respective structures, allowing simple field names to be used most of the time.

  • -r .advanced-machine-features enable-nested-virtualization=true
    • Whether to enable nested virtualization or not (default is false).
  • enable-uefi-networking=false
    • Whether to enable UEFI networking for instance creation.
  • threads-per-core=69

    • The number of threads per physical core. To disable simultaneous multithreading (SMT) set this to 1. If unset, the maximum number of threads supported per core by the underlying processor is assumed.
  • .. can-ip-forward=false

    • Allows this instance to send and receive packets with non-matching destination or source IPs. This is required if you plan to use this instance to forward routes. For more information, see Enabling IP Forwarding .
  • confidential-instance-config enable-confidential-compute=true

    • Defines whether the instance should have confidential compute enabled.
  • .. cpu-platform=ea

    • [Output Only] The CPU platform used by this instance.
  • creation-timestamp=sed
    • [Output Only] Creation timestamp in RFC3339 text format.
  • deletion-protection=true
    • Whether the resource should be protected against deletion.
  • description=sit
    • An optional description of this resource. Provide this property when you create the resource.
  • display-device enable-display=false

    • Defines whether the instance has Display enabled.
  • .. fingerprint=eirmod

    • Specifies a fingerprint for this resource, which is essentially a hash of the instance's contents and used for optimistic locking. The fingerprint is initially generated by Compute Engine and changes after every request to modify or update the instance. You must always provide an up-to-date fingerprint hash in order to update the instance. To see the latest fingerprint, make get() request to the instance.
  • hostname=voluptua.
    • Specifies the hostname of the instance. The specified hostname must be RFC1035 compliant. If hostname is not specified, the default hostname is [INSTANCE_NAME].c.[PROJECT_ID].internal when using the global DNS, and [INSTANCE_NAME].[ZONE].c.[PROJECT_ID].internal when using zonal DNS.
  • id=nonumy
    • [Output Only] The unique identifier for the resource. This identifier is defined by the server.
  • kind=ut
    • [Output Only] Type of the resource. Always compute#instance for instances.
  • label-fingerprint=diam
    • A fingerprint for this request, which is essentially a hash of the label's contents and used for optimistic locking. The fingerprint is initially generated by Compute Engine and changes after every request to modify or update labels. You must always provide an up-to-date fingerprint hash in order to update or change labels. To see the latest fingerprint, make get() request to the instance.
  • labels=key=dolore
    • Labels to apply to this instance. These can be later modified by the setLabels method.
    • the value will be associated with the given key
  • last-start-timestamp=gubergren
    • [Output Only] Last start timestamp in RFC3339 text format.
  • last-stop-timestamp=ea
    • [Output Only] Last stop timestamp in RFC3339 text format.
  • last-suspended-timestamp=magna
    • [Output Only] Last suspended timestamp in RFC3339 text format.
  • machine-type=at
    • Full or partial URL of the machine type resource to use for this instance, in the format: zones/zone/machineTypes/machine-type. This is provided by the client when the instance is created. For example, the following is a valid partial url to a predefined machine type: zones/us-central1-f/machineTypes/n1-standard-1 To create a custom machine type, provide a URL to a machine type in the following format, where CPUS is 1 or an even number up to 32 (2, 4, 6, ... 24, etc), and MEMORY is the total memory for this instance. Memory must be a multiple of 256 MB and must be supplied in MB (e.g. 5 GB of memory is 5120 MB): zones/zone/machineTypes/custom-CPUS-MEMORY For example: zones/us-central1-f/machineTypes/custom-4-5120 For a full list of restrictions, read the Specifications for custom machine types.
  • metadata fingerprint=est
    • Specifies a fingerprint for this request, which is essentially a hash of the metadata's contents and used for optimistic locking. The fingerprint is initially generated by Compute Engine and changes after every request to modify or update metadata. You must always provide an up-to-date fingerprint hash in order to update or change metadata, otherwise the request will fail with error 412 conditionNotMet. To see the latest fingerprint, make a get() request to retrieve the resource.
  • kind=sea

    • [Output Only] Type of the resource. Always compute#metadata for metadata.
  • .. min-cpu-platform=ipsum

    • Specifies a minimum CPU platform for the VM instance. Applicable values are the friendly names of CPU platforms, such as minCpuPlatform: "Intel Haswell" or minCpuPlatform: "Intel Sandy Bridge".
  • name=dolor
    • The name of the resource, provided by the client when initially creating the resource. The resource name must be 1-63 characters long, and comply with RFC1035. Specifically, the name must be 1-63 characters long and match the regular expression [a-z]([-a-z0-9]*[a-z0-9])? which means the first character must be a lowercase letter, and all following characters must be a dash, lowercase letter, or digit, except the last character, which cannot be a dash.
  • network-performance-config total-egress-bandwidth-tier=rebum.

    • No description provided.
  • ..params resource-manager-tags=key=sed

    • Resource manager tags to be bound to the instance. Tag keys and values have the same definition as resource manager tags. Keys must be in the format tagKeys/{tag_key_id}, and values are in the format tagValues/456. The field is ignored (both PUT & PATCH) when empty.
    • the value will be associated with the given key
  • .. private-ipv6-google-access=no

    • The private IPv6 google access type for the VM. If not specified, use INHERIT_FROM_SUBNETWORK as default.
  • reservation-affinity consume-reservation-type=kasd
    • Specifies the type of reservation from which this instance can consume resources: ANY_RESERVATION (default), SPECIFIC_RESERVATION, or NO_RESERVATION. See Consuming reserved instances for examples.
  • key=sit
    • Corresponds to the label key of a reservation resource. To target a SPECIFIC_RESERVATION by name, specify googleapis.com/reservation-name as the key and specify the name of your reservation as its value.
  • values=eirmod

    • Corresponds to the label values of a reservation resource. This can be either a name to a reservation in the same project or "projects/different-project/reservations/some-reservation-name" to target a shared reservation in the same zone but in a different project.
    • Each invocation of this argument appends the given value to the array.
  • .. resource-policies=tempor

    • Resource policies applied to this instance.
    • Each invocation of this argument appends the given value to the array.
  • satisfies-pzs=false
    • [Output Only] Reserved for future use.
  • scheduling automatic-restart=false
    • Specifies whether the instance should be automatically restarted if it is terminated by Compute Engine (not terminated by a user). You can only set the automatic restart option for standard instances. Preemptible instances cannot be automatically restarted. By default, this is set to true so an instance is automatically restarted if it is terminated by Compute Engine.
  • instance-termination-action=amet
    • Specifies the termination action for the instance.
  • location-hint=sea
    • An opaque location hint used to place the instance close to other resources. This field is for use by internal tools that use the public API.
  • min-node-cpus=74
    • The minimum number of virtual CPUs this instance will consume when running on a sole-tenant node.
  • on-host-maintenance=stet
    • Defines the maintenance behavior for this instance. For standard instances, the default behavior is MIGRATE. For preemptible instances, the default and only possible behavior is TERMINATE. For more information, see Set VM availability policies.
  • preemptible=false
    • Defines whether the instance is preemptible. This can only be set during instance creation or while the instance is stopped and therefore, in a TERMINATED state. See Instance Life Cycle for more information on the possible instance states.
  • provisioning-model=ipsum

    • Specifies the provisioning model of the instance.
  • .. self-link=no

    • [Output Only] Server-defined URL for this resource.
  • shielded-instance-config enable-integrity-monitoring=false
    • Defines whether the instance has integrity monitoring enabled. Enabled by default.
  • enable-secure-boot=true
    • Defines whether the instance has Secure Boot enabled. Disabled by default.
  • enable-vtpm=false

    • Defines whether the instance has the vTPM enabled. Enabled by default.
  • ..shielded-instance-integrity-policy update-auto-learn-policy=true

    • Updates the integrity policy baseline using the measurements from the VM instance's most recent boot.
  • .. source-machine-image=labore

    • Source machine image
  • source-machine-image-encryption-key kms-key-name=ipsum
    • The name of the encryption key that is stored in Google Cloud KMS. For example: "kmsKeyName": "projects/kms_project_id/locations/region/keyRings/ key_region/cryptoKeys/key
  • kms-key-service-account=takimata
    • The service account being used for the encryption request for the given KMS key. If absent, the Compute Engine default service account is used. For example: "kmsKeyServiceAccount": "name@project_id.iam.gserviceaccount.com/
  • raw-key=diam
    • Specifies a 256-bit customer-supplied encryption key, encoded in RFC 4648 base64 to either encrypt or decrypt this resource. You can provide either the rawKey or the rsaEncryptedKey. For example: "rawKey": "SGVsbG8gZnJvbSBHb29nbGUgQ2xvdWQgUGxhdGZvcm0="
  • rsa-encrypted-key=ipsum
    • Specifies an RFC 4648 base64 encoded, RSA-wrapped 2048-bit customer-supplied encryption key to either encrypt or decrypt this resource. You can provide either the rawKey or the rsaEncryptedKey. For example: "rsaEncryptedKey": "ieCx/NcW06PcT7Ep1X6LUTc/hLvUDYyzSZPPVCVPTVEohpeHASqC8uw5TzyO9U+Fka9JFH z0mBibXUInrC/jEk014kCK/NPjYgEMOyssZ4ZINPKxlUh2zn1bV+MCaTICrdmuSBTWlUUiFoD D6PYznLwh8ZNdaheCeZ8ewEXgFQ8V+sDroLaN3Xs3MDTXQEMMoNUXMCZEIpg9Vtp9x2oe==" The key must meet the following requirements before you can provide it to Compute Engine: 1. The key is wrapped using a RSA public key certificate provided by Google. 2. After being wrapped, the key must be encoded in RFC 4648 base64 encoding. Gets the RSA public key certificate provided by Google at: https://cloud-certs.storage.googleapis.com/google-cloud-csek-ingress.pem
  • sha256=accusam

    • [Output only] The RFC 4648 base64 encoded SHA-256 hash of the customer-supplied encryption key that protects this resource.
  • .. start-restricted=false

    • [Output Only] Whether a VM has been restricted for start because Compute Engine has detected suspicious activity.
  • status=consetetur
    • [Output Only] The status of the instance. One of the following values: PROVISIONING, STAGING, RUNNING, STOPPING, SUSPENDING, SUSPENDED, REPAIRING, and TERMINATED. For more information about the status of the instance, see Instance life cycle.
  • status-message=eirmod
    • [Output Only] An optional, human-readable explanation of the status.
  • tags fingerprint=lorem
    • Specifies a fingerprint for this request, which is essentially a hash of the tags' contents and used for optimistic locking. The fingerprint is initially generated by Compute Engine and changes after every request to modify or update tags. You must always provide an up-to-date fingerprint hash in order to update or change tags. To see the latest fingerprint, make get() request to the instance.
  • items=diam

    • An array of tags. Each tag must be 1-63 characters long, and comply with RFC1035.
    • Each invocation of this argument appends the given value to the array.
  • .. zone=consetetur

    • [Output Only] URL of the zone where the instance resides. You must specify this field as part of the HTTP request URL. It is not settable as a field in the request body.

About Cursors

The cursor position is key to comfortably set complex nested structures. The following rules apply:

  • The cursor position is always set relative to the current one, unless the field name starts with the . character. Fields can be nested such as in -r f.s.o .
  • The cursor position is set relative to the top-level structure if it starts with ., e.g. -r .s.s
  • You can also set nested fields without setting the cursor explicitly. For example, to set a value relative to the current cursor position, you would specify -r struct.sub_struct=bar.
  • You can move the cursor one level up by using ... Each additional . moves it up one additional level. E.g. ... would go three levels up.

Optional Output Flags

The method's return value a JSON encoded structure, which will be written to standard output by default.

  • -o out
    • out specifies the destination to which to write the server's result to. It will be a JSON-encoded structure. The destination may be - to indicate standard output, or a filepath that is to contain the received bytes. If unset, it defaults to standard output.

Optional Method Properties

You may set the following properties to further configure the call. Please note that -p is followed by one or more key-value-pairs, and is called like this -p k1=v1 k2=v2 even though the listing below repeats the -p for completeness.

  • -p minimal-action=string

    • Specifies the action to take when updating an instance even if the updated properties do not require it. If not specified, then Compute Engine acts based on the minimum action that the updated properties require.
  • -p most-disruptive-allowed-action=string

    • Specifies the most disruptive action that can be taken on the instance as part of the update. Compute Engine returns an error if the instance properties require a more disruptive action as part of the instance update. Valid options from lowest to highest are NO_EFFECT, REFRESH, and RESTART.
  • -p request-id=string

    • An optional request ID to identify requests. Specify a unique request ID so that if you must retry your request, the server will know to ignore the request if it has already been completed. For example, consider a situation where you make an initial request and the request times out. If you make the request again with the same request ID, the server can check if original operation with the same request ID was received, and if so, will ignore the second request. This prevents clients from accidentally creating duplicate commitments. The request ID must be a valid UUID with the exception that zero UUID is not supported ( 00000000-0000-0000-0000-000000000000).

Optional General Properties

The following properties can configure any call, and are not specific to this method.

  • -p $-xgafv=string

    • V1 error format.
  • -p access-token=string

    • OAuth access token.
  • -p alt=string

    • Data format for response.
  • -p callback=string

    • JSONP
  • -p fields=string

    • Selector specifying which fields to include in a partial response.
  • -p key=string

    • API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.
  • -p oauth-token=string

    • OAuth 2.0 token for the current user.
  • -p pretty-print=boolean

    • Returns response with indentations and line breaks.
  • -p quota-user=string

    • Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.
  • -p upload-type=string

    • Legacy upload protocol for media (e.g. "media", "multipart").
  • -p upload-protocol=string

    • Upload protocol for media (e.g. "raw", "multipart").
  • -p user-ip=string

    • Legacy name for parameter that has been superseded by quotaUser.