針對 Azure Windows VM 擴充功能的失敗進行疑難排解

發行項
06/01/2023

Azure 資源管理員範本概觀

Azure Resource Manager 範本可讓您藉由定義資源之間的相依性，以宣告方式指定 JSON 語言的 Azure IaaS 基礎結構。

請參閱撰寫擴充功能範本，深入了解撰寫範本以使用擴充功能。

在本文中我們將了解如何疑難排解某些常見的 VM 擴充功能失敗。

檢視擴充功能狀態

Azure Resource Manager 範本可以從 Azure PowerShell 執行。一旦執行範本之後，就可以從 Azure 資源總管或命令列工具檢視延伸模組狀態。

以下是範例：

Azure PowerShell：

Get-AzVM -ResourceGroupName $RGName -Name $vmName -Status

以下是範例輸出：

Extensions:  {
  "ExtensionType": "Microsoft.Compute.CustomScriptExtension",
  "Name": "myCustomScriptExtension",
  "SubStatuses": [
    {
      "Code": "ComponentStatus/StdOut/succeeded",
      "DisplayStatus": "Provisioning succeeded",
      "Level": "Info",
      "Message": "    Directory: C:\\temp\\n\\n\\nMode                LastWriteTime     Length Name
          \\n----                -------------     ------ ----                              \\n-a---          9/1/2015   2:03 AM         11
          test.txt                          \\n\\n",
                  "Time": null
      },
    {
      "Code": "ComponentStatus/StdErr/succeeded",
      "DisplayStatus": "Provisioning succeeded",
      "Level": "Info",
      "Message": "",
      "Time": null
    }
  ]
}

針對擴充功能失敗進行疑難排解

確認 VM 代理程式正在執行且就緒

管理、安裝和執行擴充功能需要 VM 代理。如果 VM 代理程式未執行或無法向 Azure 平台回報 [就緒] 狀態，則擴充功能將無法正常運作。

請參閱下列頁面，以針對 VM 代理程式進行疑難排解：

針對 Windows Azure 客體代理程式進行疑難排解，適用於 Windows VM
針對 Azure Linux 代理程式進行疑難排解，適用於 Linux VM

檢查您的特定擴充功能疑難排解指南

有些擴充功能具有描述如何進行疑難排解的特定頁面。您可以在疑難排解擴充功能上找到這些擴充功能和頁面的清單。

檢視擴充功能的狀態

如上所述，您可以執行 PowerShell Cmdlet 來找到擴充功能的狀態：

Get-AzVM -ResourceGroupName $RGName -Name $vmName -Status

或 CLI 命令：

az vm extension show -g <RG Name> --vm-name <VM Name>  --name <Extension Name>

或在Azure 入口網站中，瀏覽至 VM 刀鋒視窗/設定/擴充功能。然後，您可以按一下擴充功能，並檢查其狀態和訊息。

在 VM 上重新執行擴充功能

如果您使用自訂指令碼延伸模組在 VM 上執行指令碼，有時候可能會遇到雖然成功建立了 VM 但指令碼卻失敗的錯誤。在這樣的情況下，若要從此錯誤中復原，建議您移除延伸模組並再次重新執行範本。請注意：未來將增強這項功能，以移除對解除安裝延伸模組的需求。

從 Azure PowerShell 移除擴充功能

Remove-AzVMExtension -ResourceGroupName $RGName -VMName $vmName -Name "myCustomScriptExtension"

一旦移除了延伸模組，範本就可以重新執行並在 VM 上執行指令碼。

觸發新的 GoalState 至 VM

您可能會注意到擴充功能尚未執行，或因為遺漏「Windows Azure CRP 憑證產生器」(該憑證用來保護延伸模組受保護設定的傳輸) 而無法執行。從虛擬機器內重新啟動 Windows 客體代理程式，即可自動重新產生該憑證：

開啟工作管理員
移至 [詳細資料] 索引標籤
找出 WindowsAzureGuestAgent.exe 處理流程
以滑鼠右鍵按一下，並選取 [結束工作]。處理程序將自動重新啟動

您也可以藉由執行「VM Reapply」來觸發新的 GoalState 至 VM。 VM Reapply 是 2020 年引進的 API，可重新套用 VM 的狀態。建議您在可容忍的短暫 VM 停機時間內，一次執行此動作。雖然 Reapply 本身不會造成 VM 重新啟動，而且大部分呼叫 Reapply 不會重新啟動 VM，但當 Reapply 觸發新的目標狀態時，對 VM 模型套用其他擱置中的更新可能會非常小，而且其他變更可能需要重新啟動。

Azure 入口網站︰

在入口網站中，選取 VM，然後在 [支援 + 疑難排解] 下方的左窗格中，選取 [重新部署 + 重新套用]，然後選取 [Reapply]。

Azure PowerShell (將 RG 名稱和 VM 名稱取代為您的值)：

Set-AzVM -ResourceGroupName <RG Name> -Name <VM Name> -Reapply

Azure CLI (將 RG 名稱和 VM 名稱取代為您的值)：

az vm reapply -g <RG Name> -n <VM Name>

如果「VM Reapply」無法運作，您可以從 Azure 管理入口網站將新的空白資料磁碟新增至 VM，然後在重新新增憑證後再移除。

查看 VM 內的擴充功能記錄

如果先前的步驟無法運作，而且您的擴充功能仍處於失敗狀態，下一個步驟是查看其虛擬機器內的記錄。

在 Windows VM 上，擴充功能記錄通常位於

C:\WindowsAzure\Logs\Plugins

而擴充功能設定和狀態檔將會位於

