Azure Automation Runbook

Was ist ein Azure Automation Runbook?

Ein Azure Automation Runbook ist ein Skript in PowerShell oder Python, das in einem Azure Automation-Konto gespeichert wird. Es läuft entweder in der Cloud-Sandbox von Microsoft oder über einen Hybrid Runbook Worker im eigenen Rechenzentrum. Azure übernimmt Hosting, Authentifizierung über eine verwaltete Identität (Managed Identity), Zeitplanung, Protokollierung und Speicherung der Ausführungsverläufe. Die eigentliche Automatisierungslogik legst du fest.

Microsoft unterscheidet fünf Runbook-Typen, wobei grafische Runbooks in zwei Varianten verfügbar sind. Für neue Projekte sind vor allem zwei relevant:

Zwei Punkte sind besonders wichtig: Seit dem 30. September 2023 werden Run As-Konten nicht mehr unterstützt. Für die Authentifizierung solltest du daher Managed Identities verwenden. Außerdem bietet Microsoft inzwischen Runtime Environments. Damit lassen sich PowerShell-Versionen und Modulversionen je Umgebung festlegen. Ein Modulupdate in einem Runbook beeinträchtigt dadurch nicht automatisch andere Runbooks. Falls du noch Runbooks mit PowerShell 7.1 oder 7.2 nutzt, solltest du sie migrieren – diese Versionen sind abgekündigt.

Azure Runbook erstellen, testen, veröffentlichen und ausführen

Unabhängig vom späteren Einsatzzweck durchläuft jedes Azure Runbook denselben Ablauf:

So kann ein einfaches PowerShell-Runbook für den produktiven Einsatz aussehen. Es authentifiziert sich über die systemseitig zugewiesene Managed Identity des Automation-Kontos und startet eine virtuelle Maschine (VM):

param (
    [Parameter(Mandatory = $true)]
    [string] $ResourceGroupName,
[Parameter(Mandatory = $true)]
    [string] $VMName
)
# Authentifizierung mit der Managed Identity des Automation-Kontos (kein Run As-Konto, keine Geheimnisse)
Connect-AzAccount -Identity | Out-Null
$vm = Get-AzVM -ResourceGroupName $ResourceGroupName -Name $VMName -Status
$state = ($vm.Statuses | Where-Object Code -like 'PowerState/*').DisplayStatus
if ($state -eq 'VM running') {
    Write-Output "$VMName is already running."
    return
}
Start-AzVM -ResourceGroupName $ResourceGroupName -Name $VMName | Out-Null
Write-Output "$VMName started successfully."

Achte auf die Zeilen mit Write-Output: Alles, was du in den Ausgabestream schreibst, wird im Ausführungsverlauf des Jobs gespeichert. Diese Meldungen kann später auch ein Frontend der Person anzeigen, die den VM-Start angefordert hat. Die Managed Identity benötigt dazu die Rolle Virtual Machine Contributor für die entsprechende Ressourcengruppe. Diese Berechtigung wird einmalig vergeben – nicht für jedes Runbook separat.

Azure Runbook Parameters: Eingaben richtig definieren

Der param-Block legt fest, welche Eingaben dein Skript beim Start erwartet. Ob Azure-Portal, PowerShell, Webhook oder Self-Service-Portal: Alle Startmethoden orientieren sich an diesen Parametern. Eine saubere Definition spart später viel Fehlersuche – etwa wenn ein VM-Name ungültige Zeichen enthält.

param (
    [Parameter(Mandatory = $true, HelpMessage = 'Resource group that contains the VM')]
    [ValidateNotNullOrEmpty()]
    [string] $ResourceGroupName,
[Parameter(Mandatory = $true, HelpMessage = 'VM name, e.g. vm-dev-web01')]
    [ValidatePattern('^[a-zA-Z0-9-]{1,64}$')]
    [string] $VMName,
[Parameter(Mandatory = $false)]
    [ValidateSet('Start', 'Stop', 'Restart')]
    [string] $Action = 'Start',
[Parameter(Mandatory = $false)]
    [ValidateRange(0, 8)]
    [int] $AutoStopAfterHours = 4
)

Mit Mandatory legst du fest, welche Felder verpflichtend sind. Das Azure-Portal berücksichtigt außerdem Datentypen und Standardwerte. Auch ein gutes Frontend verhindert, dass erforderliche Eingaben fehlen. ValidateSet begrenzt mögliche Werte auf eine festgelegte Auswahl. Im Azure-Portal bleibt die Eingabe gegebenenfalls ein Textfeld; ein Frontend kann daraus ein Dropdown machen. So entsteht beispielsweise nicht versehentlich die Eingabe „restrt“ statt „Restart“.

