Set and remove custom metadata

Linux Windows

Each metadata entry is stored on the metadata server as key-valuepairs. Metadata keys are case sensitive. Your keys can be either predefinedor custom metadata keys.

Custom metadata enables you to create and use your own metadata key-value pairs onan individual VM or a project. You can add new custom metadata keys, update the values of yourexisting 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 aproject. 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, seeManage 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 theRequired permissions section:

Required permissions

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

  • If your VMs use service accounts:iam.serviceAccounts.actAs on the service accounts or project
  • To add, update, or remove custom project metadata:
    • compute.projects.get on the project
    • compute.projects.setCommonInstanceMetadata on the project
  • To add, update, or remove custom zonal metadata:
    • compute.instanceSettings.get on the instance settings in the required zone in the project
    • compute.instanceSettings.update on the instance settings in the required zone in the project
  • To add, update, or remove custom instance metadata:
    • compute.instances.get on the VM
    • compute.instances.setMetadata on the VM

You might also be able to get these permissions withcustom roles or otherpredefined roles.

Limitations

VM metadata entries have the following limitations.

Size limitations

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

  • Each metadatakey has a maximum limit of 128 bytes.
  • Each metadatavalue has a maximum limit of 256 KB.

For example, SSH keys are stored as custom metadata under thessh-keyskey. If your metadata content orvalue for this key exceeds the 256 KBlimit, you won't be able to add more SSH keys. If you run into this limit,considerremoving unused keysto free up metadata space for new keys.

Also, if you provide the startup or shutdown script contents directly, then thecontents of these startup and shutdown script contents might also be stored ascustom metadata and count toward these size limitations.To avoid this, store your startup or shutdown script as a file hosted at anexternal location, such as Cloud Storage, and provide the startup script URLwhen creating a VM. This way, these files are downloaded onto the VM, ratherthan stored in the metadata server.

String case limitations

  • Each metadatakey is case sensitive.

  • Each metadatavalue is case sensitive except for boolean values.

Zonal metadata limitations

  • You can set and remove zonal metadata only by using the gcloud CLIor REST.

  • You can't create two separate metadata keys with the same string,even if the keys are written in different cases. For example, if a custommetadata key namedzonal-metadata-key already exists for zonal metadatawithin a specific zone, then you can't create new zonal metadata keys that arevariations of the same string, such asZonal-Metadata-Key orZONAL-METADATA-KEY.

  • You can't set zonal metadata values for SSH keys, which are stored as custommetadata under thessh-keys key.

Boolean values

For fields that accept boolean values,TRUE orFALSE, the following valuescan also be used:

StatusAlternative values
TRUEY,Yes,1
FALSEN,No,0

Boolean values are not case-sensitive. For example, you can useFalse,false,orFALSE to disable a feature.

Set custom metadata on VMs

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

Set custom project metadata

You can add or update the custom metadata for all instances in a project byusing 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 ofbaz=bat,that metadata pair is automatically applied to all VMs in the project.

Console

  1. In the Google Cloud console, go to theMetadata page.

    Go to the Custom metadata page

  2. ClickEdit at the topof 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 theKey field, enter the name of your custom metadata key.
    3. In theValue field, enter the custom project metadata value.
    4. Optional. To add more custom project metadata entries, repeat thepreceding 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 iconnext to the metadata entry.
    5. To edit multiple custom project metadata entries, repeat thepreceding 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:

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

Example

For example to set two new entriesfoo=bar andbaz=bat on a project, runthe following command:

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

You can optionally specify one or more files from which to readmetadata by using the--metadata-from-file flag.

REST

Note: If usingcurl orInvoke-RestMethod to set project metadata,then add theContent-Type:application/json header to the request.

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

    A fingerprint is a random string of characters generated byCompute Engine. The fingerprint changes after each request, andif you provide a mismatched fingerprint, your request is rejected.

    If you don't provide a fingerprint, no check for consistency is performed,and theprojects().setCommonInstanceMetadata request succeeds. Thisbehaviour is different frominstances().setMetadata andinstanceSettings().patch methods, where a fingerprint is alwaysrequired.

    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"    }  ]}

ReplacePROJECT_ID with your your project ID.

