設定和查詢訪客屬性

訪客屬性是一種特定類型的自訂中繼資料，可供應用程式在虛擬機器 (VM) 執行個體上執行時寫入。VM 執行個體上的任何應用程式或使用者都可以讀取這些訪客屬性中繼資料值，以及將資料寫入其中。

事前準備

  • 如為 Windows Server VM，請使用 PowerShell 3.0 以上版本。建議使用 ctrl+v 貼上複製的程式碼區塊。
  • 如果尚未設定驗證，請先完成設定。 驗證可確認您的身分，以便存取 Google Cloud 服務和 API。如要從本機開發環境執行程式碼或範例，請選取下列其中一個選項，向 Compute Engine 進行驗證：

    選取這個頁面上的分頁，瞭解如何使用範例：

    控制台

    使用 Google Cloud 控制台存取 Google Cloud 服務和 API 時，無須設定驗證。

    gcloud

    1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

      gcloud init

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

  • 設定預設地區和區域。

    • REST

    如要在本機開發環境中使用本頁的 REST API 範例，請使用您提供給 gcloud CLI 的憑證。

      安裝 Google Cloud CLI。

      若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

    詳情請參閱 Google Cloud 驗證說明文件中的「使用 REST 進行驗證」。

必要的角色

所需權限或角色取決於您是在 VM 內部還是外部完成工作。

在 VM 內

如果您要從 VM 內部設定、查詢或刪除訪客屬性，只需要連線至 VM 的角色和權限。在 VM 執行個體中執行的任何程序都可以寫入訪客屬性值，包括沒有 sudo 或管理員層級權限的指令碼和應用程式。

對於 VM 內部的讀取和寫入作業，中繼資料伺服器會提供自動化的執行個體層級驗證和授權。每個 VM 都只能讀取或寫入自己的中繼資料伺服器。其他 VM 無法存取另一個 VM 的中繼資料伺服器。

VM 外部

如要啟用訪客屬性，或使用 Google Cloud CLI 或 REST 從 VM 外部查看訪客屬性，您需要下列角色和權限。您無法從 VM 外部設定或刪除訪客屬性。

為確保使用者或服務帳戶具備啟用或查看訪客屬性的必要權限，請要求管理員在 VM 或專案中，將Compute 執行個體管理員 (v1) (roles/compute.instanceAdmin.v1) IAM 角色授予使用者或服務帳戶。如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這個預先定義的角色具備啟用或查看訪客屬性所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要啟用或查看訪客屬性，必須具備下列權限：

  • 如要啟用訪客屬性： compute.instances.setMetadata 在 VM 或專案上
  • 如要查看訪客屬性： compute.instances.getGuestAttributes 在 VM 或專案上

管理員或許還可透過自訂角色或其他預先定義的角色，將這些權限授予使用者或服務帳戶。

使用訪客屬性的時機

僅將訪客屬性用於不會經常變更的少量必要資料。訪客屬性的最佳用途具有以下特性：

  • 每個屬性值的大小上限為 256 KiB。
  • 每個屬性鍵的大小上限為 128 個位元組。
  • 每個 VM 執行個體的查詢數限制為每分鐘最多 10 次查詢。
  • 查詢作業每秒不超過 3 次查詢。如果超過這個次數上限，Compute Engine 可能會任意移除正在寫入的訪客屬性。您必須移除這項資料，才能確保將其他重要系統資料寫入伺服器。

訪客屬性適用於必須發布不頻繁和少量資料的情況。例如，訪客屬性適用於以下用途：

  • 開機指令碼可以透過在訪客屬性中設定自訂狀態值來表示初始化成功。
  • 設定管理代理程式可以將客體 OS 名稱和版本發布至訪客屬性。
  • 庫存管理代理程式可以將安裝在 VM 執行個體中的套件之清單發布至訪客屬性。
  • 工作負載自動化調度管理軟體可以透過在訪客屬性中設定自訂狀態值，將客體中作業完成信號通知軟體控制層。

訪客屬性不能取代事件串流、Pub/Sub 或其他形式的資料儲存空間和設定存放區。

訪客屬性和其他 Google Cloud 服務

其他 Google Cloud 服務會以以下方式使用訪客屬性：

  • 安全殼層 (SSH) 安全性：如果啟用訪客屬性並停用 OS 登入，訪客環境和 gcloud CLI 會使用訪客屬性，透過 Google API 擷取主機金鑰，藉此提升安全殼層 (SSH) 安全性，您才能使用安全殼層 (SSH) 連線至 VM。
  • VM 管理員：OS 設定代理程式會將作業系統資料發布至訪客屬性。

如要查看這些服務儲存的中繼資料項目，請參閱「預先定義的訪客屬性中繼資料鍵」。

在 VM 上啟用訪客屬性

根據預設，訪客屬性會處於停用狀態。如要啟用訪客屬性，請在個別 VM 或全專案中繼資料中設定必要的中繼資料值：

控制台

