Gerenciar pré-scripts e pós-scripts

Artigo
06/01/2023

Pré-scripts e pós-scripts são runbooks para execução na sua conta da Automação do Azure antes (pré-tarefa) e depois (pós-tarefa) de uma implantação de atualizações. Os pré-scripts e pós-scripts são executados no contexto do Azure, não localmente. Os pré-scripts são executados no início da implantação de atualizações. No Windows, os pós-scripts são executados no final da implantação e após as reinicializações configuradas. Para o Linux, pós-scripts são executados após o final da implantação, e não após reinicializações do computador.

Requisitos de pré-script e pós-script

Para que um runbook seja usado como pré-script ou pós-script, você deve importá-lo para sua conta da Automação e publicar o runbook.

Atualmente, apenas os runbooks do PowerShell 5.1 e do Python 2 são compatíveis como pré/pós scripts. Outros tipos de runbook como o Python 3, o Gráfico, o fluxo de trabalho do PowerShell, o fluxo de trabalho gráfico do PowerShell atualmente não têm suporte como pré/pós scripts.

Parâmetros de pré-script e pós-script

Ao configurar pré-scripts e pós-scripts, você pode passar parâmetros, assim como agendar um runbook. Os parâmetros são definidos no momento da criação da implantação de atualização. Pré-scripts e pós-scripts dão suporte aos seguintes tipos:

[char]
[byte]
[int]
[long]
[decimal]
[single]
[double]
[DateTime]
[string]

Os parâmetros de runbook pré-script e pós-script não oferecem suporte a tipos boolianos, de objetos ou de matriz. Esses valores causam a falha dos runbooks.

Se precisar de outro tipo de objeto, você poderá convertê-lo em outro tipo usando com sua própria lógica no runbook.

Além dos parâmetros padrão do runbook, o parâmetro SoftwareUpdateConfigurationRunContext (tipo cadeia de caracteres JSON) é fornecido. Se você definir o parâmetro no seu runbook pré-script ou pós-script, ele será passado automaticamente pela implantação de atualizações. O parâmetro contém informações sobre a implantação de atualizações, que é um subconjunto das informações retornadas pela API SoftwareUpdateconfigurations. As seções a seguir definem as propriedades associadas.

Propriedades de SoftwareUpdateConfigurationRunContext

Propriedade	Type	Descrição
SoftwareUpdateConfigurationName	String	O nome da configuração da atualização de software.
SoftwareUpdateConfigurationRunId	GUID	A ID exclusiva para a execução.
SoftwareUpdateConfigurationSettings		Uma coleção de propriedades relacionadas à configuração da atualização de software.
SoftwareUpdateConfigurationSettings.OperatingSystem	Int	Os sistemas operacionais selecionados para a implantação de atualização. `1` = Windows e `2` = Linux
SoftwareUpdateConfigurationSettings.Duration	Timespan (HH:MM:SS)	A duração máxima da execução da implantação de atualizações, `PT[n]H[n]M[n]S` conforme a norma ISO8601, também chamada de janela de manutenção. Exemplo: 02:00:00
SoftwareUpdateConfigurationSettings.WindowsConfiguration		Uma coleção de propriedades relacionadas a computadores Windows.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.excludedKbNumbers	String	Uma lista separada por espaços de KBs que são excluídas da implantação de atualização.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.includedKbNumbers	String	Uma lista separada por espaços de KBs que são incluídas com a implantação de atualização.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.UpdateCategories	Inteiro	1 = "Critical"; 2 = "Security" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definition" 64 = "Tools" 128 = "Updates"
SoftwareUpdateConfigurationSettings.WindowsConfiguration.rebootSetting	String	Configurações de reinicialização para a implantação de atualizações. Os valores são `IfRequired`, `Never`, `Always`
SoftwareUpdateConfigurationSettings.LinuxConfiguration		Uma coleção de propriedades relacionadas a computadores Linux.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageClassifications	Inteiro	0 = "Unclassified" 1 = "Critical" 2 = "Security" 4 = "Other"
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageNameMasks	String	Uma lista separada por espaços de nomes de pacote que são incluídos com a implantação de atualização.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.ExcludedPackageNameMasks	String	Uma lista separada por espaços de nomes de pacote que são excluídos da implantação de atualização.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.RebootSetting	String	Configurações de reinicialização para a implantação de atualizações. Os valores são `IfRequired`, `Never`, `Always`
SoftwareUpdateConfiguationSettings.AzureVirtualMachines	Matriz de cadeia de caracteres	Uma lista de resourceIds para as VMs do Azure na implantação de atualizações.
SoftwareUpdateConfigurationSettings.NonAzureComputerNames	Matriz de cadeia de caracteres	Uma lista dos FQDNs de computadores não Azure na implantação de atualizações.

