查看和维护虚拟机元数据

本文档介绍了如何在 Google Distributed Cloud (GDC) 网闸隔离配置中查看和维护虚拟机 (VM) 实例元数据。

每个虚拟机都将其元数据以键值对 (KVP) 的形式存储在元数据服务器上。元数据 KVP 包含描述性属性、自定义配置值以及有助于识别虚拟机的信息（例如服务器名称）。无论虚拟机是正在运行还是已停止，您都可以添加和移除元数据、从虚拟机外部或内部查询元数据，以及使用元数据在系统之间传递信息。

本文档适用于平台管理员或应用运维人员群组中负责查看和维护 Distributed Cloud 环境中实例的虚拟机元数据的开发者。如需了解详情，请参阅适用于 GDC 网闸隔离配置文档的受众群体。

准备工作

如需使用 gdcloud 命令行界面 (CLI) 命令，请确保您已下载、安装并配置 gdcloud CLI。Distributed Cloud 的所有命令都使用 gdcloud 或 kubectl CLI，并且需要操作系统 (OS) 环境。

获取 kubeconfig 文件路径

如需针对 Management API 服务器运行命令，请确保您拥有以下资源：

  1. 如果您没有 Management API 服务器的 kubeconfig 文件，请登录并生成该文件。

  2. 在这些说明中，请使用 Management API 服务器的 kubeconfig 文件的路径替换 MANAGEMENT_API_SERVER。

申请 IAM 角色

如需使用 gdcloud CLI 和 API 为虚拟机实例添加、移除和维护元数据，请联系您的 IAM 项目管理员，让其为您的项目授予以下角色：

  • Virtual Machine Project Admin (project-vm-admin)：在项目命名空间中创建、列出、修改和删除虚拟机。

  • Project Viewer (project-viewer)：查看项目命名空间中的所有资源。

所有虚拟机角色都必须绑定到虚拟机所在项目的命名空间。 按照相关步骤验证您的访问权限。

添加或移除元数据

本部分介绍如何在现有虚拟机实例中添加和移除元数据。

您可以使用元数据来存储要添加到虚拟机中的任意键值对。例如，您可能希望添加和管理自己的自定义元数据，以标识不同的环境，例如 test 和 production。

添加元数据

gdcloud

  • 向特定虚拟机实例添加元数据。您必须在命令中添加 --metadata 或 --metadata-from-file 标志。如果您的用例需要，您也可以在同一命令中同时添加这两个标志：

    gdcloud compute instances add-metadata VM_NAME
    [--project=PROJECT_NAME]
    [--metadata=KEY=KEY_VALUE[,KEY=KEY_VALUE,...]]
    [--metadata-from-file=KEY=LOCAL_FILE_PATH,...]

    替换以下内容：

    • VM_NAME：虚拟机实例的名称。
    • PROJECT_NAME：虚拟机所在项目的名称。此值为可选值。
    • KEY：元数据对的键。
    • KEY_VALUE：元数据对的值。
    • LOCAL_FILE_PATH：本地文件中元数据对的值。

API

如需使用 API 添加元数据，您必须使用 STS 令牌。

  1. 使用 gdcloud CLI 生成 STS 令牌：

    gdcloud auth print-identity-token --audiences="https://metadata.ORG_SUFFIX"

    将 ORG_SUFFIX 替换为组织后缀。 例如，如果组织控制台网址为 https://console.example-org.com，则 ORG_SUFFIX 为 example-org.com

    输出类似于以下内容：

    STS-Bearer-QPN1nX6GVdoRKCpRx7FD-61gh6RAvWfM6sqjU2knw9n6RFn1jR2n4i1z1irH2HrMLf0tC3hqNaetYzoOBQ6hI2eS7-58_ZZGCMc_oARuX_T9Wmtwe4xlaIS97aDdu9KETEs0akoVYEsmFsWCu2Cu5pdiwjzSuWnRCMZwq9g8BmnPSck1Auf7rOfM7o2FoGE_lbLFZK4C8TCPdloDZAXYcLeNAQ

  2. 向特定虚拟机实例添加元数据：

    curl -X POST "https://metadata.ORG_SUFFIX/virtual-machines/metadata/v1/projects/PROJECT_NAME/vm/VM_NAME" \
  -H "Authorization: Bearer STS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"items": [{"key": "test-key", "value": "test-value"}]}}'

    替换以下内容：

    • ORG_SUFFIX：组织后缀。例如，如果组织控制台网址为 https://console.example-org.com，则 ORG_SUFFIX 为 example-org.com。
    • VM_NAME：虚拟机实例的名称。
    • PROJECT_NAME：虚拟机所在项目的名称。此值为可选值。
    • STS_TOKEN：从 gdcloud CLI 生成的 STS 令牌。

    以下示例展示了用于向虚拟机实例添加元数据的完整 curl 命令：

    curl -X POST "https://metadata.org-1.zone1.google.gdch.test/virtual-machines/metadata/v1/projects/username-test/vm/lancer-vm" \
  -H "Authorization: Bearer $STS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"items": [{"key": "test-key1", "value": "test-value"}]}}'

移除元数据

