gcloud

To create a managed instance with a custom name and to set stateful metadataon that VM, use thegcloud compute instance-groups managed create-instance command with the--stateful-metadata flag.

gcloud compute instance-groups managed create-instanceNAME \  --instanceINSTANCE_NAME \  --stateful-metadataKEY=VALUE[,KEY=VALUE,...]

Replace the following:

• NAME: the name of the MIG in whichto create an instance
• INSTANCE_NAME: the name of theinstance to create
• KEY andVALUE: statefulmetadata key-value pairs to set individually for the instances inaddition to metadata defined in the instance template
  • The key values that you set here take priority over any conflictingkey values from the instance template

Example

You need to deploy a cluster of nodes,example-cluster, that can operatein one of two modes:active orstandby. You set the mode individuallyfor each VM in a cluster using metadata, for example:mode:active.You also configure how elaborate logging should be for each node, using alogging metadata key that can be set tobasic orelaborate. Theapplication on the node is configured using values from instance metadata.

To create an active node,node-12, with elaborate logging, you would runthe following command:

gcloud compute instance-groups managed create-instance example-cluster \  --instance node-12 \  --stateful-metadata mode=active,logging=elaborate

The command creates a VM,node-12, in theexample-cluster MIG andsets two metadata key-value pairs,mode:active andlogging:elaborate,for the new instance.

Terraform

To create a managed instance with a custom name and to set stateful metadataon that VM, use thegoogle_compute_per_instance_config resource.

The following sample uses a zonal MIG. If you don't have a zonal MIG yet,thencreate a zonal MIG with VMs confined to a single zone.

resource "google_compute_per_instance_config" "default" {  instance_group_manager = google_compute_instance_group_manager.default.name  zone                   = google_compute_instance_group_manager.default.zone  name                   = "node-12"  preserved_state {    metadata = {      mode    = "active"      logging = "elaborate"    }  }}

To learn how to apply or remove a Terraform configuration, seeBasic Terraform commands.

REST

To create one or multiple managed instances in a MIG with custom VM namesand to set stateful metadata individually on these VMs, use one of thefollowing methods:

• For a zonal MIG, use theinstanceGroupManagers.createInstances method.
• For a regional MIG, use theregionInstanceGroupManagers.createInstances method.

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/createInstances{  "instances": [    {      "name": "INSTANCE_NAME",      "preservedState" : {        "metadata": {          "KEY" : "VALUE",          ...        }      }    },    ...  ]}

Replace the following:

• PROJECT_ID: the project ID for the request
• ZONE: thezone where the MIG is located(applies to a zonal MIG)
  • For a regional MIG, replacezones/ZONE withregions/REGION and specify the region ofthe MIG
• NAME: the name of the MIG in which to createan instance
• INSTANCE_NAME: the name of theinstance to create
• KEY andVALUE: statefulmetadata key-value pairs to set individually for the instances inaddition to metadata defined in the instance template
  • The key values that you set here take priority over any conflictingkey values from the instance template

Example

You need to deploy a cluster of nodes,example-cluster, that can operatein one of two modes:active orstandby. You set the mode individuallyfor each VM in a cluster using metadata, for example:mode:active.You also configure how elaborate logging should be for each node, using alogging metadata key that can be set tobasic orelaborate. Theapplication on the node is configured using values from instance metadata.

To create an active node,node-12, with elaborate logging, execute thefollowing method:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/createInstances{  "instances": [    {      "name": "node-12",      "preservedState" : {        "metadata": {          "mode":"active",          "logging":"elaborate"        }      }    }  ]}

The method creates a VM,node-12, in theexample-cluster MIG andsets two metadata key-value pairs,mode:active andlogging:elaborate,for the new instance.

gcloud

To configure stateful metadata individually for a VM instance in a MIG, setor remove stateful metadata in the associated per-instance configuration. If youapply the configuration to the instance at the same time(--update-instance), you can choose whether to keep the instance running,restart it, or recreate it. If you don't apply the configuration(--no-update-instance), your changes don't take effect until yourecreate or update the instance.