建立 VM 時，請在執行個體中繼資料內設定 enable-guest-attributes：

  1. 前往 Google Cloud 控制台的「Create an instance」(建立執行個體) 頁面。

    前往「建立執行個體」

  2. 指定 VM 詳細資料。

  3. 展開「Advanced options」(進階選項) 區段，然後執行下列操作：

    1. 展開「管理」部分。

    2. 在「Metadata」(中繼資料) 專區中，按一下「Add item」(新增項目)，然後新增下列中繼資料項目：

      • 金鑰：enable-guest-attributes
      • 價值：TRUE

  4. 按一下「Create」(建立)，即可建立 VM。

在全專案範圍的中繼資料內設定 enable-guest-attributes，以將其套用至您專案中的所有 VM：

  1. 前往 Google Cloud 控制台的「Metadata」頁面。

    前往「Metadata」(中繼資料) 頁面

  2. 按一下 [編輯]。

  3. 新增鍵為 enable-guest-attributes、值為 TRUE 的中繼資料項目。此外，將值設為 FALSE 即可停用這項功能。

  4. 點選「儲存」來套用變更。

在現有 VM 的中繼資料內設定 enable-guest-attributes：

  1. 前往 Google Cloud 控制台的「VM instances」(VM 執行個體) 頁面。

    前往「VM instances」(VM 執行個體) 頁面

  2. 按一下要設定中繼資料值的 VM 名稱。
  3. 在執行個體詳細資料頁面頂端，按一下 [Edit] (編輯) 即可編輯執行個體設定。
  4. 在「Custom metadata」(自訂中繼資料) 下，新增索引鍵為 enable-guest-attributes、值為 TRUE 的中繼資料項目。或者，將值設為 FALSE，即可將 VM 排除在這項功能的涵蓋範圍外。
  5. 在執行個體詳細資料頁面的最下方，按一下「儲存」，將變更套用至 VM。

gcloud

建立 VM 時，請在執行個體中繼資料內設定 enable-guest-attributes：

使用 Google Cloud CLI 的 gcloud compute instances create 指令並設定 enable-guest-attributes=TRUE，即可啟用訪客屬性。將 VM_NAME 換成您的 VM 名稱。

gcloud compute instances create VM_NAME \
    --metadata=enable-guest-attributes=TRUE

在全專案範圍的中繼資料內設定 enable-guest-attributes，以將其套用至您專案中的所有 VM：

使用 Google Cloud CLI 的 project-info add-metadata 指令並設定 enable-guest-attributes=TRUE，以啟用訪客屬性：

gcloud compute project-info add-metadata \
    --metadata=enable-guest-attributes=TRUE

您也可以將 enable-guest-attributes 設為 FALSE，以停用訪客屬性。

在現有 VM 的中繼資料內設定 enable-guest-attributes：

使用 Google Cloud CLI 的 instances add-metadata 指令並設定 enable-guest-attributes=TRUE，即可啟用訪客屬性。將 VM_NAME 換成您的 VM 名稱。

gcloud compute instances add-metadata VM_NAME \
    --metadata=enable-guest-attributes=TRUE

此外，您可以將 enable-guest-attributes 設為 FALSE，讓 VM 停用訪客屬性。

設定訪客屬性

在 VM 執行個體中執行的任何程序都可以寫入訪客屬性值，包括沒有 sudo 或管理員層級權限的指令碼和應用程式。虛擬機外部的使用者或服務帳戶無法寫入訪客屬性中繼資料值。

Linux VM

例如，您可以在 VM 中使用 curl 要求將值寫入 guest-attributes 中繼資料路徑：

curl -X PUT --data "VALUE" http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

更改下列內容：

  • NAMESPACE：KEY 的邏輯分組。訪客屬性必須具有命名空間。
  • VALUE：要寫入的值。
  • KEY：guest-attributes 中儲存值的路徑。

「NAMESPACE」和「KEY」欄位只能使用英文字母、數字、底線 (_) 和連字號 (-)。

Windows VM

例如，您可以在 VM 中使用 Invoke-RestMethod 要求，將值寫入 guest-attributes 中繼資料路徑：

