Gestire pre-script e post-script

Articolo
10/24/2023

I pre-script e i post-script sono runbook da eseguire nell'account di Automazione prima (attività preliminare) e dopo (attività successiva) una distribuzione di aggiornamento. I pre-script e i post-script vengono eseguiti nel contesto di Azure e non in locale. I pre-script sono eseguiti all'inizio della distribuzione di aggiornamento. In Windows, i post-script vengono eseguiti al termine della distribuzione e dopo eventuali riavvii configurati. Per Linux, i post-script vengono eseguiti dopo la fine della distribuzione, non dopo il riavvio del computer.

Requisiti di pre-script e post-script

Per usare un runbook come pre-script o post-script, è necessario importarlo nell'account di Automazione e pubblicare il runbook.

Attualmente, solo i runbook powerShell 5.1 e Python 2 sono supportati come script di pre/post. Altri tipi di runbook, ad esempio Python 3, grafico, flusso di lavoro PowerShell grafico, flusso di lavoro grafico di PowerShell non sono attualmente supportati come script di pre/post.

Parametri di pre-script e post-script

Quando si configurano i pre-script e i post-script è possibile passare i parametri come quando si pianifica un runbook. I parametri vengono definiti al momento della creazione della distribuzione di aggiornamento. I pre-script e i post-script supportano i tipi seguenti:

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

I parametri runbook di pre-script e post-script non supportano i tipi booleani, oggetto o matrice. Questi valori determinano l'esito negativo dei runbook.

Se è necessario un altro tipo di oggetto, è possibile eseguirne il cast in un altro tipo con la propria logica nel runbook.

Oltre ai parametri runbook standard, viene fornito il parametro SoftwareUpdateConfigurationRunContext (tipo stringa JSON). Se si definisce il parametro nel runbook di pre-script o post-script, questo viene passato automaticamente dalla distribuzione di aggiornamento. Il parametro contiene informazioni sulla distribuzione di aggiornamento costituite da un subset delle informazioni restituite dall'API SoftwareUpdateconfigurations. Le sezioni seguenti definiscono le proprietà associate.

Proprietà SoftwareUpdateConfigurationRunContext

Proprietà	Digita	Descrizione
SoftwareUpdateConfigurationName	Stringa	Nome della configurazione di aggiornamento software.
SoftwareUpdateConfigurationRunId	GUID	ID univoco per l'esecuzione.
SoftwareUpdateConfigurationSettings		Raccolta di proprietà correlate alla configurazione di aggiornamento software.
SoftwareUpdateConfiguration Impostazioni. OperatingSystem	Int	Sistemi operativi di destinazione per la distribuzione di aggiornamento. `1` = Windows e `2` = Linux
SoftwareUpdateConfiguration Impostazioni. Durata	Intervallo di tempo (HH:MM:SS)	Durata massima dell'esecuzione della distribuzione di aggiornamento in formato `PT[n]H[n]M[n]S` ISO8601, denominata anche "finestra di manutenzione". Esempio: 02:00:00
SoftwareUpdateConfiguration Impostazioni. WindowsConfiguration		Raccolta di proprietà relative ai computer Windows.
SoftwareUpdateConfiguration Impostazioni. WindowsConfiguration.excludedKbNumbers	Stringa	Elenco separato da spazi di KB esclusi dalla distribuzione degli aggiornamenti.
SoftwareUpdateConfiguration Impostazioni. WindowsConfiguration.includedKbNumbers	Stringa	Elenco separato di spazi di KB inclusi nella distribuzione degli aggiornamenti.
SoftwareUpdateConfiguration Impostazioni. WindowsConfiguration.UpdateCategories	Intero	1 = "Critico"; 2 = "Sicurezza" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definizione" 64 = "Strumenti" 128 = "Aggiornamenti"
SoftwareUpdateConfiguration Impostazioni. WindowsConfiguration.rebootSetting	Stringa	Impostazioni di riavvio per la distribuzione di aggiornamento. I valori sono `IfRequired`, `Never`, `Always`
SoftwareUpdateConfiguration Impostazioni. LinuxConfiguration		Raccolta di proprietà correlate ai computer Linux.
SoftwareUpdateConfiguration Impostazioni. LinuxConfiguration.IncludedPackageClassifications	Intero	0 = "Unclassified" 1 = "Critico" 2 = "Sicurezza" 4 = "Altro"
SoftwareUpdateConfiguration Impostazioni. LinuxConfiguration.IncludedPackageNameMasks	Stringa	Elenco separato di spazi dei nomi dei pacchetti inclusi nella distribuzione degli aggiornamenti.
SoftwareUpdateConfiguration Impostazioni. LinuxConfiguration.ExcludedPackageNameMasks	Stringa	Elenco separato da spazi dei nomi dei pacchetti esclusi dalla distribuzione degli aggiornamenti.
SoftwareUpdateConfiguration Impostazioni. LinuxConfiguration.RebootSetting	Stringa	Impostazioni di riavvio per la distribuzione di aggiornamento. I valori sono `IfRequired`, `Never`, `Always`
SoftwareUpdateConfiguation Impostazioni. AzureVirtualMachines	Matrice di stringhe	Elenco di ResourceID per le macchine virtuali di Azure nella distribuzione di aggiornamento.
SoftwareUpdateConfiguration Impostazioni. NonAzureComputerNames	Matrice di stringhe	Elenco di FQDN dei computer non Azure nella distribuzione di aggiornamento.

L'esempio seguente è una stringa JSON passata alle proprietà SoftwareUpdateConfiguration Impostazioni per un computer 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"
 }

L'esempio seguente è una stringa JSON passata alle proprietà SoftwareUpdateConfiguration Impostazioni per un computer 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"
      ]
    }
  }