ValidatePattern und ValidateRange prüfen Eingaben bereits bei der Parameterbindung, bevor die eigentliche Skriptlogik ausgeführt wird. Ein Frontend kann dieselben Regeln vor dem Start des Jobs anwenden. Standardwerte halten Formulare übersichtlich: Nicht jeder Benutzer muss beispielsweise selbst entscheiden, wie lange eine Entwicklungs-VM laufen soll.

Eine wichtige Sicherheitsregel: Übermittle niemals Passwörter oder andere Geheimnisse als Runbook-Parameter. Azure Automation protokolliert die übergebenen Eingabewerte im Job. Lege Zugangsdaten stattdessen in verschlüsselten Automation-Variablen oder in Azure Key Vault ab und lies sie erst innerhalb des Runbooks aus.

Azure Runbook starten: 5 Möglichkeiten im Überblick

Ein veröffentlichtes Azure Runbook lässt sich auf mehreren Wegen starten: direkt im Azure-Portal, zeitgesteuert, über Start-AzAutomationRunbook beziehungsweise die Az CLI, über die REST API oder mit einem Webhook. Jede Methode erfüllt einen anderen Zweck. Für Endanwender, die einfach eine IT-Aufgabe anfordern möchten, sind die ersten vier jedoch nicht unmittelbar ausgelegt.

Das Azure-Portal eignet sich für Administratoren. Dafür sind eine Azure-Anmeldung und mindestens die Rolle Automation Operator nötig – Berechtigungen, die ein Helpdesk nicht pauschal erhalten sollte. Ein Zeitplan ist ideal, um beispielsweise alle Entwicklungs-VMs um 19 Uhr herunterzufahren, aber ungeeignet für spontane Anforderungen. PowerShell und die Az CLI sind praktisch für Skripte und Pipelines, setzen aber die entsprechenden Werkzeuge und Berechtigungen voraus. Die REST API bildet die Grundlage für viele Integrationen und erfordert ein Entra-ID-Token sowie passende RBAC-Berechtigungen für das Automation-Konto.

Bleibt der Webhook: Ein einziger HTTPS-POST-Aufruf kann das Runbook starten. Damit kommt Azure einer einfachen Schaltfläche für die Ausführung am nächsten. Deshalb lohnt sich ein genauerer Blick.

Azure Automation Webhook: Runbook per HTTP starten

Ein Azure Automation Webhook ist eine eindeutige URL, die mit einem bestimmten Runbook verknüpft ist. Wer einen HTTP-POST-Request an diese URL sendet, kann das Runbook starten – ohne Anmeldung im Azure-Portal oder zusätzliches SDK. Das eignet sich beispielsweise für Azure DevOps, CI/CD-Pipelines, Monitoring-Tools und eigene Portale.

Dabei gibt es eine Besonderheit: Das Runbook erhält die Anfrage über einen einzigen Parameter mit dem Namen WebhookData. Individuelle Runbook-Parameter werden nicht automatisch aus dem Request-Body befüllt. Du musst die übermittelten Daten selbst auslesen:

param (
    [Parameter(Mandatory = $false)]
    [object] $WebhookData
)
if (-not $WebhookData) {
    throw 'This runbook expects to be started from a webhook.'
}
# Optional: Aufrufe von anderen als dem erwarteten Webhook ablehnen
if ($WebhookData.WebhookName -ne 'wh-start-vm-helpdesk') {
    throw "Unexpected webhook: $($WebhookData.WebhookName)"
}
$body = $WebhookData.RequestBody | ConvertFrom-Json
Connect-AzAccount -Identity | Out-Null
Start-AzVM -ResourceGroupName $body.ResourceGroupName -Name $body.VMName | Out-Null
Write-Output "$($body.VMName) started via webhook."

So rufst du den Webhook über PowerShell auf:

$uri  = 'https://<id>.webhook.<region>.azure-automation.net/webhooks?token=...'
$body = @{ ResourceGroupName = 'rg-dev'; VMName = 'vm-dev-web01' } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri $uri -Body $body -ContentType 'application/json'
# Gibt eine JobId zurück. Das Runbook selbst wird asynchron ausgeführt

Azure Automation Webhook: Sicherheit und Risiken

Bevor du eine Webhook-URL weitergibst, solltest du diese Punkte kennen:

• Die URL ist das Passwort. Azure prüft bei Webhook-Aufrufen keine zusätzliche Authentifizierung. Wer die URL kennt, kann das Runbook mit beliebigen Daten starten.
• Die URL wird nur einmal angezeigt – direkt bei der Erstellung. Geht sie verloren, musst du einen neuen Webhook anlegen.
• Webhooks laufen ab, standardmäßig nach einem Jahr. Plane deshalb rechtzeitig eine Rotation ein.
• Die übermittelten Daten werden protokolliert. Der Request-Body wird im Job gespeichert und kann von Personen mit Zugriff auf den Ausführungsverlauf eingesehen werden.
• Keine Benutzeridentität. Azure Automation erfasst den Start durch den Webhook, nicht die Identität der Person, die ihn aufgerufen hat.

