Extensão de Script Personalizado para o Windows

Artigo
02/01/2024

A Extensão de Script Personalizada baixa e executa scripts em máquinas virtuais (VMs) do Azure. Use esta extensão para configuração pós-implantação, instalação de software ou qualquer outra tarefa de configuração ou gerenciamento. Você pode baixar scripts do Armazenamento do Azure ou do GitHub, ou fornecê-los ao portal do Azure no tempo de execução da extensão.

A Extensão de Script Personalizada integra-se com modelos do Azure Resource Manager. Você também pode executá-lo usando a CLI do Azure, o Azure PowerShell, o portal do Azure ou a API REST das Máquinas Virtuais do Azure.

Este artigo descreve como usar a Extensão de Script Personalizada usando o módulo do Azure PowerShell e os modelos do Azure Resource Manager. Ele também fornece etapas de solução de problemas para sistemas Windows.

Pré-requisitos

Nota

Não use a extensão de script personalizado para executar Update-AzVM com a mesma VM como seu parâmetro. A prorrogação vai esperar por si só.

Sistemas operativos Windows suportados

SO Windows	x64
Windows 10	Suportado
Windows 11	Suportado
Windows Server 2008 SP2	Suportado
Windows Server 2008 R2	Suportado
2012 Windows Server	Suportado
Windows Server 2012 R2	Suportado
Windows Server 2016	Suportado
Núcleo do Windows Server 2016	Suportado
Windows Server 2019	Suportado
Núcleo do Windows Server 2019	Suportado
Windows Server 2022	Suportado
Núcleo do Windows Server 2022	Suportado

Localização do script

Pode definir a extensão para utilizar as suas credenciais de Armazenamento de Blobs do Azure de modo a que possa aceder ao Armazenamento de Blobs do Azure. A localização do script pode ser em qualquer parte, desde que a VM possa encaminhar para esse ponto final, por exemplo, GitHub ou um servidor de ficheiros interno.

Ligação à Internet

Para transferir um script externamente, tal como do GitHub ou do Armazenamento do Azure, tem de abrir outras portas de firewall ou do grupo de segurança de rede (NSG). Por exemplo, se o script estiver localizado no Armazenamento do Azure, poderá permitir o acesso utilizando etiquetas de serviço do Azure NSG para Armazenamento.

A Extensão de Script Personalizada não tem nenhuma maneira de ignorar a validação do certificado. Se você estiver baixando de um local seguro com, por exemplo, um certificado autoassinado, poderá receber erros como O certificado remoto é inválido de acordo com o procedimento de validação. Verifique se o certificado está instalado corretamente no armazenamento de Autoridades de Certificação Raiz Confiáveis na VM.

Se o seu script estiver num servidor local, poderá ainda ter de abrir outras portas de firewall ou do NSG.

Sugestões

A saída está limitada aos últimos 4096 bytes.
Escapar corretamente dos caracteres ajudará a garantir que as cadeias de caracteres sejam analisadas corretamente. Por exemplo, você sempre precisa de duas barras invertidas para escapar de uma única barra invertida literal ao lidar com caminhos de arquivo. Exemplo: {"commandToExecute": "C:\\Windows\\System32\\systeminfo.exe >> D:\\test.txt"}
A taxa de falha mais alta desta extensão deve-se a erros de sintaxe no script. Verifique se o script é executado sem erros. Coloque mais registos no script para facilitar a localização de falhas.
Escreva scripts que sejam idempotentes. de modo a que a sua execução mais de uma vez acidentalmente, não cause alterações no sistema.
Certifique-se de que os scripts não requerem dados do utilizador quando são executados.
O script pode ser executado durante 90 minutos. Se a execução for mais longa resulta numa falha do aprovisionamento da extensão.
Não coloque reinícios no script. Esta ação causa problemas noutras extensões que estão a ser instaladas e a extensão não continua após o reinício.
Se tiver um script que possa causa um reinício antes da instalação das aplicações e executa scripts, agende o reinício utilizando uma Tarefa Agendada do Windows ou com ferramentas como as extensões DSC, Chef ou Puppet.
Não execute um script que cause uma paragem ou atualização do agente de VM. Isto poderá deixar a extensão num estado de transição e resultar num tempo limite excedido.
A extensão executa um script apenas uma vez. Se quiser executar um script em cada arranque, utilize a extensão para criar uma Tarefa Agendada do Windows.
Se quiser agendar quando é que um script é executado, utilize a extensão para criar uma Tarefa Agendada do Windows.
Quando o script estiver em execução, verá apenas um estado de extensão em transição no portal ou na CLI do Azure. Se quiser atualizações de estado mais frequentes para um script em execução, crie a sua própria solução.
A Extensão de Script Personalizado não suporta servidores proxy de forma nativa. No entanto, pode utilizar uma ferramenta de transferência de ficheiros, como Invoke-WebRequest, que suporte servidores proxy no script.
Tenha em atenção as localizações de diretório não predefinidas de que os scripts ou comandos poderão depender. Tenha uma lógica para lidar com esta situação.
A Extensão de Script Personalizado é executada na conta LocalSystem.
Se planear utilizar as propriedades storageAccountName e storageAccountKey , estas propriedades devem ser colocadas no protectedSettings.
Apenas pode ter uma versão de uma extensão aplicada na VM. Para executar um segundo script personalizado, pode atualizar a extensão existente com uma nova configuração. Em alternativa, pode remover a extensão de script personalizado e voltar a aplicá-la com o script atualizado

