排解 VM 擴充功能問題

本文說明如何驗證 VM 擴充功能安裝作業、診斷政策推出和 VM 擴充功能狀態問題，以及查看 Compute Engine 虛擬機器 (VM) 執行個體上的訪客代理程式偵錯記錄檔。請按照下列操作說明，找出預期擴充功能未安裝、非預期擴充功能在 VM 上執行，或擴充功能程序停止的原因。

事前準備

排解 VM 擴充功能問題前，請先完成下列必要條件：

  • 確認您具備必要權限，可檢查擴充功能政策、VM 擴充功能管理工具支援的擴充功能中繼資料，以及 Google Cloud 資源階層中的 VM 擴充功能狀態。詳情請參閱「查看 VM 擴充功能詳細資料和狀態」。
  • 如要在連線至個別 VM 前，找出安裝失敗、當機或復原事件，請在 Cloud Logging 查看擴充功能強制執行事件記錄。詳情請參閱「查看 VM 擴充功能記錄」。
  • 如要直接在 VM 上檢查執行中的擴充功能程序和訪客代理程式偵錯記錄檔，請確認您能使用 SSH 或 RDP 連線至 VM。

確認已安裝擴充功能

如要確認 Compute Engine VM 是否已安裝並執行擴充功能，請使用唯讀方法檢查 VM 擴充功能狀態。只有在需要客體 OS 程序或記錄詳細資料時，才連線至 VM。

使用唯讀方法檢查 VM 擴充功能狀態

如要檢查已安裝擴充功能的執行階段狀態和健康狀態，而不連線至 VM，請執行 gcloud beta compute instances list-vm-extension-states 或 gcloud beta compute instances get-vm-extension-state 指令，或呼叫對等的 REST API 方法。回應會傳回各項擴充功能的使用中版本、強制執行狀態 (enforcementState)、健康狀態 (healthStatus)、診斷訊息 (healthMsg) 和管理政策 ID (policyId)。詳情請參閱「查看執行個體的 VM 擴充功能狀態」。

檢查 VM 上執行的擴充功能程序

如果遠端狀態查詢未傳回預期狀態，請連線至 VM，並檢查擴充功能程序是否在客體作業系統中執行。

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

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

如要檢查擴充功能程序是否在 VM 上執行，請選取您的作業系統：

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"

下列程式碼片段顯示 ops-agent 擴充功能在 Linux VM 上執行時，ps 指令的輸出範例：

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

查看訪客代理程式安裝項目

如要確認客體代理程式何時下載、擷取及啟動擴充功能外掛程式，請啟用並查看客體代理程式的偵錯記錄檔。

下列程式碼片段顯示在 Linux VM 上，訪客代理程式安裝並啟動 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-central1-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 未安裝擴充功能，或 VM 執行非預期的擴充功能，請先診斷政策推出、目標標籤和強制執行狀態，再重新嘗試安裝。

如要找出擴充功能無法安裝在 VM 上的原因，請完成下列診斷步驟：

  1. 等待政策違規處置。政策推出作業 (包括重試) 最多可能需要一小時，才能在目標 VM 上完成。如要進一步瞭解如何檢查推出進度，請參閱「查看擴充功能政策」。
  2. 確認政策中指定的納入標籤與 VM 上的標籤相符，並驗證 VM 擴充功能管理工具支援的擴充功能中繼資料：
    • 如要查看整個組織、資料夾或專案的政策標籤選取器和優先順序編號，請參閱「查看擴充功能政策」。
    • 如要查看 VM 擴充功能管理工具在所有可用區或特定可用區支援的擴充功能名稱、版本號碼和支援等級，請參閱「查看 VM 擴充功能和版本」。
  3. 如要查看強制執行狀態、健康狀態、診斷訊息和管理政策 ID (policyId)，請檢查受影響 VM 的擴充功能狀態。常見的錯誤狀態包括 INSTALL_FAILED、INCOMPATIBLE 和 ROLLED_BACK。如果有多項政策指定同一個 VM，policyId 欄位會顯示各項擴充功能受哪項政策控管。詳情請參閱「查看執行個體的 VM 擴充功能狀態」。
  4. 如要找出 VM 上的訪客層級安裝錯誤，請啟用並查看訪客代理程式的偵錯記錄檔。

重新安裝擴充功能

修正基礎政策設定或訪客 OS 問題後，請重新套用政策設定，讓訪客代理程式在受影響的 VM 上重試安裝。

如要重試擴充功能安裝作業，請選擇下列其中一個選項：

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

  • 套用暫時性的高優先順序政策：如要在特定 VM 上重試安裝，而不重新建立會影響大量機群的政策，請完成下列步驟：

    1. 為安裝失敗的 VM 新增臨時標籤，例如 status=failed。

    2. 建立優先順序較高 (整數值較低) 的臨時政策，並指定臨時標籤。舉例來說，如果原始政策使用預設優先順序 1000，如要建立優先順序為 500 的臨時政策，請執行下列指令：

      gcloud 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 上安裝擴充功能後，請刪除暫時政策。

    4. 從 VM 移除臨時標籤。由於原始政策仍控管這些 VM，因此擴充功能仍會保持安裝狀態。

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

如果遠端狀態查詢和 Logging 事件記錄檔未顯示擴充功能無法下載或啟動的原因，請在訪客代理程式設定檔的 Core 部分啟用詳細偵錯記錄檔。

如要啟用及查看訪客代理程式的偵錯記錄檔，請選取您的作業系統：

Linux

如要在 Linux VM 啟用偵錯記錄檔功能，請完成下列步驟：

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

  2. 在 /etc/default/instance_configs.cfg 中新增下列設定。如果 [Core] 區段已存在，請在 [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

如要在 Windows VM 啟用偵錯記錄檔功能，請完成下列步驟：

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

  2. 在 instance_configs.cfg 中新增下列設定。如果 [Core] 區段已存在，請在 [Core] 下方新增 log_level 和 log_verbosity：

    [Core]
log_level = 4
log_verbosity = 4

  3. 在提升權限的命令提示字元或 PowerShell 視窗中，執行下列指令，重新啟動訪客代理程式管理工具：

    net stop GCEAgentManager
net start GCEAgentManager

  4. 在 PowerShell 中執行下列指令，查看擴充功能安裝期間產生的訪客代理程式記錄：

    Get-Eventlog -Source google_guest_agent_manager -LogName Application

解決常見的訪客代理程式記錄錯誤

檢查訪客代理程式偵錯記錄檔時，請查看是否有資源限制錯誤，導致擴充功能無法在 VM 上擷取或執行。

下表列出客體代理程式偵錯記錄中回報的常見錯誤，以及解決方法：

錯誤狀況 解析度
磁碟空間不足 如果記錄顯示 VM 沒有足夠的磁碟空間，無法下載或擷取擴充功能封存檔，請刪除未使用的檔案或調整開機磁碟大小。
資源用量過高 如果記錄顯示客體代理程式因記憶體或 CPU 用量過高而停止擴充功能，請將 VM 的機型變更為記憶體或 vCPU 較多的機型。

後續步驟