Set and remove custom metadata (original) (raw)

Linux Windows

Each metadata entry is stored on the metadata server as key-value pairs. Metadata keys are case sensitive. Your keys can be either predefined or custom metadata keys.

Custom metadata enables you to create and use your own metadata key-value pairs on an individual VM or a project. You can add new custom metadata keys, update the values of your existing keys, and remove any custom metadata entries when you don't need them. Setting custom metadata is useful for passing in arbitrary values to VMs in a project. It is also useful for creatingstartup andshutdown scripts.

This document provides information about how to do the following:

Before you begin

Required roles

To get the permissions that you need to set or remove custom metadata on VMs, ask your administrator to grant you the following IAM roles:

For more information about granting roles, see Manage access to projects, folders, and organizations.

These predefined roles contain the permissions required to set or remove custom metadata on VMs. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to set or remove custom metadata on VMs:

You might also be able to get these permissions with custom roles or other predefined roles.

Limitations

VM metadata entries have the following limitations.

Size limitations

Compute Engine enforces a combined total limit of 512 KB for all metadata entries. Maximum size limits are also applied to each key andvalue in the following way:

For example, SSH keys are stored as custom metadata under the ssh-keyskey. 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 keysto free up metadata space for new keys.

Also, if you provide the startup or shutdown script contents directly, then 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.

String case limitations

Zonal metadata limitations

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.

This section explains how to add new custom metadata, or update existing custom metadata values, for your Compute Engine VMs in one of the following ways:

Set custom project metadata

You can add or update the custom metadata for all instances in a project by using the Google Cloud console, the Google Cloud CLI, or REST.

Use these instructions to apply metadata settings to all VMs in the project. For example, if you define a project 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 Custom metadata page
  2. Click Edit at the top of the page.
  3. To add new custom project metadata entries, do the following:
    1. Navigate to the bottom of the page and clickAdd item.
    2. In the Key field, enter the name of your custom metadata key.
    3. In the Value field, enter the custom project metadata value.
    4. Optional. To add more custom project metadata entries, repeat the preceding steps for each metadata entry that you want to add.
    5. To finish adding your custom project metadata entries, clickSave.
  4. To edit existing custom project metadata entries, do the following:
    1. Navigate to that metadata entry that you want to edit.
    2. To update the name of a specific custom metadata key, in theKey field for that entry, enter the new name.
    3. To update the value of a custom project metadata entry, in theValue field for that entry, enter the new value.
    4. Optional. To remove a specific custom project metadata entry, click the delete icon next to the metadata entry.
    5. To edit multiple custom project metadata entries, repeat the preceding steps for each metadata entry that you want to edit.
    6. To finish editing your custom project metadata entries, clickSave.

gcloud

Use theproject-info add-metadata command.

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

Replace the following:

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.

REST

  1. Optional. To perform optimistic locking, you can 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 don't provide a fingerprint, no check for consistency is performed, and the projects().setCommonInstanceMetadata request succeeds. This behaviour is different from instances().setMetadata andinstanceSettings().patch methods, where a fingerprint is always required.
    To get the current fingerprint of a project, call theproject().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 theprojects().setCommonInstanceMetadata methodand 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.

Set custom zonal metadata

When you set custom zonal metadata, you add or update the zonal metadata entries for your VMs in a specific zone in a project. You can do the following by setting custom zonal metadata:

Things to note before you set custom zonal metadata

Project and zonal metadata entries are stored in the sameproject/ directory. If you set different values for the same custom metadata keys for VMs on a project level and on a zonal level, then the zonal metadata values for those keys take precedence over the project metadata values in the respective zones.

Procedure

You can add or update the custom zonal metadata in a specific zone in a project by using the Google Cloud CLI or REST.

gcloud

Example: Add a new custom zonal metadata entry

For example, consider a project called my-project with the following custom metadata:

To add "key-4":"value-4" as a new custom zonal metadata pair in the us-central1-a zone, run the following command

gcloud compute project-zonal-metadata add
--metadata=key-4=value-4
--project=my-project
--zone=us-central1-a

Example: Update the values of an existing custom zonal metadata entry

Consider the same example project my-project, which now has the following custom metadata:

To update the zonal metadata values of key-1 and key-4in us-cerntral1-a zone with new values, run the following command.