Un esempio completo con tutte le proprietà è disponibile in: Ottenere la configurazione dell'aggiornamento software in base al nome.

Nota

L'oggetto SoftwareUpdateConfigurationRunContext può contenere voci duplicate per i computer. Questo può causare l'esecuzione di pre-script e post-script più volte nello stesso computer. Per ovviare a questo comportamento, usare Sort-Object -Unique per selezionare solo nomi di VM univoci.

Usare pre-script o post-script in una distribuzione

Per usare un pre-script o un post-script in una distribuzione di aggiornamento, iniziare creando una distribuzione di aggiornamento. Selezionare Pre-script e post-script. Verrà visualizzata la pagina Selezionare i pre-script e i post-script.

Select scripts

Selezionare lo script che si vuole usare. In questo esempio viene usato il runbook UpdateManagement-TurnOnVms. Quando si seleziona il runbook, viene visualizzata la pagina Configura script. Selezionare Pre-Script, quindi OK.

Ripetere la procedura per lo script UpdateManagement-TurnOffVms. Quando tuttavia si sceglie il tipo di script, selezionare Post-script.

La sezione Elementi selezionati mostra ora entrambi gli script selezionati. Uno è un pre-script e l'altro è un post-script:

Selected items

Completare la configurazione della distribuzione di aggiornamento.

Una volta terminata la distribuzione di aggiornamento, è possibile passare a Distribuzioni di aggiornamento per visualizzare i risultati. Come si può notare, è indicato lo stato del pre-script e del post-script:

Update results

Selezionando l'esecuzione della distribuzione di aggiornamento, vengono visualizzati altri dettagli su pre-script e post-script. Viene fornito un collegamento all'origine dello script al momento dell'esecuzione.

Deployment run results

Arrestare una distribuzione

Se si vuole arrestare una distribuzione in base a un pre-script, è necessario generare un'eccezione. In caso contrario, la distribuzione e il post-script saranno ancora in esecuzione. Il frammento di codice seguente illustra come generare un'eccezione usando 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
    }
}

In Python 2 la gestione delle eccezioni viene gestita in un blocco try .

Interagire con i computer

I pre-script e i post-script vengono eseguiti come runbook nell'account di Automazione e non direttamente nei computer della distribuzione. Anche pre-task e post-task vengono eseguiti nel contesto di Azure e non hanno accesso ai computer non Azure. Le sezioni seguenti illustrano come interagire direttamente con i computer, che si tratti di macchine virtuali di Azure o computer non Azure.

Interagire con i computer Azure

Pre-task e post-task vengono eseguiti come runbook e non in modo nativo nelle macchine virtuali di Azure nella distribuzione. Per interagire con le macchine virtuali di Azure sono necessari gli elementi seguenti:

Un'identità gestita o un account RunAs
Un runbook da eseguire

Per interagire con i computer di Azure è necessario usare il cmdlet Invoke-AzVMRunCommand per interagire con le VM di Azure. Per un esempio di come eseguire questa operazione, vedere l'esempio di Runbook Gestione aggiornamenti - Eseguire lo script con il comando Esegui.

Interagire con computer non Azure

Pre-task e post-task vengono eseguiti nel contesto di Azure e non hanno accesso ai computer non Azure. Per interagire con i computer non Azure è necessario quanto segue:

Un'identità gestita o un account RunAs
Ruolo di lavoro ibrido per runbook installato nel computer
Un runbook da eseguire in locale
Un runbook padre

Per interagire con i computer non Azure viene eseguito un runbook padre nel contesto di Azure. Questo runbook chiama un runbook figlio con il cmdlet Start-AzAutomationRunbook. È necessario specificare il RunOn parametro e specificare il nome del ruolo di lavoro ibrido per runbook in cui eseguire lo script. Vedere l'esempio di Runbook Gestione aggiornamenti - Eseguire lo script in locale.

Interrompere la distribuzione di patch

Se il pre-script restituisce un errore, può essere opportuno interrompere la distribuzione. A tale scopo, è necessario generare un errore nello script per qualsiasi logica che costituirebbe un errore.

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

In Python 2, se si vuole generare un errore quando si verifica una determinata condizione, usare un'istruzione raise .

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

Esempi

Gli esempi di pre-script e post-script sono disponibili nell'organizzazione GitHub Automazione di Azure e in PowerShell Gallery oppure è possibile importarli tramite il portale di Azure. Nell'account di Automazione selezionare Raccolta di runbook in Automazione processi. Usare Update Management come filtro.

Gallery list

In alternativa è possibile eseguire una ricerca in base al nome dello script, come indicato nell'elenco seguente:

Update Management - Turn On VMs
Update Management - Turn Off VMs
Update Management - Run Script Locally
Update Management - Template for Pre/Post Scripts
Update Management - Run Script with Run Command

Importante

Dopo aver importato i runbook, è necessario pubblicarli prima di poterli usare. A questo scopo trovare il runbook nell'account di Automazione, selezionare Modifica e quindi Pubblica.

Gli esempi sono tutti basati sul modello di base definito nell'esempio seguente. Questo modello può essere usato per creare un proprio runbook da usare con pre-script e post-script. È inclusa la logica necessaria per l'autenticazione ad Azure e la gestione del parametro SoftwareUpdateConfigurationRunContext.

<#
.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 si vuole che il runbook venga eseguito con l'identità gestita assegnata dal sistema, lasciare invariato il codice. Se si preferisce usare un'identità gestita assegnata dall'utente, procedere come illustrato di seguito:

Dalla riga 22 rimuovere $AzureContext = (Connect-AzAccount -Identity).context,
Sostituirlo con $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).contexte
Immettere l'ID client.