客户机特性是指应用在虚拟机 (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
-
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
- Set a default region and zone.
-
启用客机属性:针对虚拟机或项目的
compute.instances.setMetadata
-
查看客机属性:针对虚拟机或项目的
compute.instances.getGuestAttributes
- 每个虚拟机实例的查询次数限制为每分钟最多 10 次查询。
- 查询作业的爆发速率不超过每秒 3 次查询。如果超出此速率上限,Compute Engine 可能会任意移除正在写入的客机特性。移除此数据是为了确保能将其他关键系统数据写入服务器。
- 启动脚本可以通过在客机特性中设置自定义状态值来发送初始化成功信号。
- 配置管理代理可以将客机操作系统名称和版本发布到客机特性。
- 库存管理代理可以将虚拟机实例中安装的软件包列表发布到客机特性。
- 工作负载编排软件可以通过在客机属性中设置自定义状态值,向软件控制平面发送客机内部操作的完成信号。
- SSH 安全性:如果启用了客机属性并停用了 OS Login,则客机环境和 gcloud CLI 会使用客机属性,通过 Google API 检索主机密钥来提高 SSH 安全性,然后才能使用 SSH 连接到虚拟机。
- 虚拟机管理器:OS Config 代理会将操作系统数据发布到客机属性。
在 Google Cloud 控制台中,转到创建实例页面。
指定虚拟机详情。
展开高级选项部分,然后执行以下操作:
- 展开管理部分。
在元数据部分中,点击添加一项以添加以下元数据条目:
- 键:
enable-guest-attributes
- 值:
TRUE
- 键:
如需创建虚拟机,请点击创建。
在 Google Cloud 控制台中,转到元数据页面。
点击修改。
添加一个键为
enable-guest-attributes
且值为TRUE
的元数据条目。或者,将值设置为FALSE
以停用该功能。点击保存以应用更改。
- 在 Google Cloud 控制台中,转到虚拟机实例页面。
- 点击要设置元数据值的虚拟机的名称。
- 在实例详情页面的顶部,点击修改以修改实例设置。
- 在自定义元数据下方,添加一个元数据键,其中键为
enable-guest-attributes
,值为TRUE
。或者,将值设置为FALSE
以在虚拟机上停用该功能。 - 在实例详情页面的底部,点击保存以将更改应用于虚拟机。
NAMESPACE
:KEY
的逻辑分组。客机特性必须具有命名空间。VALUE
:要写入的值。KEY
:guest-attributes
中用于存储值的元数据路径。NAMESPACE
:KEY
的逻辑分组。客机特性必须具有命名空间。VALUE
:要写入的值。KEY
:guest-attributes
中用于存储值的元数据路径。连接到虚拟机。
查询客机属性。
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
VM_NAME
:您要从中读取客户机特性元数据值的虚拟机的名称NAMESPACE
:您要查询的guest-attributes
键的命名空间KEY
:guest-attributes
元数据中用于存储值的路径ZONE
:该虚拟机所在的可用区PROJECT_ID
:您的项目 IDZONE
:虚拟机所在的可用区VM_NAME
:您要从中读取客户机特性元数据值的虚拟机的名称NAMESPACE
:您要查询的guest-attributes
键的命名空间KEY
:guest-attributes
元数据中用于存储值的路径OAUTH_TOKEN
:您的 OAuth 令牌PROJECT_ID
:您的项目 IDZONE
:虚拟机所在的可用区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
中用于存储值的路径
- 详细了解虚拟机元数据。
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 角色。 如需详细了解如何授予角色,请参阅管理访问权限。此预定义角色可提供启用或查看客机属性所需的权限。如需查看所需的确切权限,请展开所需权限部分:
所需权限
启用或查看客机属性需要以下权限:
您的管理员也可以使用自定义角色或其他预定义角色为您的用户或服务账号授予这些权限。
何时使用客机特性
客机特性仅适用于需要少量不常更改的数据的用例,最适合使用客机特性的用例具有以下特征:
客机属性非常适合您需要发布少量不常见数据的情况。例如,客机特性在以下用例中会很实用:
客机特性不能替代事件流、Pub/Sub 或其他形式的数据存储和配置代码库。
客机属性和其他 Google Cloud 服务
客机属性供其他 Google Cloud 服务使用,如下所示:
如需查看这些服务存储的元数据条目,请参阅预定义的客机属性元数据键。
在虚拟机上启用客户机特性
默认情况下,客机特性处于停用状态。如需启用客户机特性,请在个别虚拟机或项目级元数据中设置必要的元数据值:
控制台
创建虚拟机时,在实例元数据中设置
enable-guest-attributes
:在项目范围的元数据中设置
enable-guest-attributes
,使其应用于项目中的所有虚拟机:在现有虚拟机的元数据中设置
enable-guest-attributes
: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
字段,只能使用字母、数字、下划线 (_
) 和连字符 (-
)。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
字段,只能使用字母、数字、下划线 (_
) 和连字符 (-
)。获取客户机特性
如果用户或服务账号具有所需的角色,则可以从虚拟机外部读取客机属性。此外,虚拟机中的任何用户或应用也都可以读取该特定虚拟机的元数据值。
在虚拟机中运行的任何进程都可以写入客户机特性值,包括没有 sudo 或管理员级权限的脚本和应用。
查询元数据服务器
按照以下说明从虚拟机内部查询客机属性。
使用 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
请替换以下内容:
REST
使用
compute.instances.getguestattributes
方法:GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY
替换以下内容:
如需检索
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
请替换以下内容:
删除客机特性
按照以下说明从虚拟机内部移除客机属性。
对组织或文件夹停用客机特性
如果您不希望您的组织或文件夹中的任何虚拟机启用客户机特性,则可以完全替换并停用该功能。
对您的组织或文件夹设置
constraints/compute.disableGuestAttributesAccess
限制条件,注意将PROJECT_ID
替换为您的项目名称:gcloud resource-manager org-policies enable-enforce \ constraints/compute.disableGuestAttributesAccess \ --project=PROJECT_ID
如需详细了解如何设置和管理针对组织的限制条件,请参阅使用限制条件。
后续步骤
如未另行说明,那么本页面中的内容已根据知识共享署名 4.0 许可获得了许可,并且代码示例已根据 Apache 2.0 许可获得了许可。有关详情,请参阅 Google 开发者网站政策。Java 是 Oracle 和/或其关联公司的注册商标。
最后更新时间 (UTC):2024-10-04。
-