Recursos e extensões da máquina virtual para Windows

As extensões da máquina virtual (VM) do Azure são pequenos aplicativos que fornecem tarefas de configuração e automação pós-implantação nas VMs do Azure. Por exemplo, se uma máquina virtual exigir a instalação de software, proteção antivírus ou a capacidade de executar um script dentro da VM, você poderá usar uma extensão de VM.

Você pode executar extensões de VM do Azure usando os modelos da CLI do Azure, PowerShell, Azure Resource Manager (ARM) e o portal do Azure. É possível agrupar as extensões com uma nova implantação de VM ou executá-las em qualquer sistema existente.

Este artigo fornece uma visão geral das extensões de VM do Azure, incluindo pré-requisitos e orientações sobre como detectar, gerenciar e remover extensões. Este artigo fornece informações gerais porque existem muitas extensões de VM disponíveis. Cada extensão tem uma configuração potencialmente única e sua própria documentação.

Casos de uso e exemplos

Cada extensão de VM do Azure tem um caso de uso específico. Estes são alguns exemplos:

• Aplique as configurações de estado desejado (DSC) do PowerShell a uma VM usando a extensão de DSC para Windows.

• Configure o monitoramento de uma VM usando o agente do Azure Monitor e os insights da VM.

• Configure uma VM do Azure ao usar o Chef.

• Configure o monitoramento da infraestrutura do Azure usando a extensão Datadog.

Além de extensões específicas do processo, uma Extensão de Script Personalizado está disponível para máquinas virtuais Windows e Linux. A Extensão de Script Personalizado do Windows permite que qualquer script do PowerShell seja executado em uma VM. Scripts personalizados são úteis para a criação de implantações do Azure que exigem uma configuração que vai além da capacidade das ferramentas nativas do Azure.

Pré-requisitos

Examine os seguintes pré-requisitos para trabalhar com extensões de VM do Azure.

Agente de VM do Azure

Para lidar com extensões na VM, você precisa do Agente de Máquina Virtual do Azure para Windows instalado. Esse agente também é conhecido como Agente de VM do Azure ou Agente Convidado do Windows. Ao se preparar para instalar extensões, lembre-se de que algumas extensões têm pré-requisitos individuais, como acesso a recursos ou dependências.

O agente de VM do Azure gerencia a interação entre uma VM do Azure e os recursos de infraestrutura do Microsoft Azure. O agente é responsável por muitos aspectos funcionais de implantação e gerenciamento de VMs do Azure, incluindo a execução de extensões de VM.

O Agente de VM do Azure é pré-instalado em imagens do Microsoft Azure Marketplace. O agente também pode ser instalado manualmente em sistemas operacionais com suporte.

O agente é executado em vários sistemas operacionais. No entanto, a estrutura de extensões tem um limite de sistemas operacionais usados pelas extensões. Algumas extensões não têm suporte em todos os sistemas operacionais e podem emitir o código de erro 51 ("SO sem suporte"). Consulte a documentação da extensão individual sobre a capacidade de suporte.

Acesso de rede

Os pacotes de extensão são baixados do repositório de extensões de Armazenamento do Microsoft Azure. Os uploads de status de extensão são postados no Armazenamento do Microsoft Azure.

Ao usar uma versão com suporte do agente de VM do Azure, não será necessário permitir o acesso ao Armazenamento do Microsoft Azure na região da VM. Você pode usar o Agente de VM para redirecionar a comunicação para o controlador de malha do Azure para comunicações do agente (por meio do recurso HostGAPlugin através do canal privilegiado no endereço IP privado 168.63.129.16). Se você estiver em uma versão sem suporte do Agente de VM, será necessário permitir o acesso de saída ao Armazenamento do Microsoft Azure nessa região da VM.

Importante

Se você bloquear o acesso ao endereço IP 168.63.129.16 usando o firewall convidado ou por meio de um proxy, as extensões falharão. A falha ocorre mesmo se você usar uma versão com suporte do Agente de VM ou configurar o acesso de saída. As portas 80 e 32526 são necessárias.

