设置和查询客机特性

Linux Windows

客户机特性是指应用在虚拟机 (VM) 实例上运行期间可写入的特定类型的自定义元数据。虚拟机实例上的任何应用或用户都可以对这些客户机特性元数据值执行数据读取和写入操作。

准备工作

对于 Windows Server 虚拟机，请使用 PowerShell 3.0 或更高版本。我们建议您使用 ctrl+v 来粘贴复制的代码块。
如果您尚未设置身份验证，请进行设置。身份验证是通过其进行身份验证以访问 Google Cloud 服务和 API 的过程。如需从本地开发环境运行代码或示例，您可以按如下方式向 Compute Engine 进行身份验证。

Select the tab for how you plan to use the samples on this page:
Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
gcloud
1. Install the Google Cloud CLI, then initialize it by running the following command:
  gcloud init
  Note: If you installed the gcloud CLI previously, make sure you have the latest version by running gcloud components update.
2. Set a default region and zone.

所需的角色

所需的权限或角色取决于您是从虚拟机内部还是外部完成任务。

虚拟机内部

如果您要从虚拟机内部设置、查询或删除客机属性，则您只需要具有用于连接到虚拟机的角色和权限。在虚拟机实例中运行的任何进程都可以将数据写入客机属性值，包括没有 sudo 或管理员级权限的脚本和应用。

对于虚拟机内部的读取和写入操作，元数据服务器会提供实例级的自动身份验证和授权。每个虚拟机只能对自己的元数据服务器执行读取或写入操作。一个虚拟机的元数据服务器不可供其他虚拟机访问。

虚拟机外部

使用 Google Cloud CLI 或 REST 从虚拟机外部启用客机属性或查看客机属性需要以下角色和权限。您无法从虚拟机外部设置或删除客机属性。

如需确保您的用户或服务账号具有启用或查看客机属性所需的权限，请让您的管理员为您的用户或服务账号授予虚拟机或项目的 Compute Instance Admin (v1) (roles/compute.instanceAdmin.v1) IAM 角色。如需详细了解如何授予角色，请参阅管理访问权限。

此预定义角色可提供启用或查看客机属性所需的权限。如需查看所需的确切权限，请展开所需权限部分：

所需权限

启用或查看客机属性需要以下权限：

启用客机属性：针对虚拟机或项目的 compute.instances.setMetadata 权限
查看客机属性：针对虚拟机或项目的 compute.instances.getGuestAttributes 权限

您的管理员也可以使用自定义角色或其他预定义角色为您的用户或服务账号授予这些权限。

何时使用客机特性

客机特性仅适用于需要少量不常更改的数据的用例，最适合使用客机特性的用例具有以下特征：

每个虚拟机实例的查询次数限制为每分钟最多 10 次查询。
查询作业的爆发速率不超过每秒 3 次查询。如果超出此速率上限，Compute Engine 可能会任意移除正在写入的客机特性。移除此数据是为了确保能将其他关键系统数据写入服务器。

客机属性非常适合您需要发布少量不常见数据的情况。例如，客机特性在以下用例中会很实用：

启动脚本可以通过在客机特性中设置自定义状态值来发送初始化成功信号。
配置管理代理可以将客机操作系统名称和版本发布到客机特性。
库存管理代理可以将虚拟机实例中安装的软件包列表发布到客机特性。
工作负载编排软件可以通过在客机属性中设置自定义状态值，向软件控制平面发送客机内部操作的完成信号。

客机特性不能替代事件流、Pub/Sub 或其他形式的数据存储和配置代码库。

客机属性和其他 Google Cloud 服务

客机属性供其他 Google Cloud 服务使用，如下所示：

SSH 安全性：如果启用了客机属性并停用了 OS Login，则客机环境和 gcloud CLI 会使用客机属性，通过 Google API 检索主机密钥来提高 SSH 安全性，然后才能使用 SSH 连接到虚拟机。
虚拟机管理器：OS Config 代理会将操作系统数据发布到客机属性。

如需查看这些服务存储的元数据条目，请参阅预定义的客机属性元数据键。

在虚拟机上启用客户机特性

默认情况下，客机特性处于停用状态。如需启用客户机特性，请在个别虚拟机或项目级元数据中设置必要的元数据值：

控制台

创建虚拟机时，在实例元数据中设置 enable-guest-attributes：

