Storing and Retrieving Instance Metadata

Every instance stores its metadata on a metadata server. You can query this metadata server programmatically, from within the instance and from the Compute Engine API, for information about the instance, such as the instance's host name, instance ID, startup and shutdown scripts, custom metadata, and service account information. Your instance automatically has access to the metadata server API without any additional authorization.

The metadata server is particularly useful when used in combination with startup and shutdown scripts because you can use the metadata server to programmatically get unique information about an instance, without additional authorization. For example, you can write a startup script that gets the metadata key/value pair for an instance's external IP and use that IP in your script to set up a database. Since the default metadata keys are the same on every instance, you can reuse your script without having to update it for each instance. This helps you create less brittle code for your applications.

Metadata is stored in the format key:value. There is a default set of metadata entries that every instance has access to. You can also set custom metadata.

To access the metadata server, query the http://metadata.google.internal/computeMetadata/v1/ URL. For more information, see querying metadata.

Current version: v1

Compute Engine might offer more than one metadata version at a single time, but we recommend that you always use the newest metadata server version available. At any time, Google Compute Engine can add new entries to the metadata server and add new fields to responses. Check back periodically for changes!

Before you begin

Contents

Project and instance metadata

Metadata can be assigned at both the project and instance level. Project level metadata propagates to all virtual machine instances within the project, while instance level metadata only impacts that instance.

Default metadata keys

Google Compute Engine defines a set of default metadata entries that provide information about your instance or project. Default metadata is always defined and set by the server. You cannot manually edit any of these metadata pairs.

The following is a list of default metadata available to a project. Some metadata entries are directories that contain other metadata keys. This difference is marked by a trailing slash in the metadata name. For example, attributes/ is a directory that contains other keys, while numeric-project-id is a metadata key that maps to a value.

Relative to http://metadata.google.internal/computeMetadata/v1/project/
Metadata Entry Description
attributes/ A directory of custom metadata values that have been set for this project.
attributes/sshKeys SSH keys that can connect to instances in this project. If there are multiple SSH keys, each key will be separated by a newline character (\n). This value is a string.

Example: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

numeric-project-id The numeric project ID of the instance, which is not the same as the project name visible in the Google Cloud Platform Console. This value is different from the project-id metadata entry value.
project-id The project ID.

The following is a list of default metadata for an instance:

Relative to http://metadata.google.internal/computeMetadata/v1/instance/
Metadata Entry Description
attributes/ A directory of custom metadata values passed to the instance during startup or shutdown. See Specifying Custom Metadata below.
attributes/ssh-keys SSH keys that can connect to this specific instance. If there are multiple SSH keys, each key will be separated by a newline character (\n). This value is a string.

Example: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

description The free-text description of an instance, assigned using the --description flag, or set in the API.
disks/ A directory of disks attached to this instance.
hostname The host name of the instance.
id The ID of the instance. This is a unique, numerical ID that is generated by Google Compute Engine. This is useful for identifying instances if you do not want to use instance names.
machine-type The fully-qualified machine type name of the instance's host machine.
network-interfaces/ A directory of network interfaces for the instance.
network-interfaces/<index>/forwarded-ips/ A directory of any external IPs that are currently pointing to this virtual machine instance, for the network interface at <index>. Specifically, provides a list of external IPs served by forwarding rules that direct packets to this instance.
scheduling/ A directory with the scheduling options for the instance.
scheduling/on-host-maintenance The instance's transparent maintenance event behavior setting. This value is set with the --on_host_maintenance flag or via the API.
scheduling/automatic-restart The instance's automatic restart setting. This value is set with the ‑‑automatic_restart flag or via the API.
scheduling/preemptible The instance's preemptible setting. If this value is TRUE, the instance is preemptible. This value is set when you create an instance, and it cannot be changed.
maintenance-event The path that indicates that a transparent maintenance event is affecting this instance. See Transparent maintenance notice for details.
service-accounts/ A directory of service accounts associated with the instance.
tags Any tags associated with the instance.
zone The instance's zone.

Getting metadata

You can query the contents of the metadata server by making a request to the following root URLs from within a virtual machine instance. Use the http://metadata.google.internal/computeMetadata/v1/ URL to make requests to the metadata server.

All metadata values are defined as sub-paths below these root URLs.

You can query for default metadata values only from within the associated instance. You cannot query an instance's default metadata from another instance or directly from your local computer. You can use standard tools like curl or wget from the instance to its metadata server.