If a per-instance configuration doesn't exist for a given instance, use thegcloud compute instance-groups managed instance-configs create commandwith one of the following flags:

gcloud compute instance-groups managed instance-configs createNAME \  --instanceINSTANCE_NAME \  --stateful-metadataKEY=VALUE[,KEY=VALUE,...] \  [--no-update-instance | --update-instance] \  [--instance-update-minimal-actionMINIMAL_ACTION]

If a per-instance configuration already exists for a given instance, use thegcloud compute instance-groups managed instance-configs updatecommand with:

• The--stateful-metadata flag for setting or modifying metadata, or
• The--remove-stateful-metadata flag for removing instance-specificstateful metadata.

gcloud compute instance-groups managed instance-configs updateNAME \  --instanceINSTANCE_NAME \  [--stateful-metadataKEY=VALUE[,KEY=VALUE,...]] \  [--remove-stateful-metadataKEY[,KEY,...]] \  [--no-update-instance | --update-instance] \  [--instance-update-minimal-actionMINIMAL_ACTION]

Replace the following:

• NAME: The name of the managedinstance group.
• INSTANCE_NAME: The name of theinstance for which to configure stateful metadata.
• KEY=VALUE: Stateful metadatakey-value pairs to set individually for the instance in addition to themetadata defined in the instance template. The key values that you sethere take priority over any conflicting key values from the instancetemplate.
• KEY: Instance-specific stateful metadata keys toremove from the per-instance configuration.
  • If a value for the key is not defined by the instance template,the key-value pair is removed completely from the instance when thechange is applied.
  • If a value for the key is defined by the instance template, thevalue from the instance template is set on the instance when thechange is applied.

• MINIMAL_ACTION: Perform at least the specifiedaction when applying the per-instance configuration update to the instance.AMINIMAL_ACTION can only be set when the--update-instance flag is used. The value must be one of thefollowing:

  • none: No action.
  • refresh: Apply updates that are possible to apply withoutstopping the instance.
  • restart: Stop the instance and then start it again.
  • replace: Recreate the instance.

  If omitted, the least disruptive action required by the update is used.

Example

You have a cluster of nodes,example-cluster, that can operate in one oftwo modes:active orstandby. You set the mode individually for eachVM in the cluster using metadata, for example:mode:active. You alsoconfigure how elaborate logging should be for each node, using aloggingmetadata key that can be set tobasic orelaborate. The application oneach node consumes the values from instance metadata.

The instance template definesmode:active andlogging:basic metadata tobe used as default for all instances. You have setlogging:elaborate in aper-instance configuration for thenode-12 VM in the cluster. Now, you want toswitchnode-12 to standby mode and switch logging tobasic for thisVM.

To switch thenode-12 instance to standby and its logging to basic, runthe following command:

gcloud compute instance-groups managed instance-configs update example-cluster \  --instance node-12 \  --stateful-metadata mode=standby \  --remove-stateful-metadata logging

The command does the following:

1. Setsmode:standby metadata in the per-instance configuration that isassociated with the VM,node-12, in theexample-cluster MIG.
2. Removeslogging:elaborate metadata from the per-instance configuration forthenode-12 instance.
3. Applies the per-instance configuration change to thenode-12 VM:
   • Setsmode:standby metadata, according to the configuration.
   • Setslogging:basic metadata from the instance template because thevalue for thelogging key is no longer defined by the per-instanceconfiguration.
4. The change is applied to the VM immediately by default because theflag--no-update-instance is omitted.
5. The VM keeps running during the update because the--instance-update-minimal-action flag is omitted and the leastdisruptive action is chosen for the update by default, in this case:refresh.

REST

To configure stateful metadata individually for existing VM instances in aMIG, set or remove the metadata in the associated per-instance configurations.Then update the instance toapply the configuration.

