Tutoriel : Créer un runbook de workflow PowerShell dans Automation

Article
05/11/2023

Ce didacticiel décrit la création d’un Runbook PowerShell Workflow dans Azure Automation. Les runbooks de workflow PowerShell sont des runbooks texte basés sur un workflow Windows PowerShell. Vous pouvez créer et modifier le code du runbook à l’aide de l’éditeur de texte du portail Azure.

Remarque

Cet article s’applique à PowerShell 5.1. PowerShell 7.1 (préversion) et PowerShell 7.2 ne prennent pas en charge les flux de travail.

Dans ce tutoriel, vous allez apprendre à :

Créer un runbook de workflow PowerShell
Tester et publier le runbook
Exécuter le travail du runbook et en suivre l’état
Ajouter une authentification pour gérer les ressources Azure
Mettre à jour les paramètres du runbook pour démarrer une machine virtuelle Azure

Si vous n’avez pas d’abonnement Azure, créez un compte gratuit avant de commencer.

Prérequis

Un compte Azure Automation avec au moins une identité managée affectée par l’utilisateur. Pour plus d’informations, consultez Activer l’identité managée.
Modules Az : Az.Accounts et Az.Compute importés dans le compte Automation. Pour plus d’informations, consultez Importer des modules Az.
Au moins deux machines virtuelles Azure. Étant donné que vous arrêtez et démarrez ces machines, celles-ci ne doivent pas être des machines virtuelles de production.
Le module PowerShell Azure Az installé sur votre ordinateur. Pour plus d'informations sur son installation ou sa mise à niveau, consultez Installer le module PowerShell Azure Az.

Attribuer des autorisations aux identités managées

Affectez des autorisations à l’identité managée appropriée pour lui permettre d’arrêter une machine virtuelle. Le runbook peut utiliser l’identité managée affectée par le système du compte Automation ou une identité managée affectée par l’utilisateur. Des étapes sont fournies pour affecter des autorisations à chaque identité. Les étapes ci-dessous utilisent le portail Azure. Si vous préférez utiliser PowerShell, consultez Attribuer des rôles Azure avec Azure PowerShell.

Connectez-vous au portail Azure et accédez à votre compte Automation.
Sous Paramètres du compte, sélectionnez Identité (préversion) .
Sous l’onglet Affecté par le système, sous Autorisations, sélectionnez Attributions de rôles Azure pour ouvrir la page Attributions de rôles Azure.
Sélectionnez + Ajouter une attribution de rôle (préversion) pour ouvrir la page Ajouter une attribution de rôle (préversion) .

Sélectionnez les valeurs appropriées.

Propriété	Description
Étendue	Une étendue est un ensemble de ressources auxquelles s’applique l’attribution de rôle. Dans la liste déroulante, sélectionnez Groupe de ressources.
Abonnement	Ce champ devrait être renseigné automatiquement avec votre abonnement.
Groupe de ressources	Dans la liste déroulante, sélectionnez le groupe de ressources sur lequel les autorisations d’identité doivent être accordées.
Rôle	Dans la zone de liste déroulante, sélectionnez Utilisateur DevTest Labs.

Sélectionnez Enregistrer, puis fermez la page Attributions de rôles Azure pour revenir à l’onglet Affecté par le système.
Sélectionnez l’onglet Affecté(e) par l’utilisateur.
Sélectionnez votre identité managée affectée par l’utilisateur dans la liste pour ouvrir la page Identité managée.
Notez l’ID client pour l’utiliser plus tard.
Dans le menu de gauche, sélectionnez Attributions de rôles Azure et + Ajouter une attribution de rôle (préversion) pour ouvrir la page Ajouter une attribution de rôle (préversion) .

Sélectionnez les valeurs appropriées.

Propriété	Description
Étendue	Dans la liste déroulante, sélectionnez Groupe de ressources.
Abonnement	Ce champ devrait être renseigné automatiquement avec votre abonnement.
Groupe de ressources	Dans la liste déroulante, sélectionnez le groupe de ressources sur lequel les autorisations d’identité doivent être accordées.
Rôle	Dans la zone de liste déroulante, sélectionnez Utilisateur DevTest Labs.

Sélectionnez Enregistrer, puis fermez la page Attributions de rôles Azure pour revenir à l’onglet Affecté par l’utilisateur.

Créer un runbook

Commencez par créer un runbook de workflow PowerShell simple. L'un des avantages des workflows Windows PowerShell est la possibilité d'exécuter un ensemble de commandes en parallèle, et non séquentiellement comme avec un script classique.

Notes

Avec cette version, la création de runbook a une nouvelle expérience dans le portail Azure. Quand vous sélectionnez le panneau Runbooks >Créer un runbook, une nouvelle page Créer un runbook s’ouvre avec les options applicables.

