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.

This document provides an overview about VM metadata and explains about the types and properties of 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 Compute Engine predefined 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 VM's 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 Get 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 Set and query 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.

Predefined and custom metadata keys

Each metadata entry is stored on the metadata server as key-value pairs. Metadata keys are case sensitive. Your keys can be either predefined or custom metadata keys.

Predefined metadata keys

Predefined metadata keys are metadata keys that are created by Compute Engine. When you create a VM, Compute Engine automatically sets the metadata values for some of these keys on that VM—for example, the VM instance ID or the project ID. For predefined keys where Compute Engine doesn't automatically set a value, you can choose from a set of values that are available depending on the system configuration. For example, to enable OS login for a VM, you can set the value of the enable-oslogin predefined key to TRUE for that VM. To disable OS login for that VM, you can update the value of the key to FALSE. You can only update the values for these keys but not the keys themselves.

For more information about predefined metadata keys and a list of these keys, see Predefined metadata keys.

Custom metadata keys

Custom metadata enables you to create and use your own metadata key-value pairs on an individual VM or a project. You can add new custom metadata keys, update the values of your existing keys, and remove any custom metadata entries when you don't need them. Setting custom metadata is useful for passing in arbitrary values to VMs in a project. It is also useful for creating startup and shutdown scripts.

To learn how you can add, update, or remove custom metadata for your VMs, see Configure custom metadata.

Types of metadata

VM metadata entries can provide information specific to an individual VM or a project. Your metadata is divided into project, zonal, and instance metadata, based on the scope at which you set the metadata.

Project metadata

Project metadata is defined at project scope and provides information that applies to all VMs in a project. When you set this metadata, the metadata entries propagate to all VMs in that project.

You can use both predefined and custom metadata keys to set project metadata. Learn more about predefined project metadata keys and how to set custom project metadata.

Zonal metadata

Zonal metadata is defined at a zonal scope within a project and provides information about VMs in that specific zone in that project. When you set zonal metadata, the metadata entries propagate to all VMs in that configured zone in that project. When compared to project metadata, zonal metadata helps you with fault isolation and provides greater reliability.

Compute Engine doesn't provide any predefined keys for zonal metadata. You must create your own custom metadata keys to set zonal metadata. Learn more about how to set custom zonal metadata.

Instance metadata

Instance metadata provides information about a specific VM instance. You set instance metadata separately for each individual VM instance.

You can use both predefined and custom metadata keys to set instance metadata. Learn more about predefined instance metadata keys and how to Set custom instance metadata.

How metadata is arranged

Compute Engine stores and maintains the metadata keys and values for your VMs and projects in directory listings. Depending on the type of metadata, Compute Engine stores metadata entries in one of the following directories:

Type of metadata Directory
  • Project metadata
  • Zonal metadata
 
http://metadata.google.internal/computeMetadata/v1/project/
Instance metadata 
http://metadata.google.internal/computeMetadata/v1/instance/

Each directory stores metadata entries in the form of key-value pairs. Some metadata entries are also directories that contain other metadata keys. The metadata entries that function as directories are marked by a trailing slash (/) in the metadata key name. For example, /project/attributes/ is a directory under the project/ directory that contains other metadata keys. To create your own metadata directory listing, you must use a trailing slash (/) in the metadata key name when you create your custom metadata entry.

Project and zonal metadata entries are stored in the same project/ directory. If you set different values for the same custom metadata keys for VMs on a project level and on a zonal level, then the zonal metadata values for those keys take precedence over the project metadata values in the respective zones.

  • If you add a zonal metadata value for a metadata key that already has a project metadata value, then Compute Engine overrides the project metadata value for the VMs in this specified zone and updates the /project directory with the zonal value.
  • If you add a new project-wide metadata value for a metadata key that already has a zonal metadata value, then nothing changes. Compute Engine retains the zonal metadata value in the /project directory in the specific zone.
  • If you don't specify a zonal metadata value for a custom metadata key in a specific zone, but the key has a project metadata value, then your VMs continue to have the project metadata values in those zones.

For example, suppose you define a project-wide metadata pair of key-1=value-1. Suppose you also define a zonal metadata pair of key-1=zonal-value-1 for only the us-central1-a zone. All the VMs in the us-central1-a zone for your project inherit key-1=zonal-value1 as the metadata pair. The metadata pair remains key-1=value-1 for all VMs in other zones where you haven't set any zonal metadata for key-1.

What's next?