Creare runbook modulari in Automazione

  • Articolo

È consigliabile Automazione di Azure scrivere runbook modulari riutilizzabili con una funzione discreta chiamata da altri runbook. Un runbook padre chiama spesso uno o più runbook figlio per eseguire la funzionalità richiesta.

Esistono due modi per chiamare un runbook figlio: inline o tramite un cmdlet. La tabella seguente riepiloga le differenze per decidere in quale modo è migliore per gli scenari.

Incorporato Cmdlet
Mansione I runbook figlio vengono eseguiti nello stesso processo dell’elemento padre. Viene creato un processo separato per il runbook figlio.
Esecuzione Il runbook padre attende il completamento del runbook figlio prima di continuare. Il runbook padre continua immediatamente dopo l'avvio del runbook figlio oppure il runbook padre attende il completamento del processo figlio.
Output Il runbook padre può ottenere direttamente l'output dal runbook figlio. Il runbook padre deve recuperare l'output dal processo del runbook figlio oppure il runbook padre può ottenere direttamente l'output dal runbook figlio.
Parameters I valori per i parametri di runbook figlio vengono specificati separatamente e possono utilizzare qualsiasi tipo di dati. I valori dei parametri dei runbook figlio devono essere raggruppati in un'unica tabella hash. Questa tabella hash può includere solo tipi di dati semplici, matrici e oggetti che usano la serializzazione JSON.
Account di Automazione Il runbook padre può usare solo un runbook figlio nello stesso account di Automazione. I runbook padre possono usare un runbook figlio da qualsiasi account di Automazione, dalla stessa sottoscrizione di Azure, e anche da una sottoscrizione diversa con cui si ha una connessione.
Pubblicazione Un runbook figlio deve essere pubblicato prima della pubblicazione del runbook padre. Un runbook figlio viene pubblicato in qualsiasi momento prima dell'avvio del runbook padre.

Chiamare un runbook figlio usando l'esecuzione inline

Per chiamare un runbook inline da un altro runbook, usare il nome del runbook e specificare i valori per i relativi parametri, proprio come si usa un'attività o un cmdlet. Tutti i runbook nello stesso account di Automazione sono disponibili per tutti gli altri utenti da usare in questo modo. Il runbook padre attende il completamento del runbook figlio prima di passare alla riga successiva e qualsiasi output torna direttamente all'elemento padre.

Quando si chiama un runbook inline, viene eseguito nello stesso processo del runbook padre. Non esiste alcuna indicazione nella cronologia del processo del runbook figlio. Eventuali eccezioni e output del flusso dal runbook figlio vengono associati al runbook padre. Questo comportamento ha come risultato un minor numero di processi e semplifica la traccia e la risoluzione dei problemi di questi.

Quando viene pubblicato un runbook, tutti i runbook figlio chiamati devono già essere pubblicati. Il motivo è che quando compila un runbook Automazione di Azure crea un'associazione con i runbook figlio. Se i runbook figlio non sono già stati pubblicati, il runbook padre sembra pubblicare correttamente, ma genera un'eccezione all'avvio.

Se si verifica un'eccezione, è possibile ripubblicare il runbook padre per fare riferimento correttamente ai runbook figlio. Non è necessario ripubblicare il runbook padre se viene modificato un runbook figlio perché l'associazione è già stata creata.

I dati dei parametri di un runbook figlio chiamato inline possono essere di qualsiasi tipo, inclusi oggetti complessi. Non esiste alcuna serializzazione JSON, perché è presente quando si avvia il runbook usando il portale di Azure o usando il cmdlet Start-AzAutomationRunbook.

Tipi di runbook

Attualmente, PowerShell 5.1 è supportato e solo determinati tipi di runbook possono chiamarsi tra loro:

  • Un runbook di PowerShell e un runbook grafico possono chiamarsi tra loro inline, perché entrambi sono basati su PowerShell.
  • Un runbook del flusso di lavoro PowerShell e un runbook grafico del flusso di lavoro PowerShell possono chiamarsi tra loro inline, perché entrambi sono basati sul flusso di lavoro powerShell.
  • I tipi di PowerShell e i tipi di flusso di lavoro PowerShell non possono chiamarsi tra loro inline. Devono usare Start-AzAutomationRunbook.

Importante

L'esecuzione di script figlio con .\child-runbook.ps1 non è supportata in PowerShell 7.1 e PowerShell 7.2 Soluzione alternativa: usare Start-AutomationRunbook (cmdlet interno) o Start-AzAutomationRunbook (dal modulo Az.Automation ) per avviare un altro runbook dal runbook padre.

L'ordine di pubblicazione dei runbook è importante solo per i runbook del flusso di lavoro PowerShell e per i runbook grafici del flusso di lavoro PowerShell.

