IBM Cloud Docs
使用實例 meta 資料服務

使用實例 meta 資料服務

取得實例身分存取記號之後,您可以存取 meta 資料服務,並擷取虛擬伺服器實例的相關 meta 資料。 實體元資料包括初始化資料、網路介面、磁碟區附件、公開 SSH 金鑰和放置群組等資訊。

當您向實體元資料服務提出 API 請求時,會觸發可用於稽核的事件。 如需詳細資訊,請參閱 Instance metadata service events

開始之前

依預設會停用 meta 資料服務。 若要啟用,請遵循 啟用元資料服務主題 中的步驟。

Windows 使用者有存取及使用 meta 資料服務的額外需求。 如需相關資訊,請參閱 設定 Windows 伺服器以使用 meta 資料服務

存取元資料服務以建立實體身分存取標記

若要存取實例 meta 資料服務,您必須先取得實例身分存取記號。 從虛擬伺服器向 Metadata 服務 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 的服務

從執行中的虛擬伺服器實體擷取實體元資料

使用實例 meta 資料服務來取得實例、起始設定資訊、SSH 金鑰及放置群組的相關 meta 資料。

擷取實例資訊

提出 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 列出實例的所有網路介面的 meta 資料。
/metadata/v1/instance/network_interfaces/{id} 依 ID 擷取網路介面的 meta 資料。
/metadata/v1/instance/volume_attachments 列出實例的所有磁區連接的 meta 資料。
/metadata/v1/instance/volume_attachment/{id} 依 ID 擷取磁區連接的 meta 資料。

有關所需參數和範例的詳細資訊,請參閱 Metadata 服務 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}

下一步