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

Azure虚拟机（VM）扩展是小型应用程序，这些应用程序在 Azure VM 上提供部署后配置和自动化任务。例如，如果 VM 需要软件安装、防病毒保护或能够在其中运行脚本，则可以使用 VM 扩展。

可以使用Azure CLI、Azure PowerShell、Azure Resource Manager模板（ARM 模板）和Azure portal来运行Azure VM 扩展。可将扩展与新 VM 部署捆绑在一起，也可以针对任何现有系统运行扩展。

本文概述了Azure VM 扩展、使用它们的先决条件以及如何检测、管理和删除这些扩展。本文提供了一般信息，因为有许多 VM 扩展可用。每个配置项可能具有独特的配置和其相应的文档。

注意事项

尝试 VM 辅助，以便更快地进行诊断。建议运行 VM assist for Windows 或 VM assist for Linux。这些基于脚本的诊断工具可帮助你识别影响Azure VM 来宾代理和整体 VM 运行状况的常见问题。

如果你遇到虚拟机性能问题，在联系支持人员之前，请运行这些工具。

用例和示例

每个Azure VM 扩展都有一个特定的用例。示例包括：

使用 Microsoft Monitoring Agent VM 扩展配置 VM 监视。
使用 Chef 或 Datadog 扩展配置Azure基础结构的监视。

除了特定于进程的扩展，自定义脚本扩展还可用于 Windows 和 Linux VM。使用适用于 Linux 的自定义脚本扩展可以在 VM 上运行任何 Bash 脚本。自定义脚本在设计Azure部署时非常有用，尤其是在需要进行本机Azure工具无法提供的额外配置时。

先决条件

注意事项

扩展仅在 Azure 上认可的 Linux 分发版上受支持。

Azure Linux 代理

若要处理 VM 上的扩展，必须安装 Azure Linux 代理。某些单独的扩展具有先决条件，例如需要访问资源或依赖项。

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

Azure Linux 代理预安装在Azure Marketplace映像上。还可以在受支持的操作系统上手动安装。

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

网络访问

从Azure Storage扩展存储库下载扩展包。扩展状态上传到 Azure 存储。

如果使用受支持的 Azure Linux 代理版本，则无需允许 Azure Storage 在 VM 区域中的访问。可以使用代理将通信重定向到Azure构造控制器进行代理通信。如果您使用的是不支持的代理程序版本，则需要允许从 VM 发起对 Azure 存储所在区域的出站访问。

重要

如果使用来宾防火墙阻止访问专用 IP 地址 168.63.129.16，即使使用支持的代理版本或者配置了出站访问，扩展程序也将无法运行。此外，如果 VM 没有出站访问到 *.blob.chinacloudapi.cn 和 *.blob.storage.chinacloudapi.cn，则初始化 Azure Linux 代理程序和安装扩展会产生更多的延迟。若要避免这些延迟，请确保允许访问这些端点。

只能使用代理下载扩展包和报告状态。例如，如果扩展安装需要从GitHub（自定义脚本扩展）下载脚本，或者需要access Azure Storage（Azure Backup），则需要打开更多防火墙或网络安全组（NSG）端口。不同的扩展具有不同的要求，因为它们是应用程序。对于需要访问 Azure Storage 的扩展，可以使用 Azure NSG service tags 来允许访问。

若要重定向代理流量请求，Azure Linux 代理支持代理服务器。此代理服务器支持不适用于扩展。必须配置每个单独的扩展来使用代理。

许多 VM 扩展可用于Azure VM。若要查看完整列表，请使用 az vm 扩展映像列表。以下示例列出chinanorth位置的所有可用扩展：

az vm extension image list --location chinanorth --output table

许多 VM 扩展可用于Azure VM。若要查看完整列表，请使用 Get-AzVMExtensionImage。以下示例列出chinanorth位置的所有可用扩展：

Get-AzVmImagePublisher -Location "chinanorth" |
Get-AzVMExtensionImageType |
Get-AzVMExtensionImage | Select-Object Type, PublisherName, Version

运行 VM 扩展

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

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

Azure CLI

可以使用 az vm 扩展集命令针对现有 VM 运行Azure VM 扩展。下面的示例针对名为 myResourceGroup 的资源组中名为 myVM 的 VM 运行自定义脚本扩展。请将示例资源组名称、VM 名称和脚本替换为您自己的信息，然后运行 https:\//raw.githubusercontent.com/me/project/hello.sh。

az vm extension set \
  --resource-group myResourceGroup \
  --vm-name myVM \
  --name customScript \
  --publisher Microsoft.Azure.Extensions \
  --settings '{"fileUris": ["https://raw.githubusercontent.com/me/project/hello.sh"],"commandToExecute": "./hello.sh"}'

