設定和查詢訪客屬性

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

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

事前準備

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

  Select the tab for how you plan to use the samples on this page:

  Console

  When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

  gcloud

  1. After installing the Google Cloud CLI, initialize it by running the following command:

     gcloud init

     If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. Set a default region and zone.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  After installing the Google Cloud CLI, initialize it by running the following command:

  gcloud init

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

必要的角色

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

在 VM 中

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

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

在 VM 外部

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

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

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

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

使用訪客屬性的時機

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

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

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

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

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

訪客屬性和其他 Google Cloud 服務

其他 Google Cloud 服務會使用訪客屬性，如下所示：

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

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

在 VM 上啟用訪客屬性

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

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

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

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

設定訪客屬性

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

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

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

取得訪客屬性

如果使用者或服務帳戶具備必要角色，就能從 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 compute instances get-guest-attributes VM_NAME \
    --zone=ZONE

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

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

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

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

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

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

刪除訪客屬性

請按照下列操作說明，從 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

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

後續步驟

• 進一步瞭解VM 中繼資料。