你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 Windows 的虚拟机扩展和功能

项目
10/15/2024

Azure 虚拟机 (VM) 扩展是小型应用程序，可在 Azure VM 上提供部署后配置和自动化任务。例如，如果某个虚拟机需要软件安装、防病毒保护或在虚拟机内运行脚本的功能，你可以使用 VM 扩展。

可以使用 Azure CLI、PowerShell、Azure 资源管理器 (ARM) 模板和 Azure 门户运行 Azure VM 扩展。可将扩展与新 VM 部署捆绑在一起，也可以针对任何现有系统运行扩展。

本文概括介绍 Azure VM 扩展，包括先决条件以及有关如何检测、管理和删除扩展的指导。本文提供的是概况信息，因为有许多 VM 扩展可用。每个扩展具有潜在唯一的配置和自身的文档。

用例和示例

每个 Azure VM 扩展都有特定的用例。下面是一些示例：

使用适用于 Windows 的 DSC 扩展将 PowerShell Desired State Configuration (DSC) 应用于 VM。
使用 Azure Monitor 代理和 VM 见解配置 VM 监视。
使用 Chef 配置 Azure VM。
使用 Datadog 扩展配置 Azure 基础结构监视。

除了进程特定的扩展外，自定义脚本扩展也可用于 Windows 和 Linux 虚拟机。使用适用于 Windows 的自定义脚本扩展可在 VM 上运行任何 PowerShell 脚本。在设计需要本机 Azure 工具无法提供的配置的 Azure 部署时，自定义脚本很有用。

先决条件

查看使用 Azure VM 扩展的以下先决条件。

Azure VM 代理

若要处理虚拟机上的扩展，需要安装适用于 Windows 的 Azure 虚拟机代理。此代理也称为 Azure VM 代理或 Windows 来宾代理。准备安装扩展时，请记住，某些扩展具有单独的先决条件，例如访问资源或依赖项。

Azure VM 代理可管理 Azure VM 与 Azure 结构控制器之间的交互。该代理负责部署和管理 Azure VM 的许多功能层面，包括运行 VM 扩展。

Azure VM 代理预安装在 Azure 市场映像上。也可以手动将代理安装在支持的操作系统上。

代理在多个操作系统上运行。但是，扩展框架有一个针对扩展所使用的操作系统的限制。一些扩展并非在所有操作系统上均受支持，并且可能会发出错误代码 51（“不受支持的 OS”）。请查看相应的扩展文档来了解支持情况。

网络访问

可从 Azure 存储扩展存储库下载扩展包。扩展状态上传内容会发布到 Azure 存储。

如果使用受支持的 Azure VM 代理版本，则无需允许访问 VM 区域中的 Azure 存储。可以使用 VM 代理将通信重定向到 Azure 结构控制器以进行代理通信（在专用 IP 168.63.129.16 上通过特权通道使用 HostGAPlugin 功能）。如果使用不受支持的 VM 代理版本，则需要允许从 VM 对该区域中的 Azure 存储进行出站访问。

重要

如果使用来宾防火墙或通过代理阻止对 IP 地址 168.63.129.16 的访问，则扩展会失败。即使使用受支持的 VM 代理版本或配置出站访问，也会失败。需要端口 80 和 32526。

代理只可用于下载扩展包和报告状态。例如，如果扩展安装需要从 GitHub 下载脚本（自定义脚本扩展）或需要访问 Azure 存储（Azure 备份），则你需要打开其他防火墙或网络安全组 (NSG) 端口。不同的扩展具有不同的要求，因为它们本身就是应用程序。对于需要访问 Azure 存储或 Microsoft Entra ID 的扩展，可以使用 Azure NSG 服务标记来允许访问。

Azure VM 代理不提供代理服务器支持来实现代理流量请求重定向。 VM 代理依赖于你的自定义代理（如果有）通过 IP 地址 168.63.129.16 来访问 Internet 或主机上的资源。

发现 VM 扩展

有许多 VM 扩展可与 Azure VM 配合使用。若要查看完整列表，请使用 Get-AzVMExtensionImage PowerShell cmdlet。

