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

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 VM exigir instalação de software, proteção antivírus ou a capacidade de executar um script dentro dela, você poderá usar uma extensão de VM.

Você pode executar extensões de VM do Azure usando a CLI do Azure, o Azure PowerShell, os modelos do ARM (Azure Resource Manager) 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, pré-requisitos para usá-las e orientação sobre como detectá-las, gerenciá-las e removê-las. Este artigo fornece informações gerais porque muitas extensões de VM estão disponíveis. Cada um tem uma configuração potencialmente exclusiva 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. Os exemplos incluem:

• Configure o monitoramento de uma VM usando a extensão do Microsoft Monitoring Agent VM.
• Configure o monitoramento da infraestrutura do Azure com a extensão Chef ou Datadog.

Além das extensões específicas do processo, uma extensão de Script Personalizado está disponível para VMs Windows e Linux. A extensão de Script Personalizado para Linux permite a execução de qualquer script Bash 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

Agente Linux do Azure:

Para lidar com a extensão na VM, você deve ter o Agente Linux do Azure instalado. Algumas extensões individuais têm pré-requisitos, como acesso a recursos ou dependências.

O agente de Linux do Azure gerencia a interação entre uma VM do Azure e o controlador de malha do 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 da VM.

O agente Linux do Azure está pré-instalado em imagens do Azure Marketplace. Você também pode instalá-lo 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.

Se você usar uma versão com suporte do agente Linux 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 para redirecionar a comunicação para o controlador de malha do Azure para comunicações do agente. Se estiver usando uma versão sem suporte do agente, será necessário permitir o acesso de saída para o Armazenamento do Microsoft Azure nessa região por meio da VM.

Você pode usar agentes apenas para baixar pacotes de extensão e relatar status. Por exemplo, se uma instalação de extensão precisar baixar um script do GitHub (extensão de script personalizado) ou precisar de acesso ao Armazenamento do Azure (Azure Backup), você precisará abrir mais portas de firewall ou grupo de segurança de rede (NSG). Extensões diferentes têm requisitos diferentes porque são aplicativos. Para extensões que exigem acesso ao Armazenamento do Microsoft Azure, você poderá permitir o acesso usando marcas de serviço do NSG.

Para redirecionar as solicitações de tráfego do agente, o Agente Linux do Azure tem suporte de servidor proxy. Esse suporte ao servidor proxy não aplica extensões. É necessário configurar cada extensão individual para trabalhar com um proxy.

Descobrir extensões de VM

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

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

Executar extensões de VM

Extensões de VM do Azure executadas em VMs existentes. Essa funcionalidade é ú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.

Você pode usar os métodos a seguir para executar uma extensão em uma VM existente.

CLI do Azure

Você pode executar as extensões da VM do Azure em uma VM existente usando o comando az vm extension set. O exemplo a seguir executa a extensão Custom Script em uma VM nomeada myVM em um grupo de recursos nomeado myResourceGroup. Substitua o nome do grupo de recursos de exemplo, o nome da VM e o script a serem executados https:\//raw.githubusercontent.com/me/project/hello.sh com suas próprias informações.

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

Quando a extensão executa corretamente, a saída é semelhante ao exemplo a seguir:

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

Azure PowerShell

Você pode executar as extensões da VM do Azure em uma VM existente usando o comando Set-AzVMExtension. O exemplo a seguir executa a extensão Custom Script em uma VM nomeada myVM em um grupo de recursos nomeado myResourceGroup. Substitua o nome do grupo de recursos de exemplo, o nome da VM e o script a serem executados https:\//raw.githubusercontent.com/me/project/hello.sh com suas próprias informações.

$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

Quando a extensão executa corretamente, a saída é semelhante ao exemplo a seguir:

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

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

A imagem a seguir mostra a instalação da extensão script personalizado para Linux 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.

Por exemplo, o JSON a seguir é obtido de um modelo completo do ARM que implanta um conjunto de VMs com balanceamento de carga e um banco de dados SQL do Azure. Em seguida, ele 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/', 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'))]"
    }
    }
}

Para obter mais informações sobre como criar modelos do ARM, consulte máquinas virtuais em um modelo do Azure Resource Manager.

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. Cada extensão é detalhada na documentação específica da extensão.

O exemplo a seguir mostra uma instância da extensão de Script Personalizado para Linux. 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/', 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'))]"
    }
  }
}