Esquema de extensão

A configuração da Extensão de Script Personalizada especifica coisas como o local do script e o comando a ser executado. Você pode armazenar essa configuração em arquivos de configuração, especificá-la na linha de comando ou especificá-la em um modelo do Azure Resource Manager.

Você pode armazenar dados confidenciais em uma configuração protegida, que é criptografada e descriptografada apenas dentro da VM. A configuração protegida é útil quando o comando de execução inclui segredos como uma senha ou uma referência de arquivo de assinatura de acesso compartilhado (SAS). Eis um exemplo:

{
    "apiVersion": "2018-06-01",
    "type": "Microsoft.Compute/virtualMachines/extensions",
    "name": "virtualMachineName/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.10",
        "autoUpgradeMinorVersion": true,
        "settings": {
            "timestamp":123456789
        },
        "protectedSettings": {
            "commandToExecute": "myExecutionCommand",
            "storageAccountName": "myStorageAccountName",
            "storageAccountKey": "myStorageAccountKey",
            "managedIdentity" : {},
            "fileUris": [
                "script location"
            ]
        }
    }
}

Nota

A managedIdentity propriedade não deve ser usada em conjunto com a storageAccountNamestorageAccountKey propriedade.

Apenas uma versão de uma extensão pode ser instalada em uma VM de cada vez. A especificação de um script personalizado duas vezes no mesmo modelo do Azure Resource Manager para a mesma VM falha.

Você pode usar esse esquema dentro do recurso VM ou como um recurso autônomo. Se essa extensão for usada como um recurso autônomo no modelo do Azure Resource Manager, o nome do recurso deverá estar no formato virtualMachineName/extensionName.

Valores de propriedade

Nome	Valor ou exemplo	Tipo de dados
apiVersion	`2015-06-15`	data
editora	`Microsoft.Compute`	string
tipo	`CustomScriptExtension`	string
typeHandlerVersion	`1.10`	número inteiro
fileUris	`https://raw.githubusercontent.com/Microsoft/dotnet-core-sample-templates/master/dotnet-core-music-windows/scripts/configure-music-app.ps1`	matriz
carimbo de data/hora	`123456789`	Inteiro de 32 bits
commandToExecute	`powershell -ExecutionPolicy Unrestricted -File configure-music-app.ps1`	string
storageAccountName	`examplestorageacct`	string
storageAccountKey	`TmJK/1N3AbAZ3q/+hOXoi/l73zOqsaxXDhqa9Y83/v5UpXQp2DQIBuv2Tifp60cE/OaHsJZmQZ7teQfczQj8hg==`	string
managedIdentity	`{ }` ou `{ "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }` ou `{ "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }`	Objeto JSON

Nota

Esses nomes de propriedade diferenciam maiúsculas de minúsculas. Para evitar problemas de implantação, use os nomes conforme mostrado aqui.