扩展正确运行时，输出类似于以下示例：

info:    Executing command vm extension set
+ Looking up the VM "myVM"
+ Installing extension "CustomScript", VM: "mvVM"
info:    vm extension set command OK

Azure PowerShell

可以使用 Set-AzVMExtension 命令针对现有 VM 运行Azure VM 扩展。下面的示例针对名为 myResourceGroup 的资源组中名为 myVM 的 VM 运行自定义脚本扩展。将示例资源组名称、VM 名称和脚本中的信息替换为您自己的信息，以便运行 https:\//raw.githubusercontent.com/me/project/hello.sh。

$Params = @{
    ResourceGroupName  = 'myResourceGroup'
    VMName             = 'myVM'
    Name               = 'CustomScript'
    Publisher          = 'Microsoft.Azure.Extensions'
    ExtensionType      = 'CustomScript'
    TypeHandlerVersion = '2.1'
    Settings          = @{fileUris = @('https://raw.githubusercontent.com/me/project/hello.sh'); commandToExecute = './hello.sh'}
}
Set-AzVMExtension @Params

扩展正确运行时，输出类似于以下示例：

RequestId IsSuccessStatusCode StatusCode ReasonPhrase
--------- ------------------- ---------- ------------
                         True         OK OK

Azure portal

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

下图显示了从 Azure portal 安装适用于 Linux 的自定义脚本扩展。

安装适用于 Linux 的自定义脚本扩展的对话框的屏幕截图。

Azure Resource Manager模板

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

例如，以下 JSON 取自一个完整 ARM 模板，用于部署一组负载均衡的虚拟机和一个 Azure SQL 数据库。然后，它会在每个 VM 上安装.NET核心应用程序。 VM 扩展负责安装软件。

{
    "apiVersion": "2015-06-15",
    "type": "extensions",
    "name": "config-app",
    "location": "[resourceGroup().location]",
    "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
    ],
    "tags": {
    "displayName": "config-app"
    },
    "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"
        ]
    },
    "protectedSettings": {
        "commandToExecute": "[concat('sudo sh config-music.sh ',variables('musicStoreSqlName'), ' ', parameters('adminUsername'), ' ', parameters('sqlAdminPassword'))]"
    }
    }
}

有关如何创建 ARM 模板的详细信息，请参阅 Azure Resource Manager 模板中的 Virtual machines。

帮助保护 VM 扩展数据

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

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

{
  "apiVersion": "2015-06-15",
  "type": "extensions",
  "name": "config-app",
  "location": "[resourceGroup().location]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"
      ],
      "commandToExecute": "[concat('sudo sh config-music.sh ',variables('musicStoreSqlName'), ' ', parameters('adminUsername'), ' ', parameters('sqlAdminPassword'))]"
    }
  }
}

将 commandToExecute 属性移到 protected 配置可以帮助保护执行字符串，如以下示例中所示：

{
  "apiVersion": "2015-06-15",
  "type": "extensions",
  "name": "config-app",
  "location": "[resourceGroup().location]",
  "dependsOn": [
    "[concat('Microsoft.Compute/virtualMachines/', concat(variables('vmName'),copyindex()))]"
  ],
  "tags": {
    "displayName": "config-app"
  },
  "properties": {
    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
      "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"
      ]
    },
    "protectedSettings": {
      "commandToExecute": "[concat('sudo sh config-music.sh ',variables('musicStoreSqlName'), ' ', parameters('adminUsername'), ' ', parameters('sqlAdminPassword'))]"
    }
  }
}

如何更新代理和扩展

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

当更新可用且启用了自动更新时，只有在扩展发生更改或其他 VM 模型发生更改后，才会在 VM 上安装更新，例如：

数据磁盘
扩展
扩展标记
启动诊断容器
客体操作系统机密
VM 大小
网络配置文件

发布者会在不同时间向不同地区发布更新，因此您可能拥有位于不同地区的虚拟机（VM），这些虚拟机可能运行不同版本。

注意事项

某些更新可能需要额外的防火墙规则。有关详细信息，请参阅 Network access。

代理更新

Linux VM 代理将预配代理代码和扩展处理代码包含在一个包中。他们不能被分开。

若要通过 cloud-init 在 Azure 上进行预配，您可以禁用预配代理。

代理的受支持版本可以使用自动更新。唯一可以更新的代码是扩展处理代码，不是预配代理代码。预配代理代码是一次性运行的代码。

扩展处理代码负责：

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

