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
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
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.
- For more information about startup scripts, see the startup script overview.
- For more information about shutdown scripts, see Running shutdown scripts.
The metadata server provides information about a VMs scheduling option
scheduling/ metadata directory entry and the
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 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.
Any requests that contain the header
X-Forwarded-Forare 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
curlcommand 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/VM/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/VMfirstname.lastname@example.org/?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
Parts of a metadata request
The following table summarizes the main parts of a metadata query request.
All metadata values are defined as sub-paths below the following root URL:
The following header must be in all of your requests:
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.
- Set custom metadata.
- Query VM metadata.
- Get live migration notices from the metadata server.
- Set and query guest attributes.