When you query for metadata, you must provide the following header in all of your requests:

Metadata-Flavor: Google

This header indicates that the request was sent with the intention of retrieving metadata values, rather than unintentionally from an insecure source, and allows the metadata server to return the data you requested. If you do not provide this header, the metadata server denies your request.

X-Forwarded-For header

Any requests that contain the header X-Forwarded-For will automatically be rejected by the metadata server. This header generally indicates that the request was proxied and might not be a request made by an authorized user. For security reasons, all such requests are rejected.

Is metadata information secure?

When you make a request to get information from the metadata server, your request and the subsequent metadata response never leaves the virtual machine instance. Metadata information is also encrypted on the way to the virtual machine host, so you can be sure that your metadata information is always secure.

Querying directory listings

The metadata server uses directories to organize certain metadata keys. Any metadata entry ending in a trailing slash is a directory. For example, the disks/ entry is a directory of disks attached to that instance:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"

0/
1/
2/

Similarly, if you wanted more information about the 1/ directory, you can query the specific URL for that directory:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/1/" -H "Metadata-Flavor: Google"

device-name
index
mode
type

Querying endpoints

If a metadata key is not a directory, it is an endpoint that returns one or more values. For example, to query the mode of a specific disk, query the following endpoint:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/1/mode" -H "Metadata-Flavor: Google"

READ_WRITE

By default, each endpoint has a predefined format for the response. Some endpoints might return data in JSON format by default, while other endpoints might return data as a string. You can override the default data format specification by using the alt=json or alt=text query parameters, which returns data in JSON string format or as a plaintext representation, respectively.

For example, the tags key automatically returns data in JSON format. You can return data in text format instead, by specifying the alt=text query parameter:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"

["bread","butter","cheese","cream","lettuce"]
user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?alt=text" -H "Metadata-Flavor: Google"

bread
butter
cheese
cream
lettuce

Recursively querying metadata

If you want to return all contents underneath a directory, use the recursive=true query parameter with your request:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true" -H "Metadata-Flavor: Google"

[{"deviceName":"boot","index":0,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-1","index":1,"mode":"READ_WRITE","type":"PERSISTENT"},
{"deviceName":"persistent-disk-2","index":2,"mode":"READ_ONLY","type":"PERSISTENT"}]

By default, recursive contents are returned in JSON format. If you want to return these contents in text format, append the alt=text query parameter:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/?recursive=true&alt=text" -H "Metadata-Flavor: Google"

0/device-name boot
0/index 0
0/mode READ_WRITE
0/type PERSISTENT
1/device-name persistent-disk-1
1/index 1
1/mode READ_WRITE
1/type PERSISTENT
2/device-name persistent-disk-1
2/index 2
2/mode READ_ONLY
2/type PERSISTENT

Setting custom metadata

You can set custom metadata for an instance or project from the Google Cloud Platform Console, gcloud, or the Compute Engine API. Custom metadata is useful for passing in arbitrary values to your project or instance, and also useful for setting startup and shutdown scripts.

Setting instance metadata

Set custom metadata for an instance in the Cloud Platform Console, the gcloud tool, or the API. Instance metadata applies only to a specific instance.

Setting metadata during instance creation

Console


  1. In the Cloud Platform Console, go to the VM Instances page.

    Go to the VM Instances page

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

gcloud


In gcloud, use the --metadata flag to set custom metadata.

gcloud compute instances create example-instance --metadata foo=bar

API


In the API, provide custom metadata as part of the metadata property in your request:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances

{
  "...
        }
      ]
    }
  ],
  "metadata": {
    "items": [
      {
       "key": "foo",
       "value": "bar"
      }
    ]
  },
  ..
}

Updating metadata on a running instance

Console


  1. 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 instance metadata with the gcloud tool is an additive action. Specify only the metadata keys that you want to add or change. If a key that you provided already exists, the value for that key is updated with the new value.

In gcloud, use the instances add-metadata command:

gcloud compute instances add-metadata INSTANCE \
  --metadata bread=mayo,cheese=cheddar,lettuce=romaine

If you want to change the lettuce=romaine entry to lettuce=green, use:

gcloud compute instances add-metadata INSTANCE --metadata lettuce=green

If you want to remove the lettuce=romaine entry, specify the existing key and exclude the value.

gcloud compute instances remove-metadata INSTANCE --keys lettuce

API