gcloud compute project-zonal-metadata add
--metadata=key-1=new-value-1,key-4=new-value-4
--project=my-project
--zone=us-central1-a

Example: Override the project metadata value for a key and use a zonal metadata value

Consider the same example project my-project, which now has the following custom metadata:

In this example project, consider key-3, which has a project metadata value of value-c. Suppose you want to set a zonal metadata valuevalue-3 for this key for all VMs in the us-central1-a zone. When you perform the operation, for all the VMs in the us-central1-a zone, Compute Engine overrides the project metadata values and uses the zonal metadata values. VMs in all other zones of the project retain their prevailing project or zonal metadata values for key-3.

To override the project metadata value for key-3 and set a zonal metadata value, run the following command:

gcloud compute project-zonal-metadata add
--metadata=key-3=value-3
--project=my-project
--zone=us-central1-a

REST

  1. Get the current fingerprint and view any existing key-value pairs for the project in that zone.
    To perform optimistic locking, you must provide a fingerprint. A fingerprint is a random string of characters generated by Compute Engine. The fingerprint changes every time you make a request to add, update, or remove zonal metadata, and if you provide a mismatched fingerprint, Compute Engine rejects your request.
    If you don't provide a fingerprint, a check for consistency is performed and your update request doesn't succeed. This works so that only one request can be made at a time, preventing collisions. This behavior matches instances().setMetadata, where a fingerprint is always required.
    To get the current fingerprint of the zonal metadata, make a GETrequest to theinstanceSettings().get method.
    GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings
    Replace the following:
    • PROJECT_ID: your project ID
    • ZONE: the zone where you want to set the zonal metadata.
      The following is an example output for this request:
      {
      "fingerprint": "VlRIl8dx9vk=",
      "metadata": {
      ...
      }
      }
  2. To add or update the zonal metadata, make a PATCH request to the instanceSettings().patch method. You must provide the following with your request:
    • An update mask. Use the update_mask query parameter. The update mask must contain the metadata keys for the following:
      * The new custom zonal metadata that you want to add
      * The existing custom zonal metadata for which you want to update values

    You must add the string metadata.items. as a prefix for each key—for example,metadata.items.key1,metadata.items.key3.

    • In the request body, provide the following:
      * The metadata keys and values for the new custom zonal metadata that you want to add
      * The metadata keys and values for the existing custom zonal metadata that you want to update
      * The current fingerprint value

PATCH https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instanceSettings?**update_mask**=PREFIXED_METADATA_KEYS
{
"fingerprint": "FINGER_PRINT",
"metadata": {
"items": {
"KEY1": "VALUE1",
"KEY2": "VALUE2",
...
}
}
}
Replace the following:

For example, suppose your current zonal metadata keys in a specific zone are key-1 and key-2. If you want to add a new key, key-3, for zonal metadata in that zone and also update the zonal metadata for one of the existing keys, key-1, then your update mask must have the following string:
metadata.items.key1,metadata.items.key3

Example: Add a new custom zonal metadata entry

For example, consider a project called my-project with the following custom metadata:

To add "key-4":"value-4" as a new custom zonal metadata pair in the us-central1-a zone, make the following PATCH request:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-4 { "fingerprint": "VlRIl8dx9vk=", "metadata": { "items": { "key-4": "value-4" } } }

Example: Update the values of an existing custom zonal metadata entry

Consider the same example project my-project, which now has the following custom metadata:

To update the zonal metadata values of key-1 and key-4in us-cerntral1-a zone with new values, make the following PATCH request:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-4 { "fingerprint": "VlRIl8dx9vk=", "metadata": { "items": { "key-1": "new-value-1", "key-4": "new-value-4" } } }

Example: Override the project metadata value for a key and set a zonal metadata value

Consider the same example project my-project, which now has the following custom metadata:

In this example project, consider key-3, which has a project metadata value of value-c. Suppose you want to set a zonal metadata valuevalue-3 for this key for all VMs in the us-central1-a zone. When you perform the operation, for all the VMs in the us-central1-a zone, Compute Engine overrides the project metadata values and uses the zonal metadata values. VMs in all other zones of the project retain their prevailing project or zonal metadata values for key-3.