PS C:\> 
$value = (Invoke-RestMethod `
         -Method PUT -Body "VALUE" `
         -Headers @{'Metadata-Flavor' = 'Google'} `
         -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

更改下列內容：

  • NAMESPACE：KEY 的邏輯分組。訪客屬性必須具有命名空間。
  • VALUE：要寫入的值。
  • KEY：guest-attributes 中儲存值的路徑。

「NAMESPACE」和「KEY」欄位只能使用英文字母、數字、底線 (_) 和連字號 (-)。

取得訪客屬性

如果使用者或服務帳戶具有必要角色，就能從 VM 外部讀取訪客屬性。或者，VM 中的任何使用者或應用程式都可以讀取該特定 VM 的中繼資料值。

在虛擬機器中執行的任何程序都可以寫入訪客屬性值，包括沒有 sudo 或管理員層級權限的指令碼和應用程式。

查詢中繼資料伺服器

請按照下列操作說明，從 VM 內查詢訪客屬性。

  1. 連線至 VM。

  2. 查詢訪客屬性。

    Linux VM

    例如，您可以在 VM 中使用 curl 要求，從 guest-attributes 中繼資料路徑讀取值：

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

    更改下列內容：

    • NAMESPACE：要查詢的鍵的命名空間。guest-attributes
    • KEY：您要從中讀取中繼資料值的 guest-attributes 內的路徑。

    或者，您也可以在一個要求中傳回所有訪客屬性值。將 NAMESPACE 替換為要查詢的 guest-attributes 金鑰命名空間。

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

    Windows VM

    例如，您可以在 VM 中使用 Invoke-RestMethod 要求，從 guest-attributes 中繼資料路徑讀取值：

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

    更改下列內容：

    • NAMESPACE：要查詢的鍵的命名空間。guest-attributes
    • KEY：您要從中讀取中繼資料值的 guest-attributes 內的路徑。

    或者，您也可以在一個要求中傳回所有訪客屬性值。將 NAMESPACE 替換為要查詢的 guest-attributes 金鑰命名空間。

    PS C:\> 
$value = (Invoke-RestMethod `
        -Headers @{'Metadata-Flavor' = 'Google'} `
        -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/")
$value

使用 Google Cloud CLI 或 REST

請按照下列操作說明，從 VM 外部查看訪客屬性。

gcloud

使用 Google Cloud CLI 讀取 VM 的訪客屬性中繼資料值。例如，您可以擷取 VM 的所有值，如下所示：

gcloud compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

如要擷取特定命名空間下的所有值，請包括 --query-path 標記和您定義的命名空間：

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE \
    --zone=ZONE

如要擷取特定命名空間下的所有值，請包括 --query-path 標記、命名空間和您定義的值的鍵：

gcloud compute instances get-guest-attributes VM_NAME \
    --query-path=NAMESPACE/KEY \
    --zone=ZONE

更改下列內容：

  • VM_NAME：要從中讀取訪客屬性中繼資料值的 VM 名稱
  • NAMESPACE：要查詢的鍵的命名空間guest-attributes
  • KEY：儲存值的 guest-attributes 中繼資料內的路徑
  • ZONE：VM 所在的可用區

REST

請使用 compute.instances.getguestattributes 方法：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

更改下列內容：

  • PROJECT_ID：專案 ID
  • ZONE：VM 所在的可用區
  • VM_NAME：要從中讀取訪客屬性中繼資料值的 VM 名稱
  • NAMESPACE：要查詢的鍵的命名空間guest-attributes
  • KEY：儲存值的 guest-attributes 中繼資料內的路徑

如要擷取 NAMESPACE 的所有鍵，請省略 KEY：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE

如要擷取 VM 中每個命名空間的所有鍵，請省略 NAMESPACE：

GET https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=

如果您有 OAuth 憑證，也可以使用 curl：

curl -H "Authorization: Bearer OAUTH_TOKEN" https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances/VM_NAME/getGuestAttributes?queryPath=NAMESPACE/KEY

更改下列內容：

  • OAUTH_TOKEN：您的 OAuth 權杖
  • PROJECT_ID：專案 ID
  • ZONE：VM 所在的可用區
  • VM_NAME：要從中讀取訪客屬性中繼資料值的 VM 名稱
  • NAMESPACE：要查詢的鍵的命名空間guest-attributes
  • KEY：儲存值的 guest-attributes 中繼資料內的路徑

刪除訪客屬性

請按照下列說明，從 VM 內移除訪客屬性。

  1. 連線至 VM。

  2. 刪除訪客屬性。

    Linux VM

    您也可以刪除訪客屬性。例如，使用 curl 刪除特定鍵：

    curl -X DELETE http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY -H "Metadata-Flavor: Google"

    更改下列內容：

    • NAMESPACE：要刪除的 guest-attributes 鍵的命名空間
    • KEY：儲存值的 guest-attributes 中的路徑

    Windows VM

    您也可以刪除訪客屬性。例如，使用 Invoke-RestMethod 刪除特定鍵：

    PS C:\> 
$value = (Invoke-RestMethod `
          -Method DELETE `
          -Headers @{'Metadata-Flavor' = 'Google'} `
          -Uri "http://metadata.google.internal/computeMetadata/v1/instance/guest-attributes/NAMESPACE/KEY")
$value

    更改下列內容：

    • NAMESPACE：要刪除的 guest-attributes 鍵的命名空間
    • KEY：儲存值的 guest-attributes 中的路徑

停用機構或資料夾的訪客屬性

如果您不希望機構或資料夾中的任何 VM 啟用訪客屬性，則可以完全覆寫和停用該功能。

在機構或資料夾上設定 constraints/compute.disableGuestAttributesAccess 限制，並將 PROJECT_ID 替換為專案名稱：

gcloud resource-manager org-policies enable-enforce \
    constraints/compute.disableGuestAttributesAccess \
    --project=PROJECT_ID

請參閱使用限制一文，以進一步瞭解如何設定和管理對於機構的限制。

後續步驟