In the API, make a request to the instances().setMetadata method. Provide all of the new metadata values and the current fingerprint value.

A fingerprint is a random string of characters generated by Compute Engine and is used to perform optimistic locking. Provide the matching fingerprint value in order to perform your request. The fingerprint changes after each request and if you provide a mismatched fingerprint, your request is rejected. In this way, only one update can be made at a time, preventing collisions.

To get the current fingerprint of an instance and see any existing key/value pairs for the instance. Send a instances().get request:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

{
 ...
 "name": "example-instance",
 "metadata": {
  "kind": "compute#metadata",
  "fingerprint": "zhma6O1w2l8="
  "items": [
   {
    "key": "foo",
    "value": "bar"
   }
  ]
 },
 ...
}

Next, make a request to the instances().setMetadata method and set your custom metadata key/value pairs. If the instance has existing key/value pairs that you want to keep, you must include them in this request with the new key/value pairs:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{
 "fingerprint": "zhma6O1w2l8=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  },
  {
   "key": "baz",
   "value": "bat"
  }
 ]
}

To remove all metadata key/value pairs from an instance, specify an instances().setMetadata request and exclude the items property. Note that you must still include the current metadata fingerprint property for this request to succeed:

POST https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance/setMetadata

{
 "fingerprint": "5rC_DXxBUZw="
}

Setting project-wide custom metadata

Set project-wide metadata to apply the metadata to all instances in the project. For example, if you define a project-wide metadata pair of baz=bat, that metadata pair is automatically applied to all instances in the project.

Console


  1. Go to the Metadata page.
  2. Click on Edit.
  3. Add or edit a metadata entry.
  4. Save your changes.

gcloud


In gcloud, use the project-info add-metadata command. For example:

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

...
commonInstanceMetadata:
  fingerprint: RfOFY_-eS64=
  items:
  - key: baz
    value: bat
  - key: foo
    value: bar
  - key: ssh-keys
...

One metadata key-value pair is specified with an equals sign, for example, key=value. Multiple key-value pairs are separated with spaces.

You can optionally specify one or more files from which to read metadata using the --metadata-from-file flag. You can remove metadata values with the project-info remove-metadata command.

API


In the API, make a request to the projects().setCommonInstanceMetadata method, providing all of the new metadata values and a fingerprint value.

A fingerprint is a random string of characters generated by Compute Engine and is used to perform optimistic locking. Provide the matching fingerprint value in order to perform your request. The fingerprint changes after each request and if you provide a mismatched fingerprint, your request is rejected. In this way, only one update can be made at a time, preventing collisions.

To get the current fingerprint of an instance, perform a project().get request and copy the fingerprint value:

GET https://www.googleapis.com/compute/v1/projects/myproject

