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

預先發布版

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

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

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 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 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 \
      --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 \
      --description="DESCRIPTION"

更改下列內容：

• POLICY_NAME：要更新的 VM 擴充功能政策名稱。
• ZONE：政策適用的 Google Cloud 區域。
• EXTENSION_NAME_1、EXTENSION_NAME_2：要更新的擴充功能名稱。您必須指定至少一個擴充功能。
• 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 擴充功能政策的優先順序編號。

• DESCRIPTION：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 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 擴充功能管理工具。