查看及維護 VM 中繼資料

本文說明如何在 Google Distributed Cloud (GDC) 實體隔離方案中，查看及維護虛擬機器 (VM) 執行個體中繼資料。

每個 VM 都會將中繼資料儲存於中繼資料伺服器，並以鍵/值組合 (KVP) 的形式呈現。中繼資料 KVP 包含描述性屬性、自訂設定值，以及有助於識別 VM 的資訊，例如伺服器名稱。無論 VM 正在執行或已停止，您都可以新增及移除中繼資料、從 VM 外部或內部查詢中繼資料，以及使用中繼資料在系統之間傳遞資訊。

本文件適用於平台管理員或應用程式操作員群組中的開發人員，他們會在 Distributed Cloud 環境中查看及維護執行個體的 VM 中繼資料。詳情請參閱「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 新增、移除及維護 VM 執行個體的中繼資料，請聯絡 IAM 專案管理員，要求授予下列專案角色：

  • 虛擬機器專案管理員 (project-vm-admin)：在專案命名空間中建立、列出、修改及刪除 VM。

  • 專案檢視者 (project-viewer)：查看專案命名空間中的所有資源。

所有 VM 角色都必須繫結至 VM 所在專案的命名空間。按照步驟驗證存取權。

新增或移除中繼資料

本節說明如何新增及移除現有 VM 執行個體的中繼資料。

您可以使用中繼資料，儲存要新增至 VM 的任意鍵/值組合。舉例來說，您可能想新增及管理自訂中繼資料，以識別不同的環境，例如 test 和 production。

新增中繼資料

gdcloud

  • 將中繼資料新增至特定 VM 執行個體。指令中必須包含 --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：VM 執行個體的名稱。
    • PROJECT_NAME：VM 所在專案的名稱。這個值為選用。
    • 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. 將中繼資料新增至特定 VM 執行個體：

    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：VM 執行個體的名稱。
    • PROJECT_NAME：VM 所在專案的名稱。這個值為選用。
    • STS_TOKEN：從 gdcloud CLI 產生的 STS 權杖。

    以下範例顯示完整的 curl 指令，可將中繼資料新增至 VM 執行個體：

    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

  • 移除特定 VM 執行個體的中繼資料。如要移除所有中繼資料項目，請使用 --all 旗標。您必須在指令中使用 --all 或 --keys 旗標：

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

    更改下列內容：

    • VM_NAME：VM 執行個體的名稱。
    • PROJECT_NAME：VM 所在專案的名稱。這個值為選用。
    • 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. 移除特定 VM 執行個體的中繼資料：

    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：VM 執行個體的名稱。
    • PROJECT_NAME：VM 所在專案的名稱。
    • STS_TOKEN：從 gdcloud CLI 產生的 STS 權杖。

查詢中繼資料

gdcloud

  • 列出所有 VM 執行個體中繼資料，查看中繼資料詳細資料：

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

    更改下列內容：

    • VM_NAME：VM 執行個體的名稱。
    • PROJECT_NAME：VM 所在專案的名稱。這個值為選用。

    輸出結果會與下列內容相似：

    # …
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. 列出所有 VM 執行個體中繼資料，查看中繼資料詳細資料：

    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：VM 執行個體的名稱。
    • PROJECT_NAME：VM 所在專案的名稱。這個值為選用。
    • STS_TOKEN：從 gdcloud CLI 產生的 STS 權杖。

    輸出結果會與下列內容相似：

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

從 VM 查詢中繼資料

您可以從 VM 內查詢 VM 中繼資料，不必連線至中繼資料伺服器。做法是使用 curl 指令，並將適用的中繼資料鍵附加至中繼資料網址。

查詢單一 KVP

在 VM 中查詢單一 KVP：

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

將 KEY 替換為要查詢的中繼資料組合鍵。

查詢所有含值的鍵/值組合

從 VM 內查詢所有 KVP：

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

查詢所有沒有值的中繼資料鍵

從 VM 內查詢所有沒有值的中繼資料鍵：

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