Criar runbooks modulares na Automaçã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: em linha ou por meio de um cmdlet. A tabela a seguir resume as diferenças entre elas para você decidir qual é a melhor para os seus cenários.

Embutido Cmdlet
Trabalho Os runbooks filhos são executados no mesmo trabalho que o pai. Um trabalho separado é criado para o runbook filho.
Execução O runbook pai aguarda a finalização do runbook filho antes de continuar. O runbook pai continua imediatamente após o runbook filho ser iniciado ou aguarda a finalização do trabalho filho.
Saída O runbook pai pode receber a saída diretamente do runbook filho. O runbook pai tem que recuperar a saída do trabalho do runbook filho ou pode receber a saída diretamente do runbook filho.
Parâmetros Os valores para os parâmetros de runbook filho são especificados separadamente e podem usar qualquer tipo de dados. Os valores para os parâmetros do runbook filho devem ser combinados em uma única tabela de hash. Essa tabela de hash pode incluir apenas tipos de dados simples, de matriz e de objeto que usam a serialização JSON.
Conta de Automação O runbook pai pode usar um runbook filho somente 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 com a qual você tenha uma conexão.
Publicação Um runbook filho tem que ser publicado antes da publicação do runbook pai. Um runbook filho tem que ser publicado antes do início do runbook pai.

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

Para chamar um runbook em linha por meio de outro runbook, use o nome dele e dê valores aos parâmetros exatamente como você faria ao usar uma atividade ou um cmdlet. Todos os runbooks na mesma conta de Automação estão disponíveis para que todos os outros os usem dessa maneira. O runbook pai aguarda a finalização do runbook filho antes de passar para a próxima linha. Além disso, nenhuma saída é retornada diretamente ao pai.

Quando você chama um runbook em linha, ele é executado no mesmo trabalho que o runbook pai. Não há nenhuma indicação no histórico de trabalhos do runbook filho. Todas as exceções e saídas de fluxo do runbook filho são associadas ao pai. Esse comportamento resulta em menos trabalhos e facilita o controle e a solução de problemas.

Quando um runbook é publicado, todos os runbooks filhos que ele chamar já devem ter sido publicados. Isso ocorre porque a Automação do Azure cria uma associação com os runbooks filhos quando um runbook é compilado. Se os runbooks filho ainda não tiverem sido publicados, o runbook pai parecerá publicar corretamente, mas gerará uma exceção quando for iniciado.

Caso apareça uma exceção, publique novamente o runbook pai para referenciar de forma correta os runbooks filho. Não será preciso publicar o runbook pai novamente se um runbook filho for alterado, porque a associação já foi criada.

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

Tipos de runbook

No momento, há suporte para o PowerShell 5.1 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 em linha, pois os dois 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, pois os dois são baseados no fluxo de trabalho do PowerShell.
  • Os tipos de fluxo de trabalho do PowerShell e os do PowerShell não podem chamar uns aos outros em linha. Eles têm que usar Start-AzAutomationRunbook.

Importante

Não há suporte para a execução de scripts filho usando .\child-runbook.ps1 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 é importante apenas para os runbooks de fluxo de trabalho do PowerShell e os runbooks gráficos de fluxo de trabalho do PowerShell.

Quando seu runbook chama um runbook filho ou gráfico de fluxo de trabalho do PowerShell com a execução em linha, ele usa o nome do runbook. Esse nome tem que 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 booliano. 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

A seguir, temos o mesmo exemplo, mas com 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 com um cmdlet

Importante

Caso seu runbook invoque um runbook filho com o cmdlet Start-AzAutomationRunbook e o parâmetro Wait e o runbook filho gere um resultado de objeto, talvez a operação encontre um erro. Para resolver isso, confira Runbooks filho com saída de objeto. Esse artigo mostra como implementar a lógica para sondar os resultados com o cmdlet Get-AzAutomationJobOutputRecord.

É possível usar o cmdlet Start-AzAutomationRunbook para iniciar um runbook, conforme descrito em Iniciar um runbook com o Windows PowerShell. Há dois modos de usar esse cmdlet:

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

O trabalho de um runbook filho iniciado com um cmdlet é executado separado do runbook pai. Esse comportamento resulta em mais trabalhos do que ao iniciar o runbook em linha, além de dificultar o acompanhamento deles. O pai pode iniciar mais de um runbook filho de forma assíncrona sem aguardar a finalização de cada um. Para essa execução paralela chamando os runbooks filho embutidos, o runbook pai deve usar o palavra-chave parallel.

A saída do runbook filho não retorna ao runbook pai de modo confiável devido ao tempo. Além disso, $VerbosePreference, $WarningPreference e outras variáveis podem não ser propagadas para os runbooks filho. Para evitar esses problemas, inicie os runbooks filho como trabalhos de Automação separados usando Start-AzAutomationRunbook com o parâmetro Wait. Essa técnica bloqueia o runbook pai até que o runbook filho seja finalizado.

Caso não deseje que o runbook pai seja bloqueado em espera, inicie o runbook filho usando Start-AzAutomationRunbook sem o parâmetro Wait. Nesse caso, o 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.

Parâmetros de um runbook filho iniciados com um cmdlet são fornecidos como uma tabela de hash, conforme descrito em Parâmetros de runbook. Você pode usar apenas tipos de dados simples. Se o runbook tem um parâmetro com um tipo de dados complexos, é necessário chamá-lo em linha.

É possível perder o contexto da assinatura caso você inicie os runbooks filho como trabalhos separados. Para que o runbook filho execute cmdlets do módulo Az em uma assinatura específica do Azure, o runbook filho precisa se autenticar nessa assinatura independentemente do runbook pai.

Se os trabalhos na mesma conta de Automação funcionarem com mais de uma assinatura, a seleção de uma assinatura em um trabalho poderá mudar o contexto da assinatura atualmente selecionada para outros trabalhos. Para evitar esse problema, use Disable-AzContextAutosave -Scope Process no início de cada runbook. Essa ação apenas salva o contexto nessa execução de runbook.

Exemplo

O exemplo a seguir inicia um runbook filho com parâmetros e aguarda que ele seja finalizado com o cmdlet Start-AzAutomationRunbook e o parâmetro Wait. Após a finalização do runbook filho, o exemplo coleta a saída do cmdlet do runbook filho. Para usar Start-AzAutomationRunbook, o script precisa se autenticar na 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 pelo sistema, deixe o código no estado em que se encontra. Se você preferir usar uma identidade gerenciada atribuída pelo usuário, então:

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

Próximas etapas