Set custom zonal metadata

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

  • Create new custom metadata keys for a specific zone in a project and setmetadata for all VMs in that zone in that project.
  • Update the values of existing custom zonal metadata entries for all VMs in aspecific zone in a project.
  • For existing custom metadata keys that have project metadata values, overridethose project metadata values in specific zones and instead set zonalmetadata. After you set zonal metadata for those keys in a specific zone, allVMs in that zone in that project use the zonal metadata values for those keys.

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 custommetadata keys for VMs on a project level and on a zonal level, then thezonal metadata values for those keys take precedence over theproject metadata values in the respective zones.

  • If you add a zonal metadata value for a metadata key that alreadyhas a project metadata value, then Compute Engine overrides the project metadatavalue for the VMs in this specified zone and updates the/project directorywith the zonal value.
  • If you add a new project metadata value for a metadata key that alreadyhas a zonal metadata value, then nothing changes. Compute Engine retains thezonal metadata value in the/project directory in the specific zone.
  • If you don't specify a zonal metadata value for a custom metadata key in aspecific zone, but the key has a project metadata value, then your VMs continue tohave the project metadata values in those zones.

Procedure

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

gcloud

  • To add or update custom zonal metadata, use thegcloud compute project-zonal-metadata add command.

    gcloud compute project-zonal-metadata add \  --zone=ZONE \  --project=PROJECT_ID  \  --metadata=KEY1=VALUE1,KEY2=VALUE2,...

    Replace the following:

    • PROJECT_ID: your project ID
    • ZONE: the zone where you want to add or updatezonal metadata.
    • KEY1,KEY2...:the custom metadata keys for which you want to add or update zonalmetadata values.

    • VALUE1,VALUE2...:the zonal metadata values that you want to set for yourexisting and new custom metadata keys. Depending on your custommetadata key and value, one of the following happens:

    • If the corresponding custom metadata key is an existing key that hasproject metadata, then, in the specified zone, Compute Engineoverrides the key's project metadata value with your specified zonalmetadata value. All VMs in the specified zone in the project inheritthis newly specified zonal metadata for that key and VMs in otherzones continue to retain their prevailing project or zonal metadatavalues. If you make any future updates to the project metadata valuefor this key, then VMs in this zone in the project remain unaffectedand continue to use the zonal metadata value for this key.

    • If the corresponding custom metadata key is a new metadata key that isnot used for existing project or zonal metadata, thenCompute Engine creates the custom metadata key and setsthis value as the zonal metadata in the specified zone.

    • If the corresponding custom metadata key is an existing metadata keywith a zonal metadata value in the specified zone:

      • If the specified metadata value is a different from the existingvalue, then Compute Engine updates the zonal metadata entrywith the new value.
      • If the specified metadata value is same as the existing value, thenthe zonal metadata entry remains unchanged.

Example: Add a new custom zonal metadata entry

For example, consider a project calledmy-project with the followingcustom metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"value-1"and"key-2":"value-2"

To add"key-4":"value-4" as a new custom zonal metadata pair intheus-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 projectmy-project, which now has thefollowing custom metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"value-1","key-2":"value-2", and"key-4":"value-4"

To update the zonal metadata values ofkey-1 andkey-4inus-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
Note: Forkey-1, which has different values set at project and zonallevels, only the zonal metadata value gets updated after you run the command.The project metadata value forkey-1 remains unchanged. Inthe future, if you delete the zonal metadata entry forkey-1, thenthe VMs in the zone inherit the project metadata value for this key.

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

Consider the same example projectmy-project, which now has thefollowing custom metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"new-value-1","key-2":"value-2", and"key-4":"new-value-4"

In this example project, considerkey-3, which has a project metadatavalue ofvalue-c. Suppose you want to set a zonal metadata valuevalue-3 for this key for all VMs in theus-central1-a zone. When youperform the operation, for all the VMs in theus-central1-a zone,Compute Engine overrides the project metadata values and uses thezonal metadata values. VMs in all other zones of the project retain theirprevailing project or zonal metadata values forkey-3.

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

gcloud compute project-zonal-metadata add \    --metadata=key-3=value-3 \    --project=my-project \    --zone=us-central1-a
Note: If you subsequently update the value forkey-3 on a projectlevel, then your update doesn't get added to the/project/attributesdirectory of the metadata server in theus-central1-a zone. If you wantyour future project metadata value update forkey-3 to get posted tothe/project/attributes folder in theus-central1-a zone, then you mustfirst remove the zonal metadata entry.

REST