To override the project metadata value for key-3 and use the zonal metadata value value-3 instead, make the following PATCH request:

PATCH https://compute.googleapis.com/compute/v1/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-3 { "fingerprint": "VlRIl8dx9vk=", "metadata": { "items": { "key-3": "value-3" } } }

Set custom instance metadata

You can add or update the custom metadata for a single VM instance by using the Google Cloud console, the Google Cloud CLI, or REST.

You can set custom instance metadata in one of the following ways:

Add custom instance metadata during VM creation

Use these instructions to add metadata on a specific VM instance at the time of its creation.

Console

  1. In the Google Cloud console, go to the Create an instance page.
    Go to Create an instance
  2. Specify the VM details.
  3. Expand the Advanced options section, and do the following:
    1. Expand the Management section.
    2. To add multiple key-value pairs for your custom metadata, in theMetadata section, click Add item.
  4. To create the VM, click Create.

gcloud

To set custom metadata, use thegcloud compute instances create commandwith the --metadata flag.

gcloud compute instances create VM_NAME
--zone=ZONE
--image-project=IMAGE_PROJECT
IMAGE_FLAG
--metadata=KEY=VALUE

Replace the following:

Example

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

gcloud compute instances create example-instance
--zone=us-central1-a --image-project=debian-cloud
--image-family=debian-12
--metadata=env=test

REST

Use theinstances.insert methodand 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:

Add or update custom instance metadata on an existing VM

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

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 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 theinstances add-metadata command:

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

Replace the following:

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

REST

  1. Get the current fingerprint and view any existing key-value pairs for the VM. To do this, call theinstances().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. Make a request to the instances().setMetadata method. Provide a list of the new metadata values and the current fingerprintvalue.
    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

This section provides information about how to remove custom metadata entries for your Compute Engine VMs in one of the following ways:

Remove custom project metadata

You can remove custom project metadata by using the Google Cloud console or the Google Cloud CLI.

Console

  1. In the Google Cloud console, go to the Metadata page.
    Go to the Metadata page
  2. Click Edit at the top of the page.
  3. Navigate to the metadata entry that you want to remove and click the delete button next to that entry.
    Repeat this step for each metadata entry that you want to remove.
  4. To finish removing the custom project metadata entries, click Save.

gcloud

To remove custom project metadata, use thegcloud compute project-info remove-metadata command.

gcloud compute project-info remove-metadata
--keys=KEY1,KEY2,...

gcloud compute project-info remove-metadata
--all

Replace the following:

Remove custom zonal metadata

You can remove custom zonal metadata by using the Google Cloud CLI or REST.

gcloud

To remove custom zonal metadata, use thegcloud compute project-zonal-metadata remove commandand specify all the metadata keys that you want to remove by using the--keys flag.

gcloud compute project-zonal-metadata remove
--project=PROJECT_ID
--zone=ZONE
--keys=KEY1,KEY2,...

Replace the following:

After you run the command, if any of the specified keys have project metadata values available, then the VMs in the specified zone inherit those project metadata values. If the metadata entry was set only at a zonal level and there isn't a corresponding project metadata value for that key, then VMs in that zone lose that metadata information.

Example:

Consider an example project my-project, which has the following custom project metadata:

To remove all the zonal metadata in the us-central1-a zone, run the following command.

gcloud compute project-zonal-metadata remove
--metadata=key-1,key-2,key-3,key-4
--project=my-project
--zone=us-central1-a

After you run the command, VMs in the us-central1-a zone possess the following custom project metadata entries:

