Set custom metadata

Linux Windows

Every virtual machine (VM) stores its metadata on a metadata server. For more information about metadata, see VM metadata.

Setting custom metadata is useful for passing in arbitrary values to a single VM or all the VMs in a project. It is also useful for creating startup and shutdown scripts.

This documents shows how to complete the following tasks:

Set and update custom metadata on a single VM
Set custom metadata on all VMs in a project

Before you begin

If you want to use the command-line examples in this guide, do the following:
1. Install or update to the latest version of the Google Cloud CLI.
2. Set a default region and zone.
If you want to use the API examples in this guide, set up API access.

Limitations

Compute Engine enforces a combined total limit of 512 KB for all metadata entries. Maximum size limits are also applied to each key and value as follows:

Each metadata key has a maximum limit of 128 bytes
Each metadata key is case sensitive
Each metadata value has a maximum limit of 256 KB
Each metadata value is case sensitive except for boolean values.

For example, SSH keys are stored as custom metadata under the ssh-keys key. If your metadata content or value for this key exceeds the 256 KB limit, you won't be able to add more SSH keys. If you run into this limit, consider removing unused keys to free up metadata space for new keys.

Also, if you provide the startup or shutdown script contents directly, the contents of these startup and shutdown script contents might also be stored as custom metadata and count toward these size limitations. To avoid this, store your startup or shutdown script as a file hosted at an external location, such as Cloud Storage, and provide the startup script URL when creating a VM. This way, these files are downloaded onto the VM, rather than stored in the metadata server.

Boolean values

For fields that accept boolean values, TRUE or FALSE, the following values can also be used:

Status	Alternative values
TRUE	Y, Yes, 1
FALSE	N, No, 0

Boolean values are not case-sensitive. For example, you can use False, false, or FALSE to disable a feature.

Permissions

To set metadata, the following minimum permissions are required:

compute.instances.setMetadata on the VM
compute.projects.setCommonInstanceMetadata on the project if setting project-wide metadata

You can also use a predefined role. To find predefined roles that contain these permissions, see Compute Engine IAM Roles.

How metadata values are assigned

Project and instance metadata: Metadata can be assigned to both projects and VMs. Project metadata propagates to all VMs within a project, while instance metadata only applies to a single VM.
Directory listings: Some metadata entries are directories that contain other metadata keys. To create a listing, use a trailing slash in the metadata name. For example, my-attributes/ is a directory that contains other metadata keys.

Set custom metadata on a VM

You can set custom metadata for a VM instance using either the Google Cloud console, the Google Cloud CLI, or the Compute Engine API.

Set metadata during VM creation

Use these instructions to set metadata on a specific VM instance.

Console

In the Google Cloud console, go to the Create an instance page.

Go to Create an instance
Specify the VM details.
Expand the Networking, disks, security, management, sole tenancy section, and do the following:
1. Expand the Management section.
2. To add multiple key-value pairs for your custom metadata, in the Metadata section, click Add item.
To create the VM, click Create.

gcloud

To set custom metadata, use the gcloud compute instances create command with the --metadata flag.

gcloud compute instances create VM_NAME \
    --metadata=KEY=VALUE

Replace the following:

VM_NAME: the name of your VM
KEY: the name of your metadata key
VALUE: the value stored for this key

Example

For example to set a new key foo that has a value bar on a VM named example-instance, run the following command:

gcloud compute instances create example-instance \
    --metadata=foo=bar

API

Use the instances.insert method and provide the custom metadata as part of the metadata property in your request:

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

{
  "machineType": "zones/MACHINE_TYPE_ZONE/machineTypes/MACHINE_TYPE",
  "name": "VM_NAME",
   "...": [
        {
        }
   ],
  "metadata": {
    "items": [
      {
       "key": "KEY",
       "value": "VALUE"
      }
    ]
  },
  ..
}

Replace the following:

PROJECT_ID: your project ID
ZONE: zone to create the VM in
MACHINE_TYPE: machine type, predefined or custom, for the new VM
VM_NAME: name of the new VM
KEY: the name of your metadata key
VALUE: the value stored for this key

Updating metadata on a running VM

Use these instructions to update metadata on a specific VM instance..

Console

In the Google Cloud console, go to the VM instances page.
Go to the VM instances page
Click the instance for which you want to update metadata.
Click the Edit button at the top of the page.
Under Custom metadata, click Add item or edit the existing metadata entries.
Save your changes.