Os agentes só podem ser usados para baixar pacotes de extensão e relatar o status. Por exemplo, se uma instalação de extensão precisar baixar um script do GitHub (Extensão de Script Personalizado) ou exigir acesso ao Armazenamento do Microsoft Azure (Backup do Azure), será necessário abrir outras portas de firewall ou grupo de segurança de rede (NSG). Diferentes extensões possuem requisitos diferentes, pois são aplicativos independentes. Para extensões que exigem acesso ao Armazenamento do Microsoft Azure ou ao Microsoft Entra ID, é possível permitir o acesso usando marcas de serviço do NSG do Azure.

O Agente de VM do Azure não dá suporte ao servidor proxy para habilitar o redirecionamento de solicitações de tráfego do agente. O Agente de VM depende de seu proxy personalizado (se você tiver um) para acessar recursos na Internet ou no host por meio do endereço IP 168.63.129.16.

Descobrir extensões de VM

Muitas extensões de VM diferentes estão disponíveis para uso com as VMs do Azure. Para exibir uma lista completa, use o cmdlet do PowerShell Get-AzVMExtensionImage.

O comando a seguir lista todas as extensões de VM disponíveis no local da região Oeste dos EUA:

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

Esse comando fornece uma saída semelhante ao exemplo a seguir:

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

Executar extensões de VM

As extensões da VM do Azure podem ser executadas em VMs existentes, o que é útil quando você precisa fazer alterações de configuração ou recuperar a conectividade em uma VM já implantada. Também é possível agrupar as extensões de VM com implantações de modelo do ARM. Usando extensões com modelos do ARM, é possível implantar e configurar VMs do Azure sem intervenção pós-implantação.

Use os métodos a seguir para executar uma extensão em uma VM existente.

Observação

Alguns dos exemplos a seguir usam valores de parâmetro "<placeholder>" nos comandos. Antes de executar cada comando, certifique-se de substituir todos os valores "<placeholder>" por valores específicos para sua configuração.

PowerShell

Há vários comandos do PowerShell para a execução de extensões individuais. Para exibir uma lista, use o comando Get-Command e filtre por Extensão:

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

Esse comando fornece uma saída semelhante ao exemplo a seguir:

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

O exemplo a seguir usa a Extensão de Script Personalizado para baixar um script de um repositório do GitHub na máquina virtual de destino e, em seguida, executar o script.

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>"

O exemplo a seguir usa a extensão VMAccess para redefinir a senha administrativa de uma VM do Windows para uma senha temporária. Depois de executar esse código, é necessário redefinir a senha no primeiro logon.

$cred=Get-Credential

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

Usar o comando Set-AzVMExtension para iniciar qualquer extensão de VM.

Portal do Azure

Aplique extensões de VM a uma VM existente por meio do portal do Microsoft Azure. Selecione a VM no portal, selecione Extensões + Aplicativos e, em seguida, selecione + Adicionar. Escolha a extensão que deseja na lista de extensões disponíveis e siga as instruções no assistente.

O exemplo a seguir mostra a instalação da extensão Microsoft Antimalware no portal do Azure:

Modelos do Azure Resource Manager

Adicione extensões de VM a um modelo de ARM e execute-as com a implantação do modelo. Ao implantar uma extensão com um modelo, você pode criar implantações do Azure totalmente configuradas.

O exemplo de JSON a seguir é de um modelo do ARM que implanta um conjunto de VMs com balanceamento de carga e um banco de dados SQL do Azure e, depois, instala um aplicativo .NET Core em cada VM. A extensão da VM se encarrega da instalação do software.

{
    "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')]"
    }
    }
}

Para obter mais informações sobre como criar modelos do ARM, confira Máquinas virtuais em um modelo do ARM.

Proteja dados de extensão da VM

Ao executar uma extensão de VM, talvez seja necessário incluir informações confidenciais, como credenciais, nomes de conta de armazenamento e chaves de acesso. Muitas extensões de VM incluem uma configuração protegida que criptografa dados e os descriptografa somente dentro da VM de destino. Cada extensão tem um esquema de configuração protegido específico e cada esquema é detalhado na documentação específica da extensão.

O exemplo JSON a seguir mostra uma instância da Extensão de Script Personalizado para Windows. O comando a ser executado inclui um conjunto de credenciais. Neste exemplo, o comando a ser executado não está criptografado.

{
    "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')]"
    }
    }
}

A movimentação da propriedade commandToExecute para a configuração protected ajuda a proteger a cadeia de caracteres de execução, conforme mostrado no exemplo a seguir:

{
    "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')]"
    }
    }
}

Em uma VM IaaS (infraestrutura como serviço) do Azure que usa extensões, no console de certificados, é possível ver certificados que têm o assunto Gerador de Certificados CRP Azure do Windows. Em uma VM Front-End RedDog (RDFE), esses certificados têm o nome da Gerenciamento de Serviços Azure do Windows para Extensões.

Esses certificados protegem a comunicação entre a VM e o host durante a transferência de configurações protegidas (senha, outras credenciais) usadas pelas extensões. O controlador de malha do Azure cria os certificados e os passa para o Agente de VM do Azure. Se a VM é iniciada e parada diariamente, os recursos de infraestrutura do Microsoft Azure poderão criar um novo certificado. O certificado é armazenado no repositório de certificados pessoal do computador. Esses certificados podem ser excluídos. O agente da VM do Azure recria os certificados, se necessário.

Como os agentes e as extensões são atualizados

Os agentes e as extensões compartilham o mesmo mecanismo de atualização automática.

Quando uma atualização está disponível e as atualizações automáticas estão habilitadas, a atualização é instalada na VM somente depois que uma extensão ou outro modelo de VM é alterado. As alterações podem incluir:

• Discos de dados
• Extensões
• Marcas de extensão
• Contêiner de diagnóstico de inicialização
• Segredos do sistema operacional convidado
• Tamanho da VM
• Perfil de rede

Os editores disponibilizam atualizações para as regiões em vários momentos. É possível que você tenha VMs em diferentes regiões e em outras versões.

Observação

Algumas atualizações podem exigir regras de firewall adicionais. Para obter mais informações, confira Acesso à rede.

Listar extensões implantadas em uma VM

Você pode usar o seguinte comando para listar as extensões implantadas em uma VM:

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

Esse comando produz uma saída semelhante ao seguinte exemplo:

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

Atualizações de agentes

O Agente de VM do Azure contém apenas o código de manipulação de extensão. O código de provisionamento do Windows é separado. Desinstale o Agente de VM do Azure. Não é possível desabilitar a atualização automática do Agente de VM do Azure.

O código de manipulação de extensão é responsável pelas seguintes tarefas:

• Comunicar-se com a malha do Azure.
• Lide com as operações de extensão da VM, como instalações, relatórios de status, atualização de extensões individuais e remoção de extensões. As atualizações contêm correções de segurança, correções de bug e aprimoramentos do código de manipulação de extensão.

Para verificar qual versão você está executando, confira Detectar o Agente de VM do Azure.

Atualizações de extensão

Quando uma atualização de extensão está disponível e as atualizações automáticas estão habilitadas, se um modelo de VM for alterado, o Agente de VM do Azure baixa e atualiza a extensão.

Atualizações automáticas de extensão são secundárias ou hotfix. É possível aceitar ou recusar atualizações de extensões secundárias ao provisionar a extensão. O exemplo a seguir mostra como atualizar automaticamente versões secundárias em um modelo do ARM usando o "autoUpgradeMinorVersion": true, parâmetro:

    "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"
        ]
    },

Para obter as correções de bug de versão secundária mais recentes, é altamente recomendável selecionar sempre a atualização automática nas implantações de extensão. Não é possível recusar as atualizações de hotfix que realizam correções de bug essenciais ou de segurança.

Se você desabilitar as atualizações automáticas ou precisar atualizar uma versão principal, use o comando Set-AzVMExtension e especifique a versão de destino.

Como identificar as atualizações de extensão

Há algumas maneiras de identificar as atualizações de uma extensão.

Identificar se a extensão foi definida com autoUpgradeMinorVersion em uma VM

Você pode exibir o modelo da VM para determinar se a extensão é provisionada com o parâmetro autoUpgradeMinorVersion. Para verificar o modelo da VM, use o comando Get-AzVm e forneça o grupo de recursos e o nome da VM da seguinte forma:

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

A saída de exemplo a seguir mostra que o parâmetro autoUpgradeMinorVersion está definido como true:

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

Identificar quando ocorre um evento autoUpgradeMinorVersion

Para ver quando ocorreu uma atualização na extensão, revise os logs do agente na VM em C:\WindowsAzure\Logs\WaAppAgent.log.

