Tutorial: Criar um runbook de fluxo de trabalho do PowerShell em Automação

Artigo
11/22/2023

Este tutorial explica como criar um Runbook do Fluxo de Trabalho do PowerShell na Automatização do Azure. Os runbooks do Fluxo de Trabalho do PowerShell são runbooks de texto baseados no Fluxo de Trabalho do Windows PowerShell. Você pode criar e editar o código do runbook usando o editor de texto no portal do Azure.

Nota

Este artigo é aplicável ao PowerShell 5.1; O PowerShell 7.1 (visualização) e o PowerShell 7.2 não oferecem suporte a fluxos de trabalho.

Neste tutorial, irá aprender a:

Criar um runbook de Fluxo de Trabalho do PowerShell
Testar e publicar o runbook
Executar e controlar o status do trabalho do runbook
Adicionar autenticação para gerenciar recursos do Azure
Atualizar os parâmetros do runbook para iniciar uma máquina virtual do Azure

Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.

Pré-requisitos

Uma conta da Automatização do Azure com, pelo menos, uma identidade gerida atribuída pelo utilizador. Para obter mais informações, consulte Habilitar identidade gerenciada.
Módulos Az: Az.Accounts e Az.Compute importados para a conta de automação. Para mais informações, consulte Importar módulos Az.
Duas ou mais máquinas virtuais do Azure. Como você para e inicia essas máquinas, elas não devem ser VMs de produção.
O módulo Azure Az PowerShell instalado em sua máquina. Para instalar ou atualizar, consulte Como instalar o módulo Azure Az PowerShell.

Atribuir permissões a identidades gerenciadas

Atribua permissões à identidade gerenciada apropriada para permitir que ela pare uma máquina virtual. O runbook pode usar a identidade gerenciada atribuída pelo sistema de conta de automação ou uma identidade gerenciada atribuída pelo usuário. São fornecidas etapas para atribuir permissões a cada identidade. As etapas abaixo usam o portal do Azure. Se preferir usar o PowerShell, consulte Atribuir funções do Azure usando o Azure PowerShell.

Entre no portal do Azure e navegue até sua conta de automação.
Em Configurações da conta, selecione Identidade (visualização).
Na guia Sistema atribuído, em Permissões, selecione Atribuições de função do Azure para abrir a página Atribuições de função do Azure.
Selecione + Adicionar atribuição de função (Pré-visualização) para abrir a página Adicionar atribuição de função (Pré-visualização ).

Selecione os valores apropriados.

Propriedade	Description
Scope	Escopo é um conjunto de recursos ao qual a atribuição de função se aplica. Na lista suspensa, selecione Grupo de Recursos.
Subscrição	Este campo deve ser preenchido automaticamente com a sua subscrição.
Grupo de Recursos	Na lista suspensa, selecione o grupo de recursos ao qual conceder as permissões de identidade.
Função	Na lista suspensa, selecione Usuário do DevTest Labs.

Selecione Salvar e feche a página Atribuições de função do Azure para retornar à guia Sistema atribuído.
Selecione a guia Usuário atribuído .
Selecione sua identidade gerenciada atribuída pelo usuário na lista para abrir a página Identidade gerenciada .
Anote a ID do Cliente para uso posterior.
No menu à esquerda, selecione Atribuições de função do Azure e, em seguida, + Adicionar atribuição de função (Visualização) para abrir a página Adicionar atribuição de função (Visualização ).

Selecione os valores apropriados.

Propriedade	Description
Scope	Na lista suspensa, selecione Grupo de Recursos.
Subscrição	Este campo deve ser preenchido automaticamente com a sua subscrição.
Grupo de Recursos	Na lista suspensa, selecione o grupo de recursos ao qual conceder as permissões de identidade.
Função	Na lista suspensa, selecione Usuário do DevTest Labs.

Selecione Salvar e feche a página Atribuições de função do Azure para retornar à guia Usuário atribuído.

Criar novo runbook

Comece criando um runbook simples do Fluxo de Trabalho do PowerShell. Uma vantagem dos Fluxos de Trabalho do Windows PowerShell é a capacidade de executar um conjunto de comandos em paralelo em vez de sequencialmente, como acontece com um script típico.

Nota

Com o lançamento, a criação de runbook tem uma nova experiência no portal do Azure. Quando você seleciona a lâmina> Runbooks Criar um runbook, uma nova página Criar um runbook é aberta com as opções aplicáveis.

Na página da conta de automação aberta, em Automação de processos, selecione Runbooks
Selecione + Criar um runbook.
1. Nomeie o runbook. Por exemplo, teste.
2. No menu suspenso Tipo de runbook, selecione Fluxo de trabalho do PowerShell.
3. Na lista suspensa Versão do tempo de execução , selecione 5.1.
4. Insira a Descrição aplicável.
5. Selecione Criar.