If per-instance configurations don't yet exist for the given instances, usetheinstanceGroupManagers.updatePerInstanceConfigs methodwith stateful metadata:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/updatePerInstanceConfigs{  "perInstanceConfigs": [    {      "name": "INSTANCE_NAME",      "preservedState" : {        "metadata": {          "KEY": "VALUE",          ...        }      },      "fingerprint: "FINGERPRINT"    },    ...  ]}

If per-instance configurations already exist for the given instances, use theinstanceGroupManagers.patchPerInstanceConfigs method

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceGroupManagers/NAME/patchPerInstanceConfigs{  "perInstanceConfigs": [    {      "name": "INSTANCE_NAME",      "preservedState" : {        "metadata": {          "KEY": "VALUE",          ...        }      },      "fingerprint: "FINGERPRINT"    },    ...  ]}

Replace the following:

• PROJECT_ID: The project ID for the request.
• ZONE: Thezone where the MIG is located(applies to a zonal MIG).
  • For a regional MIG, replacezones/ZONE withregions/REGION and specify the region ofthe MIG.
• NAME: The name of the MIG.
• INSTANCE_NAME: The name of theVM for which to configure stateful metadata.
• KEY andVALUE: Statefulmetadata key-value pairs to set individually for the instances inaddition to any metadata defined in the instance template.
  • Stateful metadata values defined for the keys that alreadyexist in the instance template override the values from theinstance template.
  • Other metadata entries from the instance template remainunaffected and available.
  • Providingnull as a value removes the key from theper-instance configuration.
• FINGERPRINT: (Optional). The fingerprint for thegiven configuration if it already exists. Used for optimistic locking.

TheupdatePerInstanceConfigs andpatchPerInstanceConfigs methods updatethe specified per-instance configurations but don't apply the configuration updates tothe associated VM instances. The changes are applied to a VM when youupdate or recreate the instance. To apply the changes to a VM, youcanapply the update manually or use the Updater in proactive or opportunistic mode.

Example

You have a cluster of nodes,example-cluster, that can operate in one oftwo modes:active orstandby. You set the mode individually for eachVM in the cluster using metadata, for example:mode:active. You alsoconfigure how elaborate logging should be for each node, using aloggingmetadata key that can be set tobasic orelaborate. The application oneach node consumes the values from instance metadata.

The instance template definesmode:active andlogging:basic metadata tobe used as default for all instances. You have setlogging:elaborate in aper-instance configuration for thenode-12 VM in the cluster. Now, you wantto switchnode-12 to standby mode and switch logging tobasic for thisinstance.

To switch thenode-12 VM to standby and its logging to basic, patchthe associated per-instance configuration by using thepatchPerInstanceConfigs method:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/patchPerInstanceConfigs{  "perInstanceConfigs": [    {      "name": "node-12",      "preservedState" : {        "metadata": {          "mode": "standby",          "logging": null        }      }    }  ]}

The method does the following:

1. Setsmode:standby metadata in the per-instance configuration associatedwith the VM,node-12, in theexample-cluster MIG.
2. Removeslogging:elaborate metadata from the per-instance configurationbecause the supplied value isnull.

The configuration update is not yet applied to thenode-12 VM instance. Theconfiguration update will be applied when you next recreate or update the instanceor if you useproactive auto-updating.

To apply the per-instance configuration update to thenode-12 VM instance, calltheinstanceGroupManagers.applyUpdatesToInstances method for the instance:

POST https://compute.googleapis.com/compute/v1/projects/example-project/zones/us-east1-c/instanceGroupManagers/example-cluster/applyUpdatesToInstances{  "instances": ["/zones/us-east1-c/instances/node-12"],  "minimalAction": "NONE"}

The method applies the updated per-instance configuration to thenode-12VM:

1. Setsmode:standby metadata, according to the per-instance configuration.
2. Setslogging:basic metadata from the instance template becausethe value for thelogging key is no longer defined by theper-instance configuration.
3. The VM keeps running during the update becauseminimalAction isset toNONE, which allows the MIG to use the least disruptive actionrequired for the update. An instance metadata update requires theREFRESH action, which does not disrupt a running instance.