Verwenden von Document Builder zur Erstellung von Runbooks

Wenn die AWS Systems Manager öffentlichen Runbooks nicht alle Aktionen unterstützen, die Sie für Ihre AWS Ressourcen ausführen möchten, können Sie Ihre eigenen Runbooks erstellen. Um ein benutzerdefiniertes Runbook zu erstellen, können Sie manuell eine lokale Datei im YAML- oder JSON-Format mit den entsprechenden Automatisierungsaktionen erstellen. Alternativ können Sie Document Builder in der Systems-Manager-Automation-Konsole verwenden, um ein benutzerdefiniertes Runbook zu erstellen.

Mit Document Builder können Sie Ihrem benutzerdefinierten Runbook Automatisierungsaktionen hinzufügen und die erforderlichen Parameter bereitstellen, ohne die JSON- oder YAML-Syntax verwenden zu müssen. Nachdem Sie Schritte hinzugefügt und das Runbook erstellt haben, konvertiert das System die von Ihnen hinzugefügten Aktionen in das YAML-Format, das von Systems Manager zum Ausführen von Automation verwendet werden kann.

Runbooks unterstützen die Verwendung von Markdown, einer Markup-Sprache, mit der Sie Wiki-Beschreibungen zu Runbooks und einzelnen Schritten innerhalb des Runbooks hinzufügen können. Weitere Informationen zur Verwendung von Markdown finden Sie unter Verwenden von Markdown in AWS.

Erstellen eines Runbooks mithilfe von Document Builder

Bevor Sie beginnen

Wir empfehlen Ihnen, sich über die verschiedenen Aktionen zu informieren, die Sie in einem Runbook verwenden können. Weitere Informationen finden Sie unter Systems Manager Automation Aktionen-Referenz.

So erstellen Sie ein Runbook mit Document Builder

1. Öffnen Sie die AWS Systems Manager Konsole unter https://console.aws.amazon.com/systems-manager/.

2. Wählen Sie im Navigationsbereich die Option Documents (Dokumente) aus.

3. Wählen Sie Create automation (Automation erstellen).

4. Geben Sie unter Name einen aussagekräftigen Namen für das Runbook ein.

5. Geben Sie für Document description (Dokumentbeschreibung) die Beschreibung des Markdown-Stils für das Runbook an. Sie können Anweisungen für die Verwendung des Runbooks, nummerierte Schritte oder jede andere Art von Informationen zur Beschreibung des Runbooks bereitstellen. Informationen zum Formatieren von Inhalten finden Sie im Standardtext.

   Tipp

   Wechseln Sie zwischen Hide preview (Vorschau ausblenden) und Show preview (Vorschau anzeigen), um zu sehen, wie der Beschreibungsinhalt während der Erstellung aussieht.

6. (Optional) Geben Sie unter Assume role (Rolle übernehmen) den Namen oder den ARN einer Servicerolle ein, um Aktionen in Ihrem Auftrag auszuführen. Wenn Sie keine Rolle angeben, verwendet Automation die Zugriffsberechtigungen des Benutzers, der die Automatisierung durchführt.

   Wichtig

   Für Runbooks, die sich nicht im Besitz von Amazon befinden und die die aws:executeScript-Aktion verwenden, muss eine Rolle angegeben werden. Weitere Informationen finden Sie unter Berechtigungen für die Verwendung von Runbooks.

7. (Optional) Geben Sie unter Outputs (Ausgänge) alle Ausgaben für die Automatisierung dieses Runbooks ein, um sie für andere Prozesse verfügbar zu machen.

   Wenn Ihr Runbook beispielsweise ein neues AMI erstellt, können Sie [“ CreateImage angeben. ImageId„] und verwenden Sie dann diese Ausgabe, um in einer nachfolgenden Automatisierung neue Instances zu erstellen.

8. (Optional) Erweitern Sie den Abschnitt Input parameters (Eingabeparameter) und führen Sie die folgenden Schritte aus.

   1. Geben Sie unter Parameter name (Parametername) einen beschreibenden Namen für den Runbookparameter ein, den Sie erstellen.

   2. Wählen Sie unter Type (Typ) einen Typ für den Parameter, z. B. String oder MapList.

   3. Führen Sie unter Required (Erforderlich) eine der folgenden Aktionen aus:

      • Wählen Sie Yes (Ja), wenn zur Laufzeit ein Wert für diesen Runbookparameter angegeben werden muss.

      • Wählen Sie No (Nein), wenn der Parameter nicht erforderlich ist, und geben Sie (optional) unter Default value (Standardwert) einen Standardparameterwert ein.

   4. Geben Sie unter Description (Beschreibung) eine Beschreibung für den Runbookparameter ein.

   Anmerkung

   Um weitere Runbookparameter hinzuzufügen, wählen Sie Add a parameter (Parameter hinzufügen). Um einen Runbookparameter zu entfernen, klicken Sie auf die Schaltfläche X (Entfernen).

