Criar runbooks modulares na Automatização

  • Artigo

É uma boa prática na Automação do Azure escrever runbooks reutilizáveis e modulares com uma função discreta que outros runbooks chamam. Um runbook pai geralmente chama um ou mais runbooks filho para executar a funcionalidade necessária.

Há duas maneiras de chamar um runbook filho: inline ou por meio de um cmdlet. A tabela a seguir resume as diferenças para ajudá-lo a decidir qual caminho é melhor para seus cenários.

Inline Cmdlet
Tarefa Os runbooks infantis são executados no mesmo trabalho que os pais. Um trabalho separado é criado para o runbook filho.
Execução O runbook pai aguarda que o runbook filho termine antes de continuar. O runbook pai continua imediatamente após o runbook filho ser iniciado, ou o runbook pai aguarda a conclusão do trabalho filho.
Saída O runbook pai pode obter diretamente a saída do runbook filho. O runbook pai deve recuperar a saída do trabalho runbook filho ou o runbook pai pode obter diretamente a saída do runbook filho.
Parâmetros Os valores para os parâmetros do runbook filho são especificados separadamente e podem usar qualquer tipo de dados. Os valores dos parâmetros do runbook subordinado têm de ser combinados numa única tabela hash. Essa hashtable pode incluir apenas tipos de dados simples, de matriz e de objeto que usam a serialização JSON.
Conta de Automatização O runbook pai pode usar apenas um runbook filho na mesma conta de automação. Os runbooks pai podem usar um runbook filho de qualquer conta de automação, da mesma assinatura do Azure e até mesmo de uma assinatura diferente à qual você tenha uma conexão.
Publicação Um runbook filho deve ser publicado antes que o runbook pai seja publicado. Um runbook filho é publicado a qualquer momento antes do runbook pai ser iniciado.

Chamar um runbook filho usando a execução em linha

Para chamar um runbook embutido de outro runbook, use o nome do runbook e forneça valores para seus parâmetros, assim como você usaria uma atividade ou um cmdlet. Todos os runbooks na mesma conta de automação estão disponíveis para todos os outros para serem usados desta forma. O runbook pai aguarda que o runbook filho termine antes de passar para a próxima linha, e qualquer saída retorna diretamente para o pai.

Quando você chama um runbook embutido, ele é executado no mesmo trabalho que o runbook pai. Não há nenhuma indicação no histórico de trabalho da caderneta infantil. Quaisquer exceções e quaisquer saídas de fluxo do runbook filho são associadas ao pai. Esse comportamento resulta em menos trabalhos e os torna mais fáceis de rastrear e solucionar problemas.

Quando um runbook é publicado, todos os runbooks filhos que ele chama já devem ser publicados. O motivo é que a Automação do Azure cria uma associação com qualquer runbook filho quando compila um runbook. Se os runbooks filho ainda não tiverem sido publicados, o runbook pai parece publicar corretamente, mas gera uma exceção quando é iniciado.

Se você obtiver uma exceção, poderá publicar novamente o runbook pai para fazer referência adequada aos runbooks filho. Não é necessário publicar novamente o runbook pai se algum runbook filho for alterado porque a associação já foi criada.

Os parâmetros de um runbook filho chamado inline podem ser de qualquer tipo de dados, incluindo objetos complexos. Não há serialização JSON, como há quando você inicia o runbook usando o portal do Azure ou usando o cmdlet Start-AzAutomationRunbook .

Tipos de runbooks

Atualmente, o PowerShell 5.1 é suportado e apenas determinados tipos de runbook podem chamar uns aos outros:

  • Um runbook do PowerShell e um runbook gráfico podem chamar um ao outro inline, porque ambos são baseados no PowerShell.
  • Um runbook de Fluxo de Trabalho do PowerShell e um runbook gráfico de Fluxo de Trabalho do PowerShell podem chamar um ao outro em linha, porque ambos são baseados no Fluxo de Trabalho do PowerShell.
  • Os tipos do PowerShell e os tipos de fluxo de trabalho do PowerShell não podem chamar um ao outro em linha. Eles devem usar Start-AzAutomationRunbook.

Importante

A execução de scripts filho usando .\child-runbook.ps1 não é suportada no PowerShell 7.1 e no PowerShell 7.2 Solução alternativa: use Start-AutomationRunbook (cmdlet interno) ou Start-AzAutomationRunbook (do módulo Az.Automation) para iniciar outro runbook a partir do runbook pai.

