IBM Cloud Docs
使用实例元数据服务

使用实例元数据服务

获取实例身份访问令牌后,可以访问元数据服务并检索有关虚拟服务器实例的元数据。 实例元数据包括初始化数据、网络接口、卷附件、公共 SSH 密钥和放置组等信息。

向实例元数据服务发出 API 请求时,会触发可用于审计的事件。 更多信息,请参阅 实例元数据服务事件

准备工作

元数据服务默认为禁用。 要启用它,请按照 启用元数据服务 主题中的步骤操作。

Windows 用户具有访问和使用元数据服务的额外需求。 有关更多信息,请参阅 设置 Windows 服务器以使用元数据服务

访问元数据服务以创建实例身份访问令牌

要访问实例元数据服务,必须首先获取实例身份访问令牌。 从虚拟服务器 向元数据服务 API 发出 PUT /instance_identity/v1/token 请求。

实例与元数据服务之间的通信永远不会离开主机。 您可以从实例中获取令牌。 如果在实例上启用了对实例元数据服务的安全访问,请使用 "https "协议而不是 "http "协议。

在请求中,可以指定令牌的过期时间。 默认过期时间为 5 分钟,但也可以指定 5 秒至 1 小时之间的任意值。

curl -X PUT "http://api.metadata.cloud.ibm.com/instance_identity/v1/token?version=2025-04-22" -H "Metadata-Flavor: ibm" -d '{"expires_in": 3600}'

API 响应包含实例身份访问令牌。 它显示实例身份访问令牌字符串、创建日期和时间、过期日期和时间以及你设置的过期时间。 您可以使用此令牌访问元数据服务,并生成 IAM 令牌,供您的应用程序用来访问启用了 IAM 的服务。 有关更多信息,请参阅 根据实例身份访问令牌生成 IAM 令牌

{
  "access_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlZTSS1DUl91cy1lYXN0X2I5...",
  "created_at": "2025-04-22T11:08:39.363Z",
  "expires_at": "2025-04-22T11:13:39.363Z",
  "expires_in": 3600
}

您可以创建一个环境变量,用于下一次创建 IAM 令牌的请求。 请参阅以下示例。

instance_identity_token=`curl -X PUT "http://api.metadata.cloud.ibm.com/instance_identity/v1/token?version=2024-11-12" -H "Metadata-Flavor: ibm" -d '{"expires_in": 3600}' | jq -r '(.instance_identity_token)'`

此示例使用 jq 作为解析器,这是根据 MIT 许可证 许可的第三方工具。jq 可能不会在创建实例时在所有可用的 VPC 映像上预安装。 在使用前,您可能需要安装 jq 或使用您选择的其他解析器。

从实例身份访问令牌生成 IAM 令牌

要访问帐户中支持 IBM Cloud IAM 的服务,您可以使用可信概要文件信息从实例身份访问令牌生成 IAM 令牌。 您可以使用计算资源身份的可信配置文件为虚拟服务器实例分配 IBM Cloud® IAM 身份。

生成 IAM 令牌后,就可以使用它访问启用了 IAM 的服务,而无需管理和向实例分发 IAM 秘密。 您可以多次复用该令牌。 可以在创建实例时链接可信概要文件,也可以在请求主体中提供可信概要文件。

提出 POST /instance_identity/v1/iam_token 请求,并指定受信任配置文件的 ID。 请参见以下请求示例:

iam_token=`curl -X POST "$vpc_metadata_api_endpoint/instance_identity/v1/iam_token?version=2025-04-22" -H "Authorization: Bearer $instance_identity_token" -d '{
      "trusted_profile": {
        "id": "Profile-8dd84246-7df4-4667-94e4-8cede51d5ac5"
      }
    }' | jq -r '(.iam_token)'`

API 响应会显示 IAM 令牌。

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0aGVfYmVzdCI6I8...",
  "created_at": "2025-04-22T14:10:15Z",
  "expires_at": "2025-04-22T15:10:15Z",
  "expires_in": 3600
}