Dans la page de votre compte Automation ouvert, sous Automatisation de processus, sélectionnez Runbooks
Sélectionnez + Créer un runbook.
1. Nommez le runbook. Par exemple, test.
2. Dans le menu déroulant Type de runbook, sélectionnez Workflow PowerShell.
3. Dans la liste déroulante Version du runtime, sélectionnez 5.1.
4. Entrez la Description applicable.
5. Sélectionnez Créer.

Ajouter du code au Runbook

Vous pouvez soit taper du code directement dans le runbook, soit sélectionner des cmdlets, des runbooks et des ressources à partir du contrôle Bibliothèque, puis les ajouter au runbook avec tous les paramètres associés. Pour ce tutoriel, vous entrez le code directement dans le runbook.

Pour l’instant, votre runbook est vide, à l’exception du mot clé Workflow obligatoire, du nom de votre runbook et des accolades qui entourent la totalité du workflow.

Workflow MyFirstRunbook-Workflow
{
}

Vous pouvez utiliser le mot clé Parallel pour créer un bloc de script avec plusieurs commandes qui seront exécutées simultanément. Entrez le code suivant entre accolades :

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

Enregistrez le runbook en sélectionnant Enregistrer.

Tester le Runbook

Avant de publier le runbook pour le rendre disponible en production, vous devez le tester pour vous assurer qu’il fonctionne correctement. Le test d’un runbook exécute sa version Brouillon et vous permet d’afficher sa sortie de manière interactive.

Sélectionnez Volet de test pour ouvrir la page Test.
Sélectionnez Démarrer pour démarrer le test. Une tâche de runbook est créée et son état est affiché dans le volet.

L’état initial du travail est Mis en file d’attente pour indiquer qu’il attend qu’un Runbook Worker devienne disponible dans le cloud. L’état passe ensuite à Démarrage quand un Worker revendique le travail. Enfin, l’état passe à Exécution lorsque le runbook commence à s’exécuter.
Une fois le travail du runbook terminé, la page Test affiche sa sortie. Le résultat devrait être semblable à l’image suivante :

Passez en revue la sortie. Tout ce qui se trouve dans le bloc Parallel, y compris la commande Start-Sleep, a été exécuté en même temps. Les mêmes commandes en dehors du bloc Parallel ont été exécutées de manière séquentielle, comme indiqué par les différents horodatages de date.
Fermez la page Test pour revenir au canevas.

Publier et démarrer le Runbook

Le runbook que vous avez créé est toujours en mode brouillon. Vous devez le publier pour pouvoir l’exécuter en production. Lorsque vous publiez un Runbook, vous écrasez la version publiée existante par la version brouillon. Dans ce cas, vous n’avez pas encore de version publiée car vous venez de créer le runbook.

Sélectionnez l’option Publier pour publier le runbook, puis cliquez sur Oui quand vous y êtes invité.
Le champ État montre maintenant Publié. Passez en revue les options en haut qui vous permettent de démarrer le runbook maintenant, de planifier une heure de début à venir ou de créer un webhook pour démarrer le runbook via un appel HTTP. Cliquez sur Démarrer, puis sur Oui quand vous y êtes invité pour démarrer le runbook.
Une page Travail s’ouvre pour le travail du runbook qui a été créé. Dans le cas présent, laissez la page ouverte pour pouvoir suivre la progression du travail. Le champ État correspond aux états que vous avez vus lors du test du runbook.
Lorsque l’état du runbook est Terminé, sélectionnez Sortie. La sortie devrait ressembler à la sortie du test.
Fermez la page Travail, puis revenez à la page Vue d’ensemble du runbook.
Sous Ressources, sélectionnez Travaux. Cette page répertorie tous les travaux créés par votre runbook. Vous ne devriez en voir qu’un seul, car vous n’avez exécuté le travail qu’une seule fois.
Sélectionnez la tâche pour ouvrir la même page Tâche que celle consultée au démarrage du runbook. Utilisez cette page pour voir les détails de tout travail créé pour le runbook. Fermez la page Travail, puis revenez à la page Vue d’ensemble du runbook.

Ajouter une authentification pour gérer les ressources Azure

Vous avez testé et publié votre runbook, mais jusqu’à présent, il ne fait rien d’utile. Vous souhaitez qu’il gère les ressources Azure. Il ne peut le faire que s’il s’authentifie à l’aide des informations d’identification de l’abonnement. Le runbook utilise l’identité managée affectée par le système du compte Automation pour s’authentifier auprès d’Azure afin d’effectuer l’action de gestion sur la machine virtuelle. Le runbook peut être facilement modifié pour utiliser une identité managée affectée par l’utilisateur.

Sélectionnez Vue d’ensemble et Modifier pour ouvrir l’éditeur de texte.

Remplacez le code existant par le code ci-dessous :

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>"
}

