About VM metadata

Every virtual machine (VM) instance stores its metadata on a metadata server. Your VM automatically has access to the metadata server API without any additional authorization. Metadata is stored as key:value pairs.

There is a default set of metadata keys that are available for VMs running on Compute Engine. For a list of these default metadata keys, see Default metadata values. You can also use your own custom metadata keys on an individual VM or project. For more information, see Setting custom metadata.

After setting a default or custom metadata entry, you can review the metadata information for that VM or project. To view metadata, see Querying VM metadata.

VM metadata uses

The following sections describe a few scenarios where you can use metadata entries to manage your VMs.

Startup and shutdown scripts

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 a VM, without additional authorization.

For example, you can write a startup script that gets the metadata key:value pair for a VM's external IP and use that IP in your script to set up a database. Because the default metadata keys are the same on every VM, you can reuse your script without having to update it for each VM. This helps you create less brittle code for your applications.

Host maintenance

The metadata server provides information about a VMs scheduling option through the scheduling/ metadata directory entry and the maintenance-event attribute. You can use these metadata values to notify you when a maintenance event is about to happen so that you can prepare your environment for the event. For more information, see Getting live migration notices.

Guest attributes

Guest attributes are a specific type of custom metadata that your applications can write to while running on your VMs. Use guest attributes only for use cases that require small amounts of data that don't change frequently. For more information about guest attributes, see Setting and querying guest attributes.

Metadata security considerations

When you make a request to get information from the metadata server, your request and the subsequent metadata response never leave the physical host that is running the VM.

However, any process that can query the metadata URL, has access to all values in the metadata server. This includes any custom metadata values that you write to the server. Google recommends that you exercise caution when writing sensitive values to the metadata server or when running third-party processes.

Limitations

  • Any requests that contain the header X-Forwarded-For are automatically 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.

  • When you use the curl command to retrieve metadata from the server, note that some encoded characters aren't supported in the request path. Encoded characters are only supported in the query path.

    For example, the following request might not work:

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/123456789-compute%40developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

    For this request to work, you must replace the unsupported encoded character in the request path (%40) with the equivalent accepted value (@).

    curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/1234567898-compute@developer.gserviceaccount.com/?query_path=https%3A%2F%2Flocalhost%3A8200%2Fexample%2Fquery&another_param=true" -H "Metadata-Flavor: Google"

    The following table summarises the encoded characters that aren't supported in a request path.

    Encoded character Accepted value
    %21 
    !
    %24 
    $
    %27 
    '
    %28 
    (
    %29 
    )
    %2A 
    *
    %2C 
    ,
    %40 
    @

Parts of a metadata request

The following table summarizes the main parts of a metadata query request.

Components Description
Root URL

All metadata values are defined as sub-paths below the following root URL:

http://metadata.google.internal/computeMetadata/v1
Request header

The following header must be 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 lets the metadata server return the data you requested. If you don't provide this header, the metadata server denies your request.

What's next?