有关详细信息,请参阅 使用受信任配置文件请求启用 IAM 的服务

从运行中的虚拟服务器实例检索实例元数据

使用实例元数据服务可获取有关实例,初始化信息,SSH 密钥和放置组的元数据。

检索实例信息

提出 GET "/metadata/v1/instance" 请求,以获取有关实例的详细信息。

curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance?version=2025-04-22" -H "Authorization: Bearer $instance_identity_token"

响应列出实例的所有详细信息,包括网络接口,计算概要文件和卷连接。

{
  "boot_volume_attachment": {
    "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
    "name": "my-boot-volume-attachment",
    "volume": {
      "crn": "crn:[...]",
      "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
      "name": "my-boot-volume"
    }
  },
  "created_at": "2021-10-19T16:11:57Z",
  "crn": "crn:[...]",
  "disks": [],
  "id": "eb1b7391-2ca2-4ab5-84a8-b92157a633b0",
  "image": {
    "crn": "crn:[...]",
    "id": "9aaf3bcb-dcd7-4de7-bb60-24e39ff9d366",
    "name": "my-image"
  },
  "memory": 8,
  "name": "my-instance",
  "network_interfaces": [
    {
      "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
      "name": "my-network-interface",
      "primary_ipv4_address": "10.0.0.32",
      "resource_type": "network_interface",
      "subnet": {
        "crn": "crn:[...]",
        "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
        "name": "my-subnet",
        "resource_type": "subnet"
      }
    }
  ],
  "primary_network_interface": {
    "id": "7ca88dfb-8962-469d-b1de-1dd56f4c3275",
    "name": "my-network-interface",
    "primary_ipv4_address": "10.0.0.32",
    "resource_type": "network_interface",
    "subnet": {
      "crn": "crn:[...]",
      "id": "bea6a632-5e13-42a4-b4b8-31dc877abfe4",
      "name": "my-subnet",
      "resource_type": "subnet"
    }
  },
  "profile": {
    "name": "bx2-2x8"
  },
  "resource_type": "instance",
  "vcpu": {
    "architecture": "amd64",
    "count": 2
  },
  "volume_attachments": [
    {
      "id": "a8a15363-a6f7-4f01-af60-715e85b28141",
      "name": "my-boot-volume-attachment",
      "volume": {
        "crn": "crn:[...]",
        "id": "49c5d61b-41e7-4c01-9b7a-1a97366c6916",
        "name": "my-boot-volume"
      }
    },
    {
      "id": "e77125cb-4df0-4988-a878-531ae0ae0b70",
      "name": "my-volume-attachment-1",
      "volume": {
        "crn": "crn:[...]",
        "id": "2cc091f5-4d46-48f3-99b7-3527ae3f4392",
        "name": "my-data-volume"
      }
    }
  ],
  "vpc": {
    "crn": "crn:[...]",
    "id": "f0aae929-7047-46d1-92e1-9102b07a7f6f",
    "name": "my-vpc",
    "resource_type": "vpc"
  },
  "zone": {
    "name": "us-south-1"
  }
}

检索实例初始化信息

您可以通过 GET /metadata/v1/instance/initialization 请求,以编程方式检索实例的初始化信息。 请参阅以下示例。

curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/instance/initialization?version=2025-04-22" -H "Authorization: Bearer $instance_identity_token" | jq -r '(.user_data)'

在示例中,命令的返回值是用户数据,由 jq 提取并放入 user_data 环境变量中。

响应会列出实例初始化时使用的 SSH 公钥,并提取实例供应时可用的任何其他用户数据。 响应包含用于标识 SSH 密钥的 SHA256 值。