以下命令列出了美国西部区域的所有可用 VM 扩展：

Get-AzVmImagePublisher -Location "West US" |
Get-AzVMExtensionImageType |
Get-AzVMExtensionImage | Select Type, Version

此命令提供类似于以下示例的输出：

Type                Version
----                -------
AcronisBackup       1.0.33
AcronisBackup       1.0.51
AcronisBackupLinux  1.0.33
AlertLogicLM        1.3.0.1
AlertLogicLM        1.3.0.0
AlertLogicLM        1.4.0.1

运行 VM 扩展

Azure VM 扩展在现有 VM 上运行，需要在已部署的 VM 上进行配置更改或恢复连接时，这很有用。 VM 扩展还可以与 ARM 模板部署捆绑在一起。将扩展与 ARM 模板配合使用，在部署后无需干预即可部署和配置 Azure VM。

可使用以下方法针对现有 VM 运行扩展。

注意

下面的一些示例在命令中使用 "<placeholder>" 参数值。在运行每个命令之前，请确保将任何 "<placeholder>" 值替换为配置的特定值。

PowerShell

存在多个用于运行单个扩展的 PowerShell 命令。若要查看列表，请使用 Get-Command 并根据“扩展”筛选：

Get-Command Set-Az*Extension* -Module Az.Compute

此命令提供类似于以下示例的输出：

CommandType     Name                                          Version    Source
-----------     ----                                          -------    ------
Cmdlet          Set-AzVMAccessExtension                       4.5.0      Az.Compute
Cmdlet          Set-AzVMADDomainExtension                     4.5.0      Az.Compute
Cmdlet          Set-AzVMAEMExtension                          4.5.0      Az.Compute
Cmdlet          Set-AzVMBackupExtension                       4.5.0      Az.Compute
Cmdlet          Set-AzVMBginfoExtension                       4.5.0      Az.Compute
Cmdlet          Set-AzVMChefExtension                         4.5.0      Az.Compute
Cmdlet          Set-AzVMCustomScriptExtension                 4.5.0      Az.Compute
Cmdlet          Set-AzVMDiagnosticsExtension                  4.5.0      Az.Compute
Cmdlet          Set-AzVMDiskEncryptionExtension               4.5.0      Az.Compute
Cmdlet          Set-AzVMDscExtension                          4.5.0      Az.Compute
Cmdlet          Set-AzVMExtension                             4.5.0      Az.Compute
Cmdlet          Set-AzVMSqlServerExtension                    4.5.0      Az.Compute
Cmdlet          Set-AzVmssDiskEncryptionExtension             4.5.0      Az.Compute

以下示例使用自定义脚本扩展从 GitHub 存储库将脚本下载到目标虚拟机，然后运行该脚本。