gcloud

Updating VM metadata with the gcloud CLI is an additive action. Specify only the metadata keys that you want to add or change. If a key that you provided already exists, the value for that key is updated with the new value.

Use the instances add-metadata command:

gcloud compute instances add-metadata VM_NAME \
    --metadata=KEY=VALUE,KEY=VALUE

Replace the following:

VM_NAME: the name of your VM
KEY: the name of your metadata key
VALUE: the value stored for this key

Examples

If you want to add the foo=bar entry, use:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bar

If you want to change the foo=bar entry to foo=bat, use:

gcloud compute instances add-metadata VM_NAME \
    --metadata=foo=bat

If you want to remove the foo=bar entry, specify the existing key and exclude the value.

gcloud compute instances remove-metadata VM_NAME \
    --keys=foo

API

Get the current fingerprint and view any existing key-value pairs for the VM. To do this, call the instances().get method.

A fingerprint is a random string of characters generated by Compute Engine and is used to perform optimistic locking. To update the VM, you need to provide the matching fingerprint value. The fingerprint changes after each request, and if you provide a mismatched fingerprint, your request is rejected. This works so that only one update can be made at a time, preventing collisions.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME
```
Replace the following:
- PROJECT_ID: your project ID
- ZONE: the zone where your VM is located
- VM_NAME: name of your VM
The output is similar to the following:
```
{
 ...
 "name": "example-instance",
 "metadata": {
  "kind": "compute#metadata",
  "fingerprint": "zhma6O1w2l8="
  "items": [
   {
    "key": "foo",
    "value": "bar"
   }
  ]
 },
 ...
}
```
In the API, make a request to the instances().setMetadata method. Provide a list of the new metadata values and the current fingerprint value.

If the VM has existing key-value pairs that you want to keep, you must include them in this request with the new key-value pairs.

Example
```
POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "zhma6O1w2l8=",
"items": [
 {
  "key": "foo",
  "value": "bar"
 },
 {
  "key": "baz",
  "value": "bat"
 }
]
}
```
Replace the following:
- PROJECT_ID: your project ID
- ZONE: the zone where your VM is located
- VM_NAME: name of your VM

Removing metadata keys

To remove all custom metadata key-value pairs from a VM, specify an instances().setMetadata request and exclude the items property. Note that you must still include the current metadata fingerprint property for an instances().setMetadata request to succeed:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata

{
"fingerprint": "5rC_DXxBUZw="
}

Setting project-wide custom metadata

Use these instructions to apply metadata settings to all VMs in the project. For example, if you define a project-wide metadata pair of baz=bat, that metadata pair is automatically applied to all VMs in the project.

Console

In the Google Cloud console, go to the Metadata page.
Go to the Metadata page
Click Edit.
Add or edit a metadata entry.
Save your changes.

gcloud

Use the project-info add-metadata command.

gcloud compute project-info add-metadata \
    --metadata=KEY=VALUE

Replace the following:

KEY: the name of your metadata key
VALUE: the value stored for this key

Example

For example to set two new entries foo=bar and baz=bat on a project, run the following command:

gcloud compute project-info add-metadata \
    --metadata=foo=bar,baz=bat

You can optionally specify one or more files from which to read metadata by using the --metadata-from-file flag. You can remove metadata values with the project-info remove-metadata command.

API

Optional. To perform optimistic locking, you can optionally provide a fingerprint.

A fingerprint is a random string of characters generated by Compute Engine. The fingerprint changes after each request, and if you provide a mismatched fingerprint, your request is rejected.

If you do not provide a fingerprint, no check for consistency is performed, and the projects().setCommonInstanceMetadata request succeeds. This behaviour is different from instances().setMetadata, where a fingerprint is always required.

To get the current fingerprint of a project, call the project().get method.
```
GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID
```
The output is similar to the following:
```
{
 "name": "myproject",
 "commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "FikclA7UBC0=",
  ...
}
```

Make a request to the projects().setCommonInstanceMetadata method and set your custom metadata key-value pairs:

POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/setCommonInstanceMetadata

{
 "fingerprint": "FikclA7UBC0=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  }
 ]
}

Replace PROJECT_ID with your your project ID.

What's next

Learn more about VM metadata.
Learn how to query metadata.
Learn more about running startup scripts or shutdown scripts in the metadata server.