Adicionar código ao runbook

Você pode digitar código diretamente no runbook ou selecionar cmdlets, runbooks e ativos do controle Library e adicioná-los ao runbook com quaisquer parâmetros relacionados. Para este tutorial, você digita o código diretamente no runbook.

Atualmente, seu runbook está vazio apenas com a palavra-chave necessária Workflow , o nome do runbook e as chaves que envolvem todo o fluxo de trabalho.

Workflow MyFirstRunbook-Workflow
{
}

Você pode usar a Parallel palavra-chave para criar um bloco de script com vários comandos que serão executados simultaneamente. Insira o seguinte código entre os aparelhos:

Parallel {
     Write-Output "Parallel"
     Get-Date
     Start-Sleep -s 3
     Get-Date
 }

Write-Output " `r`n"
Write-Output "Non-Parallel"
Get-Date
Start-Sleep -s 3
Get-Date

Salve o runbook selecionando Salvar.

Testar o runbook

Antes de publicar o runbook para disponibilizá-lo em produção, você deve testá-lo para garantir que ele funcione corretamente. O teste de um runbook executa sua versão Draft e permite que você visualize sua saída interativamente.

Selecione Painel de teste para abrir a página Teste .
Selecione Iniciar para iniciar o teste. Um trabalho de runbook é criado e seu status é exibido no painel.

O status do trabalho começa como Enfileirado, indicando que o trabalho está aguardando que um trabalhador runbook na nuvem fique disponível. O status muda para Iniciando quando um trabalhador reivindica o emprego. Finalmente, o status se torna Executando quando o runbook realmente começa a ser executado.
Quando o trabalho do runbook for concluído, a página Teste exibirá sua saída. A saída deve ser semelhante à seguinte imagem:

Reveja a saída. Tudo no Parallel bloco, incluindo o Start-Sleep comando, executado ao mesmo tempo. Os mesmos comandos fora do Parallel bloco eram executados sequencialmente, como mostram os diferentes carimbos de data e hora.
Feche a página Teste para retornar à tela.

Publicar e iniciar o runbook

O runbook que você criou ainda está no modo Rascunho. Tem de publicá-lo antes de o poder executar em produção. Quando publica um runbook, substitui a versão Publicada existente pela versão de Rascunho. Neste caso, ainda não tem uma versão Publicada porque acabou de criar o runbook.

Selecione Publicar para publicar o runbook e, em seguida, Sim quando solicitado.
O campo Status agora mostra Publicado. Revise as opções na parte superior que permitem iniciar o runbook agora, agendar uma hora de início futura ou criar um webhook para que o runbook possa ser iniciado por meio de uma chamada HTTP. Selecione Iniciar e, em seguida, Sim quando lhe for pedido para iniciar o runbook.
Uma página Trabalho é aberta para o trabalho de runbook que foi criado. Neste caso, deixe a página aberta para que possa acompanhar o progresso do trabalho. O campo Status corresponde aos status que você viu ao testar o runbook.
Quando o status do runbook mostrar Concluído, selecione Saída. A saída deve ser semelhante à saída do teste.
Feche a página Trabalho para retornar à página Visão geral do runbook.
Em Recursos, selecione Trabalhos. Esta página lista todos os trabalhos criados pelo seu runbook. Você só deve ver um trabalho listado, já que você executou o trabalho apenas uma vez.
Selecione o trabalho para abrir a mesma página Trabalho que você visualizou quando iniciou o runbook. Use esta página para visualizar os detalhes de qualquer trabalho criado para o runbook. Feche a página Trabalho para retornar à página Visão geral do runbook.

Adicionar autenticação para gerenciar recursos do Azure

Testou e publicou o seu runbook, mas, até ao momento, não faz nada de útil. Deve fazer com que gira os recursos do Azure. Ele não pode fazer isso a menos que se autentique usando as credenciais da assinatura. O runbook usa a identidade gerenciada atribuída ao sistema da conta de automação para autenticar com o Azure para executar a ação de gerenciamento na VM. O runbook pode ser facilmente modificado para usar uma identidade gerenciada atribuída pelo usuário.

Selecione Visão geral e, em seguida, Editar para abrir o editor de texto.

Substitua o código existente pelo seguinte:

workflow MyFirstRunbook-Workflow
{
$resourceGroup = "resourceGroupName"

# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process

# Connect to Azure with system-assigned managed identity
Connect-AzAccount -Identity

# set and store context
$AzureContext = Set-AzContext –SubscriptionId "<SubscriptionID>"
}