安装代理时，创建父守护程序。然后，此父级会生成处理扩展的子进程。如果代理有可用的更新，会下载该更新。父进程停止子进程，升级它，然后重新启动它。如果更新出现问题，父进程将回滚到以前的子版本。

父进程无法自动更新。只有分发包才能更新父组件。

若要检查正在运行的版本，请检查 waagent：

waagent --version

输出类似于以下示例：

WALinuxAgent-2.2.45 running on <Linux Distro>
Python: 3.6.9
Goal state agent: 2.7.1.0

在前面的示例输出中，父进程或“部署包的版本”是 WALinuxAgent-2.2.45。 Goal state agent 值是自动更新版本。

强烈建议始终启用自动更新代理：AutoUpdate.Enabled=y。如果未启用自动更新，则需要继续手动更新代理。你也不会收到漏洞和安全修补程序。

插件更新

当扩展更新可用且启用自动更新后，更改为 VM 模型后，Azure Linux 代理会下载并升级该扩展。

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

    "publisher": "Microsoft.Azure.Extensions",
    "type": "CustomScript",
    "typeHandlerVersion": "2.1",
    "autoUpgradeMinorVersion": true,
    "settings": {
        "fileUris": [
        "https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-linux/scripts/config-music.sh"
        ]
    },

若要获取最新的次要版本 bug 修复，强烈建议始终在扩展部署中选择自动更新。您不能选择不安装包含安全或关键漏洞修复的紧急更新。

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

检查扩展版本

注意事项

模型与实例视图

在 Azure 中，model 视图捕获为扩展定义的配置（发布者、类型和请求的版本），而 instance 视图显示每个 VM 或规模集实例上实际运行的处理程序版本。验证实际安装内容时，请使用实例视图作为准确来源。

检查单个 VM

Azure CLI

az vm get-instance-view -g <rg> -n <vm> \
  --query "extensions[].{name:name,type:type,version:typeHandlerVersion,status:statuses[0].displayStatus}" \
  -o table

读取 VM 的 实例视图 以显示实际安装的处理程序版本和状态。

检查规模集（统一或灵活）

Azure CLI

# Scale set summary (health)
az vmss get-instance-view -g <rg> -n <vmss>

# Per-instance extension versions
az vmss list-instances -g <rg> -n <vmss> --expand instanceView \
  --query "[].{instanceId:instanceId, extVers:instanceView.extensions[].typeHandlerVersion}"

# Specific instance
az vmss vm get-instance-view -g <rg> -n <vmss> --instance-id <id>

使用规模集或每个实例级别的实例视图来验证实际处理程序版本。

返回每个实例运行时状态，包括扩展版本和状态。

如何识别扩展更新

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

Azure CLI
Azure PowerShell

您可以从虚拟机模型中查看是否使用 autoUpgradeMinorVersion 预配了扩展。若要检查，请使用 az vm show并提供资源组和 VM 名称：

az vm show --resource-group myResourceGroup --name myVM

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

  "resources": [
    {
      "autoUpgradeMinorVersion": true,
      "forceUpdateTag": null,
      "id": "/subscriptions/guid/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/myVM/extensions/customScript",

您可以从虚拟机模型中查看是否使用 AutoUpgradeMinorVersion 预配了扩展。若要检查，请使用 Get-AzVM 并提供资源组和 VM 名称：

Get-AzVM -ResourceGroupName myResourceGroup -Name myVM | Select-Object -ExpandProperty Extensions

以下示例输出显示 AutoUpgradeMinorVersion 设置为 True：

ForceUpdateTag                :
Publisher                     : Microsoft.Azure.Extensions
VirtualMachineExtensionType   : CustomScript
TypeHandlerVersion            : 2.1
AutoUpgradeMinorVersion       : True
EnableAutomaticUpgrade        :
...

确定 autoUpgradeMinorVersion 事件发生的时间

若要查看何时对扩展执行了更新，请查看 VM 上的代理日志，路径为 /var/log/waagent.log。

在下面的示例中，VM 已安装 Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9025。为 Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027 提供了修补程序。

INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Expected handler state: enabled
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Decide which version to use
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Use version: 2.3.9027
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Current handler state is: NotInstalled
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Download extension package
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Unpack extension package
INFO Event: name=Microsoft.OSTCExtensions.LinuxDiagnostic, op=Download, message=Download succeeded
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Initialize extension directory
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Update settings file: 0.settings
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9025] Disable extension.
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9025] Launch command:diagnostic.py -disable
...
INFO Event: name=Microsoft.OSTCExtensions.LinuxDiagnostic, op=Disable, message=Launch command succeeded: diagnostic.py -disable
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Update extension.
INFO [Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9027] Launch command:diagnostic.py -update
2017/08/14 20:21:57 LinuxAzureDiagnostic started to handle.