Modifiez la variable $resourceGroup avec une valeur valide représentant votre groupe de ressources.

Si vous souhaitez que le runbook s’exécute avec l’identité managée affectée par le système, laissez le code tel quel. Si vous préférez utiliser une identité managée affectée par l’utilisateur, procédez comme suit :
1. À la ligne 9, supprimez Connect-AzAccount -Identity,
2. Remplacez-la par Connect-AzAccount -Identity -AccountId <ClientId> et
3. Entrez l’ID client que vous avez obtenu précédemment.
Sélectionnez Enregistrer, puis volet Test.
Sélectionnez Démarrer pour démarrer le test. Une fois le test terminé, une sortie semblable à celle illustrée ci-dessous devrait afficher des informations de base sur votre compte. Cette action confirme la validité des informations d’identification.
Fermez la page Test pour revenir au canevas.

Ajouter du code pour démarrer une machine virtuelle

À présent que votre runbook s’authentifie auprès de l’abonnement Azure, vous pouvez gérer les ressources. Ajoutez une commande pour démarrer une machine virtuelle. Vous pouvez choisir n’importe quelle machine virtuelle de votre abonnement Azure. Pour l’instant, vous allez coder ce nom en dur dans le runbook.

Ajoutez le code ci-dessous comme dernière ligne, juste avant l’accolade fermante. Remplacez VMName par le nom de la machine virtuelle.
```
Start-AzVM -Name "VMName" -ResourceGroupName $resourceGroup -DefaultProfile $AzureContext
```
Testez le runbook et confirmez que la machine virtuelle a démarré. Revenez ensuite au canevas.

Ajouter des paramètres d’entrée au runbook

Votre runbook démarre actuellement la machine virtuelle que vous avez codée en dur dans le runbook. Elle sera plus utile si vous pouvez la spécifier au démarrage du runbook. Ajoutez des paramètres d’entrée au runbook pour fournir cette fonctionnalité.

Remplacez la ligne 3, $resourceGroup = "resourceGroupName", par le code suivant :
```
Param(
    [string]$resourceGroup,
    [string]$VMName
)
```

Remplacez la commande Start-AzVM précédente par le code suivant :

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

Testez le runbook et confirmez que la machine virtuelle a démarré. Revenez ensuite au canevas.

Gérer plusieurs machines virtuelles simultanément

Vous pouvez utiliser la construction ForEach -Parallel pour traiter simultanément les commandes de chaque élément d'une collection. Modifiez le code pour que le runbook :

Accepte un regroupement de noms de machines virtuelles,
Accepte un paramètre pour arrêter ou démarrer les machines virtuelles, et
Exécute les actions en parallèle sur toutes les machines virtuelles

Remplacez tout le code existant par ce qui suit :

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'."
   }
   }

Si vous souhaitez que le runbook s’exécute avec l’identité managée affectée par le système, laissez le code tel quel. Si vous préférez utiliser une identité managée affectée par l’utilisateur, procédez comme suit :
1. À la ligne 9, supprimez Connect-AzAccount -Identity,
2. Remplacez-la par Connect-AzAccount -Identity -AccountId <ClientId> et
3. Entrez l’ID client que vous avez obtenu précédemment.
Sélectionnez Enregistrer, Publier, puis Oui lorsque vous y êtes invité.
À partir de la page Vue d’ensemble, sélectionnez Démarrer.

Renseignez les paramètres, puis sélectionnez OK.

Paramètre	Description
RESOURCEGROUP	Entrez le nom du groupe de ressources des machines virtuelles.
Machines virtuelles	Entrez les noms des machines virtuelles à l’aide de la syntaxe suivante : `["VM1","VM2","VM3"]`
Action	Entrez `stop` ou `start`.

Accédez à la liste des machines virtuelles et actualisez la page toutes les quelques secondes. Notez que l’action pour chaque machine virtuelle s’effectue en parallèle. Sans le mot clé -Parallel, les actions auraient été effectuées de manière séquentielle. Tandis que les machines virtuelles démarrent de façon séquentielle, chaque machine virtuelle peut atteindre la phase En cours d’éxecution à des moments légèrement différents en fonction des caractéristiques de chaque machine virtuelle.

Nettoyer les ressources

Si vous ne comptez pas continuer à utiliser ce runbook, supprimez-le en effectuant les étapes suivantes :

Accédez à votre compte Automation.
Sous Automatisation de processus, sélectionnez Runbooks.
Sélectionnez le Runbook.
À partir de la page Vue d’ensemble du runbook, sélectionnez Supprimer.

Étapes suivantes

Dans ce tutoriel, vous avez créé un runbook de workflow PowerShell. Pour obtenir un aperçu des runbooks Python 3, consultez :

Tutoriel : créer un runbook Python 3