{
 "name": "myproject",
 "commonInstanceMetadata": {
  "kind": "compute#metadata",
  "fingerprint": "FikclA7UBC0=",
  ...
}

Next, make a request to the projects().setCommonInstanceMetadata method and set your custom metadata key/value pairs:

POST https://www.googleapis.com/compute/v1/projects/myproject

{
 "fingerprint": "FikclA7UBC0=",
 "items": [
  {
   "key": "foo",
   "value": "bar"
  }
 ]
}

Querying custom metadata

Query custom instance or project metadata through the Cloud Platform Console, gcloud, or the API.

Console


To see project-wide custom metadata, go to the the Metadata page.

To see an instance's custom metadata:

  1. Go to the VM instances page.
  2. Click on the instance for which you view metadata.
  3. Under Custom metadata, view the instance's custom metadata.

gcloud


Query project-wide metadata:

gcloud compute project-info describe

commonInstanceMetadata:
  fingerprint: FikclA7UBC0=
  items:
  - key: peanut
    value: butter
  kind: compute#metadata
creationTimestamp: '2014-07-08T10:32:36.417-07:00'
...
name: example-instance
quotas:
...
selfLink: https://www.googleapis.com/compute/v1/projects/example-instance

Query for instance metadata:

gcloud compute instances describe example-instance

canIpForward: false
cpuPlatform: Intel Sandy Bridge
...
metadata:
  fingerprint: xLQdf0brGqE=
  items:
  - key: peanut
    value: butter
  kind: compute#metadata
name: example-instance
networkInterfaces:
...

API


To query for a project's metadata, perform an empty request to the projects().get method:

GET https://www.googleapis.com/compute/v1/projects/myproject

To query for an instance's metadata, perform an empty request to the instance().get method:

GET https://www.googleapis.com/compute/v1/projects/myproject/zones/us-central1-a/instances/example-instance

Waiting for updates

Given that metadata values can change while your instance is running, the metadata server offers the ability to be notified of metadata changes using the wait-for-change feature. This feature allows you to perform hanging HTTP GET requests that only return when your specified metadata has changed. You can use this feature on custom metadata or server-defined metadata, so if anything changes about your instance or project, or if someone updates a custom metadata, you can programmatically react to the change. For example, you can perform a request on the tags key so that the request only returns if the contents of the tags metadata has changed. When the request returns, it provides the new value of that metadata key.

To perform a wait-for-change request, query a metadata key and append the ?wait_for_change=true query parameter:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

After there is a change to the specified metadata key, the query returns with the new value. In this example, if a request is made to the setInstanceTags method, the request returns with the new values:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true" -H "Metadata-Flavor: Google"

cheese
lettuce

You can also perform a wait-for-change request recursively on the contents of a directory:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

The metadata server returns the new contents if there is any change:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true&wait_for_change=true" -H "Metadata-Flavor: Google"

{"cheese":"lettuce","cookies":"cream"}

The wait-for-change feature also lets you match with your request and set timeouts.

Using ETags

When you submit a simple wait-for-change query, the metadata server returns a response if anything has changed in the contents of that metadata. However, there is an inherent race condition between a metadata update and a wait-for-change request being issued, so it is useful to have a reliable way to know you are getting the latest metadata value.

To help with this, you can use the last_etag query parameter, which compares the ETag value you provide with the ETag value saved on the metadata server. If the ETag values match, then the wait-for-change request will be accepted. If the ETag values do not match, this indicates that the contents of the metadata has changed since the last time you retrieved the ETag value, and the metadata server returns immediately with this latest value.

To grab the current ETag value for a metadata key, make a request to that key and print the headers. In CURL, you can do this with the -v flag:

user@myinst:~$ curl -v "http://metadata.google.internal/computeMetadata/v1/instance/tags" -H "Metadata-Flavor: Google"
* About to connect() to metadata port 80 (#0)
*   Trying 169.254.169.254... connected
* Connected to metadata (169.254.169.254) port 80 (#0)
> GET /computeMetadata/v1/instance/tags?wait_for_change=true HTTP/1.1
> User-Agent: curl/7.19.7 (x86_64-pc-linux-gnu) libcurl/7.19.7 OpenSSL/0.9.8k zlib/1.2.3.3 libidn/1.15
> Host: metadata
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/text
< ETag: 411261ca6c9e654e
< Date: Wed, 13 Feb 2013 22:43:45 GMT
< Server: Metadata Server for VM
< Content-Length: 26
< X-XSS-Protection: 1; mode=block
< X-Frame-Options: SAMEORIGIN
<
cheese
lettuce

You can then use that ETag value in your wait-for-change request:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&last_etag=411261ca6c9e654e" -H "Metadata-Flavor: Google"

The metadata server will match your specified ETag value and if that value changes, the request returns with the new contents of your metadata key.

The following Python sample shows how to to programmatically watch the metadata server for changes:

last_etag = '0'

while True:
    r = requests.get(
        url,
        params={'last_etag': last_etag, 'wait_for_change': True},
        headers=METADATA_HEADERS)

    # During maintenance the service can return a 503, so these should
    # be retried.
    if r.status_code == 503:
        time.sleep(1)
        continue
    r.raise_for_status()

    last_etag = r.headers['etag']

Setting timeouts

If you would like your wait-for-change request to time out after a certain number of seconds, you can set the timeout_sec=<timeout-in-seconds> query parameter. The timeout_sec parameter limits the wait time of your request to the number of seconds you specified and when the request reaches that limit, it returns the current contents of the metadata key. Here is an example of a wait-for-change request that is set to time out after 360 seconds:

user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/tags?wait_for_change=true&timeout_sec=360" -H "Metadata-Flavor: Google"

When you set the timeout_sec parameter, the request always returns after the specified number of seconds, whether or not the metadata value has actually changed. It is only possible to set an integer value for your timeout.

Status codes

When you perform a wait-for-change request, the metadata server returns standard HTTP status codes to indicate success or failure. In the case of errors, network conditions can cause the metadata server to fail your request and return an error code. In these cases, you should design your application to be fault-tolerant and to be able to recognize and handle these errors.

The possible statuses that the metadata server returns are:

Status Description
HTTP 200 Success! A value was changed, or you reached your specified timeout_sec and the request returned successfully.
Error 400 Your request was invalid. Please fix your query and retry the request.
Error 404 The metadata value you specified no longer exists. The metadata server also returns this error if your metadata is deleted while you are waiting on a change.
Error 503 There was a temporary server error or a temporary maintenance event. Retry the request.

Getting transparent maintenance notices

The metadata server provides information about an instance's scheduling options and settings, through the scheduling/ directory and the maintenance-event attribute. You can use these attributes to learn about a virtual machine instance's scheduling options, and also use this metadata to notify you when a maintenance event is about to happen, specifically through the maintenance-event attribute.

You can learn when a transparent maintenance event will happen by querying the maintenance-event attribute periodically. The value of this attribute will change 60 seconds before a maintenance event starts, giving your application code a way to trigger any tasks you want to perform prior to a maintenance event, such as backing up data or updating logs.

To query the maintenance-event attribute:

user@myinst:~$ curl http://metadata.google.internal/computeMetadata/v1/instance/maintenance-event -H "Metadata-Flavor: Google"

NONE

The initial and default value of the maintenance-event attribute is NONE. Before a transparent maintenance event begins, the maintenance-event value:

  1. Changes from NONE to MIGRATE_ON_HOST_MAINTENANCE
  2. Throughout the duration of the maintenance event, the value remains as MIGRATE_ON_HOST_MAINTENANCE.
  3. After the maintenance event ends, the value returns to NONE.

Note that Compute Engine gives the 60 second warning before updating the maintenance-event attribute only if you have queried this attribute at least once since the last maintenance event. If you have never queried the maintenance-event attribute or have not queried the attribute since the last migration, Compute Engine assumes that the instance does not require advance warning of maintenance events. The maintenance event initiates immediately instead, skipping the 60 second warning. If you don't want to skip the 60 second warning, make sure your client code queries the maintenance-event attribute at least once after the last migration event.

You can use the maintenance-event attribute with the waiting for updates feature to notify your scripts and applications when a maintenance event is about to start and end. This lets you automate any actions that you might want to run before or after the event. The following Python sample provides an example of how you might implement these two features together.

import time

import requests


METADATA_URL = 'http://metadata.google.internal/computeMetadata/v1/'
METADATA_HEADERS = {'Metadata-Flavor': 'Google'}


def wait_for_maintenance(callback):
    url = METADATA_URL + 'instance/maintenance-event'
    last_maintenance_event = None
    last_etag = '0'

    while True:
        r = requests.get(
            url,
            params={'last_etag': last_etag, 'wait_for_change': True},
            headers=METADATA_HEADERS)

        # During maintenance the service can return a 503, so these should
        # be retried.
        if r.status_code == 503:
            time.sleep(1)
            continue
        r.raise_for_status()

        last_etag = r.headers['etag']

        if r.text == 'NONE':
            maintenance_event = None
        else:
            # Possible events:
            #   MIGRATE_ON_HOST_MAINTENANCE: instance will be migrated
            #   SHUTDOWN_ON_HOST_MAINTENANCE: instance will be shut down
            maintenance_event = r.text

        if maintenance_event != last_maintenance_event:
            last_maintenance_event = maintenance_event
            callback(maintenance_event)


def maintenance_callback(event):
    if event:
        print('Undergoing host maintenance: {}'.format(event))
    else:
        print('Finished host maintenance')


def main():
    wait_for_maintenance(maintenance_callback)


if __name__ == '__main__':
    main()

Transitioning to v1

The v1 metadata server functions slightly differently that the previous v1beta1 server. Here are some of the changes that need to be made for the new metadata server:

  • Update metadata requests to include the Metadata-Flavor: Google header

    The new metadata server requires that all requests provide the Metadata-Flavor: Google header, which indicates that the request was made with the intention of retrieving metadata values, Update your requests to include this new header. For example, a request to the disks/ attribute now looks like the following:

    user@myinst:~$ curl "http://metadata.google.internal/computeMetadata/v1/instance/disks/" -H "Metadata-Flavor: Google"
    

  • Update requests that use the header X-Forwarded-For header

    These requests are automatically rejected by the server, as it generally indicates that the requests are proxied. Update your requests so they do not contain this header.

Send feedback about...

Compute Engine Documentation