设置和查询客机特性

客户机特性是指应用在虚拟机 (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

  2. Set a default region and zone.

  REST

  如需在本地开发环境中使用本页面上的 REST API 示例，请使用您提供给 gcloud CLI 的凭据。

  Install the Google Cloud CLI, then initialize it by running the following command:

  gcloud init

  如需了解详情，请参阅 Google Cloud 身份验证文档中的使用 REST 时进行身份验证。

所需的角色

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

虚拟机内部

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

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

虚拟机外部

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

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

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

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

何时使用客机特性

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

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

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

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

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

客机属性和其他 Google Cloud 服务

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

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

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

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

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

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

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

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

设置客户机特性

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

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

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

获取客户机特性

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

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

查询元数据服务器

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

1. 连接到虚拟机。

2. 查询客机属性。

   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 compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

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

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

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

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

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

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

删除客机特性

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

1. 连接到虚拟机。

2. 删除客机属性。

   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

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

后续步骤

• 详细了解虚拟机元数据。