Every virtual machine (VM) instance stores its metadata on a metadata server.Your VM automatically has access to the metadata server API without anyadditional authorization. Compute Engine maintains the metadata keysand values for your VMs and projects in directories. Each directory storesmetadata entries in the form of key-value pairs. Some directories containsubdirectories.

This document provides an overview about VM metadata and explains about thetypes and properties of VM metadata.

VM metadata uses

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

Startup and shutdown scripts

The metadata server is particularly useful when used in combination withstartup and shutdown scripts because you can use the metadata server toprogrammatically get unique information about a VM, without additional authorization.

For example, you can write a startup script that gets the metadata key-valuepair 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. Thishelps you create less brittle code for your applications.

• For more information about startup scripts, see thestartup script overview.
• For more information about shutdown scripts, seeRunning shutdown scripts.

Host maintenance

The metadata server provides information about a VM's scheduling optionin thescheduling/ metadata directory by using themaintenance-eventkey. You can use these metadata values to notify you when a maintenance eventis about to happen so that you can prepare your environment for the event.For more information, seeGet live migration notices.

Guest attributes

Guest attributes are a specific type of custom metadata that your applicationscan write to while running on your VMs. Use guest attributes only for usecases that require small amounts of data that don't change frequently. Formore information about guest attributes, seeSet and query guest attributes.

Partner attributes

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

Partner attributes are a specific type of instance metadata. Google Cloudservices can use partner attributes to create a namespace within which they candefine instance metadata entries. You can set, update, delete, and view thevalues of the instance metadata entries to configure that service.

For example, when you use managed workload identities for Compute Engine, youcan specify the configuration details in themetadata entries of that service's namespace.

Metadata security considerations

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

However, any process that canquery the metadata URL,has access to all values in the metadata server. This includes any custommetadata values, client certificates, and private keys that you write tothe server. Google recommends that youexercise caution when writing sensitive values to the metadata server or whenrunning third-party processes. You must sandbox any process that shouldn't beable to access the metadata server.

Metadata server endpoints

The metadata server is accessible from the following endpoints:

• An HTTP endpoint:http://metadata.google.internal/computeMetadata/v1.This endpoint is accessible from all VMs including Shielded VMs.
• An HTTPS endpoint:https://metadata.google.internal/computeMetadata/v1. This endpoint is accessiblefrom Shielded VMs only.

HTTPS metadata server endpoint

