预定义的元数据键


每个元数据条目以键值对的形式存储在元数据服务器上。元数据键区分大小写。您的键可以是预定义键,也可以是自定义元数据键。

预定义的元数据键是由 Compute Engine 创建的元数据键。当您创建虚拟机时,Compute Engine 会自动设置该虚拟机上某些键的元数据值,例如虚拟机实例 ID 或项目 ID。对于 Compute Engine 不会自动设置值的预定义键,您可以根据系统配置从一组可用值中进行选择。 例如,如需为虚拟机启用 OS Login,您可以将该虚拟机的 enable-oslogin 预定义键的值设置为 TRUE。如需为该虚拟机停用 OS Login,您可以将键的值更新为 FALSE。 您只能更新这些键的值,不能更新键本身。

本文档介绍了 Compute Engine 在 instance/project/ 元数据目录中提供的预定义元数据键。

如需了解如何定义、分类和排列 Compute Engine 虚拟机元数据,请参阅虚拟机元数据简介

预定义的项目元数据键

项目元数据的预定义元数据键存储在以下目录下:

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

下表提供了 Compute Engine 在 project/ 元数据目录中自动创建的元数据键和目录的列表:

元数据条目 说明
attributes/

在启动或关停期间传递给项目中虚拟机的自定义元数据值的目录。这些自定义值可以是 Google Cloud 特性或用户创建的元数据值。

如需查看您可以设置的项目级 Google Cloud 特性的列表,请参阅项目特性

如需详细了解如何设置自定义元数据,请参阅设置自定义元数据

numeric-project-id 此实例的数字项目 ID(项目编号)(而非 Google Cloud 控制台中显示的项目名称)。此值与 project-id 元数据条目值不同。
project-id 项目 ID

预定义的项目属性元数据键

项目属性的预定义元数据键存储在以下目录下:

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

下表提供了 Compute Engine 在 project/attributes/ 元数据目录中自动创建的元数据键的列表:

元数据条目 说明
disable-legacy-endpoints

对项目中的所有虚拟机停用旧版元数据服务器端点。

旧版端点已弃用,请始终设置 disable-legacy-endpoints=TRUE

enable-guest-attributes

设置项目的客机特性。

客机特性是自定义虚拟机实例元数据值,可用于发布不常见状态通知、少量数据或频率较低的数据。这些值可用于指示启动脚本的完成时间,或用于向其他应用提供有关其他不常见状态的通知。

如需详细了解客户机属性,请参阅设置和查询客户机属性

enable-os-inventory

为项目启用或停用操作系统清点。

收集和存储操作系统信息。其中包括主机名、内核版本、架构和已安装的软件包等信息。

如需详细了解操作系统清单,请参阅查看操作系统详情

enable-oslogin

启用或停用项目的 SSH 密钥管理。

如需详细了解 OS Login,请参阅设置 OS Login

enable-windows-ssh

为 Windows 虚拟机启用或停用 SSH。

如需了解详情,请参阅使用 SSH 连接到 Windows 虚拟机

google-compute-default-region 如果设置此项,则系统会存储项目使用的默认区域。

如需详细了解如何设置默认区域,请参阅默认区域和可用区

google-compute-default-zone 如果设置此项,则系统会存储项目使用的默认可用区。

如需详细了解如何设置默认可用区,请参阅默认区域和可用区

ssh-keys

如果您使用元数据管理 SSH 密钥,则可以通过此特性配置可连接到此项目中虚拟机的 SSH 公钥。如果有多个 SSH 密钥,则各个密钥之间将以换行符 (\n) 分隔。ssh-keys 特性的值是一个字符串。

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

OS Login 管理的 SSH 密钥不会显示在元数据中。

sshKeys 已弃用:使用 ssh-keys
vmdnssetting

为您项目中的虚拟机启用可用区 DNS 和全球 DNS。

如需详细了解如何为虚拟机使用区域级 DNS 名称,请参阅将区域级 DNS 用于您的内部 DNS 类型

预定义的实例元数据键

实例元数据的预定义元数据键存储在以下目录下:

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

下表提供了 Compute Engine 在 instance/ 元数据目录中自动创建的元数据键和目录的列表:

元数据条目 说明
attributes/

在启动或关停期间传递给此虚拟机的自定义元数据值的目录。这些自定义值可以是 Google Cloud 特性或用户创建的元数据值。

如需查看可供设置的实例级 Google Cloud 特性的列表,请参阅实例特性

如需详细了解如何设置自定义元数据,请参阅设置自定义元数据

cpu-platform

虚拟机的 CPU 平台。

如需了解 CPU 平台,请参阅 CPU 平台

description 此实例的自由文本说明;可以使用 Google Cloud CLI 或 API 通过 --description 标志分配。
disks/

挂接到虚拟机的磁盘目录。对于每个磁盘,您可以看到以下信息:

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

如需详细了解磁盘,请参阅存储选项

gce-workload-certificates/预览版

存储虚拟机中运行的应用所使用的托管式工作负载身份功能的以下端点。

  • config-status:包含通过虚拟机元数据提供的配置值中的任何错误。
  • workload-identities:包含由 Compute Engine 控制平面管理的身份。此端点包含虚拟机信任网域的 X.509 证书和私钥。
  • trust-anchors:包含一组用于对等 X.509 证书链验证的受信任证书。