9. (Optional) Erweitern Sie den Abschnitt Target type (Zieltyp) und wählen Sie einen Zieltyp, um die Arten der Ressourcen zu definieren, auf denen die Automatisierung ausgeführt werden kann. Um beispielsweise ein Runbook auf EC2-Instances zu wählen, wählen Sie /AWS::EC2::Instance.

   Anmerkung

   Wenn Sie den Wert '/' angeben, kann das Runbook auf allen Arten von Ressourcen ausgeführt werden. Eine Liste gültiger Ressourcentypen finden Sie unter AWS -Ressourcentypen – Referenz im AWS CloudFormation Benutzerhandbuch.

10. (Optional) Erweitern Sie den Abschnitt Document tags (Dokument-Tags) und geben Sie ein oder mehrere Tag-Schlüssel-Wert-Paare ein, die auf das Runbook angewendet werden sollen. Tags erleichtern die Identifizierung, Organisation und Suche nach Ressourcen. Weitere Informationen finden Sie unter Markierungen von Systems Manager-Dokumenten.

11. Geben Sie im Abschnitt Step 1 (Schritt 1) die folgenden Informationen an.

    • Geben Sie unter Step name (Schrittname) einen beschreibenden Namen für den ersten Schritt der Automatisierung ein.

    • Wählen Sie unter Action type (Aktionstyp) den Aktionstyp aus, der für diesen Schritt verwendet werden soll.

      Eine Liste und Informationen zu den verfügbaren Aktionstypen finden Sie unter Systems Manager Automation Aktionen-Referenz.

    • Geben Sie unter Description (Beschreibung) eine Beschreibung für den Automatisierungsschritt ein. Sie können Markdown verwenden, um Ihren Text zu formatieren.

    • Je nach ausgewähltem Action type (Aktionstyp) geben Sie im Abschnitt Step inputs (Schritteingaben) die erforderlichen Eingaben für den Aktionstyp ein. Wenn Sie beispielsweise die Aktion aws:approve ausgewählt haben, müssen Sie einen Wert für die Approvers-Eigenschaft angeben.

      Informationen zu den Schritteingabefeldern finden Sie im Eintrag Systems Manager Automation Aktionen-Referenz für den ausgewählten Aktionstyp. Zum Beispiel: aws:executeStateMachine – Führen Sie eine AWS Step Functions-State Machine aus..

    • (Optional) Geben Sie für Additional inputs (Zusätzliche Eingaben) alle zusätzlichen Eingabewerte an, die für das Runbook erforderlich sind. Die verfügbaren Eingabetypen hängen vom Aktionstyp ab, den Sie für den Schritt ausgewählt haben. (Beachten Sie, dass einige Aktionstypen Eingabewerte erfordern.)

      Anmerkung

      Um weitere Eingaben hinzuzufügen, wählen Sie Add optional input (Optionale Eingabe hinzufügen). Um eine Eingabe zu entfernen, wählen Sie die Schaltfläche X (Entfernen).

    • (Optional) Geben Sie unter Outputs (Ausgänge) alle Ausgaben für diesen Schritts ein, um sie für andere Prozesse verfügbar zu machen.

      Anmerkung

      Outputs (Ausgaben) sind nicht für alle Aktionstypen verfügbar.

    • (Optional) Erweitern Sie den Abschnitt Common properties (Allgemeine Eigenschaften) und geben Sie Eigenschaften für die Aktionen an, die allen Automation-Aktionen gemeinsam sind. Beispielsweise können Sie für Timeout seconds (Timeout in Sekunden) anhand eines Werts in Sekunden angeben, wie lange der Schritt ausgeführt werden kann, bevor er beendet wird.

      Weitere Informationen finden Sie unter Von allen Aktionen gemeinsam genutzte Eigenschaften.

    Anmerkung

    Um weitere Schritte hinzuzufügen, wählen Sie Add step (Schritt hinzufügen) aus und wiederholen Sie das Verfahren zum Erstellen eines Schritts. Um einen Schritt zu entfernen, wählen Sie Remove step (Schritt entfernen).

