Gerir pré-scripts e pós-scripts

Artigo
09/15/2024

Importante

O Gerenciamento de Atualização de Automação foi desativado em 31 de agosto de 2024 e recomendamos que você use o Azure Update Manager. Siga as diretrizes para migração do Automation Update Management para o Azure Update Manager.

Os pré-scripts e pós-scripts são runbooks para executar na conta de Automatização do Azure antes (pré-tarefa) e depois (pós-tarefa) de uma implementação de atualização. 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 implementação da atualização. No Windows, os pós-scripts são executados no final da implementação e após os reinícios configurados. No Linux, o pós-scripts são executados após o fim da implementação e não após o reinício do computador.

Requisitos dos pré-scripts e pós-scripts

Para que um runbook seja usado como um pré-script ou post-script, você deve importá-lo para sua conta de automação e publicar o runbook.

Atualmente, apenas runbooks do PowerShell 5.1 e Python 2 são suportados como scripts Pre/Post. Outros tipos de runbook como Python 3, Gráfico, Fluxo de Trabalho do PowerShell, Fluxo de Trabalho Gráfico do PowerShell não são suportados atualmente como scripts Pré/Post.

Parâmetros pré-script e post-script

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

[char]
[byte]
[int]
[longo]
[decimal]
[único]
[duplo]
[DateTime]
[string]

Os parâmetros de runbook pré-script e pós-script não suportam tipos booleanos, objetos ou matrizes. Esses valores fazem com que os runbooks falhem.

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

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

Propriedades SoftwareUpdateConfigurationRunContext

Propriedade	Type	Description
SoftwareUpdateConfigurationName	String	O nome da configuração de atualização de software.
SoftwareUpdateConfigurationRunId	GUID	O ID exclusivo para a execução.
SoftwareUpdateConfigurationSettings		Uma coleção de propriedades relacionadas à configuração de atualização de software.
SoftwareUpdateConfigurationSettings.OperatingSystem	Int	Os sistemas operacionais destinados à implantação da atualização. `1` = Windows e `2` = Linux
SoftwareUpdateConfigurationSettings.Duration	Período de tempo (HH:MM:SS)	A duração máxima da implantação da atualização é executada conforme `PT[n]H[n]M[n]S` 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ço de KBs que são excluídos da implantação da atualização.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.includedKbNumbers	String	Uma lista separada por espaço de KBs incluídas na implantação da atualização.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.UpdateCategories	Número inteiro	1 = "Crítico"; 2 = "Segurança" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definição" 64 = "Ferramentas" 128 = "Atualizações"
SoftwareUpdateConfigurationSettings.WindowsConfiguration.rebootSetting	String	Reinicialize as configurações para a implantação da atualização. Os valores são `IfRequired`, `Never`, `Always`
SoftwareUpdateConfigurationSettings.LinuxConfiguration		Uma coleção de propriedades relacionadas a computadores Linux.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageClassifications	Número inteiro	0 = "Não classificado" 1 = "Crítico" 2 = "Segurança" 4 = "Outros"
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageNameMasks	String	Uma lista separada por espaço de nomes de pacotes incluídos na implantação da atualização.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.ExcludedPackageNameMasks	String	Uma lista separada por espaço de nomes de pacotes que são excluídos da implantação da atualização.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.RebootSetting	String	Reinicialize as configurações para a implantação da atualização. Os valores são `IfRequired`, `Never`, `Always`
SoftwareUpdateConfigurationSettings.AzureVirtualMachines	Matriz de cadeias de carateres	Uma lista de resourceIds para as VMs do Azure na implantação da atualização.
SoftwareUpdateConfigurationSettings.NonAzureComputerNames	Matriz de cadeias de carateres	Uma lista dos FQDNs de computadores que não são do Azure na implantação da atualização.

O exemplo a seguir é uma cadeia de caracteres JSON passada para as propriedades SoftwareUpdateConfigurationSettings de 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/resourceGroupName/providers/Microsoft.Compute/virtualMachines/vm-01"
     ],
     "Duration": "02:00:00",
     "PSComputerName": "localhost",
     "PSShowComputerName": true,
     "PSSourceJobInstanceId": "2477a37b-5262-4f4f-b636-3a70152901e9"
 }