如需了解详情,请参阅通过 mTLS 向其他工作负载验证工作负载的身份

guest-attributes/

设置虚拟机的客机特性。这些自定义值可以是 Google Cloud 特性或用户创建的元数据值。

如需查看可供设置的实例级 Google Cloud 特性的列表,请参阅实例客机特性

如需详细了解客户机属性,请参阅设置和查询客户机属性

hostname 虚拟机的主机名。
id 虚拟机的 ID。这是由 Compute Engine 生成的唯一数字 ID。如果您未使用虚拟机名称,这将有助于识别虚拟机。
image 虚拟机使用的操作系统映像。该值的格式如下:projects/IMAGE_PROJECT/global/images/IMAGE_NAME
legacy-endpoint-access/ 存储旧版端点的列表。值为 0.1v1beta1
licenses/ 用于将许可附加到映像、快照和磁盘的许可代码 ID 的列表。
machine-type 此虚拟机的机器类型。该值的格式如下:projects/PROJECT_NUM/machineTypes/MACHINE_TYPE
maintenance-event 指示维护事件是否正影响此虚拟机。如需了解详情,请参阅实时迁移
name 虚拟机的名称。
network-interfaces/

网络接口目录。对于每个网络接口,系统会提供以下信息:

  • access-configs/

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

如需详细了解网络接口,请参阅多个网络接口概览

partner-attributes/预览版

一个目录,其中包含用于存储元数据条目的命名空间。命名空间由 Google Cloud 服务创建,这些服务使用合作伙伴属性存储其配置。当没有服务使用合作伙伴属性时,该目录为空。

例如,托管式工作负载身份会使用合作伙伴属性来进行配置。

preempted

一个布尔值,指示虚拟机是否即将被抢占。

scheduling/

设置虚拟机的时间安排选项。

安排元数据值包括:

  • on-host-maintenance:指示在主机维护期间虚拟机终止还是实时迁移。
  • automatic-restart:如果此值为 TRUE,则虚拟机会在维护事件或崩溃后自动重启。
  • preemptible:如果此值为 TRUE,则表示虚拟机为抢占式实例。此值是在您创建虚拟机时设置的,无法更改。

如需详细了解时间安排选项,请参阅设置实例可用性政策

service-accounts/

与此虚拟机关联的服务账号的目录。对于每个服务账号,系统会提供以下信息:

  • aliases
  • email:服务账号的电子邮件地址。
  • identity:虚拟机独有的 JSON Web 令牌。您必须在针对此虚拟机元数据值的请求中添加 audience 参数。例如,?audience=http://www.example.com

    如需了解如何请求和验证实例身份令牌,请参阅验证虚拟机身份

  • scopes:分配给服务账号的访问权限范围。
  • token:可用于对应用进行身份验证的 OAuth2 访问令牌。

    如需了解访问令牌,请参阅直接使用访问令牌对应用进行身份验证

如需详细了解 Compute Engine 如何使用服务账号,请参阅服务账号

tags

列出与虚拟机关联的所有网络标记。

如需详细了解网络标记,请参阅添加网络标记

zone 此虚拟机所在的可用区。该值的格式如下: projects/PROJECT_NUM/zones/ZONE

预定义的实例属性元数据键

实例属性的预定义元数据键存储在以下目录下:

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

下表提供了 Compute Engine 在 instance/attributes/ 元数据目录中自动创建的元数据键的列表:

元数据条目 说明
physical_host

表示创建时使用了紧凑布置政策的虚拟机所在位置的哈希字符串。

如需详细了解此属性,请参阅验证虚拟机的实际位置

enable-oslogin

在虚拟机上启用或停用 SSH 密钥管理。

如需详细了解 OS Login,请参阅设置 OS Login

enable-windows-ssh预览版

为 Windows 虚拟机启用或停用 SSH。

如需了解详情,请参阅使用 SSH 连接到 Windows 虚拟机

enable-workload-certificate预览版

在虚拟机上启用或停用托管式工作负载身份。

如需了解更多信息,请参阅为各个虚拟机启用托管式工作负载身份

vmdnssetting

为虚拟机启用可用区 DNS 和全球 DNS。

如需详细了解如何为虚拟机 DNS 使用区域级 DNS 名称,请参阅将区域级 DNS 用于您的内部 DNS 类型

ssh-keys

如果您使用元数据管理 SSH 密钥,则可以通过此特性配置可连接到此项目中虚拟机的 SSH 公钥。如果有多个 SSH 密钥,则各个密钥之间将以换行符 (\n) 分隔。ssh-keys 特性的值是一个字符串。

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

OS Login 管理的 SSH 密钥不会显示在元数据中。

预定义的客户机属性元数据键

实例客户机属性的预定义元数据键存储在以下目录下:

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

下表提供了 Compute Engine 在 instance/guest-attributes/ 元数据目录中自动创建的元数据键和目录的列表:

元数据条目 说明
guestInventory/

存储虚拟机的操作系统清点。

收集和存储操作系统详细信息。其中包括主机名、内核版本、架构和已安装的软件包详细信息等信息。

如需详细了解操作系统清单,请参阅查看操作系统详情

hostkeys/

存储 SSH 主机密钥。主机密钥可用于识别特定主机或机器。

如需了解主机密钥,请参阅通过启用客机特性存储主机密钥

后续步骤