O exemplo a seguir mostra a VM com a versão Microsoft.Compute.CustomScriptExtension1.8 instalada e um hotfix disponível para a versão 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'

Permissões de agente

Para executar suas tarefas, o Agente de VM do Azure precisa ser executado como Sistema Local.

Solucionar problemas de extensões de VM

As extensões de VM podem ter etapas de solução de problemas específicas. Por exemplo, quando você usa a Extensão de Script Personalizado, pode encontrar detalhes de execução do script localmente na VM onde a extensão é executada.

As seguintes ações de solução de problemas aplicam-se a todas as extensões de VM:

• Para verificar o Log do Agente Convidado de VM do Azure, observe a atividade quando a extensão estiver sendo provisionada em C:\WindowsAzure\Logs\WaAppAgent.log.

• Verifique os logs de extensão para obter mais detalhes em C:\WindowsAzure\Logs\Plugins<extensionName>.

• Verifique as seções de solução de problemas na documentação específica da extensão para obter códigos de erro, problemas conhecidos e outras informações específicas da extensão.

• Examine os logs do sistema. Verifique se há outras operações que podem ter interferido na extensão, como uma instalação de execução longa de outro aplicativo que exigia acesso exclusivo ao gerenciador de pacotes.

• Em uma VM, se houver uma extensão existente com um estado de provisionamento com falha, qualquer outra extensão nova falhará na instalação.

Motivos comuns para falhas na extensão

Aqui estão alguns motivos comuns pelos quais uma extensão pode falhar:

• As extensões têm 20 minutos para ser executadas. (As exceções são Script Personalizado, Chef e DSC, que têm 90 minutos.) Se a implantação exceder esse tempo, será marcada como tempo limite. A causa desse problema pode ser VMs com poucos recursos ou outras configurações de VM ou tarefas de inicialização consumindo grandes quantidades de recursos enquanto a extensão está tentando provisionar.

• Os pré-requisitos mínimos não foram atendidos. Algumas extensões têm dependências em SKUs da VM, como imagens HPC. As extensões podem exigir certos requisitos de acesso à rede, como comunicação com o Armazenamento do Microsoft Azure ou serviços públicos. Outros exemplos podem ser o acesso a repositórios de pacote, ficando sem espaço em disco, ou restrições de segurança.

• O acesso ao gerenciador de pacotes é exclusivo. Em alguns casos, uma configuração de VM de execução longa e uma instalação de extensão podem entrar em conflito porque ambas precisam de acesso exclusivo ao gerenciador de pacotes.

Exibir o status da extensão

Depois que uma extensão de VM é executada em uma VM, use o comando Get-AzVM para retornar o status da extensão. O resultado Substatuses[0] mostra que o provisionamento da extensão foi bem-sucedido, o que significa que foi implantado com êxito na VM. Se você exibir o resultado Substatuses[1], a execução da extensão dentro da VM falhou.

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

A saída deverá ser semelhante ao seguinte exemplo:

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

Também é possível encontrar o status de execução da extensão no portal do Microsoft Azure. Selecione a VM, selecione Extensões e, em seguida, selecione a extensão desejada.

Executar novamente uma extensão de VM

Em determinados casos, pode ser necessário executar novamente uma extensão de VM. Você pode executar novamente uma extensão removendo-a e, em seguida, executando novamente a extensão com um método de execução de sua escolha. Para remover uma extensão, use o comando Remove-AzVMExtension da seguinte maneira:

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

Também é possível remover uma extensão no portal do Azure. Selecione uma VM, selecione Extensões e selecione a extensão desejada. Selecione Desinstalar.

Referência à extensão VM comum

A tabela a seguir fornece algumas referências comuns para extensões de VM.

Nome da extensão	Descrição
Extensão de script personalizado para o Windows	Executar scripts em uma máquina virtual do Azure.
Extensão DSC para Windows	Aplique as configurações de estado desejado do PowerShell a uma máquina virtual.
Extensão de Diagnóstico do Azure	Gerenciar Diagnóstico do Microsoft Azure.
Extensão do VMAccess	Gerenciar usuários e credenciais.

Próximas etapas

Para obter mais informações sobre extensões de VM, consulte Recursos e extensões de máquina virtual do Azure.