Setting and querying guest attributes

Linux Windows

Guest attributes are a specific type of custom metadata that your applicationscan write to while running on your virtual machine (VM) instance. Any applicationor user on your VM instance can both read and write data to these guestattribute metadata values.

Before you begin

Required roles

The required permissions or roles depend on whether you are completing tasksfrom within or outside the VM.

Within the VM

If you are setting, querying or deleting the guest attributes from within the VM,you only need the roles and permissions for connecting to the VM.Any process running in the VM instance can write to the guestattributes values including scripts and applications that don't have sudo oradministrator level privileges.

For reads and writes from within an VM, the metadata server providesautomatic instance-level authentication and authorization. Each VM canread or write only to its own metadata server. Other VMs cannot access themetadata server of another VM.

Outside the VM

The following roles and permissions are needed to enable guest attributes,or view guest attributes from outside the VM by using the Google Cloud CLIor REST. You can't set or delete guest attributes from outside a VM.

To ensure that your user or service account has the necessary permissions to enable or view guest attributes, ask your administrator to grant your user or service account theCompute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM role on the VM or project. For more information about granting roles, seeManage access to projects, folders, and organizations.

This predefined role contains the permissions required to enable or view guest attributes. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

The following permissions are required to enable or view guest attributes:

  • To enable guest attributes:compute.instances.setMetadata on the VM or project
  • To view guest attributes:compute.instances.getGuestAttributes on the VM or project

Your administrator might also be able to give your user or service account these permissions withcustom roles or otherpredefined roles.

When to use guest attributes

Caution: All applications and users on your VM can both read and write data toand from guest attribute metadata values. Users and service accounts fromoutside the VM with certain roles can read the guest attributes metadata values.Don't include sensitive information such as personally identifiable information(PII), or security data such as private keys or passwords in yourguest attributes. Guest attributes aren't designed for use cases that requireapplication or user authentication and authorization.

Use guest attributes only for use cases that require small amounts of data thatdon't change frequently. The best use cases for guest attributes have thefollowing characteristics:

  • The number of queries are limited to a maximum of 10 queriesper minute per VM instance.
  • Queries don't exceed a burst of 3 queries per second. If this maximumrate is exceeded, Compute Engine might arbitrarily remove guestattributes that are in the process of being written. This data removal isneeded to ensure that other critical system data can be written to the server.

Guest attributes work well for situations where you must publish infrequent andlow volume data. For example, guest attributes work well for the following usecases:

  • Startup scripts that can signal successful initialization by setting a customstatus value in guest attributes.
  • Configuration management agents that can publish a guest OS name and versionto guest attributes.
  • Inventory management agents that can publish list of packages installed inthe VM instance to guest attributes.
  • Workload orchestration software that can signal completion of an operationin the guest to the software control plane by setting a custom status valuein guest attributes.

Guest attributes aren't a replacement for event streaming,Pub/Sub, or other forms of datastorage and configuration repositories.

Guest attributes and other Google Cloud services

Guest attributes are used by other Google Cloud services as follows:

  • SSH security: If guest attributes is enabled and OS Login is disabled, theguest environment andgcloud CLI use guest attributes to improve SSH securityby using the Google API to retrieve host keys before you can connect to yourVM using SSH.
  • VM Manager: TheOS config agent publishesoperating system data to guest attributes.

To review the metadata entries stored by these services, seePredefined guest attribute metadata keys.

Enable guest attributes on your VM

By default, guest attributes are disabled. To enable guest attributes, setthe necessary metadata values on either your individualVMs or in project-wide metadata:

Console

Setenable-guest-attributes in instance metadata when you create a VM:

  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 the following:

    1. Expand theManagement section.

    2. In theMetadata section, clickAdd item add the following metadata entries:

      • Key:enable-guest-attributes
      • Value:TRUE

  4. To create the VM, clickCreate.

Setenable-guest-attributes in project-wide metadata so that it applies toall of the VMs in your project:

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

    Go to the Metadata page

  2. ClickEdit.

  3. Add a metadata entry where the key isenable-guest-attributes and thevalue isTRUE. Alternatively, set the value toFALSE to disable thefeature.

  4. ClickSave to apply the changes.