Detalhes do valor da propriedade

Property	Opcional ou obrigatório	Detalhes
fileUris	Opcional	URLs para arquivos a serem baixados. Se as URLs forem confidenciais, por exemplo, se contiverem chaves, esse campo deverá ser especificado em `protectedSettings`.
commandToExecute	Obrigatório	O script de ponto de entrada a ser executado. Use essa propriedade se o comando contiver segredos, como senhas, ou se os URIs do arquivo forem confidenciais.
carimbo de data/hora	Opcional	Altere esse valor apenas para disparar uma nova execução do script. Qualquer valor inteiro é aceitável, desde que seja diferente do valor anterior.
storageAccountName	Opcional	O nome da conta de armazenamento. Se você especificar credenciais de armazenamento, todos os `fileUris` valores deverão ser URLs para blobs do Azure.
storageAccountKey	Opcional	A chave de acesso da conta de armazenamento.
managedIdentity	Opcional	A identidade gerenciada para baixar arquivos. Os valores válidos são `clientId` (opcional, string), que é a ID do cliente da identidade gerenciada, e `objectId` (optional, string), que é a ID do objeto da identidade gerenciada.

As configurações públicas são enviadas em texto não criptografado para a VM onde o script é executado. As configurações protegidas são criptografadas por meio de uma chave conhecida apenas pelo Azure e pela VM. As configurações são salvas na VM como foram enviadas. Ou seja, se as configurações foram criptografadas, elas são salvas criptografadas na VM. O certificado usado para descriptografar os valores criptografados é armazenado na VM. O certificado também é usado para descriptografar configurações, se necessário, em tempo de execução.

O uso de configurações públicas pode ser útil para depuração, mas recomendamos que você use configurações protegidas.

Você pode definir os seguintes valores em configurações públicas ou protegidas. A extensão rejeita qualquer configuração em que esses valores sejam definidos em configurações públicas e protegidas.

commandToExecute
fileUris

Propriedade: managedIdentity

Nota

Essa propriedade deve ser especificada somente em configurações protegidas.

A Extensão de Script Personalizada, versão 1.10 e posterior, oferece suporte a identidades gerenciadas para download de arquivos de URLs fornecidas na fileUris configuração. A propriedade permite que a Extensão de Script Personalizada acesse blobs ou contêineres privados do Armazenamento do Azure sem que o usuário precise passar segredos como tokens SAS ou chaves de conta de armazenamento.

Para usar esse recurso, adicione uma identidade atribuída pelo sistema ou pelo usuário à VM ou ao Conjunto de Escala de Máquina Virtual onde a Extensão de Script Personalizada é executada. Em seguida, conceda à identidade gerenciada acesso ao contêiner ou blob de Armazenamento do Azure.

Para usar a identidade atribuída pelo sistema na VM de destino ou no Conjunto de Escala da Máquina Virtual, defina managedidentity como um objeto JSON vazio.

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : {}
}

Para usar a identidade atribuída pelo usuário na VM de destino ou no Conjunto de Dimensionamento de Máquina Virtual, configure managedidentity com a ID do cliente ou a ID do objeto da identidade gerenciada.

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : { "clientId": "31b403aa-c364-4240-a7ff-d85fb6cd7232" }
}

{
  "fileUris": ["https://mystorage.blob.core.windows.net/privatecontainer/script1.ps1"],
  "commandToExecute": "powershell.exe script1.ps1",
  "managedIdentity" : { "objectId": "12dd289c-0583-46e5-b9b4-115d5c19ef4b" }
}

Nota

A managedIdentity propriedade não deve ser usada em conjunto com a storageAccountNamestorageAccountKey propriedade.

Implementação de modelos

Você pode implantar extensões de VM do Azure usando modelos do Azure Resource Manager. O esquema JSON detalhado na seção anterior pode ser usado em um modelo do Azure Resource Manager para executar a Extensão de Script Personalizada durante a implantação do modelo. Os exemplos a seguir mostram como usar a extensão de script personalizado:

Implementação do PowerShell

Você pode usar o Set-AzVMCustomScriptExtension comando para adicionar a extensão de script personalizado a uma máquina virtual existente. Para obter mais informações, consulte Set-AzVMCustomScriptExtension.