Note: If you're usingcurl orInvoke-RestMethod to set zonalmetadata, then add theContent-Type:application/json header tothe request.

  1. Get the current fingerprint and view any existing key-value pairs forthe project in that zone.

    To perform optimistic locking, you must provide a fingerprint.A fingerprint is a random string of characters generated byCompute Engine. The fingerprint changes every time you make arequest to add, update, or remove zonal metadata, and if youprovide a mismatched fingerprint, Compute Engine rejects your request.

    If you don't provide a fingerprint, a check for consistency isperformed and your update request doesn't succeed. This works so thatonly one request can be made at a time, preventing collisions. Thisbehavior matchesinstances().setMetadata, where a fingerprint isalways required.

    To get the current fingerprint of the zonal metadata, make aGETrequest 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 thezonal metadata.

    The following is an example output for this request:

        {      "fingerprint": "VlRIl8dx9vk=",      "metadata": {        ...      }    }

  2. To add or update the zonal metadata, make aPATCH request totheinstanceSettings().patch method.You must provide the following with your request:

    Caution: If you specify any existing custom zonal metadata keys inthe update mask but don't include them in the request body, thenCompute Engine removes those zonal metadata entries. For moreinformation, seeRemove custom zonal metadata.

    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:

    • PROJECT_ID: the ID of the project.
    • ZONE: the zone where you want to set thezonal metadata.

    • PREFIXED_METADATA_KEYS: the list ofmetadata keys for the following, where each key is prefixed with thestringmetadata.items.:

      • The new custom zonal metadata that you want to add
      • The existing custom zonal metadata for which you want toupdate values

      For example, suppose your current zonal metadata keys in a specificzone arekey-1 andkey-2. If you want to add a new key,key-3,for zonal metadata in that zone and also update the zonal metadata forone of the existing keys,key-1, then your update mask must have thefollowing string:

      metadata.items.key1,metadata.items.key3

    • FINGER_PRINT: the current fingerprint value.

    • KEY1,KEY2...:the custom zonal metadata keys for which you want to add orupdate values. Specify all the custom zonal metadata keys thatyou specified in the update mask.

      Caution: If you specify any existing custom zonal metadata keys inthe update mask but don't include them in the request body, thenCompute Engine removes those zonal metadata entries. For moreinformation, seeRemove custom zonal metadata.

    • VALUE1,VALUE2...:the zonal metadata values that you want to set for yourexisting and new custom metadata keys. Depending on your custommetadata key and value, one of the following happens:

      • If the corresponding custom metadata key is an existing key that hasproject metadata, then, in the specified zone, Compute Engineoverrides the key's project metadata value with your specified zonalmetadata value. All VMs in the specified zone in the project inheritthis newly specified zonal metadata for that key and VMs in otherzones continue to retain their prevailing project or zonal metadatavalues. If you make any future updates to the project metadata valuefor this key, then VMs in this zone in the project remain unaffectedand continue to use the zonal metadata value for this key.
      • If the corresponding custom metadata key is a new metadata key thatis not used for existing project or zonal metadata, thenCompute Engine creates the custom metadata key and setsthis value as the zonal metadata in the specified zone.

      • If the corresponding custom metadata key is an existing metadata keywith a zonal metadata value in the specified zone:

      • If the specified metadata value is a different from the existingvalue, then Compute Engine updates the zonal metadataentry with the new value.

      • If the specified metadata value is same as the existing value,then the zonal metadata entry remains unchanged.

Example: Add a new custom zonal metadata entry

For example, consider a project calledmy-project with the followingcustom metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"value-1"and"key-2":"value-2"

To add"key-4":"value-4" as a new custom zonal metadata pair intheus-central1-a zone, make the followingPATCH 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 projectmy-project, which now has thefollowing custom metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"value-1","key-2":"value-2", and"key-4":"value-4"

To update the zonal metadata values ofkey-1 andkey-4inus-cerntral1-a zone with new values, make the followingPATCH 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"    }  }}
Note: Forkey-1, which has different values set at project andzonal levels, only the zonal metadata value gets updated after you run thecommand. The project metadata value forkey-1 remains unchanged. Inthe future, if you delete the zonal metadata entry forkey-1, thenthe VMs in the zone inherit the project metadata value.

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

Consider the same example projectmy-project, which now has thefollowing custom metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"new-value-1","key-2":"value-2", and"key-4":"new-value-4"

In this example project, considerkey-3, which has a project metadatavalue ofvalue-c. Suppose you want to set a zonal metadata valuevalue-3 for this key for all VMs in theus-central1-a zone. When youperform the operation, for all the VMs in theus-central1-a zone,Compute Engine overrides the project metadata values and uses thezonal metadata values. VMs in all other zones of the project retain theirprevailing project or zonal metadata values forkey-3.

To override the project metadata value forkey-3 and use the zonalmetadata valuevalue-3 instead, make the followingPATCH 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"    }  }}
Note: If you subsequently update the value forkey-3 on a projectlevel, then your update doesn't get added to the/project/attributesdirectory of the metadata server in theus-central1-a zone. If you wantyour future project metadata value update forkey-3 to get posted tothe/project/attributes folder in theus-central1-a zone, then you mustfirst remove the zonal metadata entry.