{
  "keys": [
    {
      "crn": "crn:[...]",
      "fingerprint": "SHA256:RJ+YWs3rupwGFiJuLqY43tvmdeLOUjcIc9cA6IR8n8E",
      "id": "dadae729-1d81-4a13-966e-f5d92699f103",
      "name": "my-key-1",
      "resource_type": "key"
    }
  ],
  "user_data": "Content-Type: multipart/form-data; boundary=3efa30189c9e0e8ebc24a4decbbf4c2be7b26120c1cdd7cb7bc2ecb0c07c\nMIME-Version: 1.0\n\n--3efa30189c9e0e8ebc24a4decbbf4c2be7b26120c1cdd7cb7bc2ecb0c07c\nContent-Type: text/cloud-config\n\n#cloud-config\ndisable_root: false\nchpasswd:\n  list: |\n    root:genes1s\n  expire: false\nusers:\n- default\n- name: root\n  lock-passwd: false\n  ssh_pwauth: true\n\n--3efa30189c9e0e8ebc24a4decbbf4c2be7b26120c1cdd7cb7bc2ecb0c07c--"
}

更多信息,请参阅 API 参考:检索初始化信息

其他实例元数据方法

下表列出了 API GET 请求的更多方法,您可以使用这些方法获取有关实例的特定信息。

实例元数据端点
API 端点 描述
/metadata/v1/instance/cluster_network_attachments 集群网络附件列表
/metadata/v1/instance/cluster_network_attachments/{id} 读取群集网络附件
/metadata/v1/instance/network_attachments 列出网络附件
/metadata/v1/instance/network_attachments/{id} 检索网络附件
/metadata/v1/instance/network_interfaces 列出实例的所有网络接口的元数据。
/metadata/v1/instance/network_interfaces/{id} 按标识检索网络接口的元数据。
/metadata/v1/instance/volume_attachments 列出实例的所有卷连接的元数据。
/metadata/v1/instance/volume_attachment/{id} 按标识检索卷连接的元数据。

有关所需参数和示例的更多信息,请参阅 元数据服务 API 参考指南

检索 SSH 密钥的元数据

发送 GET /metadata/v1/keys 请求,以获取为实例配置的所有 SSH 密钥的信息。

curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/keys?version=2025-04-22" -H "Authorization: Bearer $instance_identity_token"

示例输出显示了一个 SSH 密钥。

{
  "keys": [
    {
      "created_at": "2024-10-19T16:39:23.000Z",
      "crn": "crn:bluemix:public:is:us-south:a/a1234567::key:r006-44e5e06b-9450-4f5f-a9be-96feebf770d8",
      "fingerprint": "SHA256:lZmocJFsWfJcIl8Jdp8r6Ak8gzMqxrFb9UtwWCk27CM",
      "id": "r006-44e5e06b-9450-4f5f-a9be-96feebf770d8",
      "length": 4096,
      "name": "my-key-1",
      "public_key": "ssh-rsa AAAAB...n",
      "resource_type": "key",
      "type": "rsa"
    }
  ]
}

如果有多个 SSH 密钥,可以使用其中一个 SSH 密钥的 ID 发出 GET /metadata/v1/keys/{id} 请求。 响应会提供有关指定 SSH 密钥的信息。

检索安置组的元数据

发送 GET /metadata/v1/placement_groups 请求,检索为实例配置的安置组信息。 在示例中,命令的返回值是放置组的列表,从第一个开始,直到 50 个。

curl -X GET "$vpc_metadata_api_endpoint/metadata/v1/placement_groups?version=2025-04-22" -H "Authorization: Bearer $instance_identity_token" -d '{"start": "first","limit": 50}'

示例输出只显示了一个安置组。

{
  "first": {
    "href": "http://169.254.169.254/v1/placement_groups?limit=50"
  },
  "limit": 50,
  "placement_groups": [
    {
      "created_at": "2022-10-12T19:55:00Z",
      "crn": "crn:[...]",
      "id": "r018-418fe842-a3e9-47b9-a938-1aa5bd632871",
      "lifecycle_state": "stable",
      "name": "my-placement-group",
      "resource_type": "placement_group",
      "strategy": "host_spread"
    }
  ],
  "total_count": 1
}

您还可以申请实例使用的特定放置组的详细信息。 要检索特定安置组的信息,请发送 GET "/metadata/v1/placement_groups/{id}" 请求,并用安置组的实际 ID 替换 {id}

后续步骤