使用擴充功能政策管理 VM 擴充功能

預先發布版

這項功能 適用《服務專屬條款》。 正式發布前的功能是按照「原樣」提供，支援範圍可能有限。 詳情請參閱推出階段說明。

VM 擴充功能管理工具會使用擴充功能政策，大規模管理 VM 擴充功能。詳情請參閱「關於 VM 擴充功能管理工具」。 本文說明如何查看、更新及刪除 VM 擴充功能政策。

注意： 使用 Google Cloud 控制台時，只能管理區域擴充功能政策。

IAM 角色和權限

如要取得查看、修改及刪除 VM 擴充功能政策所需的權限，請要求管理員在專案中授予您下列 IAM 角色：

• 如要查看擴充功能政策，請按照下列步驟操作：
  • VM 擴充功能政策檢視者 (roles/compute.vmExtensionPolicyViewer)
  • VM 擴充功能政策管理員 (roles/compute.vmExtensionPolicyAdmin)
• 如要修改擴充功能政策：VM 擴充功能政策管理員 (roles/compute.vmExtensionPolicyAdmin)
• 如要刪除擴充功能政策： VM 擴充功能政策管理員 (roles/compute.vmExtensionPolicyAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備查看、修改及刪除 VM 擴充功能政策所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要查看、修改及刪除 VM 擴充功能政策，必須具備下列權限：

• 如要查看擴充功能政策，請按照下列方式操作： compute.vmExtensionPolicies.list
• 如要查看擴充功能政策的詳細資料： compute.vmExtensionPolicies.get
• 如要修改擴充功能政策： compute.vmExtensionPolicies.update
• 如要刪除擴充功能政策： compute.vmExtensionPolicies.delete

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

如要進一步瞭解 Compute Engine 中的 IAM 角色和權限，請參閱「Compute Engine 角色和權限」。

查看擴充功能政策

您可以使用 Google Cloud 控制台或 Google Cloud CLI，查看專案中的 VM 擴充功能政策清單，或查看特定政策的詳細資料。

控制台

1. 前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

   前往 VM 擴充功能政策

   這個頁面會列出專案中的所有 VM 擴充功能政策。
2. 如要查看特定擴充功能政策的詳細資料，請按一下政策名稱。

gcloud

全球

如要查看專案中的所有全域擴充功能政策，請使用 gcloud beta compute global-vm-extension-policies list 指令：

gcloud beta compute global-vm-extension-policies list \
  --project=PROJECT_ID \
  --page-size=PAGE_SIZE

更改下列內容：

• PROJECT_ID： Google Cloud 專案的 ID。
• PAGE_SIZE：每頁要傳回的結果數量上限。

如要查看特定全域擴充功能政策的詳細資料，請使用 gcloud beta compute global-vm-extension-policies describe 指令：

gcloud beta compute global-vm-extension-policies describe POLICY_NAME \
  --project=PROJECT_ID

更改下列內容：

• POLICY_NAME：要說明的 VM 擴充功能政策名稱。
• PROJECT_ID：您的 Google Cloud 專案 ID。

區域

如要查看專案中的所有擴充功能政策，請使用 gcloud beta compute zone-vm-extension-policies list 指令：

gcloud beta compute zone-vm-extension-policies list \
  --project=PROJECT_ID \
  --zone=ZONE \
  --page-size=PAGE_SIZE

更改下列內容：

• PROJECT_ID： Google Cloud 專案的 ID。
• ZONE：要列出 VM 擴充功能政策的可用區名稱。
• PAGE_SIZE：每頁要傳回的結果數量上限。

如要查看特定擴充功能政策的詳細資料，請使用 gcloud beta compute zone-vm-extension-policies describe 指令：

gcloud beta compute zone-vm-extension-policies describe POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

更改下列內容：

• POLICY_NAME：要說明的 VM 擴充功能政策名稱。
• PROJECT_ID：您的 Google Cloud 專案 ID。
• ZONE：VM 擴充功能政策所在的 Google Cloud 區域。

更新 VM 擴充功能政策，即可修改擴充功能

更新政策後，VM 擴充功能管理工具通常會在 1 分鐘內，將變更套用至所有適用的 VM。如果您修改納入標籤，系統可能會根據新 VM 是否符合更新後的標籤，在新 VM 上安裝擴充功能，或從現有 VM 解除安裝擴充功能。

控制台

1. 前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

   前往 VM 擴充功能政策

2. 選取要更新的政策。
3. 按一下 [編輯]。
4. 修改「說明」、「優先順序」、「擴充功能」或「目標 VM 執行個體」。
5. 按一下 [儲存]。

gcloud

全球

使用 gcloud beta compute global-vm-extension-policies update 指令修改現有的全域 VM 擴充功能政策。使用 gcloud 更新政策時，要求會完全取代現有政策。您略過的任何選填欄位都會還原為預設值，而不是保留修改後政策的現有值。

如要更新全域 VM 擴充功能政策，請執行下列指令：

  gcloud beta compute global-vm-extension-policies update POLICY_NAME \
      --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
      --description="DESCRIPTION" \
      --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
      --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
      --inclusion-labels=KEY_1=VALUE_1 \
      --priority=PRIORITY_NUMBER \
      --rollout-predefined-plan=ROLLOUT_PLAN \
      --rollout-retry-uuid=RETRY_UUID \
      --rollout-conflict-behavior=ROLLOUT_CONFLICT_BEHAVIOR

更改下列內容：

• POLICY_NAME：要更新的 VM 擴充功能政策名稱。
• EXTENSION_NAME_1、EXTENSION_NAME_2：要更新的擴充功能名稱。您必須至少指定一個擴充功能。
• DESCRIPTION：VM 擴充功能政策的說明。
• VERSION_1：第一個 VM 擴充功能的版本。
• VERSION_2：第二個 VM 擴充功能的版本。

• EXTENSION_NAME_1=CONFIG_FILE_PATH_1、EXTENSION_NAME_2=CONFIG_FILE_PATH_2：以半形逗號分隔的鍵/值配對清單，其中鍵是擴充功能名稱，值是該擴充功能的設定檔路徑。這個路徑位於執行 gcloud 指令的 VM 上，而非安裝擴充功能的 VM。

  或者，如要以內嵌字串形式提供設定，請使用 --config 旗標，而非 --config-from-file，例如 EXTENSION_NAME_1="CONFIG_1"。您可以使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。

• KEY_1=VALUE_1：以半形逗號分隔的鍵/值組合清單，用於定義選擇器的納入標籤。VM 必須具備選取器中的所有指定標籤，才能成為目標。如果您多次指定 --inclusion-labels，政策會以符合任何所提供選取器 (邏輯 OR) 的 VM 為目標。如果省略這個標記，政策會以專案中所有可用區的所有 VM 為目標。

• PRIORITY_NUMBER：VM 擴充功能政策的優先順序編號。

• ROLLOUT_PLAN：指定 slow_rollout 或 fast_rollout。 如要使用自訂推出計畫，請使用 --rollout-custom-plan 標記 (而非 --rollout-predefined-plan)，並指定計畫名稱，例如：

  --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME
  

  更改下列內容：

  • PROJECT_NUMBER：定義推出計畫的專案。
  • ROLLOUT_PLAN_NAME：您定義的自訂推出計畫名稱。

  如未指定任何發布計畫旗標，系統會使用 slow_rollout。

• ROLLOUT_CONFLICT_BEHAVIOR：指定系統偵測到區域和全域政策之間發生衝突時的行為。可能的值包括：

  • "" (空字串)：使用區域政策值。
  • overwrite：全域政策會覆寫區域政策。

  詳情請參閱 --rollout-conflict-behavior 旗標。

• RETRY_UUID：用於識別政策更新推出作業重試嘗試的 UUID。您可以重新嘗試更新，但不會進行任何變更。如果您設定這個標記並修改政策，就會發生錯誤。詳情請參閱「重試推出」。

區域

使用 gcloud beta compute zone-vm-extension-policies update 指令修改現有的 VM 擴充功能政策。使用 gcloud 更新政策時，要求會做為完整替代項目。您省略的任何選填欄位都會還原為預設值，而不是保留修改後政策的現有值。

如要更新 VM 擴充功能政策，請執行下列指令：

  gcloud beta compute zone-vm-extension-policies update POLICY_NAME \
      --zone=ZONE \
      --extensions=EXTENSION_NAME_1,EXTENSION_NAME_2 \
      --description="DESCRIPTION" \
      --version=EXTENSION_NAME_1=VERSION_1,EXTENSION_NAME_2=VERSION_2 \
      --config-from-file=EXTENSION_NAME_1=CONFIG_FILE_PATH_1,EXTENSION_NAME_2=CONFIG_FILE_PATH_2 \
      --inclusion-labels=KEY_1=VALUE_1 \
      --priority=PRIORITY_NUMBER

更改下列內容：

• POLICY_NAME：要更新的 VM 擴充功能政策名稱。
• ZONE：政策適用的 Google Cloud 區域。
• EXTENSION_NAME_1、EXTENSION_NAME_2：要更新的擴充功能名稱。您必須至少指定一個擴充功能。
• DESCRIPTION：VM 擴充功能政策的選填說明。
• VERSION_1：第一個 VM 擴充功能的版本。
• VERSION_2：第二個 VM 擴充功能的版本。

• EXTENSION_NAME_1=CONFIG_FILE_PATH_1、EXTENSION_NAME_2=CONFIG_FILE_PATH_2：以半形逗號分隔的鍵/值配對清單，其中鍵是擴充功能名稱，值是該擴充功能的設定檔路徑。這個路徑位於執行 gcloud 指令的 VM 上，而非安裝擴充功能的 VM。

  或者，如要以內嵌字串形式提供設定，請使用 --config 旗標而非 --config-from-file，例如 EXTENSION_NAME_1="CONFIG_1"。您可以使用 --config-from-file 或 --config，但不能在同一個指令中同時使用兩者。

• KEY_1=VALUE_1：以半形逗號分隔的鍵/值組合清單，用於定義選擇器的納入標籤。VM 必須具備選取器中的所有指定標籤，才能成為目標。如果您多次指定 --inclusion-labels，政策會以符合任何所提供選取器 (邏輯 OR) 的 VM 為目標。如果省略這個標記，政策會以指定可用區中的所有 VM 為目標。

• PRIORITY_NUMBER：VM 擴充功能政策的優先順序編號。

刪除 VM 擴充功能政策，解除安裝擴充功能

刪除政策後，VM 擴充功能管理工具會從該政策管理的任何 VM 解除安裝擴充功能。不過，如果另一個優先順序較低的有效政策適用於 VM，且聲明相同的擴充功能，則該擴充功能會根據優先順序較低的政策，繼續安裝在該 VM 上。

VM 擴充功能管理工具會在政策刪除後一分鐘內，從所有可存取的 VM 移除擴充功能。如果 VM 無法存取 (因為客體代理程式已移除或 VM 已刪除)，VM 擴充功能管理員會略過擴充功能刪除作業。如果這類 VM 恢復運作，VM Extension Manager 會移除擴充功能。

控制台

1. 前往 Google Cloud 控制台的「VM extension policies」(VM 擴充功能政策) 頁面。

   前往 VM 擴充功能政策

2. 選取要刪除的政策。
3. 按一下「Delete」(刪除)。
4. 在確認對話方塊中按一下「刪除」。

gcloud

全球

使用 gcloud beta compute global-vm-extension-policies delete 指令刪除現有的全域 VM 擴充功能政策。

gcloud beta compute global-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --rollout-predefined-plan=ROLLOUT_PLAN \
  --rollout-retry-uuid=RETRY_UUID

更改下列內容：

• POLICY_NAME：要刪除的 VM 擴充功能政策名稱。
• PROJECT_ID： Google Cloud 專案的 ID。

• ROLLOUT_PLAN：指定 slow_rollout 或 fast_rollout。 如要使用自訂推出計畫，請使用 --rollout-custom-plan 標記 (而非 --rollout-predefined-plan)，並指定計畫名稱，例如：

  --rollout-custom-plan=projects/PROJECT_NUMBER/locations/global/rolloutPlans/ROLLOUT_PLAN_NAME
  

  更改下列內容：

  • PROJECT_NUMBER：定義推出計畫的專案。
  • ROLLOUT_PLAN_NAME：您定義的自訂推出計畫名稱。

  如未指定任何發布計畫旗標，系統會使用 slow_rollout。

• RETRY_UUID：用於重試刪除擴充功能政策的 UUID。只有在重試刪除 DELETING 狀態的現有政策要求時，才需要設定這個欄位。如果政策不是處於 DELETING 狀態，設定這個欄位會導致錯誤。詳情請參閱「重試推出」。

區域

使用 gcloud beta compute zone-vm-extension-policies delete 指令刪除現有的 VM 擴充功能政策。

gcloud beta compute zone-vm-extension-policies delete POLICY_NAME \
  --project=PROJECT_ID \
  --zone=ZONE

更改下列內容：

• POLICY_NAME：要刪除的 VM 擴充功能政策名稱。
• PROJECT_ID： Google Cloud 專案的 ID。
• ZONE：政策所在的 Google Cloud 區域。

排解 VM 擴充功能問題

本節說明如何排解 VM 擴充功能的問題。

確認已安裝擴充功能

如要確認擴充功能是否已安裝，請在 VM 上檢查下列項目：

• 連線至 VM，並檢查是否有正在執行的程序。

  下表列出各個擴充功能的程序名稱：

  擴充功能名稱	擴充功能程序名稱
  google-cloud-sap-extension	google_cloud_sap_agent
  google-cloud-workload-extension	google_cloud_workload_agent
  ops-agent	ops-agent

  Linux

  ps aux | grep 'EXTENSION_PROCESS_NAME'

  將 EXTENSION_PROCESS_NAME 替換為擴充功能的程序名稱。 舉例來說，如要檢查 Ops Agent 程序，請執行下列指令：

  ps aux | grep 'ops-agent'

  Windows

  tasklist | findstr "EXTENSION_PROCESS_NAME"

  將 EXTENSION_PROCESS_NAME 替換為擴充功能的程序名稱。 舉例來說，如要檢查 Ops Agent 程序，請執行下列指令：

  tasklist | findstr "ops-agent"

  在 Linux VM 上，Ops Agent 的 ps 指令輸出內容可能會顯示類似下列的項目：

  ....
  /var/lib/google-guest-agent/931374772276853249/plugins/ops-agent_baddabb3dac3
  ....

• 啟用及查看訪客代理程式記錄。擴充功能安裝及啟動時，系統會記錄在訪客代理程式記錄中。

  安裝 Ops Agent 擴充功能後，您可能會在客體代理程式記錄中看到下列輸出內容：

  my-instance google_guest_agent [14972]: Installing plugin "ops-agent", revision "2dfa648c1892da87"
  my-instance google_guest_agent [14972]: (client.go:181) Sent message [[type.googleapis.com/agent_controlplane.PluginEventMessage: (revision_id:"2dfa648c1892da87)]]
  my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "DownloadPluginStep" on plugin "ops-agent_2dfa648c1892da87"
  my-instance google_guest_agent [14972]: (pluginengine.go:316) Successfully downloaded "https://storage.googleapis.com/acp-gcs-bucket-us-centrall-a/ops-agent
  my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "UnpackPluginArchiveStep" on plugin "ops-agent_2dfa648c1892da87"
  my-instance google_guest_agent [14972]: (pluginengine.go:361) Successfully unpacked "/var/lib/google-guest-agent/ops-agent.tar.gz" to "/google-guest-agent/ops-agent_2dfa648c1892da87
  my-instance google_guest_agent [14972]: (pluginengine.go:202) Running "LaunchPluginStep" on plugin "ops-agent_2dfa648c1892da87"
  my-instance google_guest_agent [14972]: (run_linux.go:32) Attempting process start: (OutputType:0 Name:/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87)
  my-instance google_guest_agent [14972]: (pluginlauncher.go:132) Launched a plugin process from "/var/lib/google-guest-agent/plugins/ops-agent_2dfa648c1892da87"
  my-instance google_guest_agent [14972]: (plugin.go:136) Dialing in on plugin "ops-agent 2dfa648c1892da87"
  my-instance google_guest_agent [14972]: (plugin.go:51) Executing start request on plugin "ops-agent_2dfa648c1892da87"

排解安裝問題。

如果您建立政策後，擴充功能未安裝在 VM 上，請按照下列步驟排解問題：

1. 等待政策違規處置。政策最多可能需要 1 小時才會套用，包括任何重試作業。
2. 確認政策中指定的納入標籤與 VM 上的標籤相符。
3. 如要找出潛在的安裝錯誤，請為訪客代理程式啟用偵錯記錄功能。

4. 修正根本問題後，請使用下列其中一種方法重試安裝：

   • 重新建立政策：刪除政策，然後建立新政策。

   • 使用暫時的高優先順序政策：如要避免重新建立影響多部 VM 的政策，請使用暫時的高優先順序政策，在特定 VM 上重試安裝作業：

     1. 為安裝失敗的 VM 新增標籤。例如新增 status=failed 標籤。
     2. 建立優先順序較高的政策，並指定新標籤。 舉例來說，如果失敗的原始政策優先順序為預設值 1000，請建立優先順序較高的政策，例如 500。

        gcloud beta compute zone-vm-extension-policies create temp-policy  
        
        --project=test-project 
        
        --zone=us-central1-f 
        
        --extensions=ops-agent 
        
        --config-from-file=ops-agent="/usr/ops-agent-config.yaml" 
        
        --priority=500 
        
        --inclusion-labels=status=failed

     3. 擴充功能安裝完成後，請刪除臨時政策並從 VM 移除標籤。 由於原始政策仍有效，因此擴充功能會繼續安裝。

查看訪客代理程式的偵錯記錄

如要啟用偵錯記錄，請在客層代理程式設定檔的 Core 區段中新增記錄層級和詳細程度設定，如下所示：

Linux

1. 開啟位於 /etc/default/instance_configs.cfg 的客體代理程式設定檔。

2. 在檔案中新增下列幾行內容。如果 [Core] 區段已存在，請將 log_level 和 log_verbosity 設定新增至該區段。

   [Core]
   log_level = 4
   log_verbosity = 4
   

3. 執行下列指令，重新啟動客層代理程式管理員：

    sudo systemctl restart google-guest-agent-manager
   

4. 如要在擴充功能安裝期間查看客體代理程式活動的記錄，請執行下列指令：

   journalctl -u google-guest-agent-manager
   

Windows

1. 開啟位於 C:\Program Files\Google\Compute Engine\instance_configs.cfg 的客體代理程式設定檔。

2. 在檔案中新增下列幾行內容。如果 [Core] 區段已存在，請將 log_level 和 log_verbosity 設定新增至該區段。

   [Core]
   log_level = 4
   log_verbosity = 4
   

3. 以 Windows 系統管理員身分執行下列指令，重新啟動客層代理程式管理員：

    net stop GCEAgentManager
    net start GCEAgentManager
   

4. 如要查看擴充功能安裝期間的客體代理程式活動記錄，請在 PowerShell 中執行下列指令：

   Get-Eventlog -Source google_guest_agent_manager -LogName Application
   

啟用偵錯記錄後，請檢查是否有下列常見錯誤：

• 磁碟空間不足：如果記錄檔回報磁碟空間不足，請釋放磁碟空間或調整磁碟大小，增加更多空間。
• 資源用量過高：如果記錄顯示訪客代理程式因記憶體或 CPU 用量過高而停止擴充功能，請將 VM 的機器類型變更為資源較多的類型。

後續步驟

• 進一步瞭解 VM 擴充功能管理工具。