Set-AzVMCustomScriptExtension -ResourceGroupName "<myResourceGroup>" `
    -VMName "<myVM>" -Name "<myCustomScript>" `
    -FileUri "https://raw.githubusercontent.com/neilpeterson/nepeters-azure-templates/master/windows-custom-script-simple/support-scripts/Create-File.ps1" `
    -Run "Create-File.ps1" -Location "<myVMregion>"

以下示例使用 VMAccess 扩展将 Windows VM 的管理密码重置为临时密码。运行此代码后，应在首次登录时重置密码。

$cred=Get-Credential

Set-AzVMAccessExtension -ResourceGroupName "myResourceGroup" -VMName "myVM" -Name "myVMAccess" `
    -Location "myVMregion" -UserName $cred.GetNetworkCredential().Username `
    -Password $cred.GetNetworkCredential().Password -typeHandlerVersion "2.0"

可以使用 Set-AzVMExtension 命令启动任何 VM 扩展。

Azure 门户

可通过 Azure 门户将 VM 扩展应用到现有 VM。在门户中选择该 VM，然后依次选择“扩展 + 应用程序”和“+ 添加”。从可用扩展列表中选择所需扩展，并按向导中的说明操作。

以下示例演示如何从 Azure 门户安装 Microsoft 反恶意软件扩展。

用于安装 Microsoft Antimalware 扩展的对话框的屏幕截图。

Azure 资源管理器模板

可以将 VM 扩展添加到 ARM 模板，通过部署该模板来运行扩展。使用模板部署扩展时，可以创建完全配置的 Azure 部署。

以下 JSON 示例来自某个 ARM 模板，该模板在每个 VM 上部署一组负载均衡的 VM、一个 Azure SQL 数据库，然后安装一个 .NET Core 应用程序。 VM 扩展负责安装软件。

{
    "apiVersion": "2015-06-15",
    "type": "extensions",
    "name": "config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
    "[variables('musicstoresqlName')]"
    ],
    "tags": {
    "displayName": "config-app"
    },
    "properties": {
    "publisher": "Microsoft.Compute",
    "type": "CustomScriptExtension",
    "typeHandlerVersion": "1.9",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1"
        ]
    },
    "protectedSettings": {
        "commandToExecute": "[concat('powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 -user ',parameters('adminUsername'),' -password ',parameters('adminPassword'),' -sqlserver ',variables('musicstoresqlName'),'.database.windows.net')]"
    }
    }
}

有关创建 ARM 模板的详细信息，请参阅 ARM 模板中的虚拟机。

帮助保护 VM 扩展数据

运行 VM 扩展时，可能需要包括敏感信息，例如凭据、存储帐户名称和访问密钥。许多 VM 扩展包括受保护的配置，该配置对数据进行加密并且仅在目标 VM 内才对数据进行解密。每个扩展都有一个特定的受保护配置架构，扩展特定的文档中详述了各个架构。

以下 JSON 示例显示了适用于 Windows 的自定义脚本扩展的一个实例。要运行的命令包含一组凭据。在此示例中，要运行的命令是未加密的。

{
    "apiVersion": "2015-06-15",
    "type": "extensions",
    "name": "config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
    "[variables('musicstoresqlName')]"
    ],
    "tags": {
    "displayName": "config-app"
    },
    "properties": {
    "publisher": "Microsoft.Compute",
    "type": "CustomScriptExtension",
    "typeHandlerVersion": "1.9",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1"
        ],
        "commandToExecute": "[concat('powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 -user ',parameters('adminUsername'),' -password ',parameters('adminPassword'),' -sqlserver ',variables('musicstoresqlName'),'.database.windows.net')]"
    }
    }
}

将 commandToExecute 属性移至 protected 配置有助于保护执行字符串，如以下示例所示：

{
    "apiVersion": "2015-06-15",
    "type": "extensions",
    "name": "config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', variables('vmName'),copyindex())]",
    "[variables('musicstoresqlName')]"
    ],
    "tags": {
    "displayName": "config-app"
    },
    "properties": {
    "publisher": "Microsoft.Compute",
    "type": "CustomScriptExtension",
    "typeHandlerVersion": "1.9",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1"
        ]
    },
    "protectedSettings": {
        "commandToExecute": "[concat('powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1 -user ',parameters('adminUsername'),' -password ',parameters('adminPassword'),' -sqlserver ',variables('musicstoresqlName'),'.database.windows.net')]"
    }
    }
}

在使用扩展的 Azure 基础结构即服务 (IaaS) VM 上的证书控制台中，可能会看到使用者为 Windows Azure CRP Certificate Generator 的证书。在经典 RedDog 前端 (RDFE) VM 上，这些证书的使用者名称为 Windows Azure Service Management for Extensions。

这些证书用于保护在传输扩展所使用的受保护设置（密码和其他凭据）期间 VM 与其主机之间的通信。 Azure 结构控制器生成证书并将其传递给 Azure VM 代理。如果每天都停止并启动 VM，结构控制器可能会创建新证书。此证书存储在计算机的个人证书存储中。可以删除这些证书。 Azure VM 代理会根据需要重新创建证书。

如何更新代理和扩展

代理和扩展使用相同的自动更新机制。

如果有更新可用并且已启用自动更新，则仅当扩展或其他 VM 模型发生更改后，才会在 VM 上安装更新。更改可能包括：

数据磁盘数
扩展
扩展标记
启动诊断容器
来宾 OS 机密
VM 大小
网络配置文件

发布者在不同时间向区域提供更新。你可以在不同区域拥有不同版本的虚拟机。

注意

某些更新可能不需要附加的防火墙规则。有关详细信息，请参阅网络访问。

列出已部署到 VM 的扩展

可以使用以下命令列出部署到 VM 的扩展：

$vm = Get-AzVM -ResourceGroupName "<myResourceGroup>" -VMName "<myVM>"
$vm.Extensions | select Publisher, VirtualMachineExtensionType, TypeHandlerVersion

此命令会生成类似于以下示例的输出：

Publisher             VirtualMachineExtensionType          TypeHandlerVersion
---------             ---------------------------          ------------------
Microsoft.Compute     CustomScriptExtension                1.9

代理更新

Azure VM 代理仅包含扩展处理代码。 Windows 预配代码是独立存在的。你可以卸载 Azure VM 代理，但不能禁用 Azure VM 代理的自动更新。

扩展处理代码负责执行以下任务：

与 Azure 结构通信。
处理 VM 扩展操作，例如安装、报告状态、更新单个扩展和删除扩展。更新包含扩展处理代码的安全修补程序、bug 修复和增强功能。

若要检查你正在运行哪个版本，请参阅检测 Azure VM 代理。

扩展更新

当扩展更新可用并启用了自动更新时，如果 VM 模型发生更改，则 Azure VM 代理会下载并升级扩展。

自动扩展更新以次要版本或修补程序的形式提供。预配扩展时，可以选择安装或不安装次要版本更新。以下示例演示如何使用 "autoUpgradeMinorVersion": true, 参数自动升级 ARM 模板中的次要版本：

    "properties": {
    "publisher": "Microsoft.Compute",
    "type": "CustomScriptExtension",
    "typeHandlerVersion": "1.9",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1"
        ]
    },

若要获取最新的次要版本 bug 修复，强烈建议始终在扩展部署中选择自动更新。无法选择不安装包含安全或关键 bug 修复的修补程序更新。

如果禁用自动更新或需要升级主版本，请使用 Set-AzVMExtension 命令并指定目标版本。

如何识别扩展更新

有几种方法可以识别扩展的更新。

在 VM 上使用 autoUpgradeMinorVersion 识别是否设置了扩展

可以查看 VM 模型，确定扩展是否预配了 autoUpgradeMinorVersion 参数。若要检查 VM 模型，请使用 Get-AzVm 命令，并按如下方式提供资源组和 VM 名称：

 $vm = Get-AzVm -ResourceGroupName "myResourceGroup" -VMName "myVM"
 $vm.Extensions

以下示例输出显示 autoUpgradeMinorVersion 参数设置为 true：

ForceUpdateTag              :
Publisher                   : Microsoft.Compute
VirtualMachineExtensionType : CustomScriptExtension
TypeHandlerVersion          : 1.9
AutoUpgradeMinorVersion     : True

识别 autoUpgradeMinorVersion 事件的发生时间

若要查看何时对扩展进行了更新，可查看 VM 上的代理日志，其路径为 C:\WindowsAzure\Logs\WaAppAgent.log。

以下示例演示安装了 Microsoft.Compute.CustomScriptExtension 版本 1.8 的 VM，以及可用于版本 1.9 的修补程序。

[INFO]  Getting plugin locations for plugin 'Microsoft.Compute.CustomScriptExtension'. Current Version: '1.8', Requested Version: '1.9'
[INFO]  Auto-Upgrade mode. Highest public version for plugin 'Microsoft.Compute.CustomScriptExtension' with requested version: '1.9', is: '1.9'

代理权限

若要执行任务，Azure VM 代理需要作为本地系统运行。

排查 VM 扩展的问题

每个 VM 扩展可能都有特定的故障排除步骤。例如，使用自定义脚本扩展时，可以在运行该扩展的 VM 本地找到脚本执行详细信息。

以下故障排除操作适用于所有 VM 扩展：

若要检查 Azure VM 代理日志，请在 C:\WindowsAzure\Logs\WaAppAgent.log 中查看预配扩展时的活动。
查看 C:\WindowsAzure\Logs\Plugins<extensionName> 中的扩展日志，以了解更多详细信息。
有关错误代码、已知问题和其他特定于扩展的信息，请查看特定于扩展的文档中的故障排除部分。
查看系统日志。检查其他可能影响了扩展的操作，例如，长时间安装另一个需要包管理器独占访问权限的应用程序。
在 VM 中，如果存在处于预配失败状态的现有扩展，则无法安装任何其他新的扩展。

扩展失败的常见原因

下面是扩展可能失败的一些常见原因：

扩展有 20 分钟的运行时间。（自定义脚本、Chef 和 DSC 除外，其运行时间为 90 分钟）如果部署超过此时间，则会标记为超时。导致此问题的原因可能是 VM 资源不足，或者在扩展尝试预配时其他 VM 配置或启动任务消耗了大量资源。
不满足先决条件的最低要求。某些扩展依赖于 VM SKU，例如 HPC 映像。扩展可能需要满足特定的网络访问要求，例如，能够与 Azure 存储或公共服务通信。其他可能的示例包括访问包存储库、磁盘空间耗尽或安全限制。
包管理器独占访问权限。在某些情况下，长时间运行的 VM 配置可能与扩展安装相冲突，因为两者都需要包管理器独占访问权限。

查看扩展状态

针对 VM 运行 VM 扩展后，请使用 Get-AzVM 命令返回扩展状态。 Substatuses[0] 结果显示扩展预配成功，这意味着该扩展已成功部署到 VM。如果看到 Substatuses[1] 结果，则表示 VM 中的扩展执行失败。

Get-AzVM -ResourceGroupName "myResourceGroup" -VMName "myVM" -Status

输出类似于以下示例：

Extensions[0]           :
  Name                  : CustomScriptExtension
  Type                  : Microsoft.Compute.CustomScriptExtension
  TypeHandlerVersion    : 1.9
  Substatuses[0]        :
    Code                : ComponentStatus/StdOut/succeeded
    Level               : Info
    DisplayStatus       : Provisioning succeeded
    Message             : Windows PowerShell \nCopyright (C) Microsoft Corporation. All rights reserved.\n
  Substatuses[1]        :
    Code                : ComponentStatus/StdErr/succeeded
    Level               : Info
    DisplayStatus       : Provisioning succeeded
    Message             : The argument 'cseTest%20Scriptparam1.ps1' to the -File parameter does not exist. Provide the path to an existing '.ps1' file as an argument to the

-File parameter.
  Statuses[0]           :
    Code                : ProvisioningState/failed/-196608
    Level               : Error
    DisplayStatus       : Provisioning failed
    Message             : Finished executing command

此外，还可以在 Azure 门户中找到扩展执行状态。选择该 VM，然后依次选择“扩展”和所需的扩展。

重新运行 VM 扩展

在某些情况下，可能需要重新运行 VM 扩展。若要重新运行扩展，请先删除扩展，然后使用所选执行方法重新运行扩展。若要删除扩展，请使用 Remove-AzVMExtension 命令，如下所示：

Remove-AzVMExtension -ResourceGroupName "myResourceGroup" -VMName "myVM" -Name "myExtensionName"

也可以在 Azure 门户中删除扩展。依次选择 VM、“扩展”和所需的扩展。选择“卸载”。

常见 VM 扩展参考

下表提供了 VM 扩展的一些常见参考。

扩展名称	说明
适用于 Windows 的自定义脚本扩展	针对 Azure 虚拟机运行脚本。
适用于 Windows 的 DSC 扩展	将 PowerShell Desired State Configuration 应用于虚拟机。
Azure 诊断扩展	管理 Azure 诊断。
VMAccess 扩展	管理用户和凭据。

后续步骤

有关 VM 扩展的详细信息，请参阅 Azure 虚拟机扩展和功能。

通过