Set custom instance metadata

You can add or update the custom metadata for a single VM instance by usingthe 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 ofits creation.

Console

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

    Go to Create an instance

  2. Specify the VM details.

  3. Expand theAdvanced options section, and do thefollowing:

    1. Expand theManagement section.
    2. To add multiple key-value pairs for your custom metadata, in theMetadata section, clickAdd item.

  4. To create the VM, clickCreate.

gcloud

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

gcloud compute instances createVM_NAME \--zone=ZONE \--image-project=IMAGE_PROJECT \IMAGE_FLAG \--metadata=KEY=VALUE

Replace the following:

  • VM_NAME: the name of your VM
  • ZONE: the zone to create the VM in
  • IMAGE_PROJECT: theproject containing theimage to use for the VM

  • IMAGE_FLAG: specify one of the following:

    • Use the--imageIMAGE_NAME flag to specifya specific version of a public image.

      For example,--image debian-12-bookworm-v20241112.

    • Use the--image-familyIMAGE_FAMILY_NAME flagto specify animage family.

      This creates the VM from the most recent non-deprecated OS imagein the image family. For example, if youspecify--image-family debian-12,Compute Engine uses the latest version of the OS image in theDebian 12 image family.

  • KEY: the name of your metadata key

  • VALUE: the value stored for this key

Example

For example to set a new keyenv that has a valuetest on aVM namedexample-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 themetadata property inyour 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,predefinedorcustom,for the new VM
  • VM_NAME:name of the newVM
  • KEY: the name of your metadata key
  • VALUE: the value stored for this key

Add or update custom instance metadata on an existing VM

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

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to the VM instances page

  2. Click the instance for which you want to update metadata.
  3. Click theEdit button at the top of the page.
  4. UnderCustom metadata, clickAdd item or edit the existingmetadata entries.
  5. Save your changes.

gcloud

Updating VM metadata with the gcloud CLI is an additiveaction. Specify only the metadata keys that you want to add or change. Ifa key that you provided already exists, the value for that key is updatedwith the new value.

Use theinstances add-metadata command:

gcloud compute instances add-metadataVM_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 thefoo=bar entry, use:

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

If you want to change thefoo=bar entry tofoo=bat, use:

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

REST

Note: If usingcurl orInvoke-RestMethod to update metadata on a VM,then add theContent-Type:application/json header to the request.

  1. Get the current fingerprint and view any existing key-valuepairs for the VM. To do this, call theinstances().get method.

    A fingerprint is a random string of characters generated byCompute Engine and is used to perform optimistic locking. To update theVM, you need to provide the matching fingerprint value. The fingerprintchanges after each request, and if you provide a mismatched fingerprint,your request is rejected. This works so that only one update can be madeat 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 theinstances().setMetadata method.Provide a list of the new metadata values and the currentfingerprintvalue.

    If the VM has existing key-value pairs that you want to keep, you mustinclude 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

Remove custom metadata from VMs

This section provides information about how to remove custom metadata entriesfor 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 theGoogle Cloud CLI.

Console

  1. In the Google Cloud console, go to theMetadata page.

    Go to the Metadata page

  2. ClickEdit at the top ofthe page.

  3. Navigate to the metadata entry that you want to remove and click the delete button next to thatentry.

    Repeat this step for each metadata entry that you want to remove.

  4. To finish removing the custom project metadata entries, clickSave.

gcloud

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

  • If you want to remove the custom metadata entries for specific keys,specify those keys by using the--keys flag, and exclude the values ofthose keys.
gcloud compute project-info remove-metadata \--keys=KEY1,KEY2,...
  • If you want to remove all custom metadata for the VM, specify the--allflag.
gcloud compute project-info remove-metadata \--all

Replace the following:

  • KEY1,KEY2...:the custom instance metadata keys that you want to remove.

Remove custom zonal metadata

You can remove custom zonal metadata by usingthe 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:

  • PROJECT_ID: your project ID
  • ZONE: the zone where you want to remove thezonal metadata.
  • KEY1,KEY2...:the custom zonal metadata keys that you want to remove.

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

Example:

Consider an example projectmy-project, which has the following customproject metadata:

  • Project metadata:"key-1":"value-a","key-2":"value-b", and"key-3":"value-c"
  • Zonal metadata inus-central1-a zone:"key-1":"new-value-1","key-2":"value-2","key-3":"value-3", and"key-4":"new-value-4"

To remove all the zonal metadata in theus-central1-a zone, run thefollowing 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 theus-central1-a zone possess thefollowing custom project metadata entries:

  • "key-1":"value-a"
  • "key-2":"value-b"
  • "key-3":"value-c"

