Gestire pre-script e post-script

Articolo
09/15/2024

Importante

Gestione aggiornamenti di Automazione è stato ritirato il 31 agosto 2024 ed è consigliabile usare Gestore aggiornamenti di Azure. Seguire le linee guida per la migrazione da Gestione aggiornamenti di Automazione a Gestore aggiornamenti di Azure.

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, sono supportati come pre-script e post-script solo i runbook di PowerShell 5.1 e Python 2. Altri tipi di runbook, come Python 3, grafico, flusso di lavoro PowerShell e flusso di lavoro di PowerShell grafico non sono attualmente supportati come pre-script e post-script.

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à	Type	Descrizione
SoftwareUpdateConfigurationName	String	Nome della configurazione di aggiornamento software.
SoftwareUpdateConfigurationRunId	GUID	ID univoco per l'esecuzione.
SoftwareUpdateConfigurationSettings		Raccolta di proprietà correlate alla configurazione di aggiornamento software.
SoftwareUpdateConfigurationSettings.OperatingSystem	Int	Sistemi operativi di destinazione per la distribuzione di aggiornamento. `1` = Windows e `2` = Linux
SoftwareUpdateConfigurationSettings.Duration	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
SoftwareUpdateConfigurationSettings.WindowsConfiguration		Raccolta di proprietà relative ai computer Windows.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.excludedKbNumbers	String	Elenco delimitato da spazi di Knowledge Base escluse dalla distribuzione dell'aggiornamento.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.includedKbNumbers	String	Elenco delimitato da spazi di Knowledge Base incluse nella distribuzione dell'aggiornamento.
SoftwareUpdateConfigurationSettings.WindowsConfiguration.UpdateCategories	Intero	1 = "Critical"; 2 = "Security" 4 = "UpdateRollUp" 8 = "FeaturePack" 16 = "ServicePack" 32 = "Definition" 64 = "Tools" 128 = "Updates"
SoftwareUpdateConfigurationSettings.WindowsConfiguration.rebootSetting	String	Impostazioni di riavvio per la distribuzione di aggiornamento. I valori sono `IfRequired`, `Never`, `Always`
SoftwareUpdateConfigurationSettings.LinuxConfiguration		Raccolta di proprietà relative ai computer Linux.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageClassifications	Intero	0 = "Unclassified" 1 = "Critical" 2 = "Security" 4 = "Other"
SoftwareUpdateConfigurationSettings.LinuxConfiguration.IncludedPackageNameMasks	String	Elenco delimitato da spazi di nomi di pacchetti inclusi nella distribuzione dell'aggiornamento.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.ExcludedPackageNameMasks	String	Elenco delimitato da spazi di nomi di pacchetti esclusi dalla distribuzione dell'aggiornamento.
SoftwareUpdateConfigurationSettings.LinuxConfiguration.RebootSetting	String	Impostazioni di riavvio per la distribuzione di aggiornamento. I valori sono `IfRequired`, `Never`, `Always`
SoftwareUpdateConfiguationSettings.AzureVirtualMachines	Matrice di stringhe	Elenco di ResourceID per le macchine virtuali di Azure nella distribuzione di aggiornamento.
SoftwareUpdateConfigurationSettings.NonAzureComputerNames	Matrice di stringhe	Elenco di FQDN dei computer non Azure nella distribuzione di aggiornamento.

Di seguito è riportato un esempio di stringa JSON passata alle proprietà SoftwareUpdateConfigurationSettings 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/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"
 }

Di seguito è riportato un esempio di stringa JSON passata alle proprietà SoftwareUpdateConfigurationSettings 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/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"
      ]
    }
  }

Un esempio completo con tutte le proprietà è disponibile in: Recuperare la configurazione degli aggiornamenti 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.

Selezionare gli script

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:

Elementi selezionati

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:

Risultati aggiornamento

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.

Risultati dell'esecuzione della distribuzione

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 con 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 eseguita con 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 Update Management - Run Script with Run Command.

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 Update Management - Run Script Locally.

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 di GitHub per Automazione di Azure e in PowerShell Gallery oppure è possibile importarli attraverso il portale di Azure. Nell'account di Automazione selezionare Raccolta di runbook in Automazione processi. Usare Update Management come filtro.

Elenco della raccolta

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>).context e
Immettere l'ID client.

Nota

Per runbook PowerShell non grafici, Add-AzAccount e Add-AzureRMAccount sono alias di Connect-AzAccount. È possibile usare questi cmdlet oppure è possibile aggiornare i moduli nell'account di Automazione alle versioni più recenti. Potrebbe essere necessario aggiornare i moduli, anche se è stato appena creato un nuovo account di Automazione.

Passaggi successivi

Per informazioni dettagliate sulla gestione degli aggiornamenti, vedere Gestire gli aggiornamenti e le patch per le macchine virtuali.

Condividi tramite