Quando il runbook chiama un runbook figlio grafico o flusso di lavoro PowerShell usando l'esecuzione inline, usa il nome del runbook. Il nome deve iniziare con .\\ per specificare che lo script si trova nella directory locale.

Esempio

Nell'esempio seguente viene avviato un runbook figlio di test che accetta un oggetto complesso, un valore intero e un valore booleano. L'output del runbook figlio viene assegnato a una variabile. In questo caso, il runbook figlio è un runbook del flusso di lavoro PowerShell.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = PSWF-ChildRunbook -VM $vm -RepeatCount 2 -Restart $true

Di seguito è riportato lo stesso esempio, ma si usa un runbook di PowerShell come figlio.

$vm = Get-AzVM -ResourceGroupName "LabRG" -Name "MyVM"
$output = .\PS-ChildRunbook.ps1 -VM $vm -RepeatCount 2 -Restart $true

Avviare un runbook figlio usando un cmdlet

Importante

Se il runbook chiama un runbook figlio usando il cmdlet con il Start-AzAutomationRunbookWait parametro e il runbook figlio produce un risultato dell'oggetto, l'operazione potrebbe riscontrare un errore. Per risolvere l'errore, vedere Runbook figlio con output dell'oggetto. Questo articolo illustra come implementare la logica per eseguire il polling dei risultati usando il cmdlet Get-AzAutomationJobOutputRecord .

È possibile usare Start-AzAutomationRunbook per avviare un runbook, come descritto in Avviare un runbook con Windows PowerShell. Per questo cmdlet sono disponibili due modalità di utilizzo:

  • Il cmdlet restituisce l'ID processo quando viene creato il processo per il runbook figlio.
  • Il cmdlet attende il completamento del processo figlio e restituisce l'output del runbook figlio. Lo script abilita questa modalità specificando il Wait parametro .

Il processo di un runbook figlio avviato con un cmdlet viene eseguito separatamente dal processo del runbook padre. Questo comportamento comporta più processi rispetto all'avvio inline del runbook e rende i processi più difficili da tenere traccia. L'elemento padre può avviare più runbook figlio in modo asincrono senza attendere il completamento di ogni runbook. Per questa esecuzione parallela che chiama i runbook figlio inline, il runbook padre deve usare la parola chiave parallela.

L'output del runbook figlio non torna al runbook padre in modo affidabile a causa di tempi. Inoltre, $VerbosePreference, $WarningPreferencee altre variabili potrebbero non essere propagate ai runbook figlio. Per evitare questi problemi, è possibile avviare i runbook figlio come processi di automazione separati usando Start-AzAutomationRunbook con il Wait parametro . Questa tecnica blocca il runbook padre fino al termine del runbook figlio.

Se non si vuole che il runbook padre venga bloccato in attesa, è possibile avviare il runbook figlio usando Start-AzAutomationRunbook senza il Wait parametro . In questo caso, il runbook deve usare Get-AzAutomationJob per attendere il completamento del processo. Deve anche usare Get-AzAutomationJobOutput e Get-AzAutomationJobOutputRecord per recuperare i risultati.

I parametri per un runbook figlio avviato con un cmdlet vengono resi disponibili sotto forma di tabella hash, come descritto in Parametri di runbook. È possibile usare solo tipi di dati semplici. Se il runbook ha un parametro con un tipo di dati complesso, deve essere chiamato inline.

Il contesto della sottoscrizione potrebbe andare perso quando si avviano runbook figlio come processi separati. Perché il runbook figlio possa eseguire i cmdlet del modulo Az per una sottoscrizione di Azure specifica, il runbook figlio deve eseguire l'autenticazione in tale sottoscrizione indipendentemente dal runbook padre.

Se i processi nello stesso account di Automazione usano più sottoscrizioni, la selezione di una sottoscrizione in un processo può cambiare il contesto della sottoscrizione attualmente selezionata anche per altri processi. Per evitare questa situazione, usare Disable-AzContextAutosave -Scope Process all'inizio di ogni runbook. Questa azione salva solo il contesto dell'esecuzione del runbook.

Esempio

L'esempio seguente avvia un runbook figlio con parametri e quindi attende il completamento usando il Start-AzAutomationRunbook cmdlet con il Wait parametro . Al termine del runbook figlio, l'esempio raccoglie l'output del cmdlet dal runbook figlio. Per usare Start-AzAutomationRunbook lo script deve eseguire l'autenticazione alla sottoscrizione di Azure.

# Ensure that the runbook does not inherit an AzContext
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

$params = @{"VMName"="MyVM";"RepeatCount"=2;"Restart"=$true}

Start-AzAutomationRunbook `
    -AutomationAccountName 'MyAutomationAccount' `
    -Name 'Test-ChildRunbook' `
    -ResourceGroupName 'LabRG' `
    -DefaultProfile $AzureContext `
    -Parameters $params -Wait

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:

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

Passaggi successivi