Microsoft empfiehlt für sensible Aktionen eine zusätzliche Validierungs- und Sicherheitsschicht vor dem Webhook. Genau diese Aufgabe muss ein geeignetes Frontend übernehmen.

Warum ein Azure Automation Webhook allein kein Frontend ersetzt

Ein Webhook löst einen Vorgang aus – mehr nicht. Anwender benötigen aber eine vollständige Benutzeroberfläche. Wenn du etwa einen Teams-Button oder ein SharePoint-Formular direkt mit einem Webhook verbindest, fehlen typischerweise mindestens sechs Funktionen:

1. Ein Formular passend zu den Parametern. Dropdowns für ValidateSet, Pflichtfelder, sinnvolle Standardwerte und verständliche Beschriftungen in der Sprache der Benutzer.
2. Authentifizierung und Berechtigungen. Wer darf welches Runbook mit welchen Parametern starten? Der Helpdesk darf beispielsweise vm-dev-* neu starten, aber keinen Domänencontroller.
3. Genehmigungen. Bevor eine neue VM Kosten verursacht, sollte etwa die Teamleitung zustimmen.
4. Eingabeprüfung vor dem Jobstart. Ungültige Werte werden direkt im Formular zurückgewiesen, statt später einen fehlgeschlagenen Job zu verursachen.
5. Nachvollziehbares Audit-Log. Wer hat wann was aus welchem Grund angefordert und wer hat es genehmigt? Der Webhook-Ausführungsverlauf allein liefert diese Informationen nicht.
6. Rückmeldung an die anfragende Person. Die Ausgabe des Runbooks – etwa „vm-dev-web01 started successfully“ – sollte beim Benutzer ankommen und nicht nur im Jobprotokoll stehen.

Diese sechs Funktionen kannst du selbst entwickeln – etwa mit App-Registrierung, Webanwendung, Datenbank, Rollenverwaltung, Genehmigungsworkflow und Abfrage des Jobstatus. Das ist machbar. Allerdings betreiben viele Teams anschließend dauerhaft eine eigene Anwendung, statt sich auf die eigentliche IT-Automatisierung zu konzentrieren. Eine Alternative ist ein Self-Service-Portal, das diese Funktionen bereits mitbringt.

Vom Azure Runbook zum Self-Service-Portal in 3 Schritten

So setzen wir au2mator als Frontend für Azure Automation ein. Das Azure Automation Runbook selbst bleibt unverändert. Hinzu kommen die Funktionen für sichere und komfortable Self-Service-Prozesse:

Schritt 1: Automation-Konto verbinden. au2mator authentifiziert sich gegenüber deinem Azure Automation-Konto und liest die veröffentlichten Runbooks sowie deren Parameterdefinitionen aus. Du musst keine Webhook-URLs verteilen und keine gemeinsamen Zugangsdaten in Chats speichern.

Schritt 2: Service einrichten. Jeder Runbook-Parameter wird zu einer Frage in einem Formular. Du bestimmst, wer den Service über Entra-ID-Gruppen sehen darf, ob eine Genehmigung erforderlich ist und welche Werte Benutzer auswählen können. Aus ValidateSet wird beispielsweise eine Auswahlliste. Ein Ressourcengruppen-Parameter lässt sich vorbelegen oder vollständig ausblenden, sodass der Benutzer nur noch eine VM auswählen muss.

Schritt 3: Service für Benutzer bereitstellen. Helpdesk-Mitarbeiter oder Endanwender öffnen das Portal, füllen das Formular aus und senden ihre Anfrage ab. Falls eine Genehmigung vorgesehen ist, kann die zuständige Person diese mit einem Klick erteilen oder ablehnen. au2mator startet den Runbook-Job, verfolgt dessen Status und zeigt die Ausgabe an. Jede Anfrage wird nachvollziehbar dokumentiert: Wer hat was, wann, wo und warum angefordert?

Silhouette International nutzt dieses Prinzip für rund 80.000 Benutzer. Standortadministratoren weltweit starten damit mehr als 100-mal täglich Services wie „Neuen Benutzer anlegen“ oder „Benutzer zu Gruppe hinzufügen“, ohne selbst Zugriff auf Active Directory zu benötigen. Die Runbooks erledigen die technische Arbeit. Das Portal steuert, wer sie anfordern darf.

Praxisbeispiel: Entwicklungs-VM per Azure Runbook starten

