Predefined 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 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.

This document provides information about the predefined metadata keys that Compute Engine provides in your instance/ and project/ metadata directories.

For information about how VM metadata for Compute Engine is defined, categorized, and arranged, see About VM metadata.

Predefined project metadata keys

Predefined metadata keys for project metadata are stored under the following directory:

  • http://metadata.google.internal/computeMetadata/v1/project/

The following table provides a list of metadata keys and directories that Compute Engine automatically creates in the project/ metadata directory:

Metadata entry Description
attributes/

A directory of custom metadata values passed to the VMs in your project during startup or shutdown. These custom values can either be Google Cloud attributes or user-created metadata values.

For a list of project-level Google Cloud attributes that you can set, see Project attributes.

For more information about setting custom metadata, see Set custom metadata.
numeric-project-id The numeric project ID (project number) of the instance, which is not the same as the project name that is visible in the Google Cloud console. This value is different from the project-id metadata entry value.
project-id The project ID.

Predefined project attribute metadata keys

Predefined metadata keys for project attributes are stored under the following directory:

  • http://metadata.google.internal/computeMetadata/v1/project/attributes/

The following table provides a list of metadata keys that Compute Engine automatically creates in the project/attributes/ metadata directory:

Metadata entry Description
disable-legacy-endpoints

Disables legacy metadata server endpoints for all VMs in your project.

Legacy endpoints are deprecated, always set disable-legacy-endpoints=TRUE.

enable-guest-attributes

Sets guest attributes for the project.

Guest attributes are custom VM instance metadata values that you can use to publish infrequent status notifications, low volume data, or low frequency data. These values are useful for indicating when startup scripts have finished or for providing other infrequent status notifications to other applications.

For more information about guest attributes, see Set and query guest attributes.

enable-os-inventory

Enables or disables OS inventory for the project.

Collects and stores OS information. This includes information such as hostname, kernel version, architecture, and installed packages.

For more information about OS inventory, see View operating system details.

enable-oslogin

Enables or disables SSH key management on your project.

For more information about OS Login, see Set up OS Login.

enable-windows-ssh

Enables or disables SSH for Windows VMs.

For more information, see Connect to Windows VMs using SSH.

google-compute-default-region If set, stores the default region that is used by the project.

For more information about setting default regions, see Default region and zone.

google-compute-default-zone If set, stores the default zone that is used by the project.

For more information about setting default zones, see Default region and zone.

ssh-keys

If you are managing SSH keys using metadata, this attribute lets you configure public SSH keys that can connect to VMs in this project. If there are multiple SSH keys, each key is separated by a newline character (\n). The value of the ssh-keys attribute is a string.

Example: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

SSH keys managed by OS Login aren't visible in metadata.

sshKeys Deprecated: Use ssh-keys.
vmdnssetting

Enable zonal DNS and global DNS for the VMs in your project.

For more information about using zonal DNS names for your VMs, see Use Zonal DNS for your internal DNS type.

Predefined instance metadata keys

Predefined metadata keys for instance metadata are stored under the following directory:

  • http://metadata.google.internal/computeMetadata/v1/instance/

The following table provides a list of metadata keys and directories that Compute Engine automatically creates in the instance/ metadata directory:

Metadata entry Description
attributes/

A directory of custom metadata values passed to the VM during startup or shutdown. These custom values can either be Google Cloud attributes or user-created metadata values.

For a list of instance-level Google Cloud attributes that you can set, see Instance attributes

For more information about setting custom metadata, see Set custom metadata.
cpu-platform

CPU platform of the VM.

For information about CPU platforms, see CPU platforms.
description The free-text description of an instance that is assigned using the --description flag by using the Google Cloud CLI or the API.
disks/

A directory of disks that are attached to the VM. For each disk, the following information is available:

  • device-name
  • index
  • interface
  • mode
  • type

For more information about disks, see Storage options.

gce-workload-certificates/(Preview)

Stores the following endpoints for the managed workload identities feature used by applications running in the VM.

  • config-status: Contains any errors in the configuration values provided through the VM metadata.
  • workload-identities: Contains the identities managed by the Compute Engine control plane. This endpoint contains the X.509 certificate and the private key for the VM's trust domain.
  • trust-anchors: Contains a set of trusted certificates for peer X.509 certificate chain validation.

For more information, see Authenticate workloads to other workloads over mTLS.

guest-attributes/

Sets guest attributes for the VM. These custom values can either be Google Cloud attributes or user-created metadata values.

For a list of instance-level Google Cloud attributes that you can set, see Instance guest attributes

For more information about guest attributes, see Set and query guest attributes.