代理权限

为了执行其任务，代理需要以 root 用户身份运行。

VM 扩展故障排除

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

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

检查 Azure Linux 代理日志。查看在 /var/log/waagent.log 中预配扩展时的活动。
请查看扩展日志，了解 /var/log/azure/<extensionName>中的更多详细信息。
有关错误代码、已知问题和其他特定于扩展的信息，请查看特定于扩展的文档中的故障排除部分。
查看系统日志。检查其他操作是否对扩展产生了干扰，例如另一个需要包管理器专用访问的应用程序的长时间运行安装。

扩展失败的常见原因

扩展有 20 分钟的运行时间。（例外是自定义脚本和 Chef，有 90 分钟）。如果部署超过这个时间，则会将其标记为超时。超时的原因可以是：
- 资源有限的虚拟机。
- 在扩展尝试预配时消耗大量资源的其他 VM 配置或启动任务。
未达到最低的先决条件。某些扩展依赖于 VM 版本，例如高性能计算镜像。扩展可能有某些网络访问要求，例如需要与 Azure 存储或公共服务通信。其他示例可能包括访问包存储库、磁盘空间不足或安全限制。
软件包管理器访问是独占的。在某些情况下，由于长时间运行的虚拟机（VM）配置和扩展安装都需要对包管理器的独占访问，可能会发生冲突。

查看扩展状态

Azure CLI
Azure PowerShell

在 VM 上运行 VM 扩展后，请使用 az vm get-instance-view 来获取扩展状态：

az vm get-instance-view \
    --resource-group myResourceGroup \
    --name myVM \
    --query "instanceView.extensions"

输出类似于以下示例：

  {
    "name": "customScript",
    "statuses": [
      {
        "code": "ProvisioningState/failed/0",
        "displayStatus": "Provisioning failed",
        "level": "Error",
        "message": "Enable failed: failed to execute command: command terminated with exit status=127\n[stdout]\n\n[stderr]\n/bin/sh: 1: ech: not found\n",
        "time": null
      }
    ],
    "substatuses": null,
    "type": "Microsoft.Azure.Extensions.CustomScript",
    "typeHandlerVersion": "2.1.6"
  }

对 VM 运行 VM 扩展后，使用 Get-AzVM 并指定 -Status 开关参数以返回扩展状态：

Get-AzVM -ResourceGroupName myResourceGroup -Name myVM -Status |
Select-Object -ExpandProperty Extensions |
Select-Object -ExpandProperty Statuses

输出类似于以下示例：

Code          : ProvisioningState/failed/0
Level         : Error
DisplayStatus : Provisioning failed
Message       : Enable failed: failed to execute command: command terminated with exit status=127
                [stdout]

                [stderr]
                /bin/sh: 1: ./hello.sh: not found

Time          :

还可以在Azure portal中找到扩展执行状态。选择 VM，选择 “扩展”，然后选择所需的扩展。

重新运行 VM 扩展

在某些情况下，必须重新运行 VM 扩展。若要重新运行扩展，请将其删除，然后使用所选的执行方法重新运行该扩展。

Azure CLI
Azure PowerShell

若要删除扩展，请使用 az vm extension delete：

az vm extension delete \
    --resource-group myResourceGroup \
    --vm-name myVM \
    --name customScript

若要删除扩展，请使用 Remove-AzVMExtension：

Remove-AzVMExtension -ResourceGroupName myResourceGroup -VMName myVM -Name customScript

若要强制命令在不要求用户确认的情况下运行，请指定 -Force switch 参数。

还可以删除Azure portal中的扩展：

选择 VM。
选择扩展。
选择该扩展。
选择“卸载”。

常见虚拟机扩展参考

扩展名称	说明
适用于 Linux 的自定义脚本扩展	针对Azure VM 运行脚本。
VMAccess 扩展	重新获得对 Azure VM 的访问权限。还可以使用它来管理用户和凭据。

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

Last updated on 2026-03-10

Compartir a través de

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

用例和示例

先决条件

Azure Linux 代理

网络访问

了解虚拟机扩展

运行 VM 扩展

Azure CLI

Azure PowerShell

Azure portal

Azure Resource Manager模板

帮助保护 VM 扩展数据

如何更新代理和扩展

代理更新

插件更新

检查扩展版本

如何识别扩展更新

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

确定 autoUpgradeMinorVersion 事件发生的时间

代理权限

VM 扩展故障排除

扩展失败的常见原因

查看扩展状态

重新运行 VM 扩展

常见虚拟机扩展参考

相关内容

Recursos adicionales