REST

  1. Get the current fingerprint and view any existing key-value pairs forthe project in that zone.

    To perform optimistic locking, you must provide a fingerprint.A fingerprint is a random string of characters generated byCompute Engine. The fingerprint changes every time you make arequest to add, update, or remove zonal metadata, and if youprovide a mismatched fingerprint, Compute Engine rejects your request.

    If you don't provide a fingerprint, a check for consistency isperformed and your deletion request doesn't succeed. This works so thatonly one request can be made at a time, preventing collisions. Thisbehavior matchesinstances().setMetadata, where a fingerprint isalways 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 thezonal metadata.

    The following is an example output for this request:

        {      "fingerprint": "FikclA7UBC0=",      "metadata": {        ...      }    }

  2. To remove custom zonal metadata, make aPATCH request totheinstanceSettings().patch methodby excluding the metadata keys, for which you want to remove the zonalmetadata, from the request body. You must provide the followingwith your request:

    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 thezonal metadata.

    • PREFIXED_METADATA_KEYS: the list of all theexisting custom metadata keys for which you want to remove zonalmetadata, where each key is prefixed with the stringmetadata.items.. To ensure that your deletion requestis successful, exclude these metadata keys from the request body.If you include any of the metadata keys in both the update mask andthe request body, then Compute Engine doesn't remove thezonal metadata for those keys.

      For example, suppose your current metadata keys with zonal metadataarekey-1,key-2,key-3, andkey-4, and you want to remove thezonal metadata entries forkey-1 andkey-2, then your update maskmust 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 projectmetadata values available, then the VMs in the specified zone inherit thoseproject metadata values. If the metadata key was set only at a zonal leveland there isn't a corresponding project metadata value for that key, thenVMs in that zone lose that metadata information.

Example:

Consider an example projectmy-project, which has the following customproject metadata:

To remove the zonal metadata forkey-1 andkey-2 in theus-central1-a zone, make the followingPATCH 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 theus-central1-a zone possess thefollowing custom metadata. VMs inherit the project metadata values forkey-1 andkey-2, but retain the zonal metadata forkey-3 andkey-4.

  • Project metadata:"key-1":"value-a" and"key-2":"value-b"
  • Zonal metadata inus-central1-a zone:"key-3":"value-3" and"key-4":"new-value-4"

Remove custom instance metadata

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

Console

  1. In the Google Cloud console, go to theVM instances page.

    Go to the VM instances page

  2. In theName column, click the name of the VM for which you want toremove metadata.
  3. ClickEdit at the top ofthe page.
  4. In theMetadata 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.

  • If you want to remove the custom metadata entries for specific keys,specify those keys by using the--keys flag, and exclude the values ofthose keys.
gcloud compute instances remove-metadataVM_NAME \    --zone=ZONE  \--keys=KEY1,KEY2,...
  • If you want to remove all custom metadata for the VM, specify the--allflag.
gcloud compute instances remove-metadataVM_NAME \    --zone=ZONE  \--all

Replace the following:

  • PROJECT_ID: your project ID.
  • ZONE: the zone of your VM.
  • VM_NAME: name of your VM
  • KEY1,KEY2...:the custom instance metadata keys that you want to remove.

REST

  1. Get the current fingerprint and view any existing key-valuepairs for the VM. To do this, call theinstances().get method.

    A fingerprint is a random string of characters generated byCompute Engine and is used to perform optimistic locking. To update theVM, you need to provide the matching fingerprint value. The fingerprintchanges after each request, and if you provide a mismatched fingerprint,your request is rejected. This works so that only one update can be madeat 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 theinstances().setMetadata method.You must include the current metadata fingerprint value for your requestto succeed.

    • To remove all custom metadata key-value pairs from a VM, in theitems property, exclude the metadata keys for which you want toremove metadata values.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata{"fingerprint": "FINGER_PRINT""items": [  {    "key": "KEY1"    "value": "VALUE1"  }  {    "key": "KEY2"    "value": "VALUE2"  }  ...]}

    • To remove all custom instance metadata on the VM, exclude theitemsproperty altogether.

      POST https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/setMetadata{"fingerprint":FINGER_PRINT}

    Replace the following:

    • PROJECT_ID: your project ID.
    • ZONE: the zone of your VM.
    • VM_NAME: name of your VM
    • FINGER_PRINT: the current fingerprint value.
    • KEY1,KEY2...:the custom instance metadata keys that you want to remove.
    • VALUE1,VALUE2...:the values of the custom instance metadata keys that you want toremove.

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.