hostname The hostname of the VM.
id The ID of the VM. This is a unique, numerical ID that is generated by Compute Engine. This is useful for identifying VMs if you don't use VM names.
image The operating system image used by the VM. This value has the following format: projects/IMAGE_PROJECT/global/images/IMAGE_NAME.
legacy-endpoint-access/ Stores the list of legacy endpoints. Values are 0.1 and v1beta1.
licenses/ A list of license code IDs that are used to attach the licenses to images, snapshots, and disks.
machine-type The machine type for this VM. This value has the following format: projects/PROJECT_NUM/machineTypes/MACHINE_TYPE
maintenance-event Indicates whether a maintenance event is affecting this VM. For more information, see Live migrate.
name The name of the VM.
network-interfaces/

A directory of network interfaces. For each network interface the following information is available:

  • access-configs/

    • external-ip
    • type
  • dns-servers
  • forwarded-ips/
  • gateway
  • ip
  • ip-aliases/
  • mac
  • mtu
  • network
  • subnetmask
  • target-instance-ips

For more information about network interfaces, see Multiple network interfaces overview.

partner-attributes/(Preview)

A directory containing namespaces within which metadata entries are stored. The namespaces are created by Google Cloud services, which use partner-attributes to store their configurations. When there are no services using the partner-attributes, the directory is empty.

For example, managed workload identities use partner-attributes for its configurations.

preempted

A boolean value that indicates whether a VM is about to be preempted.
scheduling/

Sets the scheduling options for the VM.

Scheduling metadata values include the following:

  • on-host-maintenance: indicates whether the VM terminates or live migrates during host maintenance.
  • automatic-restart: If this value is TRUE, the VM automatically restarts after a maintenance event or crash.
  • preemptible: If this value is TRUE, the VM is preemptible. This value is set when you create a VM, and it can't be changed.

For more information about scheduling options, see Set instance availability policies.

service-accounts/

A directory of service accounts associated with the VM. For each service account, the following information is available:

  • aliases
  • email: The email address for the service account.
  • identity: A JSON Web Token that is unique to the VM. You must include the audience parameter in your request for this VM metadata value. For example, ?audience=http://www.example.com.

    For information about how to request and verify instance identity tokens, see Verify VM identity.

  • scopes: The access scopes assigned to the service account.
  • token: The OAuth2 access token that can be used to authenticate applications.

    For information about access tokens, see Authenticating applications directly with access tokens.

For more information about how Compute Engine uses service accounts, see Service accounts.

tags

Lists any network tags associated with the VM.

For more information about network tags, see Add network tags.

zone The zone where this VM is located. This value has the following format: projects/PROJECT_NUM/zones/ZONE

Predefined instance attribute metadata keys

Predefined metadata keys for instance attributes are stored under the following directory:

  • http://metadata.google.internal/computeMetadata/v1/instance/attributes/

The following table provides a list of metadata keys that Compute Engine automatically creates in the instance/attributes/ metadata directory:

Metadata entry Description
physical_host

A hash string that represents the location of a VM created with a compact placement policy.

For more information about this attribute, see Verify the physical location of a VM.

enable-oslogin

Enables or disables SSH key management on your VM.

For more information about OS Login, see Set up OS Login.

enable-windows-ssh (Preview)

Enables or disables SSH for Windows VMs.

For more information, see Connect to Windows VMs using SSH.

enable-workload-certificate (Preview)

Enables or disables managed workload identities on a VM.

For more information, see Enable managed workload identities for individual VMs.
vmdnssetting

Enable zonal DNS and global DNS for the VM.

For more information about using zonal DNS names for your VMs DNS, see Use Zonal DNS for your internal DNS type.

ssh-keys

If you are managing SSH keys using metadata, this attribute lets you configure public SSH keys that can connect to VMs in this project. If there are multiple SSH keys, each key is separated by a newline character (\n). The value of the ssh-keys attribute is a string.

Example: "user1:ssh-rsa mypublickey user1@host.com\nuser2:ssh-rsa mypublickey user2@host.com"

SSH keys managed by OS Login aren't visible in metadata.

Predefined guest attribute metadata keys

Predefined metadata keys for instance guest attributes are stored under the following directory:

  • http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/

The following table provides a list of metadata keys and directories that Compute Engine automatically creates in the instance/guest-attributes/ metadata directory:

Metadata entry Description
guestInventory/

Stores OS inventory for the VM.

Collects and stores OS details information. This includes information such as hostname, kernel version, architecture, and installed packages details.

For more information about OS inventory, see View operating system details.

hostkeys/

Stores SSH host keys. Host keys can be used to identify a particular host or machine.

For information host keys, see Storing host keys by enabling guest attributes.

What's next?