Set-AzVMCustomScriptExtension -ResourceGroupName <resourceGroupName> `
    -VMName <vmName> `
    -Location myLocation `
    -FileUri <fileUrl> `
    -Run 'myScript.ps1' `
    -Name DemoScriptExtension

Exemplos

Usando vários scripts

Este exemplo usa três scripts para criar seu servidor. A commandToExecute propriedade chama o primeiro script. Em seguida, você tem opções sobre como os outros são chamados. Por exemplo, você pode ter um script de lead que controla a execução, com o tratamento correto de erros, registro em log e gerenciamento de estado. Os scripts são baixados para a máquina local para serem executados.

Por exemplo, em 1_Add_Tools.ps1, você chamaria 2_Add_Features.ps1 adicionando .\2_Add_Features.ps1 ao script. Repita esse processo para os outros scripts definidos no $settings.

$fileUri = @("https://xxxxxxx.blob.core.windows.net/buildServer1/1_Add_Tools.ps1",
"https://xxxxxxx.blob.core.windows.net/buildServer1/2_Add_Features.ps1",
"https://xxxxxxx.blob.core.windows.net/buildServer1/3_CompleteInstall.ps1")

$settings = @{"fileUris" = $fileUri};

$storageAcctName = "xxxxxxx"
$storageKey = "1234ABCD"
$protectedSettings = @{"storageAccountName" = $storageAcctName; "storageAccountKey" = $storageKey; "commandToExecute" = "powershell -ExecutionPolicy Unrestricted -File 1_Add_Tools.ps1"};

#run command
Set-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -Location <locationName> `
    -VMName <vmName> `
    -Name "buildserver1" `
    -Publisher "Microsoft.Compute" `
    -ExtensionType "CustomScriptExtension" `
    -TypeHandlerVersion "1.10" `
    -Settings $settings `
    -ProtectedSettings $protectedSettings;

Neste exemplo, talvez você queira usar um servidor SMB (Server Message Block) local para seu local de script. Em seguida, você não precisa fornecer nenhuma outra configuração, exceto commandToExecute.

$protectedSettings = @{"commandToExecute" = "powershell -ExecutionPolicy Unrestricted -File \\filesvr\build\serverUpdate1.ps1"};

Set-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -Location <locationName> `
    -VMName <vmName> `
    -Name "serverUpdate"
    -Publisher "Microsoft.Compute" `
    -ExtensionType "CustomScriptExtension" `
    -TypeHandlerVersion "1.10" `
    -ProtectedSettings $protectedSettings

Executando um script personalizado mais de uma vez usando a CLI

O manipulador de Extensão de Script Personalizado impede a reexecução de um script se as mesmas configurações tiverem sido passadas. Esse comportamento impede a reexecução acidental, o que pode causar comportamentos inesperados se o script não for idempotente. Para confirmar se o manipulador bloqueou a reexecução, examine C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension\<HandlerVersion>\CustomScriptHandler.log*. Procurando por um aviso como este:

Current sequence number, <SequenceNumber>, is not greater than the sequence number
of the most recently executed configuration. Exiting...

Se você quiser executar a extensão de script personalizado mais de uma vez, você pode fazer isso somente sob estas condições:

O parâmetro da extensão é o mesmo que a implantação anterior da Name extensão.
Você atualizou a configuração. Você pode adicionar uma propriedade dinâmica ao comando, como um carimbo de data/hora. Se o manipulador detetar uma alteração nas definições de configuração, ele considerará essa alteração como um desejo explícito de executar novamente o script.

Como alternativa, você pode definir a propriedade ForceUpdateTag como true.

Usando Invoke-WebRequest

Se você estiver usando Invoke-WebRequest em seu script, deverá especificar o parâmetro -UseBasicParsing. Se você não especificar o parâmetro, receberá o seguinte erro ao verificar o status detalhado:

The response content cannot be parsed because the Internet Explorer engine
is not available, or Internet Explorer's first-launch configuration
is not complete. Specify the UseBasicParsing parameter and try again.

Conjuntos de Dimensionamento de Máquinas Virtuais

Se você implantar a Extensão de Script Personalizada do portal do Azure, não terá controle sobre a expiração do token SAS para acessar o script em sua conta de armazenamento. A implantação inicial funciona, mas quando o token SAS da conta de armazenamento expira, qualquer operação de dimensionamento subsequente falha porque a Extensão de Script Personalizada não pode mais acessar a conta de armazenamento.

Recomendamos que você use o PowerShell, a CLI do Azure ou um modelo do Azure Resource Manager ao implantar a Extensão de Script Personalizada em um Conjunto de Dimensionamento de Máquina Virtual. Dessa forma, você pode optar por usar uma identidade gerenciada ou ter controle direto da expiração do token SAS para acessar o script em sua conta de armazenamento pelo tempo que precisar.

Solução de problemas e suporte

Você pode recuperar dados sobre o estado das implantações de extensão no portal do Azure e usando o módulo do Azure PowerShell. Para ver o estado de implantação das extensões de uma VM, execute o seguinte comando:

Get-AzVMExtension -ResourceGroupName <resourceGroupName> `
    -VMName <vmName> -Name myExtensionName