REST

  1. Get the current fingerprint and view any existing key-value pairs for the project in that zone.
    To perform optimistic locking, you must provide a fingerprint. A fingerprint is a random string of characters generated by Compute Engine. The fingerprint changes every time you make a request to add, update, or remove zonal metadata, and if you provide a mismatched fingerprint, Compute Engine rejects your request.
    If you don't provide a fingerprint, a check for consistency is performed and your deletion request doesn't succeed. This works so that only one request can be made at a time, preventing collisions. This behavior matches instances().setMetadata, where a fingerprint is always required.
    To get the current fingerprint of a project, make a call theinstanceSettings().get method.
    GET https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings
    Replace the following:
    • PROJECT_ID: your project ID
    • ZONE: the zone where you want to remove the zonal metadata.
      The following is an example output for this request:
      {
      "fingerprint": "FikclA7UBC0=",
      "metadata": {
      ...
      }
      }
  2. To remove custom zonal metadata, make a PATCH request to the instanceSettings().patch methodby excluding the metadata keys, for which you want to remove the zonal metadata, from the request body. You must provide the following with your request:
    • An update mask. Use the update_mask query parameter. The update mask must contain all the existing custom metadata keys for which you want to remove the zonal metadata. You must add the stringmetadata.items. as a prefix for each key—for example, metadata.items.key1,metadata.items.key3.
    • In the request body, provide only the current fingerprint value. Exclude all the custom metadata keys that you specified in the update mask. If you include any of the metadata keys in both the update mask and the request body, then Compute Engine doesn't remove the zonal metadata for those keys.
      PATCH https://compute.googleapis.com/compute/beta/projects/PROJECT_ID/zones/ZONE/instanceSettings?**update_mask**=PREFIXED_METADATA_KEYS
      {
      "fingerprint": "FINGER_PRINT",
      "metadata": {
      "items": {
      }
      }
      }
      Replace the following:
    • PROJECT_ID: the ID of the project.
    • ZONE: the zone where you want to remove the zonal metadata.
    • PREFIXED_METADATA_KEYS: the list of all the existing custom metadata keys for which you want to remove zonal metadata, where each key is prefixed with the stringmetadata.items.. To ensure that your deletion request is successful, exclude these metadata keys from the request body. If you include any of the metadata keys in both the update mask and the request body, then Compute Engine doesn't remove the zonal metadata for those keys.
      For example, suppose your current metadata keys with zonal metadata are key-1, key-2, key-3, and key-4, and you want to remove the zonal metadata entries for key-1 and key-2, then your update mask must have the following string:
      metadata.items.key1,metadata.items.key2
    • FINGER_PRINT: the current fingerprint value.

After you make the request, if any of the specified keys have project metadata values available, then the VMs in the specified zone inherit those project metadata values. If the metadata key was set only at a zonal level and there isn't a corresponding project metadata value for that key, then VMs in that zone lose that metadata information.

Example:

Consider an example project my-project, which has the following custom project metadata:

To remove the zonal metadata for key-1 and key-2 in theus-central1-a zone, make the following PATCH request.

PATCH https://compute.googleapis.com/compute/beta/projects/my-project/zones/us-central1-a/instanceSettings?update_mask=metadata.items.key-1,metadata.items.key-2 { "fingerprint": "FikclA7UBC0=", "metadata": { "items": { } } }

After this request goes through, VMs in the us-central1-a zone possess the following custom metadata. VMs inherit the project metadata values forkey-1 and key-2, but retain the zonal metadata for key-3 and key-4.

Remove custom instance metadata

You can remove custom instance metadata by using the Google Cloud console, the Google Cloud CLI or REST.

Console

  1. In the Google Cloud console, go to the VM instances page.
    Go to the VM instances page
  2. In the Name column, click the name of the VM for which you want to remove metadata.
  3. Click Edit at the top of the page.
  4. In the Metadata section, clickDelete item for each of the metadata entries that you want to remove.
  5. To confirm your changes and remove the custom instance metadata, clickSave.

gcloud

To remove custom instance metadata, use thegcloud compute instances remove-metadata command.

gcloud compute instances remove-metadata VM_NAME
--zone=ZONE
--keys=KEY1,KEY2,...

gcloud compute instances remove-metadata VM_NAME
--zone=ZONE
--all

Replace the following:

REST

  1. Get the current fingerprint and view any existing key-value pairs for the VM. To do this, call theinstances().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 of your VM.
    • VM_NAME: name of your VM
      The output is similar to the following:
      {
      ...
      "name": "example-instance",
      "metadata": {
      "kind": "compute#metadata",
      "fingerprint": "zhma6O1w2l8="
      "items": [
      {
      "key": "key-1",
      "value": "value-1"
      }
      {
      "key": "key-2",
      "value": "value-2"
      }
      ]
      },
      ...
      }
  2. Make a request to the instances().setMetadata method. You must include the current metadata fingerprint value for your request to succeed.

What's next