The HTTPS metadata server endpoint (https://metadata.google.internal/computeMetadata/v1) provides addedsecurity for transmission of information between the metadata server and the VM.This endpoint is only available for Shielded VMs.

Benefits of using the HTTPS metadata server endpoint

Using the HTTPS endpoint to query the metadata server provides the followingbenefits:

• Improves security: helps to prevent unauthorized access to your sensitivemetadata. It prevents an attacker from being able to perform any of thefollowing actions:

  • Spoofing or impersonating the metadata server to gain access to a VM
  • Viewing or tampering with sensitive metadata before it reaches the VM

• Reduces costs: helps you avoid the costs associated with security breaches

How the process works

For shielded VMs that have the guest environment installed,the following processes take place on your VM:

1. Compute Engine creates three certificates as follows:

   • A self-signed root certificate: a unique certificateCompute Engine generates for the VM. Compute Enginegenerates this certificate only on the first boot of the VM, and it is validfor 50 years.
   • A server identity certificate: a certificate for the metadata server.

   • A client identity certificate: a certificate for the client. Themetadata server does not cache this certificate. The guest environmentreceives a new certificate from the metadata server on each call to theclient certificate endpoint. This certificate is valid for 7 days.The guest environment must call the endpoint at least every 7 daysto get a new certificate and maintain a valid one.

     For storage locations of client identity and root certificates, seeWhere are certificates stored.

2. On first boot, Compute Engine transfers the public portion of theroot certificate to the guest environment of the VM by using aGoogle-generated UEFI variable. This root certificate is then stored onthe VM.

3. Periodically, the guest environment requests a client identity certificate.When this happens, the guest agent downloads this certificate fromthe metadata server and validates it by using the root certificate for thatVM.

When you make aquery to the HTTPS metadata server endpoint,you specify the client identity certificates which are then used by the metadataserver and the VM to verify that this query is authorized.

Enable automatic certificate setup

If you want your instances or projects toautomatically setup the HTTPS MDS certificates,set thedisable-https-mds-setup metadata key on your instance or projecttoFALSE.

For more information, seePredefined Metadata Keys.

Where are certificates stored

The following sections list the storage location for root and client identitycertificates that are generated by Compute Engine.

Root certificates

/run/google-mds-mtls/root.crt

/run/google-mds-mtls/root.crt

/run/google-mds-mtls/root.crt

/run/google-mds-mtls/root.crt

C:\ProgramData\Google\ComputeEngine\mds-mtls-root.crt

Client identity certificates

Client identity certificates are accessible to all processes that arerunning on the VM. This is needed so that all processes have access to themetadata server by using the HTTPS endpoint, similar to the HTTP endpoint.For more information, seeMetadata security considerations.

/run/google-mds-mtls/client.key

Enabling root certificate storage in OS trust store

If you want Compute Engine to automatically add the HTTPS metadata server rootcertificate to your OS trust store, set theenable-https-mds-native-cert-storemetadata key on your instance or project toTRUE.

If you enable this option, Compute Engine adds the root certificate to thefollowing locations in addition to their default location.

/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem

/etc/ssl/certs/ca-certificates.crt

/etc/pki/tls/certs/ca-bundle.crt

/etc/ssl/ca-bundle.pem

Cert:\LocalMachine\Root

For more information, seePredefined Metadata Keys.

Predefined and custom metadata keys

Each metadata entry is stored on the metadata server as key-valuepairs. Metadata keys are case sensitive. Your keys can be either predefinedor 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 setsthe metadata values for some of these keys on that VM—for example, the VMinstance ID or the project ID. For predefined keys where Compute Engine doesn'tautomatically set a value, you can choose from a set of values that are availabledepending on the system configuration.Forexample, to enable OS login for a VM, you can set the value of theenable-osloginpredefined key toTRUE for that VM. To disable OS login for that VM, you can updatethe value of the key toFALSE.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,seePredefined metadata keys.

Custom metadata keys

Custom metadata enables you to create and use your own metadata key-value pairs onan individual VM or a project. You can add new custom metadata keys, update the values of yourexisting 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 aproject. It is also useful for creatingstartup andshutdown scripts.

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

Types of metadata

VM metadata entries can provide information specific to an individual VM or aproject. 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 thatapplies to all VMs in a project. When you set this metadata, the metadataentries propagate to all VMs in that project.

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

Zonal metadata

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

Compute Engine doesn't provide any predefined keys for zonal metadata. Youmust create your own custom metadata keys to set zonal metadata. Learn moreabout how toset custom zonal metadata.

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

How metadata is arranged

Compute Engine stores and maintains the metadata keys and values foryour VMs and projects in directory listings. Depending on the type ofmetadata, Compute Engine stores metadata entries in one of the followingdirectories:

Each directory stores metadata entries in the form of key-value pairs. Somemetadata entries are also directories that contain other metadata keys. Themetadata entries that function as directories are marked by a trailing slash(/) in the metadata key name. For example,/project/attributes/ is adirectory under theproject/ directory that contains other metadata keys. Tocreate 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 sameproject/ directory. If you set different values for the same custommetadata keys for VMs on a project level and on a zonal level, then thezonal metadata values for those keys take precedence over theproject metadata values in the respective zones.

• If you add a zonal metadata value for a metadata key that alreadyhas a project metadata value, then Compute Engine overrides the project metadatavalue for the VMs in this specified zone and updates the/project directorywith the zonal value.
• If you add a new project metadata value for a metadata key that alreadyhas a zonal metadata value, then nothing changes. Compute Engine retains thezonal 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 aspecific zone, but the key has a project metadata value, then your VMs continue tohave the project metadata values in those zones.

For example, suppose you define a project metadata pair ofkey-1=value-1. Suppose you also define a zonal metadatapair ofkey-1=zonal-value-1 for only theus-central1-azone. All the VMs in theus-central1-a zone for your projectinheritkey-1=zonal-value1 as the metadata pair. The metadata pairremainskey-1=value-1 for all VMs in other zones where you haven'tset any zonal metadata forkey-1.

What's next?

• Learn about thepredefined metadata keysthat Google Cloud offers.
• Learn how toconfigure custom metadata entries.
• Learn how toset and query guest attributes.
• After setting values for your metadata keys, learn how toview and query VM metadata informationfor a VM or a project.
• Learn how toget live migration noticesfrom the metadata server.