A saída da extensão é registrada em arquivos encontrados na seguinte pasta na máquina virtual de destino:

C:\WindowsAzure\Logs\Plugins\Microsoft.Compute.CustomScriptExtension

Os arquivos especificados são baixados para a seguinte pasta na máquina virtual de destino:

C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.*\Downloads\<n>

No caminho anterior, <n> é um inteiro decimal que pode mudar entre execuções da extensão. O 1.* valor corresponde ao valor real e atual typeHandlerVersion da extensão. Por exemplo, o diretório real poderia ser C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2.

Quando você executa o comando, a extensão define esse diretório, por exemplo, ...\Downloads\2como o commandToExecute diretório de trabalho atual. Esse processo permite o uso de caminhos relativos para localizar os arquivos baixados usando a fileURIs propriedade. Aqui estão exemplos de arquivos baixados:

URI em `fileUris`	Local de download relativo	Local de download absoluto
`https://someAcct.blob.core.windows.net/aContainer/scripts/myscript.ps1`	`./scripts/myscript.ps1`	`C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\scripts\myscript.ps1`
`https://someAcct.blob.core.windows.net/aContainer/topLevel.ps1`	`./topLevel.ps1`	`C:\Packages\Plugins\Microsoft.Compute.CustomScriptExtension\1.8\Downloads\2\topLevel.ps1`

Os caminhos de diretório absolutos mudam ao longo do tempo de vida da VM, mas não em uma única execução da Extensão de Script Personalizada.

Como o caminho de download absoluto pode variar ao longo do tempo, é melhor optar por caminhos de script/arquivo relativos na commandToExecute cadeia de caracteres, sempre que possível. Por exemplo:

"commandToExecute": "powershell.exe . . . -File \"./scripts/myscript.ps1\""

As informações de caminho após o primeiro segmento de URI são mantidas para arquivos baixados usando a lista de fileUris propriedades. Como mostrado na tabela anterior, os arquivos baixados são mapeados em subdiretórios de download para refletir a fileUris estrutura dos valores.

Suporte

Se precisar de ajuda com qualquer parte deste artigo, contacte os especialistas do Azure no Suporte da Comunidade do Azure.
Para registrar um incidente de suporte do Azure, vá para o site de suporte do Azure e selecione Obter suporte.
Para obter informações sobre como usar o suporte do Azure, leia as Perguntas frequentes de suporte do Microsoft Azure.

Extensão de Script Personalizado para o Windows

Pré-requisitos

Sistemas operativos Windows suportados

Localização do script

Ligação à Internet

Sugestões

Esquema de extensão

Valores de propriedade

Detalhes do valor da propriedade

Propriedade: managedIdentity

Implementação de modelos

Implementação do PowerShell

Exemplos

Usando vários scripts

Executando scripts de um compartilhamento local

Executando um script personalizado mais de uma vez usando a CLI

Usando Invoke-WebRequest

Conjuntos de Dimensionamento de Máquinas Virtuais

Solução de problemas e suporte

Suporte

Recursos adicionais