A ordem de publicação dos runbooks é importante apenas para o Fluxo de Trabalho do PowerShell e os runbooks gráficos do Fluxo de Trabalho do PowerShell.

Quando seu runbook chama um runbook filho gráfico ou do Fluxo de Trabalho do PowerShell usando a execução embutida, ele usa o nome do runbook. O nome deve começar com .\\ para especificar que o script está no diretório local.

Exemplo

O exemplo a seguir inicia um runbook filho de teste que aceita um objeto complexo, um valor inteiro e um valor booleano. A saída do runbook filho é atribuída a uma variável. Nesse caso, o runbook filho é um runbook de fluxo de trabalho do PowerShell.

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

Aqui está o mesmo exemplo, mas usando um runbook do PowerShell como filho.

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

Iniciar um runbook filho usando um cmdlet

Importante

Se o runbook chamar um runbook filho usando o cmdlet com o parâmetro e o Start-AzAutomationRunbookWait runbook filho produzir um resultado de objeto, a operação poderá encontrar um erro. Para contornar o erro, consulte Runbooks filho com saída de objeto. Esse artigo mostra como implementar a lógica para sondar os resultados usando o cmdlet Get-AzAutomationJobOutputRecord .

Você pode usar Start-AzAutomationRunbook para iniciar um runbook, conforme descrito em Iniciar um runbook com o Windows PowerShell. Há dois modos de uso para este cmdlet:

  • O cmdlet retorna a ID do trabalho quando o trabalho é criado para o runbook filho.
  • O cmdlet aguarda até que o trabalho filho seja concluído e retorna a saída do runbook filho. Seu script habilita esse modo especificando o Wait parâmetro.

O trabalho de um runbook filho iniciado com um cmdlet é executado separadamente do trabalho de runbook pai. Esse comportamento resulta em mais trabalhos do que iniciar o runbook em linha e torna os trabalhos mais difíceis de rastrear. O pai pode iniciar mais de um runbook filho de forma assíncrona sem esperar que cada um termine. Para essa execução paralela chamando os runbooks filho em linha, o runbook pai deve usar a palavra-chave paralela.

A saída do runbook filho não retorna ao runbook pai de forma confiável devido ao tempo. Além disso, , $VerbosePreference$WarningPreferencee outras variáveis podem não ser propagadas para os runbooks filho. Para evitar esses problemas, você pode iniciar os runbooks filho como trabalhos de automação separados usando Start-AzAutomationRunbook com o Wait parâmetro. Esta técnica bloqueia o runbook pai até que o runbook filho seja concluído.

Se você não quiser que o runbook pai seja bloqueado durante a espera, você pode iniciar o runbook filho usando Start-AzAutomationRunbook sem o Wait parâmetro. Nesse caso, seu runbook deve usar Get-AzAutomationJob para aguardar a conclusão do trabalho. Ele também deve usar Get-AzAutomationJobOutput e Get-AzAutomationJobOutputRecord para recuperar os resultados.

Os parâmetros para um runbook subordinado iniciado com um cmdlet são proporcionados sob a forma de uma tabela hash, conforme descrito em Parâmetros de runbooks. Você pode usar apenas tipos de dados simples. Se o runbook tiver um parâmetro com um tipo de dados complexo, ele deverá ser chamado inline.

O contexto da assinatura pode ser perdido quando você está iniciando runbooks filhos como trabalhos separados. Para que o runbook filho execute cmdlets do módulo Az em uma assinatura específica do Azure, o filho deve autenticar-se nessa assinatura independentemente do runbook pai.

Se os trabalhos dentro da mesma conta de automação funcionarem com mais de uma assinatura, selecionar uma assinatura em um trabalho poderá alterar o contexto de assinatura selecionado atualmente para outros trabalhos. Para evitar essa situação, use Disable-AzContextAutosave -Scope Process no início de cada runbook. Essa ação salva apenas o contexto para essa execução de runbook.

Exemplo

O exemplo a seguir inicia um runbook filho com parâmetros e, em seguida, aguarda que ele termine usando o cmdlet com o Start-AzAutomationRunbookWait parâmetro. Após a conclusão do runbook filho, o exemplo coleta a saída do cmdlet do runbook filho. Para usar Start-AzAutomationRunbooko , o script deve se autenticar em sua assinatura do 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 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:

  1. Da linha 5, remover $AzureContext = (Connect-AzAccount -Identity).context,
  2. Substitua-o por $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, e
  3. Insira a ID do cliente.

Próximos passos