在 Google Cloud 控制台中，转到创建实例页面。

转到“创建实例”
指定虚拟机详情。
展开高级选项部分，然后执行以下操作：
1. 展开管理部分。
2. 在元数据部分中，点击添加一项以添加以下元数据条目：
  - 键：enable-guest-attributes
  - 值：TRUE
如需创建虚拟机，请点击创建。

在项目范围的元数据中设置 enable-guest-attributes，使其应用于项目中的所有虚拟机：

在 Google Cloud 控制台中，转到元数据页面。

转到“元数据”页面
点击修改。
添加一个键为 enable-guest-attributes 且值为 TRUE 的元数据条目。或者，将值设置为 FALSE 以停用该功能。
点击保存以应用更改。

在现有虚拟机的元数据中设置 enable-guest-attributes：

在 Google Cloud 控制台中，转到虚拟机实例页面。
转到“虚拟机实例”页面
点击要设置元数据值的虚拟机的名称。
在实例详情页面的顶部，点击修改以修改实例设置。
在自定义元数据下方，添加一个元数据键，其中键为 enable-guest-attributes，值为 TRUE。或者，将值设置为 FALSE 以在虚拟机上停用该功能。
在实例详情页面的底部，点击保存以将更改应用于虚拟机。

gcloud

创建虚拟机时，在实例元数据中设置 enable-guest-attributes：

在 Google Cloud CLI 中，使用 gcloud compute instances create 命令并设置 enable-guest-attributes=TRUE，以启用客机特性。将 VM_NAME 替换为虚拟机名称。

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

在项目范围的元数据中设置 enable-guest-attributes，使其应用于项目中的所有虚拟机：

在 Google Cloud CLI 中，使用 project-info add-metadata 命令并设置 enable-guest-attributes=TRUE，以启用客机特性：

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

您也可以将 enable-guest-attributes 设为 FALSE 以停用客机特性。

在现有虚拟机的元数据中设置 enable-guest-attributes：

在 Google Cloud CLI 中，使用 instances add-metadata 命令并设置 enable-guest-attributes=TRUE，以启用客机特性。将 VM_NAME 替换为虚拟机名称。

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

您也可以将 enable-guest-attributes 设为 FALSE，以对虚拟机停用客户机特性。

设置客户机特性

在虚拟机实例中运行的任何进程都可以写入客户机特性值，包括没有 sudo 或管理员级权限的脚本和应用。虚拟机外部的用户或服务账号不能写入客户机特性元数据值。

Linux 虚拟机

例如，您可以在自己的虚拟机中使用 curl 请求向 guest-attributes 元数据路径写入值：

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

请替换以下内容：

NAMESPACE：KEY 的逻辑分组。客机特性必须具有命名空间。
VALUE：要写入的值。
KEY：guest-attributes 中用于存储值的元数据路径。

对于 NAMESPACE 和 KEY 字段，只能使用字母、数字、下划线 (_) 和连字符 (-)。

Windows 虚拟机

例如，您可以在自己的虚拟机中使用 Invoke-RestMethod 请求向 guest-attributes 元数据路径写入值：

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

请替换以下内容：

NAMESPACE：KEY 的逻辑分组。客机特性必须具有命名空间。
VALUE：要写入的值。
KEY：guest-attributes 中用于存储值的元数据路径。

对于 NAMESPACE 和 KEY 字段，只能使用字母、数字、下划线 (_) 和连字符 (-)。

获取客户机特性

如果用户或服务账号具有所需的角色，则可以从虚拟机外部读取客机属性。此外，虚拟机中的任何用户或应用也都可以读取该特定虚拟机的元数据值。

在虚拟机中运行的任何进程都可以写入客户机特性值，包括没有 sudo 或管理员级权限的脚本和应用。

查询元数据服务器

按照以下说明从虚拟机内部查询客机属性。