Sehen wir uns an, wie sich das oben gezeigte Runbook in einen sicheren Self-Service für den First-Level-Helpdesk verwandeln lässt.

Das Runbook heißt Start-DevVM und nutzt die Parameter ResourceGroupName, VMName und Action (mit ValidateSet für Start/Stop/Restart). Die Managed Identity besitzt die Rolle Virtual Machine Contributor ausschließlich für rg-dev.

Im Portal bleibt ResourceGroupName verborgen und ist fest auf rg-dev eingestellt. Für VMName steht ein Dropdown zur Verfügung, das ein separates Lookup-Runbook mit den VMs dieser Ressourcengruppe befüllt. Unter Action sind die drei Aktionen auswählbar. Der Service ist nur für die Entra-ID-Gruppe Helpdesk-L1 sichtbar. Start und Stop benötigen keine Genehmigung; für einen Neustart muss zunächst der VM-Verantwortliche zustimmen, da möglicherweise jemand an der VM arbeitet.

Nach erfolgreicher Ausführung sieht die anfragende Person die Meldung „vm-dev-web01 started successfully“ im Portal und erhält sie per E-Mail. Tritt ein Fehler auf, wird der Fehlerstream an die Anfrage angehängt und die IT benachrichtigt.

Der Helpdesk muss weder das Azure-Portal öffnen noch Webhook-URLs verwalten. Außerdem kann er ausschließlich VMs in rg-dev bedienen. Wieder ein wiederkehrendes Ticket weniger.

Best Practices für Azure Automation Runbooks im Produktivbetrieb

Ein Skript, das nur gelegentlich im eigenen Konto läuft, stellt andere Anforderungen als ein Runbook, das hundertmal täglich von anderen Personen gestartet wird. Vor der Bereitstellung als Service prüfen wir deshalb folgende Punkte:

• Managed Identity und minimale Berechtigungen. Weise Rollen nur im tatsächlich benötigten Ressourcenumfang zu. Nicht aus Bequemlichkeit die Rolle Contributor für das gesamte Abonnement vergeben.
• Runtime Environment festlegen. Nutze PowerShell 7.4 (oder 7.6) mit definierten Modulversionen. Automatische Updates auf die neueste Version können bestehende Services unerwartet beeinträchtigen.
• Idempotente Abläufe. Benutzer klicken manchmal zweimal. „Zur Gruppe hinzufügen“ sollte deshalb auch dann erfolgreich sein, wenn die Person bereits Mitglied ist.
• Verständliche Ausgaben. Gib mit Write-Output eine klare Erfolgsmeldung und mit Write-Error aussagekräftige Fehlerinformationen aus. Diese Texte sehen später die Anfragenden.
• Dreistündiges Fair-Share-Limit beachten. Jobs in der Cloud-Sandbox werden nach drei Stunden beendet. Längere oder lokale Aufgaben gehören auf einen Hybrid Runbook Worker.
• Keine Geheimnisse in Parametern oder Ausgaben. Beide können protokolliert werden. Nutze verschlüsselte Automation-Variablen oder Key Vault.
• Child Runbooks für gemeinsame Logik. Ein Lookup-Runbook wie Get-AuthorizedVMs kann von zehn Services wiederverwendet werden, statt die gleiche Logik zehnmal zu kopieren.
• Versionsverwaltung. Entwickle in VS Code mit der Azure-Automation-Erweiterung, sichere Änderungen in Git und veröffentliche über eine Pipeline. Der Portal-Editor eignet sich eher für schnelle Korrekturen.

Weitere typische Fehler – von abgelaufenen Webhooks bis hin zu übermäßig weitreichenden Berechtigungen – findest du in unserem kostenlosen PDF 8 Ways to Screw Your Azure Automation.

FAQ: Häufige Fragen zu Azure Automation Runbooks

Fazit: Das Runbook ist nur der Anfang

Ein Azure Automation Runbook zu schreiben, ist oft in wenigen Stunden erledigt. Die eigentliche Herausforderung besteht darin, festzulegen, wer es mit welchen Parametern starten darf, welche Genehmigungen notwendig sind und wie Benutzer Rückmeldungen erhalten. Erst dadurch wird aus einem Skript ein sicher nutzbarer Service. Ein Webhook liefert lediglich den Auslöser. Ein Self-Service-Portal kann dagegen viele manuelle Helpdesk-Tickets überflüssig machen.

Du möchtest sehen, wie sich deine bestehenden Runbooks als Self-Service anbieten lassen? Dann vereinbare einen 30-minütigen Termin mit Michael Seidl, Microsoft MVP und Gründer von au2mator. Bring ein Runbook mit – gemeinsam richten wir dafür ein Formular ein.