gdcloud

  • 从特定虚拟机实例中移除元数据。如果要移除所有元数据条目，请使用 --all 标志。您必须在命令中使用 --all 或 --keys 标志：

    gdcloud compute instances remove-metadata VM_NAME
    [--project=PROJECT_NAME]
    [--keys=KEY,[KEY,...]]
    [--all]

    替换以下内容：

    • VM_NAME：虚拟机实例的名称。
    • PROJECT_NAME：虚拟机所在项目的名称。此值为可选值。
    • KEY：元数据对的键字符串。

API

如需使用 API 移除元数据，您必须使用 STS 令牌。

  1. 使用 gdcloud CLI 生成 STS 令牌：

    gdcloud auth print-identity-token --audiences="https://metadata.ORG_SUFFIX"

    将 ORG_SUFFIX 替换为组织后缀。 例如，如果组织控制台网址为 https://console.example-org.com，则 ORG_SUFFIX 为 example-org.com。

    输出类似于以下内容：

    STS-Bearer-QPN1nX6GVdoRKCpRx7FD-61gh6RAvWfM6sqjU2knw9n6RFn1jR2n4i1z1irH2HrMLf0tC3hqNaetYzoOBQ6hI2eS7-58_ZZGCMc_oARuX_T9Wmtwe4xlaIS97aDdu9KETEs0akoVYEsmFsWCu2Cu5pdiwjzSuWnRCMZwq9g8BmnPSck1Auf7rOfM7o2FoGE_lbLFZK4C8TCPdloDZAXYcLeNAQ

  2. 从特定虚拟机实例中移除元数据：

    curl -X POST "https://metadata.ORG_SUFFIX/virtual-machines/metadata/v1/projects/PROJECT_NAME/vm/VM_NAME" \
  -H "Authorization: Bearer STS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {}}'

    替换以下内容：

    • ORG_SUFFIX：组织后缀。例如，如果组织控制台网址为 https://console.example-org.com，则 ORG_SUFFIX 为 example-org.com。
    • VM_NAME：虚拟机实例的名称。
    • PROJECT_NAME：虚拟机所在项目的名称。
    • STS_TOKEN：从 gdcloud CLI 生成的 STS 令牌。

查询元数据

gdcloud

  • 列出所有虚拟机实例元数据以查看元数据详情：

    gdcloud compute instances describe VM_NAME
    [--project=PROJECT_NAME]

    替换以下内容：

    • VM_NAME：虚拟机实例的名称。
    • PROJECT_NAME：虚拟机所在项目的名称。此值为可选值。

    输出类似于以下内容：

    # …
metadata:
  items:
  - key: Key-1
    value: val12
  - key: key2
    value:
      lksdjfhk-user1

API

  1. 使用 gdcloud CLI 生成 STS 令牌：

    gdcloud auth print-identity-token --audiences="https://metadata.ORG_SUFFIX"

    将 ORG_SUFFIX 替换为组织后缀。

    输出类似于以下内容：

    STS-Bearer-QPN1nX6GVdoRKCpRx7FD-61gh6RAvWfM6sqjU2knw9n6RFn1jR2n4i1z1irH2HrMLf0tC3hqNaetYzoOBQ6hI2eS7-58_ZZGCMc_oARuX_T9Wmtwe4xlaIS97aDdu9KETEs0akoVYEsmFsWCu2Cu5pdiwjzSuWnRCMZwq9g8BmnPSck1Auf7rOfM7o2FoGE_lbLFZK4C8TCPdloDZAXYcLeNAQ

  2. 列出所有虚拟机实例元数据以查看元数据详情：

    curl "https://metadata.ORG_SUFFIX/virtual-machines/metadata/v1/projects/PROJECT_NAME/vm/VM_NAME" \
  -H "Authorization: Bearer STS_TOKEN" \
  -H "Content-Type: application/json"

    替换以下内容：

    • ORG_SUFFIX：组织后缀。例如，如果组织控制台网址为 https://console.example-org.com，则 ORG_SUFFIX 为 example-org.com
    • VM_NAME：虚拟机实例的名称。
    • PROJECT_NAME：虚拟机所在项目的名称。此值为可选值。
    • STS_TOKEN：从 gdcloud CLI 生成的 STS 令牌。

    输出类似于以下内容：

    # …
metadata:
  items:
  - key: Key-1
    value: val12
  - key: key2
    value:
      lksdjfhk-user1

从虚拟机内查询元数据

您可以在虚拟机内查询虚拟机元数据，而无需连接到元数据服务器。为此，请使用 curl 命令，并将适用的元数据键附加到元数据网址。

查询单个 KVP

从虚拟机内查询单个 KVP：

curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/KEY" \
  -H "Metadata-Flavor: Google"

将 KEY 替换为您要查询的元数据对的键。

查询所有具有值的键值对

从虚拟机内查询所有 KVP：

curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=true" \
  -H "Metadata-Flavor: Google"

查询所有没有值的元数据键

从虚拟机内查询所有不含值的元数据键：

curl "http://metadata.google.internal/computeMetadata/v1/instance/attributes/?recursive=false" \
  -H "Metadata-Flavor: Google"