Setting and querying guest attributes


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

Before you begin

When to use guest attributes

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

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

Guest attributes work well for situations where you must publish infrequent and low volume data. For example, guest attributes work well for the following use cases:

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

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

For reads and writes from within an VM, the metadata server provides automatic instance-level authentication and authorization. Each VM can read or write only to its own metadata server. Other VMs cannot access the metadata server of another VM. Users and service accounts can read a VM's guest attributes from outside the VM only if they have an Identity and Access Management (IAM) role that provides the compute.instances.getGuestAttributes permission.

Enable guest attributes on your VM

By default, guest attributes are disabled. To enable guest attributes, set the necessary metadata values on either your individual VMs or in project-wide metadata:

Console

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

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

    Go to the VM instances page

  2. Click Create instance.
  3. On the Create a new instance page, fill in the desired properties for your VM.
  4. In the Metadata section, add a metadata entry where the key is enable-guest-attributes and the value is TRUE.
  5. Click Create to create the VM.

Set enable-guest-attributes in project-wide metadata so that it applies to all of the VMs in your project:

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

    Go to the Metadata page

  2. Click Edit.
  3. Add a metadata entry where the key is enable-guest-attributes and the value is TRUE. Alternatively, set the value to FALSE to disable the feature.
  4. Click Save to apply the changes.

Set enable-guest-attributes in metadata of an existing VM:

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

    Go to the VM instances page

  2. Click the name of the VM on which you want to set the metadata value.
  3. At the top of the instance details page, click Edit to edit the instance settings.
  4. Under Custom metadata, add a metadata entry where the key is enable-guest-attributes and the value is TRUE. Alternatively, set the value to FALSE to exclude the VM from the feature.
  5. At the bottom of the instance details page, click Save to apply your changes to the VM.

gcloud

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

Use the gcloud compute instances create command in the gcloud command-line tool and set enable-guest-attributes=TRUE to enable guest attributes. Replace VM_NAME with the name of your VM.

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

Set enable-guest-attributes in project-wide metadata so that it applies to all of the VMs in your project:

Use the project-info add-metadata command in the gcloud command-line tool and set enable-guest-attributes=TRUE to enable guest attributes:

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

Alternatively, you can set enable-guest-attributes to FALSE to disable guest attributes.

Set enable-guest-attributes in metadata of an existing VM:

Use the instances add-metadata command in the gcloud command-line tool and set enable-guest-attributes=TRUE to enable guest attributes. Replace VM_NAME with the name of your VM.

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

Alternatively, you can set enable-guest-attributes to FALSE to exclude your VM from using guest attributes.

Set guest attributes

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

Linux VMs

For example, you might use a curl request from within your VM to write a value to the guest-attributes metadata path:

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 your KEY. Guest attributes must have a namespace.
  • VALUE: the value that you want to write.
  • KEY: the metadata path within guest-attributes where the value is stored.

Use only letters, numerals, underscores (_), and hyphens (-) for the NAMESPACE and KEY fields.

Windows VMs

For example, you might use an Invoke-RestMethod request from within your VM to write a value to the guest-attributes metadata path:

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 your KEY. Guest attributes must have a namespace.
  • VALUE: the value that you want to write.
  • KEY: the metadata path within guest-attributes where the value is stored.

Use only letters, numerals, underscores (_), and hyphens (-) for the NAMESPACE and KEY fields.

Get guest attributes

Users or service accounts can read guest attributes if they have an IAM role that provides the compute.instances.getGuestAttributes permission. Alternatively, any user or application within the VM can read the metadata values for that specific VM.

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

Query the metadata server

Linux VMs

For example, you might use a curl request from within your VM to read a value from the guest-attributes metadata path:

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

Replace the following:

  • NAMESPACE: the namespace for the guest-attributes key that you want to query.
  • KEY: the path within guest-attributes from which you want to read the metadata value.

Alternatively, you can return all of the guest attribute values in one request. Replace NAMESPACE with the namespace for the guest-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 an Invoke-RestMethod request from within your VM to read a value from the guest-attributes metadata path:

 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 the guest-attributes key that you want to query.
  • KEY: the path within guest-attributes from which you want to read the metadata value.

Alternatively, you can return all of the guest attribute values in one request. Replace NAMESPACE with the namespace for the guest-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 the gcloud command-line tool or Compute Engine API

gcloud

Use the gcloud command-line tool to read guest attribute metadata values from a VM. For example, you can retrieve all of the values for the VM:

gcloud compute instances get-guest-attributes VM_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-attributes VM_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 you defined:

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

Replace the following:

  • VM_NAME: the name of the VM from which you want to read the guest attribute metadata value
  • NAMESPACE: the namespace for the guest-attributes key that you want to query
  • KEY: the path within guest-attributes metadata where the value is stored
  • ZONE: the zone where the VM is located

API

Use the compute.instances.getguestattributes API 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 which you want to read the guest attribute metadata value
  • NAMESPACE: the namespace for the guest-attributes key that you want to query
  • KEY: the path within guest-attributes metadata where the value is stored

To retrieve all of the keys for a NAMESPACE, omit the KEY:

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 the NAMESPACE and queryPath entirely:

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

Alternatively, if you have an OAuth token, you can use curl:

curl -H "Authorization: Bearer OAUTH_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 which you want to read the guest attribute metadata value
  • NAMESPACE: the namespace for the guest-attributes key that you want to query
  • KEY: the path within guest-attributes metadata where the value is stored

Deleting guest attributes

Linux VMs

You can also delete guest attributes. For example, use curl to delete a specific 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 the guest-attributes key that you want to delete
  • KEY: the path within guest-attributes where the value is stored

Windows VMs

You can also delete guest attributes. For example, use Invoke-RestMethod to 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 the guest-attributes key that you want to delete
  • KEY: the path within guest-attributes where the value is stored

Disabling guest attributes on your organization or folder

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

Set the constraints/compute.disableGuestAttributesAccess constraint on your organization or folder, replacing PROJECT_ID with the name of your project:

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

Read Using constraints to learn more about how to set and manage constraints on your organizations.

What's next?