A seguir há um exemplo de cadeia de caracteres JSON passada para as propriedades SoftwareUpdateConfigurationSettings para um computador Linux:

"SoftwareUpdateConfigurationSettings": {
     "OperatingSystem": 2,
     "WindowsConfiguration": null,
     "LinuxConfiguration": {
         "IncludedPackageClassifications": 7,
         "ExcludedPackageNameMasks": "fgh xyz",
         "IncludedPackageNameMasks": "abc bin*",
         "RebootSetting": "IfRequired"
     },
     "Targets": {
         "azureQueries": null,
         "nonAzureQueries": ""
     },
     "NonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
     ],
     "AzureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/resourceGroupName/providers/Microsoft.Compute/virtualMachines/vm-01"
     ],
     "Duration": "02:00:00",
     "PSComputerName": "localhost",
     "PSShowComputerName": true,
     "PSSourceJobInstanceId": "2477a37b-5262-4f4f-b636-3a70152901e9"
 }

A seguir há um exemplo de cadeia de caracteres JSON passada para as propriedades SoftwareUpdateConfigurationSettings para um computador Windows:

"SoftwareUpdateConfigurationRunContext": {
    "SoftwareUpdateConfigurationName": "sampleConfiguration",
    "SoftwareUpdateConfigurationRunId": "00000000-0000-0000-0000-000000000000",
    "SoftwareUpdateConfigurationSettings": {
      "operatingSystem": "Windows",
      "duration": "02:00:00",
      "windows": {
        "excludedKbNumbers": [
          "168934",
          "168973"
        ],
        "includedUpdateClassifications": "Critical",
        "rebootSetting": "IfRequired"
      },
      "azureVirtualMachines": [
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-01",
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-02",
        "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-03"
      ],
      "nonAzureComputerNames": [
        "box1.contoso.com",
        "box2.contoso.com"
      ]
    }
  }

Um exemplo completo com todas as propriedades pode ser encontrado em: Obter configuração de atualização de software por nome.

Observação

O objeto SoftwareUpdateConfigurationRunContext pode conter entradas duplicadas para computadores. Isso pode fazer com que os pré-scripts e os pós-scripts sejam executados várias vezes no mesmo computador. Para contornar esse comportamento, use Sort-Object -Unique para selecionar apenas nomes de VM exclusivos.

Usar um pré-script ou pós-script em uma implantação

Para usar um pré-script ou um pós-script em uma implantação de atualização, comece criando uma implantação de atualização. Selecione Pré-Scripts + Pós-scripts. Essa ação abre a página Selecionar Pré-scripts + Pós-scripts.

Select scripts

Selecione o script que você deseja usar. Neste exemplo, usamos o runbook UpdateManagement-TurnOnVms. Quando você seleciona o runbook, a página Configurar Script é aberta. Selecione Pré-script e, em seguida, selecione OK.

Repita esse processo para o script UpdateManagement-TurnOffVms. Porém, quando escolher o Tipo de script, selecione Pós-script.

A seção Itens selecionados agora mostra os dois scripts selecionados. Um é um pré-script e o outro é um post-script:

Selected items

Conclua a configuração da implantação de atualizações.

Quando a implantação de atualizações estiver concluída, você poderá acessar Implantações de atualizações para exibir os resultados. Como pode ver, são informados os status do pré-script e do pós-script:

Update results

Ao selecionar a execução da implantação de atualizações, você verá detalhes adicionais de pré-scripts e pós-scripts. Um link para a fonte do script no momento da execução é fornecido.

Deployment run results

Interromper uma implantação

Se você deseja interromper uma implantação com base em um pré-script, lance uma exceção. Se não, a implantação e o post-script ainda serão executados. O snippet de código a seguir mostra como lançar uma exceção usando o PowerShell.

#In this case, we want to terminate the patch job if any run fails.
#This logic might not hold for all cases - you might want to allow success as long as at least 1 run succeeds
foreach($summary in $finalStatus)
{
    if ($summary.Type -eq "Error")
    {
        #We must throw in order to fail the patch deployment.
        throw $summary.Summary
    }
}

No Python 2, o tratamento de exceção é gerenciado em um bloco try.

Interação com computadores

Os pré-scripts e pós-scripts são executados como runbooks em sua conta da Automação e não diretamente nos computadores em sua implantação. As pré-tarefas e as pós-tarefas também são executadas no contexto do Azure e não têm acesso a computadores não Azure. As seções a seguir mostram como você pode interagir com os computadores diretamente, sejam eles VMs do Azure ou computadores não Azure.

Interação com computadores Azure

Pré-tarefas e pós-tarefas são executadas como runbooks e não são executadas nativamente nas VMs do Azure em sua implantação. Para interagir com as VMs do Azure, você precisa ter os seguintes itens:

Uma identidade gerenciada ou uma conta Executar como
Um runbook que você deseja executar

Para interagir com computadores do Azure, você deve usar o cmdlet Invoke-AzVMRunCommand para interagir com suas VMs do Azure. Para obter um exemplo de como fazer isso, confira o exemplo do runbook Gerenciamento de Atualizações - executar script com o comando Executar.

Interação com computadores não Azure

As pré-tarefas e as pós-tarefas são executadas no contexto do Azure e não têm acesso a computadores não Azure. Para interagir com os computadores não Azure, você precisa ter os seguintes itens:

Uma identidade gerenciada ou uma conta Executar como
Um Hybrid Runbook Worker instalado no computador
Um runbook que deseja executar localmente
Um runbook pai

Para interagir com computadores não Azure, um runbook pai é executado no contexto do Azure. Esse runbook chama um runbook filho com o cmdlet Start-AzAutomationRunbook. É necessário especificar o parâmetro RunOn e fornecer o nome do Hybrid Runbook Worker para o script ser executado. Confira o exemplo de runbook Gerenciamento de Atualizações - executar script localmente.

Anular implantação de patch

Se o seu pré-script retornar um erro, você poderá anular a implantação. Para fazer isso, você deve lançar um erro em seu script para qualquer lógica que possa constituir uma falha.

if (<My custom error logic>)
{
    #Throw an error to fail the patch deployment.
    throw "There was an error, abort deployment"
}

No Python 2, se você quiser gerar um erro quando uma determinada condição ocorrer, use uma instrução Raise.

If (<My custom error logic>)
   raise Exception('Something happened.')

Exemplos

Os exemplos de pré-scripts e pós-scripts podem ser encontrados na organização GitHub da Automação do Azure e na Galeria do PowerShell ou você pode importá-los por meio do portal do Azure. Para tal, na sua conta da Automação, em Automação de Processo, selecione Galeria de Runbooks. Use Gerenciamento de Atualizações para o filtro.

Gallery list

Ou pode pesquisar por elas usando o nome do script, como mostrado na lista a seguir:

Gerenciamento de Atualizações – Ligar VMs
Gerenciamento de Atualizações – Desligar VMs
Gerenciamento de Atualizações – Executar script localmente
Gerenciamento de Atualizações – Modelo para scripts pré/pós
Gerenciamento de Atualizações – Executar script com comando de execução

Importante

Depois de importar os runbooks, você precisa publicá-los antes que eles possam ser usados. Para fazer isso, localize o runbook na sua conta da Automação, selecione Editar e, em seguida, Publicar.

Todos os exemplos se baseiam no modelo básico que é definido no exemplo a seguir. Esse modelo pode ser usado para criar seu runbook para usar com pré-scripts e pós-scripts. A lógica necessária para autenticar com o Azure e lidar com o parâmetro SoftwareUpdateConfigurationRunContext está incluída.

<#
.SYNOPSIS
 Barebones script for Update Management Pre/Post

.DESCRIPTION
  This script is intended to be run as a part of Update Management pre/post-scripts.
  It requires the Automation account's system-assigned managed identity.

.PARAMETER SoftwareUpdateConfigurationRunContext
  This is a system variable which is automatically passed in by Update Management during a deployment.
#>

param(
    [string]$SoftwareUpdateConfigurationRunContext
)

#region BoilerplateAuthentication
# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context

# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext
#endregion BoilerplateAuthentication

#If you wish to use the run context, it must be converted from JSON
$context = ConvertFrom-Json $SoftwareUpdateConfigurationRunContext
#Access the properties of the SoftwareUpdateConfigurationRunContext
$vmIds = $context.SoftwareUpdateConfigurationSettings.AzureVirtualMachines | Sort-Object -Unique
$runId = $context.SoftwareUpdateConfigurationRunId

Write-Output $context

#Example: How to create and write to a variable using the pre-script:
<#
#Create variable named after this run so it can be retrieved
New-AzAutomationVariable -ResourceGroupName $ResourceGroup -AutomationAccountName $AutomationAccount -Name $runId -Value "" -Encrypted $false
#Set value of variable
Set-AutomationVariable -Name $runId -Value $vmIds
#>

#Example: How to retrieve information from a variable set during the pre-script
<#
$variable = Get-AutomationVariable -Name $runId
#>

Se você quiser que o runbook seja executado com a identidade gerenciada atribuída pelo sistema, deixe o código no estado em que se encontra. Se você preferir usar uma identidade gerenciada atribuída pelo usuário, então:

A partir da linha 22, remova $AzureContext = (Connect-AzAccount -Identity).context,
Substitua-o por $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context e
Insira a ID do cliente.