O exemplo a seguir é uma cadeia de caracteres JSON passada para as propriedades SoftwareUpdateConfigurationSettings de 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/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-01",
        "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/myResourceGroup/providers/Microsoft.Compute/virtualMachines/vm-02",
        "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/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.

Nota

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

Usar um pré-script ou post-script em uma implantação

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

Selecionar scripts

Selecione o script que 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 . Mas quando você escolher o tipo de script, selecione Post-Script.

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

Itens selecionados

Conclua a configuração da implantação da atualização.

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

Atualizar resultados

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

Resultados da execução da implantação

Parar uma implementação

Se quiser interromper uma implantação com base em um pré-script, você deve lançar uma exceção. Se não o fizer, a implementação e o pós-script continuarão a ser executados. O trecho 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ções é gerenciado em um bloco try .

Interagir com computadores

Os pré-scripts e pós-scripts são executados como runbooks na conta de Automatização e não diretamente nos computadores na implementação. As pré-tarefas e pós-tarefas também são executadas no contexto do Azure e não têm acesso a computadores que não sejam do Azure. As seções a seguir mostram como você pode interagir diretamente com as máquinas, sejam elas VMs do Azure ou máquinas que não sejam do Azure.

Interagir com máquinas do Azure

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

Uma identidade gerenciada ou uma conta Run As
Um runbook que você deseja executar

Para interagir com máquinas do Azure, você deve usar o cmdlet Invoke-AzVMRunCommand para interagir com suas VMs do Azure. Para obter um exemplo de como fazer isso, consulte o exemplo de runbook Gerenciamento de atualizações - script de execução com o comando Executar.

Interagir com máquinas que não são do Azure

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

Uma identidade gerenciada ou uma conta Run As
Função de Trabalho de Runbook Híbrida instalada no computador
Um runbook que você deseja executar localmente
Um runbook principal

Para interagir com computadores não Azure, é executado um runbook principal no contexto do Azure. Este runbook chama um runbook subordinado com o cmdlet Start-AzAutomationRunbook. Você deve especificar o RunOn parâmetro e fornecer o nome do Hybrid Runbook Worker para que o script seja executado. Veja o exemplo de runbook Gerenciamento de atualizações - execute o script localmente.

Abortar implementação de patch

Se o pré-script retornar um erro, convém abortar a implantação. Para fazer isso, você deve lançar um erro em seu script para qualquer lógica que constitua 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 lançar um erro quando uma determinada condição ocorrer, use uma instrução get.

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

Exemplos

Exemplos de pré-scripts e pós-scripts podem ser encontrados na organização do GitHub de Automação do Azure e na Galeria do PowerShell, ou você pode importá-los por meio do portal do Azure. Para fazer isso, em sua conta de automação, em Automação de processos, selecione Galeria de runbooks. Use o Gerenciamento de Atualizações para o filtro.

Lista de galerias

Ou você pode procurá-los pelo nome do script, conforme mostrado na lista a seguir:

Gerenciamento de atualizações - Ativar VMs
Gerenciamento de atualizações - Desativar 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 o comando Executar

Importante

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

Os exemplos são todos baseados no modelo básico definido no exemplo a seguir. Este modelo pode ser usado para criar seu próprio runbook para usar com pré-scripts e post-scripts. A lógica necessária para autenticar com o Azure e manipular o SoftwareUpdateConfigurationRunContext parâmetro 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 ao sistema, deixe o código como está. Se preferir usar uma identidade gerenciada atribuída pelo usuário, então:

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

Nota

Para runbooks não gráficos do PowerShell, Add-AzAccount e Add-AzureRMAccount são aliases para Connect-AzAccount. Você pode usar esses cmdlets ou atualizar seus módulos em sua conta de automação para as versões mais recentes. Talvez seja necessário atualizar seus módulos mesmo que tenha acabado de criar uma nova conta de automação.

Próximos passos

Para obter detalhes sobre o gerenciamento de atualizações, consulte Gerenciar atualizações e patches para suas VMs.

Partilhar via