Setting custom metadata


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:

Before you begin

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 value has a maximum limit of 256 KB

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 gcloud command-line tool, or the Compute Engine API.

Set metadata during VM creation

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

Console

  1. In the Cloud Console, go to the VM instances page.

    Go to VM instances

  2. Click Create instance.
  3. On the Create a new instance page, fill in the properties for your instance.
  4. In the Metadata section, fill in as many key-value pairs for your custom metadata as you need.
  5. Click Create to create the instance.

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

  1. In the Google Cloud Console, go to the VM instances page.

    Go to the VM instances page

  2. Click the instance for which you want to update metadata.
  3. Click the Edit button at the top of the page.
  4. Under Custom metadata, click Add item or edit the existing metadata entries.
  5. Save your changes.

gcloud

Updating VM metadata with the gcloud tool 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

  1. 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"
       }
      ]
     },
     ...
    }
    
  2. 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
    
    {
    "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

{
"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

  1. In the Google Cloud Console, go to the Metadata page.

    Go to the Metadata page

  2. Click Edit.
  3. Add or edit a metadata entry.
  4. 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

  1. 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=",
      ...
    }
    
  2. 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