连接到虚拟机。
查询客机属性。
Linux 虚拟机
例如，您可以在自己的虚拟机中使用 curl 请求从 guest-attributes 元数据路径中读取值：
```
curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"
```
请替换以下内容：
- NAMESPACE：您要查询的 guest-attributes 键的命名空间。
- KEY：您要从中读取元数据值的 guest-attributes 路径。
您也可以在一个请求中返回所有客机特性值。将 NAMESPACE 替换为您要查询的 guest-attributes 键的命名空间。
```
curl http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/ -H "Metadata-Flavor: Google"
```
Windows 虚拟机
例如，您可以在自己的虚拟机中使用 Invoke-RestMethod 请求从 guest-attributes 元数据路径中读取值：
```
PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value
```
请替换以下内容：
- NAMESPACE：您要查询的 guest-attributes 键的命名空间。
- KEY：您要从中读取元数据值的 guest-attributes 路径。
您也可以在一个请求中返回所有客机特性值。将 NAMESPACE 替换为您要查询的 guest-attributes 键的命名空间。
```
PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/")
$value
```

使用 Google Cloud CLI 或 REST

按照以下说明从虚拟机外部查看客机属性。

gcloud

使用 Google Cloud CLI 读取虚拟机的客机属性元数据值。例如，您可以按如下所示检索虚拟机的所有值：

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

如需检索特定命名空间下的所有值，请加入 --query-path 标志和您定义的命名空间：

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

如需检索特定命名空间下的所有值，请加入 --query-path 标志、相应命名空间和您所定义的值对应的键：

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

请替换以下内容：

VM_NAME：您要从中读取客户机特性元数据值的虚拟机的名称
NAMESPACE：您要查询的 guest-attributes 键的命名空间
KEY：guest-attributes 元数据中用于存储值的路径
ZONE：该虚拟机所在的可用区

REST

使用 compute.instances.getguestattributes 方法：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

替换以下内容：

PROJECT_ID：您的项目 ID
ZONE：虚拟机所在的可用区
VM_NAME：您要从中读取客户机特性元数据值的虚拟机的名称
NAMESPACE：您要查询的 guest-attributes 键的命名空间
KEY：guest-attributes 元数据中用于存储值的路径

如需检索 NAMESPACE 的所有键，请省略 KEY：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

如需检索该虚拟机在每个命名空间中的所有键，请完全省略 NAMESPACE 和 queryPath：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes

或者，如果您有 OAuth 令牌，则可以使用 curl：

curl -H "Authorization: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

请替换以下内容：

OAUTH_TOKEN：您的 OAuth 令牌
PROJECT_ID：您的项目 ID
ZONE：虚拟机所在的可用区
VM_NAME：您要从中读取客户机特性元数据值的虚拟机的名称
NAMESPACE：您要查询的 guest-attributes 键的命名空间
KEY：guest-attributes 元数据中用于存储值的路径

删除客机特性

按照以下说明从虚拟机内部移除客机属性。

连接到虚拟机。
删除客机属性。
Linux 虚拟机
您还可以删除客机特性。例如，使用 curl 删除特定键：
```
curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"
```
请替换以下内容：
- NAMESPACE：您要删除的 guest-attributes 键的命名空间
- KEY：guest-attributes 中用于存储值的路径
Windows 虚拟机
您还可以删除客机特性。例如，使用 Invoke-RestMethod 删除特定键：
```
PS C:\> 
$value = (Invoke-RestMethod `
          -Method DELETE `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value
```
请替换以下内容：
- NAMESPACE：您要删除的 guest-attributes 键的命名空间
- KEY：guest-attributes 中用于存储值的路径

对组织或文件夹停用客机特性

如果您不希望您的组织或文件夹中的任何虚拟机启用客户机特性，则可以完全替换并停用该功能。

对您的组织或文件夹设置 constraints/compute.disableGuestAttributesAccess 限制条件，注意将 PROJECT_ID 替换为您的项目名称：

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project=PROJECT_ID

如需详细了解如何设置和管理针对组织的限制条件，请参阅使用限制条件。

后续步骤

详细了解虚拟机元数据。

设置和查询客机特性

准备工作

Console

gcloud

REST

所需的角色

虚拟机内部

虚拟机外部

所需权限

何时使用客机特性

客机属性和其他 Google Cloud 服务

在虚拟机上启用客户机特性

控制台

gcloud

设置客户机特性

Linux 虚拟机

Windows 虚拟机

获取客户机特性

查询元数据服务器

Linux 虚拟机

Windows 虚拟机

使用 Google Cloud CLI 或 REST

gcloud

REST

删除客机特性

Linux 虚拟机

Windows 虚拟机

对组织或文件夹停用客机特性

后续步骤