Setenable-guest-attributes in metadata of an existing VM:

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

    Go to the VM instances page

  2. Click the name of the VM on which you want to set the metadatavalue.
  3. At the top of the instance details page, clickEdit to edit theinstance settings.
  4. UnderCustom metadata, add a metadata entry where the key isenable-guest-attributes and the value isTRUE. Alternatively, set thevalue toFALSE to exclude the VM from the feature.
  5. At the bottom of the instance details page, clickSave to apply yourchanges to the VM.

gcloud

Setenable-guest-attributes in instance metadata when you create an VM:

Use thegcloud compute instances createcommand in the Google Cloud CLI and setenable-guest-attributes=TRUE to enable guest attributes. ReplaceVM_NAME with the name of your VM.

gcloud compute instances createVM_NAME \    --metadata=enable-guest-attributes=TRUE

Setenable-guest-attributes in project-wide metadata so that itapplies to all of the VMs in your project:

Use theproject-info add-metadatacommand in the Google Cloud CLI and setenable-guest-attributes=TRUE to enable guest attributes:

gcloud compute project-info add-metadata \    --metadata=enable-guest-attributes=TRUE

Alternatively, you can setenable-guest-attributes toFALSE to disableguest attributes.

Setenable-guest-attributes in metadata of an existing VM:

Use theinstances add-metadatacommand in the Google Cloud CLI and setenable-guest-attributes=TRUE to enable guest attributes. ReplaceVM_NAME with the name of your VM.

gcloud compute instances add-metadataVM_NAME \    --metadata=enable-guest-attributes=TRUE

Alternatively, you can setenable-guest-attributes toFALSE toexclude your VM from using guest attributes.

Set guest attributes

Any process running in the VM instance can write to the guestattributes values including scripts and applications that don't have sudo oradministrator level privileges. Users or service accounts outside of theVM cannot write to guest attributes metadata values.

Linux VMs

For example, you might use acurl requestfrom within your VM to write a value to theguest-attributes metadatapath:

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

Replace the following:

  • NAMESPACE: a logical grouping for yourKEY. Guest attributes must have a namespace.
  • VALUE: the value that you want to write.
  • KEY: the metadata path withinguest-attributes wherethe value is stored.

Use only letters, numerals, underscores (_), and hyphens (-) for theNAMESPACE andKEY fields.

Windows VMs

For example, you might use anInvoke-RestMethod requestfrom within your VM to write a value to theguest-attributes metadatapath:

PS C:\>$value = (Invoke-RestMethod `         -Method PUT -Body "VALUE" `         -Headers @{'Metadata-Flavor' = 'Google'} `         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")$value

Replace the following:

  • NAMESPACE: a logical grouping for yourKEY. Guest attributes must have a namespace.
  • VALUE: the value that you want to write.
  • KEY: the metadata path withinguest-attributes wherethe value is stored.

Use only letters, numerals, underscores (_), and hyphens (-) for theNAMESPACE andKEY fields.

Get guest attributes

Users or service accounts can read guest attributes from outside a VM ifthey have therequired role.Alternatively, any user or application within the VM can readthe metadata values for that specific VM.

Any process running in the virtual machine can write to the guest attributesvalue, which include scripts and applications that don't have sudo oradministrator level privileges.

Query the metadata server

Use the following instructions to query guest attributes from within a VM.

  1. Connect to the VM.

  2. Query the guest attributes.

    Linux VMs

    For example, you might use acurl requestfrom within your VM to read a value from theguest-attributes metadatapath:

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    Replace the following:

    • NAMESPACE: the namespace for theguest-attributeskey that you want to query.
    • KEY: the path withinguest-attributes from which youwant to read the metadata value.

    Alternatively, you can return all of the guest attribute values in one request.ReplaceNAMESPACE with the namespace for theguest-attributes key that you want to query.

    curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"

    Windows VMs

    For example, you might use anInvoke-RestMethod requestfrom within your VM to read a value from theguest-attributes metadatapath:

    PS C:\>$value = (Invoke-RestMethod `        -Headers @{'Metadata-Flavor' = 'Google'} `        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")$value

    Replace the following:

    • NAMESPACE: the namespace for theguest-attributeskey that you want to query.
    • KEY: the path withinguest-attributes from which youwant to read the metadata value.

    Alternatively, you can return all of the guest attribute values in one request.ReplaceNAMESPACE with the namespace for theguest-attributes key that you want to query.

    PS C:\>$value = (Invoke-RestMethod `        -Headers @{'Metadata-Flavor' = 'Google'} `        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/")$value

Use Google Cloud CLI or REST

Use the following instructions to view guest attributes from outside a VM.

gcloud

Use the Google Cloud CLI to read guest attribute metadatavalues for a VM. For example, you can retrieve all of the valuesfor the VM as follows:

gcloud compute instances get-guest-attributesVM_NAME \    --zone=ZONE

To retrieve all of the values under a specific namespace, include the--query-path flag and the namespace that you defined:

gcloud compute instances get-guest-attributesVM_NAME \    --query-path=NAMESPACE \    --zone=ZONE

To retrieve all of the values under a specific namespace, include the--query-path flag, the namespace, and the key for the value that youdefined:

gcloud compute instances get-guest-attributesVM_NAME \    --query-path=NAMESPACE/KEY \    --zone=ZONE

Replace the following:

  • VM_NAME: the name of the VM fromwhich you want to read the guest attribute metadata value
  • NAMESPACE: the namespace for theguest-attributeskey that you want to query
  • KEY: the path withinguest-attributes metadatawhere the value is stored
  • ZONE: the zone where the VM is located

REST

Use thecompute.instances.getguestattributes method:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Replace the following:

  • PROJECT_ID: your project ID
  • ZONE: the zone where your VM is located
  • VM_NAME: the name of the VM from whichyou want to read the guest attribute metadata value
  • NAMESPACE: the namespace for theguest-attributeskey that you want to query
  • KEY: the path withinguest-attributes metadatawhere the value is stored

To retrieve all of the keys for aNAMESPACE, omit theKEY:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

To retrieve all of the keys in each namespace on the VM, omit theNAMESPACE:

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=

Alternatively, if you have an OAuth token, you can usecurl:

curl -H "Authorization: BearerOAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

Replace the following:

  • OAUTH_TOKEN: your OAuth token
  • PROJECT_ID: your project ID
  • ZONE: the zone where your VM is located
  • VM_NAME: the name of the VM from whichyou want to read the guest attribute metadata value
  • NAMESPACE: the namespace for theguest-attributeskey that you want to query
  • KEY: the path withinguest-attributes metadatawhere the value is stored

Deleting guest attributes

Use the following instructions to remove guest attributes from within a VM.

  1. Connect to the VM.

  2. Delete the guest attributes.

    Linux VMs

    You can also delete guest attributes. For example, usecurl to delete aspecific key:

    curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    Replace the following:

    • NAMESPACE: the namespace for theguest-attributeskey that you want to delete
    • KEY: the path withinguest-attributes where thevalue is stored

    Windows VMs

    You can also delete guest attributes. For example, useInvoke-RestMethodto delete a specific key:

    PS C:\>$value = (Invoke-RestMethod `          -Method DELETE `          -Headers @{'Metadata-Flavor' = 'Google'} `          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")$value

    Replace the following:

    • NAMESPACE: the namespace for theguest-attributeskey that you want to delete
    • KEY: the path withinguest-attributes where thevalue is stored

Disabling guest attributes on your organization or folder

If you don't want any of the VMs in your organization or folder toenable guest attributes, you can override and disable the feature completely.

Set theconstraints/compute.disableGuestAttributesAccess constraint on yourorganization or folder, replacingPROJECT_ID with thename of your project:

gcloud resource-manager org-policies enable-enforce \    constraints/compute.disableGuestAttributesAccess \    --project=PROJECT_ID

ReadUsing constraintsto learn more about how to set and manage constraints on your organizations.

Note: Disabling guest attributes on your organization or folder prevents you fromdeploying new apps or updating existing apps in App Engine flexible environment. To continue deploying apps in the flexible environment, you must disable the organizational policy constraintconstraints/compute.disableGuestAttributesAccess.

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 2025-12-15 UTC.