12. Wählen Sie Create automation (Automation erstellen), um das Runbook zu speichern.

Erstellen eines Runbooks, das Skripte ausführt

Das folgende Verfahren zeigt, wie Sie mit Document Builder in der AWS Systems Manager -Automation-Konsole ein benutzerdefiniertes Runbook erstellen, das ein Skript ausführt.

Im ersten Schritt des von Ihnen erstellten Runbooks wird ein Skript ausgeführt, um eine Amazon Elastic Compute Cloud (Amazon EC2)-Instance zu starten. Im zweiten Schritt wird ein weiteres Skript ausgeführt, um zu überwachen, ob die Instance-Zustandsprüfung auf ok geändert werden soll. Anschließend wird für die Automatisierung ein Gesamtzustand von Success gemeldet.

Bevor Sie beginnen

Stellen Sie sicher, dass Sie die folgenden Schritte ausgeführt haben:

• Stellen Sie sicher, dass Sie über Administratorrechte verfügen oder dass Ihnen die entsprechenden Berechtigungen für den Zugriff auf Systems Manager in AWS Identity and Access Management (IAM) erteilt wurden.

  Weitere Informationen finden Sie unter Überprüfen des Benutzerzugriffs für Runbooks.

• Stellen Sie sicher, dass Sie in Ihrem AWS-Kontoüber eine IAM-Service-Rolle für Automation (auch als Rolle übernehmen bezeichnet) verfügen. Die Rolle ist erforderlich, da in dieser Anleitung die Aktion aws:executeScript verwendet wird.

  Weitere Informationen zum Erstellen dieser Rolle finden Sie unter Konfigurieren eines Service-Rollenzugriffs (Rolle übernehmen) für Automatisierungen.

  Hinweise zur IAM-Service-Rollenanforderung zum Ausführen von aws:executeScript, finden Sie unter Berechtigungen für die Verwendung von Runbooks.

• Stellen Sie sicher, dass Sie berechtigt sind, EC2-Instances zu starten.

  Weitere Informationen finden Sie unter IAM und Amazon EC2 im Amazon EC2 EC2-Benutzerhandbuch.

So erstellen Sie ein benutzerdefiniertes Runbook, das Skripts mit Document Builder ausführt

1. Öffnen Sie die AWS Systems Manager Konsole unter https://console.aws.amazon.com/systems-manager/.

2. Wählen Sie im Navigationsbereich die Option Documents (Dokumente) aus.

3. Wählen Sie Create automation (Automation erstellen).

4. Geben Sie unter Name diesen beschreibenden Namen für das Runbook ein: LaunchInstanceAndCheckStatus.

5. (Optional) Ersetzen Sie bei Document description (Dokumentbeschreibung) den Standardtext durch eine Beschreibung für dieses Runbooks, indem Sie Markdown verwenden. Im Folgenden wird ein Beispiel gezeigt.

   ##Title: LaunchInstanceAndCheckState
       -----
       **Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook continuously checks the instance status check value for the launched instance until the status ```ok``` is returned.
       
       ##Parameters:
       -----
       Name | Type | Description | Default Value
       ------------- | ------------- | ------------- | -------------
       assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | -
       imageId  | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}

6. Geben Sie unter Assume role (Rolle übernehmen) den ARN der IAM-Service-Rolle für Automation (Rolle übernehmen) für die Automatisierung im Format arn:aws:iam::111122223333:role/AutomationServiceRole ein. Ersetzen Sie 111122223333 durch Ihre AWS-Konto ID.

   Die von Ihnen angegebene Rolle wird verwendet, um die Berechtigungen bereitzustellen, die zum Starten der Automatisierung erforderlich sind.

   Wichtig

   Für Runbooks, die sich nicht im Besitz von Amazon befinden und die die aws:executeScript-Aktion verwenden, muss eine Rolle angegeben werden. Weitere Informationen finden Sie unter Berechtigungen für die Verwendung von Runbooks.