Edite a variável com um valor válido que represente $resourceGroup seu grupo de recursos.

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 9, remova Connect-AzAccount -Identity,
2. Substitua-o por Connect-AzAccount -Identity -AccountId <ClientId>, e
3. Introduza o ID de Cliente obtido anteriormente.
Selecione Salvar e, em seguida, Painel de teste.
Selecione Iniciar para iniciar o teste. Depois de concluído, você verá uma saída semelhante à seguinte, exibindo informações básicas da sua conta. Esta ação confirma que a credencial é válida.
Feche a página Teste para retornar à tela.

Adicionar código para iniciar uma máquina virtual

Agora que seu runbook está se autenticando na assinatura do Azure, você pode gerenciar recursos. Adicione um comando para iniciar uma máquina virtual. Você pode escolher qualquer VM em sua assinatura do Azure e, por enquanto, está codificando esse nome no runbook.

Adicione o código abaixo como a última linha imediatamente antes da chave de fechamento. Substitua VMName pelo nome real de uma VM.
```
Start-AzVM -Name "VMName" -ResourceGroupName $resourceGroup -DefaultProfile $AzureContext
```
Teste o runbook e confirme se a VM foi iniciada. Em seguida, volte para a tela.

Adicionar parâmetros de entrada ao runbook

Seu runbook atualmente inicia a VM que você codificou no runbook. Será mais útil se você puder especificar a VM quando o runbook for iniciado. Adicione parâmetros de entrada ao runbook para fornecer essa funcionalidade.

Substitua a linha 3, , $resourceGroup = "resourceGroupName"pelo seguinte:
```
Param(
    [string]$resourceGroup,
    [string]$VMName
)
```

Substitua o comando anterior Start-AzVM pelo seguinte:

Start-AzVM -Name $VMName -ResourceGroupName $resourceGroup -DefaultProfile $AzureContext

Teste o runbook e confirme se a VM foi iniciada. Em seguida, volte para a tela.

Gerencie várias VMs simultaneamente

Você pode usar a ForEach -Parallel construção para processar comandos para cada item em uma coleção simultaneamente. Revise o código para que o runbook agora:

Aceitar uma coleção de nomes de máquinas virtuais,
Aceite um parâmetro para parar ou iniciar as máquinas virtuais e
Execute as ações em paralelo em todas as máquinas virtuais

Substitua todo o código existente pelo seguinte:

workflow MyFirstRunbook-Workflow
{
   Param(
       [string]$resourceGroup,
       [string[]]$VMs,
       [string]$action
   )

   # Ensures you do not inherit an AzContext in your runbook
   Disable-AzContextAutosave -Scope Process

   # Connect to Azure with system-assigned managed identity
   Connect-AzAccount -Identity

   # set and store context
   $AzureContext = Set-AzContext –SubscriptionId "<SubscriptionID>"

   # Start or stop VMs in parallel
   if ($action -eq "Start") {
       ForEach -Parallel ($vm in $VMs)
       {
           Start-AzVM -Name $vm -ResourceGroupName $resourceGroup -DefaultProfile $AzureContext
       }
   }
   elseif ($action -eq "Stop") {
       ForEach -Parallel ($vm in $VMs)
       {
           Stop-AzVM -Name $vm -ResourceGroupName $resourceGroup -DefaultProfile $AzureContext -Force
       }
   }
   else {
       Write-Output "`r`n Action not allowed. Please enter 'stop' or 'start'."
   }
   }

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 9, remova Connect-AzAccount -Identity,
2. Substitua-o por Connect-AzAccount -Identity -AccountId <ClientId>, e
3. Introduza o ID de Cliente obtido anteriormente.
Selecione Salvar, Publicar e Sim quando solicitado.
Na página Visão geral, selecione Iniciar.

Preencha os parâmetros e selecione OK.

Parâmetro	Description
GRUPO DE RECURSOS	Insira o nome do grupo de recursos das VMs.
VMs	Insira os nomes das máquinas virtuais usando a seguinte sintaxe: `["VM1","VM2","VM3"]`
Ação	Digite `stop` ou `start`.

Navegue até sua lista de máquinas virtuais e atualize a página a cada poucos segundos. Observe que a ação para cada VM acontece em paralelo. Sem a palavra-chave -Parallel , as ações teriam sido executadas sequencialmente. Embora as VMs sejam iniciadas sequencialmente, cada VM pode atingir a fase de Execução em momentos ligeiramente diferentes com base nas características de cada VM.

Clean up resources (Limpar recursos)

Se você não vai continuar a usar este runbook, exclua-o com as seguintes etapas:

Navegue até sua conta de automação.
Em Automação de processos, selecione Runbooks.
Selecione o runbook.
Na página Visão geral do runbook, selecione Excluir.

Próximos passos

Neste tutorial, você criou um runbook de fluxo de trabalho do PowerShell. Para dar uma olhada nos runbooks do Python 3, consulte:

Tutorial: Criar um runbook Python 3