A movimentação da commandToExecutepropriedade 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/', 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'))]"
    }
  }
}

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 há uma alteração em uma extensão ou depois de outras alterações de modelo de VM, como:

• Discos de dados
• Extensões
• Tags 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 regiões em vários momentos, para que você possa ter VMs em regiões diferentes em diferentes versões.

Atualizações de agentes

O Agente de VM Linux contém o código de Agente de Provisionamento e o código de manipulação de extensão em um pacote. Eles não podem ser separados.

É possível desabilitar o Agente de Provisionamento quando quiser provisionar no Azure utilizando o cloud-init.

Versões com suporte para Agentes podem usar atualizações automáticas. O único código que pode ser atualizado é o código de manipulação de extensão, não o código de Agente de Provisionamento. O Código de Agente de Provisionamento é um código de execução única.

O código de manipulação de extensão é responsável por:

• Comunicação com os recursos de infraestrutura do Microsoft Azure.
• Tratamento das operações de extensão de VM, como instalações, status de relatório, atualização das 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 para o código de tratamento de extensão.

Quando o agente é instalado, um daemon pai é criado. Esse pai gera um processo filho que lida com extensões. Se uma atualização estiver disponível para o agente, ela será baixada. O pai interrompe o processo filho, atualiza-o e, em seguida, reinicia-o. Se ocorrer um problema com a atualização, o processo pai reverterá para a versão anterior do filho.

O processo pai não pode ser atualizado automaticamente. Somente um pacote de distribuição pode atualizar o pai.

Para verificar qual versão você está executando, verifique waagent:

waagent --version

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

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

Na saída do exemplo anterior, o pai (ou a versão de pacote implantado) é WALinuxAgent-2.2.45. O valor Goal state agent é a versão de atualização automática.

É altamente recomendável sempre ter uma atualização automática para o agente, AutoUpdate.Enabled=y. Se você não habilitar a atualização automática, precisará continuar atualizando manualmente o agente. Você também não recebe correções de bugs e de segurança.

Atualizações de extensão

Quando uma atualização de extensão está disponível e as atualizações automáticas estão habilitadas, depois que ocorre uma alteração no modelo de VM, o agente do Linux 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 "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"
        ]
    },

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 az vm extension set ou Set-AzVMExtension e especifique a versão de destino.

Como identificar as atualizações de extensão

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

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

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

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

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

Identificar quando ocorreu um evento autoUpgradeMinorVersion

Para ver quando ocorreu uma atualização na extensão, revise os logs do agente na VM em /var/log/waagent.log.

No exemplo a seguir, a VM tinha Microsoft.OSTCExtensions.LinuxDiagnostic-2.3.9025 instalada. Um hotfix estava disponível para 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.

Permissões de agente

Para executar as tarefas, o agente precisa executar como raiz.

Solucionar problemas de extensões de VM

As extensões de VM podem ter etapas de solução de problemas específicas. Por exemplo, ao usar a extensão de script personalizado, é possível encontrar detalhes da execução do script localmente na VM em que a extensão foi executada.

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

• Verifique o log do Agente linux do Azure. Examine a atividade quando sua extensão estava sendo provisionada em /var/log/waagent.log.
• Verifique os logs de extensão para obter mais detalhes em /var/log/azure/<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 outras operações interferiram na extensão, como uma instalação de execução prolongada de outro aplicativo que exigia acesso exclusivo ao gerenciador de pacotes.

Motivos comuns para falhas na extensão

• As extensões têm 20 minutos para ser executadas. (As exceções são Script Personalizado e Chef, que têm 90 minutos.) Se a implantação exceder esse tempo, será marcada como tempo limite. A causa de um timeout pode ser:

  • VMs de baixo recurso.
  • Outras configurações de VM ou tarefas de inicialização que consomem 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 de versão da VM, como imagens de computação de alto desempenho. 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

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

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          :

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 selecione a extensão desejada.

Executar novamente uma extensão de VM

Pode haver casos em que uma extensão de VM deve ser executada novamente. Para executar novamente uma extensão, remova-a e execute novamente a extensão com um método de execução de sua escolha.

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

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

Também é possível remover uma extensão no portal do Microsoft Azure:

1. Selecione uma VM.
2. Selecione Extensões.
3. Selecione a extensão.
4. Selecionar Desinstalar.

Referência à extensão VM comum

Conteúdo relacionado

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