7. Erweitern Sie Input parameters (Eingabeparameter) und gehen Sie folgendermaßen vor.

   1. Geben Sie unter Parameter name (Parametername) imageId ein.

   2. Wählen Sie für Type (Typ) die Option String aus.

   3. Wählen Sie unter Required (Erforderlich) die Option No.

   4. Geben Sie unter Default value (Standardwert) Folgendes ein.

      {{ ssm:/aws/service/ami-amazon-linux-latest/amzn-ami-hvm-x86_64-gp2 }}

      Anmerkung

      Dieser Wert startet eine Amazon EC2 EC2-Instance mit der neuesten Amazon Linux 1 Amazon Machine Image (AMI) -ID. Wenn Sie ein anderes AMI verwenden möchten, ersetzen Sie den Wert durch Ihre AMI-ID.

   5. Geben Sie unter Description (Beschreibung) Folgendes ein.

      (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux AMI ID.

8. Wählen Sie Add a parameter (Parameter hinzufügen), um den zweiten Parameter tagValue zu erstellen, und geben Sie Folgendes ein.

   1. Geben Sie unter Parameter name (Parametername) tagValue ein.

   2. Wählen Sie für Type (Typ) die Option String aus.

   3. Wählen Sie unter Required (Erforderlich) die Option No.

   4. Für Default value (Standardwert) geben Sie LaunchedBySsmAutomation ein. Dadurch wird der Instance der Schlüsselpaarwert des Tags Name:LaunchedBySsmAutomation hinzugefügt.

   5. Geben Sie unter Description (Beschreibung) Folgendes ein.

      (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation.

9. Wählen Sie Add a parameter (Parameter hinzufügen), um den dritten Parameter instanceType zu erstellen, und geben Sie folgende Informationen ein.

   1. Geben Sie unter Parameter name (Parametername) instanceType ein.

   2. Wählen Sie für Type (Typ) die Option String aus.

   3. Wählen Sie unter Required (Erforderlich) die Option No.

   4. Für Default value (Standardwert) geben Sie t2.micro ein.

   5. Geben Sie unter Parameter description (Parameterbeschreibung) Folgendes ein.

      (Optional) The instance type to use for the instance. The default value is t2.micro.

10. Erweitern Sie Target type (Zieltyp) und wählen Sie "/".

11. (Optional) Erweitern Sie Document tags (Dokument-Tags), um Ressourcen-Tags auf Ihr Runbook anzuwenden. Geben Sie für Tag key (Tag-Schlüssel Purpose und für Tag value (Tag-Wert) LaunchInstanceAndCheckState ein.

12. Führen Sie im Abschnitt Step 1 (Schritt 1) die folgenden Schritte aus.

    1. Geben Sie unter Step name (Schrittname) diesen beschreibenden Schrittnamen für den ersten Schritt der Automatisierung ein: LaunchEc2Instance.

    2. Wählen Sie unter Action type (Aktionstyp) die Option Run a script (Skript ausführen) (aws:executeScript).

    3. Geben Sie unter Description (Beschreibung) eine Beschreibung für den Automation-Schritt ein, wie etwa folgende.

       **About This Step**
           
           This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script.

    4. Erweitern Sie Inputs (Eingaben).

    5. Wählen Sie für Runtime (Laufzeit) die Laufzeitsprache aus, die zum Ausführen des bereitgestellten Skripts verwendet werden soll.

    6. Geben Sie unter Handler launch_instance ein. Dies ist der Funktionsname, der im folgenden Skript deklariert wird.

       Anmerkung

       Dies ist nicht erforderlich für PowerShell.

    7. Ersetzen Sie für Script (Skript) den Standardinhalt durch Folgendes. Stellen Sie sicher, dass das Skript dem entsprechenden Laufzeitwert entspricht.

       Python

       def launch_instance(events, context):
             import boto3
             ec2 = boto3.client('ec2')
           
             image_id = events['image_id']
             tag_value = events['tag_value']
             instance_type = events['instance_type']
           
             tag_config = {'ResourceType': 'instance', 'Tags': [{'Key':'Name', 'Value':tag_value}]}
           
             res = ec2.run_instances(ImageId=image_id, InstanceType=instance_type, MaxCount=1, MinCount=1, TagSpecifications=[tag_config])
           
             instance_id = res['Instances'][0]['InstanceId']
           
             print('[INFO] 1 EC2 instance is successfully launched', instance_id)
           
             return { 'InstanceId' : instance_id }

       PowerShell

       Install-Module AWS.Tools.EC2 -Force
           Import-Module AWS.Tools.EC2
           
           $payload = $env:InputPayload | ConvertFrom-Json
           
           $imageid = $payload.image_id
           
           $tagvalue = $payload.tag_value
           
           $instanceType = $payload.instance_type
           
           $type = New-Object Amazon.EC2.InstanceType -ArgumentList $instanceType
           
           $resource = New-Object Amazon.EC2.ResourceType -ArgumentList 'instance'
           
           $tag = @{Key='Name';Value=$tagValue}
           
           $tagSpecs = New-Object Amazon.EC2.Model.TagSpecification
           
           $tagSpecs.ResourceType = $resource
           
           $tagSpecs.Tags.Add($tag)
           
           $res = New-EC2Instance -ImageId $imageId -MinCount 1 -MaxCount 1 -InstanceType $type -TagSpecification $tagSpecs
           
           return @{'InstanceId'=$res.Instances.InstanceId}

    8. Erweitern Sie Additional inputs (Zusätzliche Eingaben).

    9. Wählen Sie für Eingabename die Option InputPayload. Geben Sie unter Input value (Eingabewert) die folgenden YAML-Daten ein.

       image_id: "{{ imageId }}"
           tag_value: "{{ tagValue }}"
           instance_type: "{{ instanceType }}"

13. Erweitern Sie Outputs (Ausgänge) und gehen Sie folgendermaßen vor:

    • Geben Sie unter Name payload ein.

    • Geben Sie für Selector (Selektor) $.Payload ein.

    • Wählen Sie für Type (Typ) die Option StringMap aus.

14. Klicken Sie auf Schritt hinzufügen, um dem Runbook einen zweiten Schritt hinzuzufügen. Der zweite Schritt fragt den Status der in Schritt 1 gestarteten Instance ab und wartet, bis der zurückgegebene Status ok ist.

15. Gehen Sie im Abschnitt Step 2 (Schritt 2) folgendermaßen vor.

    1. Geben Sie unter Step name (Schrittname) diesen beschreibenden Namen für den zweiten Schritt der Automatisierung ein: WaitForInstanceStatusOk.

    2. Wählen Sie unter Action type (Aktionstyp) die Option Run a script (Skript ausführen) (aws:executeScript).

    3. Geben Sie unter Description (Beschreibung) eine Beschreibung für den Automation-Schritt ein, wie etwa folgende.

       **About This Step**
           
           The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned.

    4. Bei Runtime (Laufzeit) wählen Sie die Laufzeitsprache für die Ausführung des bereitgestellten Skripts verwendet werden soll.

    5. Geben Sie unter Handler poll_instance ein. Dies ist der Funktionsname, der im folgenden Skript deklariert wird.

       Anmerkung

       Dies ist nicht erforderlich für PowerShell.

    6. Ersetzen Sie für Script (Skript) den Standardinhalt durch Folgendes. Stellen Sie sicher, dass das Skript dem entsprechenden Laufzeitwert entspricht.

       Python

       def poll_instance(events, context):
             import boto3
             import time
           
             ec2 = boto3.client('ec2')
           
             instance_id = events['InstanceId']
           
             print('[INFO] Waiting for instance status check to report ok', instance_id)
           
             instance_status = "null"
           
             while True:
               res = ec2.describe_instance_status(InstanceIds=[instance_id])
           
               if len(res['InstanceStatuses']) == 0:
                 print("Instance status information is not available yet")
                 time.sleep(5)
                 continue
           
               instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status']
           
               print('[INFO] Polling to get status of the instance', instance_status)
           
               if instance_status == 'ok':
                 break
           
               time.sleep(10)
           
             return {'Status': instance_status, 'InstanceId': instance_id}

       PowerShell

       
           Install-Module AWS.Tools.EC2 -Force
           
           $inputPayload = $env:InputPayload | ConvertFrom-Json
           
           $instanceId = $inputPayload.payload.InstanceId
           
           $status = Get-EC2InstanceStatus -InstanceId $instanceId
           
           while ($status.Status.Status -ne 'ok'){
              Write-Host 'Polling get status of the instance', $instanceId
           
              Start-Sleep -Seconds 5
           
              $status = Get-EC2InstanceStatus -InstanceId $instanceId
           }
           
           return @{Status = $status.Status.Status; InstanceId = $instanceId}

    7. Erweitern Sie Additional inputs (Zusätzliche Eingaben).

    8. Wählen Sie für Eingabename die Option InputPayload. Geben Sie unter Input value (Eingabewert) Folgendes ein:

       {{ LaunchEc2Instance.payload }}

16. Wählen Sie Create automation (Automation erstellen), um das Runbook zu speichern.