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 and instance metadata, based on the kind of information it provides.

Project metadata

Project metadata provides information about the project. Project metadata is further divided into the following types, depending on the scope you define for your project metadata:

  • Project-wide metadata is project metadata that you define with a project scope. You set this metadata on a project level and the metadata propagates to all VMs in that project.

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

  • Project zonal metadata (Preview) is project metadata that you define with a zonal scope within the project. The metadata that you set propagates only to the VMs in the configured zone in that project. Project zonal metadata helps you with fault isolation and provides greater reliability. You can also use project zonal metadata to override the project-wide values for any existing keys and use zone-specific values.

    Compute Engine doesn't provide any predefined keys for project zonal metadata. You must create your own custom project zonal metadata keys. Learn more about how to set custom project 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-wide metadata
  • Project zonal metadata
Instance metadata

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 project 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 project zonal level, then the project zonal metadata values for those keys take precedence over the project-wide metadata values in the respective zones.

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

For example, suppose you define a project-wide metadata pair of key-1=value-1. Suppose you also define a project 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 project zonal metadata for key-1.

What's next?