C:\Packages\Plugins

在 Linux VM 上，擴充功能記錄通常位於

/var/log/azure/

而擴充功能設定和狀態檔將會位於

/var/lib/waagent/

每個擴充功能都不同，但通常會遵循類似的原則：

延伸模組套件和二進位檔會在 VM 上下載 (例如 Linux 的 "/var/lib/waagent/custom-script/download/1" 或 Windows 的 "C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\Downloads\0")。

其組態和設定會透過 VM 代理程式，從 Azure 平台傳遞至延伸模組處理常式 (例如 Linux 的 "/var/lib/waagent/Microsoft.Azure.Extensions.CustomScript-2.1.3/config" 或 Windows 的 "C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\RuntimeSettings")

VM 內的延伸模組常式會寫入狀態檔 (例如 Linux 的 "/var/lib/waagent/Microsoft.Azure.Extensions.CustomScript-2.1.3/status/1.status" 或 Windows 的 "C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\Status")，接著會向 Azure 平台報告。該狀態是透過 PowerShell、CLI 或 Azure 入口網站中 VM 的擴充功能刀鋒視窗中報告的狀態。

其也會寫入執行的詳細記錄 (例如 Linux 的 "/var/log/azure/custom-script/handler.log"，或 Windows 的 "C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\1.10.12\CustomScriptHandler.log")。

如果 VM 是從現有的 VM 重新建立

您可能會根據來自另一個 Azure VM 的特製化磁碟來建立 Azure VM。在此情況下，舊的 VM 可能包含擴充功能，因此會有保留二進位檔、記錄檔和狀態檔。新的 VM 模型不會察覺先前 VM 的擴充功能狀態，而且可能會回報這些擴充功能的狀態不正確。強烈建議您先從舊 VM 移除擴充功能，再建立新的 VM，然後在建立新的 VM 之後重新安裝這些擴充功能。當您從現有的 Azure VM 建立一般化映像時，可能會發生相同的情況。我們邀請您移除擴充功能，以避免擴充功能的狀態不一致。

已知問題

PowerShell 無法辨識為內部或外部命令

您會注意到 RunCommand 擴充功能輸出中有下列錯誤項目：

RunCommandExtension failed with "'powershell' isn't recognized as an internal or external command,"

分析

擴充功能會在本機系統帳戶下執行，因此很有可能在您 RDP 連線到 VM 時，powershell.exe 運作正常，但在使用 RunCommand 執行時會失敗。

方案

檢查 PATH 環境變數中是否已正確列出 PowerShell：
- 開啟 [控制台]
- 系統及安全性
- 系統
- 進階索引標籤 - > 環境變數
在 [系統變數] 下，按一下 [編輯]，並確定 PowerShell 位於 PATH 環境變數中 (通常是：「C:\Windows\System32\WindowsPowerShell\v1.0」)
重新啟動 VM 或重新啟動 WindowsAzureGuestAgent 服務，然後再次嘗試執行命令。

命令無法辨識為內部或外部命令

您會在 C:\WindowsAzure\Logs\Plugins<ExtensionName><Version>\CommandExecution.log file 檔案中看到下列內容：

Execution Error: '<command>' isn't recognized as an internal or external command, operable program or batch file.

分析

擴充功能會在本機系統帳戶下執行，因此很有可能在您 RDP 連線到 VM 時，powershell.exe 運作正常，但在使用 RunCommand 執行時會失敗。

方案

在 VM 中開啟命令提示字元，並執行命令以重現錯誤。 VM 代理程式會使用系統管理員 cmd.exe，而且您可能有一些預先設定的命令，可在每次啟動 Cmd 時執行。
您的 PATH 變數可能設定不正確，但這將取決於發生問題的命令。

VMAccessAgent 失敗，無法更新系統管理員帳戶的遠端桌面連線設定。錯誤：System.Runtime.InteropServices.COMException (0x800706D9)：端點對應程式沒有其他可用的端點。

您會在擴充功能的狀態中看到下列內容：

Type Microsoft.Compute.VMAccessAgent
Version 2.4.8
Status Provisioning failed
Status level Error
Status message Cannot update Remote Desktop Connection settings for Administrator account. Error: System.Runtime.InteropServices.COMException (0x800706D9): There are no more endpoints available from the endpoint mapper. (Exception from HRESULT: 0x800706D9) at NetFwTypeLib.INetFwRules.GetEnumerator() at 
Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccess.RemoteDesktopManager.EnableRemoteDesktopFirewallRules() 
at Microsoft.WindowsAzure.GuestAgent.Plugins.JsonExtensions.VMAccess.RemoteDesktopManager.EnableRemoteDesktop() at

分析

當 Windows 防火牆服務未執行時，就會發生此錯誤。

方案

檢查 Windows 防火牆服務是否已啟用並執行。如果未執行，請啟用並啟動服務 - 然後再試一次以執行 VMAccessAgent。

根據驗證程序，遠端憑證無效。

您會在 WaAppAgent.log 中看到下列內容

System.Net.WebException: The underlying connection was closed: Could not establish trust relationship for the SSL/TLS secure channel. ---> System.Security.
Authentication.AuthenticationException: The remote certificate is invalid according to the validation procedure.

分析

您的 VM 可能遺失「受信任的根憑證授權單位」中的 Baltimore CyberTrust 根憑證。

方案

使用 certmgr.msc 開啟憑證主控台，並檢查憑證是否存在。

另一個可能的問題是憑證鏈結是由協力廠商 SSL 檢查工具中斷，例如 ZScaler。應該將這類工具設定為略過 SSL 檢查。