Tutorial: Criar um runbook de Fluxo de Trabalho do PowerShell na Automação

Artigo
05/11/2023

Este tutorial orienta você durante a criação de um runbook de Fluxo de Trabalho do PowerShell na Automaçã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 diretamente usando o editor de texto do portal do Azure.

Observação

Este artigo é aplicável ao PowerShell 5.1; PowerShell 7.1 (versão prévia) e PowerShell 7.2 não dá suporte a fluxos de trabalho.

Neste tutorial, você aprenderá a:

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

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

Pré-requisitos

Uma conta da Automação do Azure com pelo menos uma identidade gerenciada atribuída pelo usuário. Para obter mais informações, confira Habilitar identidades gerenciadas.
Módulos Az: Az.Accounts e Az.Compute importados para a conta de Automação. Para obter mais informações, confira Importar módulos Az.
Duas ou mais máquinas virtuais do Azure. Como você para e inicia esses máquinas, elas não devem ser VMs de produção.
O módulo Azure Az do PowerShell instalado em seu computador. Para instalar ou atualizar, confira Como instalar o módulo Azure Az do PowerShell.

Atribuir permissões a identidades gerenciadas

Atribua permissões à identidade gerenciada adequada para permitir que ela pare e inicie uma máquina virtual. O runbook pode usar a identidade gerenciada atribuída pelo sistema ou pelo usuário da conta de Automação. As etapas são fornecidas para atribuir permissões a cada identidade. Use o portal do Azure nas etapas a seguir. Se você preferir usar o PowerShell, confira 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 (versão prévia) .
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 (versão prévia) para abrir a página Adicionar atribuição de função (versão prévia) .

Selecione os valores apropriados.

Propriedade	Description
Escopo	O escopo é um conjunto de recursos ao qual a atribuição de função se aplica. Na lista suspensa, selecione Grupo de Recursos.
Subscription	Esse campo deve ser preenchido automaticamente com sua assinatura.
Grupo de recursos	Na lista suspensa, selecione o grupo de recursos para o 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 voltar para a guia Atribuído pelo sistema.
Selecionar a guia Atribuído pelo usuário.
Selecione sua identidade gerenciada atribuída pelo usuário na lista para abrir a página Identidade Gerenciada.
Anote a ID do cliente para as etapas posteriores.
No menu esquerdo, selecione Atribuições de função do Azure e + Adicionar atribuição de função (versão prévia) para abrir a página Adicionar atribuição de função (versão prévia) .

Selecione os valores apropriados.

Propriedade	Description
Escopo	Na lista suspensa, selecione Grupo de Recursos.
Subscription	Esse campo deve ser preenchido automaticamente com sua assinatura.
Grupo de recursos	Na lista suspensa, selecione o grupo de recursos para o 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 voltar à guia Atribuído pelo usuário.

Criar o novo runbook

Comece criando um runbook de Fluxo de Trabalho simples 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 com um script típico.

Observação

Na versão, há uma nova experiência de criação de runbook no portal do Azure. Quando você seleciona a folha Runbooks>Criar um runbook, uma nova página Criar um runbook é aberta com as opções aplicáveis.

Na página da sua 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 runtime, selecione 5.1.
4. Insira uma Descrição aplicável.
5. Selecione Criar.

Adicionar código ao runbook

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

No momento, seu runbook está vazio, com apenas a palavra-chave Workflow necessária, o nome do seu runbook e as chaves que encerrarão o fluxo de trabalho inteiro.

Workflow MyFirstRunbook-Workflow
{
}

É possível utilizar a palavra-chave Parallel para criar um bloco de script com diversos comandos que serão executados simultaneamente. Insira o seguinte código entre chaves:

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 clicando em Salvar.

Testar o runbook

Antes de publicar o runbook para disponibilizá-lo na produção, você deve testá-lo para verificar se ele funciona corretamente. Ao testar um runbook, você executa sua versão de rascunho e pode ver a saída dele interativamente.

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

O status do trabalho inicia como Na fila, indicando que o trabalho está aguardando um trabalho de runbook na nuvem ficar disponível. O status é alterado para Iniciando quando um trabalho reivindica o trabalho. Por fim, o status se torna Em execução quando o runbook começa a ser executado.
Quando o trabalho do runbook é concluído, a página Teste é exibida no painel. A saída deve ser semelhante à seguinte imagem:

Examine a saída. Tudo no bloco Parallel, incluindo o comando Start-Sleep, executado ao mesmo tempo. Os mesmos comandos fora do bloco Parallel foram executados em sequência, conforme mostrado pelos diferentes carimbos de data/hora.
Feche a página Testar para voltar à tela.

Publicar e iniciar o runbook

O runbook que você criou ainda está em modo de Rascunho. Você precisa publicá-lo antes que possa executá-lo na produção. Quando você publica um runbook, substitui a versão Publicada existente pela versão de Rascunho. Nesse caso, ainda não há uma versão publicada porque você acabou de criar o runbook.

Selecione Publicar para publicar o runbook e em Sim quando solicitado.
O campo Status agora mostra Publicado. Examine as opções na parte superior que permitem que você inicie o runbook imediatamente, faça o agendamento para ele ser iniciado em algum momento no futuro ou crie um webhook para que o runbook possa ser iniciado por meio de uma chamada HTTP. Selecione Iniciar e em Sim quando solicitado para iniciar o runbook.
Uma página Trabalho é aberta para o trabalho de runbook criado. Nesse caso, deixe a página aberta para que você possa ver o progresso do trabalho. O campo Status corresponde aos status que você viu ao testar o runbook.
Depois que o status do runbook mostrar Concluído, clique em Saída. A saída deve ser semelhante à saída do teste.
Feche a página Trabalho para voltar à página Visão geral do runbook.
Em Recursos, selecione Trabalhos. Esta página lista todos os trabalhos criados pelo seu runbook. Você deve ver apenas 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 essa página para exibir os detalhes de qualquer trabalho criado para o runbook. Feche a página Trabalho para voltar à página Visão geral do runbook.

Adicionar a autenticação para gerenciar os recursos do Azure

Você testou e publicou seu runbook, mas, até o momento, ele não faz nada útil. Você gostaria que ele gerencie recursos do Azure. Ele não pode fazer isso, a menos que seja autenticado usando as credenciais da assinatura. O runbook usa a identidade gerenciada atribuída pelo sistema da conta de Automação para se 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 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 $resourceGroup por um valor válido que representa o grupo de recursos.

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 9, remova Connect-AzAccount -Identity,
2. Substitua-o por Connect-AzAccount -Identity -AccountId <ClientId> e
3. Insira a ID de cliente obtida anteriormente.
Selecione Salvar e Testar painel.
Clique em Iniciar para iniciar o teste. Quando ele for concluído, você deverá ver uma saída semelhante ao exemplo a seguir, que exibe informações básicas de sua conta. Essa ação confirma que a credencial é válida.
Feche a página Testar para voltar à tela.

Adicionar código para iniciar uma máquina virtual

Agora que o seu runbook está se autenticando na sua assinatura do Azure, você pode gerenciar os recursos. Adicionamos um comando para iniciar uma máquina virtual. Você pode escolher qualquer VM em sua assinatura do Azure e, por enquanto, codificará 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 que a VM foi iniciada. Em seguida, retorne à tela.

Adicionar parâmetros de entrada ao runbook

Atualmente, o runbook inicia a VM que você codificou no runbook. Ele será mais útil se você puder especificar a VM quando o runbook for iniciado. Adicione os 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 Start-AzVM anterior pelo seguinte:

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

Teste o runbook e confirme que a VM foi iniciada. Em seguida, retorne à tela.

Gerenciar várias VMs simultaneamente

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

Aceite uma coleção de nomes de máquina virtual,
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 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 9, remova Connect-AzAccount -Identity,
2. Substitua-o por Connect-AzAccount -Identity -AccountId <ClientId> e
3. Insira a ID de cliente obtida anteriormente.
Clique em Salvar, em Publicar e Sim quando solicitado.
Na página Visão Geral, selecione Iniciar.

Preencha os parâmetros e selecione OK.

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

Navegue até a lista de máquinas virtuais e atualize a página a cada poucos segundos. Observe que a ação de cada VM ocorre em paralelo. Sem a palavra-chave -Parallel, as ações teriam sido executadas sequencialmente. Embora as VMs sejam iniciadas sequencialmente, cada uma delas pode chegar à fase Em execução em tempos diferentes de acordo com as características de cada VM.

Limpar os recursos

Caso não vá continuar usando esse runbook, exclua-o seguindo estas etapas:

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

Próximas etapas

Neste tutorial, você criou um runbook de fluxo de trabalho do PowerShell. Para examinar os runbooks do Python 3, confira:

Tutorial: criar um runbook do Python 3