使用实例元数据服务
获取实例身份访问令牌后,可以访问元数据服务并检索有关虚拟服务器实例的元数据。 实例元数据包括初始化数据、网络接口、卷附件、公共 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}
。
后续步骤
- 从正在运行的实例访问元数据,并使用它来引导新实例。
- 创建并使用可信概要文件 以访问启用 IAM 的服务。