Créer des runbooks à l'aide de Document Builder - AWS Systems Manager
Créer un runbook à l'aide de Document BuilderCréer un runbook qui exécute des scripts

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Créer des runbooks à l'aide de Document Builder

Si les runbooks AWS Systems Manager publics ne prennent pas en charge toutes les actions que vous souhaitez effectuer sur vos AWS ressources, vous pouvez créer vos propres runbooks. Pour créer un runbook personnalisé, vous pouvez créer manuellement un fichier local YAML ou JSON formaté avec les actions d'automatisation appropriées. Vous pouvez également utiliser Document Builder dans la console Systems Manager Automation pour créer un runbook personnalisé.

À l'aide de Document Builder, vous pouvez ajouter des actions d'automatisation à votre runbook personnalisé et fournir les paramètres requis sans avoir à utiliser JSON de YAML syntaxe. Après avoir ajouté des étapes et créé le runbook, le système convertit les actions que vous avez ajoutées dans le YAML format que Systems Manager peut utiliser pour exécuter l'automatisation.

Les runbooks prennent en charge l'utilisation de Markdown, un langage de balisage, qui vous permet d'ajouter des descriptions de style wiki aux runbooks et des étapes individuelles au sein du runbook. Pour plus d'informations sur l'utilisation de Markdown, consultez Utilisation de Markdown dans AWS.

Créer un runbook à l'aide de Document Builder

Avant de commencer

Nous vous recommandons de prendre connaissance des différentes actions que vous pouvez effectuer dans un runbook. Pour de plus amples informations, veuillez consulter Référence sur les actions Systems Manager Automation.

Pour créer un runbook à l'aide de Document Builder

  1. Ouvrez la AWS Systems Manager console à l'adresse https://console.aws.amazon.com/systems-manager/.

  2. Dans le panneau de navigation, cliquez sur Documents.

  3. Sélectionnez Create automation (Créer une automatisation).

  4. Pour Name (Nom), saisissez un nom descriptif pour le runbook.

  5. Pour Document description (Description du document), indiquez la description du style de balisage pour le runbook. Vous pouvez fournir des instructions sur l'utilisation du runbook, des étapes numérotées ou tout autre type d'information pour décrire le runbook. Reportez-vous au texte par défaut pour plus d'informations sur la mise en forme de votre contenu.

    Astuce

    Basculez entre Hide preview (Masquer l'aperçu) et Show preview (Afficher l'aperçu) pour voir à quoi ressemble le contenu de votre description lors de la composition.

  6. (Facultatif) Dans Assumer le rôle, entrez le nom ou le nom ARN d'un rôle de service pour effectuer des actions en votre nom. Si vous ne spécifiez pas de rôle, Automation utilise les autorisations d'accès de l'utilisateur qui exécute l'automatisation.

    Important

    Pour les runbooks qui ne sont pas la propriété d'Amazon et qui utilisent l'action aws:executeScript, un rôle doit être spécifié. Pour plus d’informations, veuillez consulter Autorisations pour l'utilisation de runbooks.

  7. (Facultatif) Pour Outputs (Sorties), saisissez une sortie pour l'automatisation de ce runbook à mettre à disposition d'autres processus.

    Par exemple, si votre runbook en crée un nouveauAMI, vous pouvez spécifier [». CreateImage ImageId«], puis utilisez cette sortie pour créer de nouvelles instances lors d'une automatisation ultérieure.

  8. (Facultatif) Développez la section Input Parameters (Paramètres d'entrée) et procédez comme suit.

    1. Dans Parameter name (Nom de paramètre), saisissez un nom descriptif pour le paramètre de runbook que vous créez.

    2. Pour Type, sélectionnez un type pour le paramètre, par exemple, String ou MapList.

    3. Pour Required (Obligatoire), effectuez l'une des opérations suivantes :

      • Sélectionnez Yes (Oui) si une valeur pour ce paramètre de runbook doit être fournie lors de l'exécution.

      • Sélectionnez No (Non) si le paramètre n'est pas obligatoire et (facultatif) saisissez une valeur de paramètre par défaut dans Defaults value (Valeur par défaut).

    4. Dans Description, saisissez une description pour le paramètre de runbook.

    Note

    Pour ajouter d'autres paramètres de runbook, sélectionnez Add a parameter (Ajouter un paramètre). Pour supprimer un paramètre de runbook, cliquez sur le bouton X (Supprimer).

  9. (Facultatif) Développez la section Target type (Type de cible) et sélectionnez un type de cible pour définir les types de ressources sur lesquelles l'automatisation peut s'exécuter. Par exemple, pour utiliser un runbook sur des EC2 instances, choisissez/AWS::EC2::Instance.

    Note

    Si vous spécifiez la valeur « / », le runbook peut s'exécuter sur tous les types de ressources. Pour obtenir la liste des types de ressources valides, consultez la Référence des types de ressources AWS dans le Guide de l'utilisateur AWS CloudFormation .

  10. (Facultatif) Développez la section Document tags (Balises de document) et saisissez une ou plusieurs paires clé-valeur de balise à appliquer au runbook. Les balises facilitent l'identification, l'organisation et la recherche de ressources.

  11. Dans la section Step 1 (Étape 1) fournissez les informations suivantes.

    • Pour Step name (Nom de l'étape), entrez un nom descriptif pour la première étape de l'automatisation.

    • Pour Action type (Type d'action), sélectionnez le type d'action à utiliser pour cette étape.

      Pour obtenir une liste et des informations sur les types d'action disponibles, consultez Référence sur les actions Systems Manager Automation.

    • Dans Description, entrez une description pour l'étape d'automatisation. Vous pouvez utiliser Markdown pour mettre en forme votre texte.

    • Selon le Type d'action sélectionné, saisissez les entrées requises pour le type d'action dans la section Step inputs (Entrées d'étape). Par exemple, si vous avez sélectionné l'action aws:approve, vous devez spécifier une valeur pour la propriété Approvers.

      Pour plus d'informations sur les champs d'entrée d'étape, consultez l'entrée de Référence sur les actions Systems Manager Automation correspondant au type d'action sélectionné. olpPar exemple : aws:executeStateMachine – exécuter une machine d'état AWS Step Functions.

    • (Facultatif) Pour Additional inputs (entrées supplémentaires), indiquez toutes les valeurs d'entrée supplémentaires nécessaires à votre runbook. Les types d'entrée disponibles dépendent du type d'action que vous avez sélectionné pour l'étape. (Notez que certains types d'action nécessitent des valeurs d'entrée.)

      Note

      Pour ajouter d'autres entrées, sélectionnez Add optional input (Ajouter une entrée facultative). Pour supprimer une entrée, cliquez sur le bouton X (Supprimer).

    • (Facultatif) Pour Outputs (Sorties), saisissez une sortie pour cette étape à mettre à disposition d'autres processus.

      Note

      L'option Outputs (Sorties) n'est pas disponible pour tous les types d'action.

    • (Facultatif) Développez la section Common properties (Propriétés communes) et spécifiez les propriétés des actions communes à toutes les actions d'automatisation. Par exemple, pour Timeout seconds (Expiration en secondes), vous pouvez fournir une valeur en secondes pour spécifier la durée de l'exécution de l'étape avant qu'elle ne soit arrêtée.

      Pour de plus amples informations, veuillez consulter Propriétés partagées par toutes les actions.

    Note

    Pour ajouter d'autres étapes, sélectionnez Add step (Ajouter étape) et répétez la procédure de création d'une étape. Pour supprimer une étape, sélectionnez Remove step (Supprimer étape).

  12. Sélectionnez Create automation (Créer une automatisation) pour enregistrer le runbook.

Créer un runbook qui exécute des scripts

La procédure suivante explique comment utiliser Document Builder dans la console AWS Systems Manager Automation pour créer un runbook personnalisé qui exécute un script.

La première étape du runbook que vous créez exécute un script pour lancer une instance Amazon Elastic Compute Cloud (AmazonEC2). La deuxième étape exécute un autre script pour surveiller la vérification de l'état de l'instance à remplacer par ok. Ensuite, un état général de Success est signalé pour l'automatisation.

Avant de commencer

Assurez-vous que vous avez suivi les étapes ci-dessous :

Créer un runbook personnalisé qui exécute des scripts à l'aide de Document Builder

  1. Ouvrez la AWS Systems Manager console à l'adresse https://console.aws.amazon.com/systems-manager/.

  2. Dans le panneau de navigation, cliquez sur Documents.

  3. Sélectionnez Create automation (Créer une automatisation).

  4. Dans Name (Nom), saisissez ce nom descriptif pour le runbook : LaunchInstanceAndCheckStatus.

  5. (Facultatif) Pour Document description (Description du document), remplacez le texte par défaut par une description pour ce runbook, à l'aide de Markdown. Voici un exemple.

    ##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. Dans le champ Assumer le rôle, entrez le rôle ARN de IAM service pour Automation (Assumer le rôle) pour l'automatisation, au formatarn:aws:iam::111122223333:role/AutomationServiceRole. Remplacez votre Compte AWS identifiant par 111122223333.

    Le rôle que vous spécifiez est utilisé pour fournir les autorisations nécessaires pour démarrer l'automatisation.

    Important

    Pour les runbooks qui ne sont pas la propriété d'Amazon et qui utilisent l'action aws:executeScript, un rôle doit être spécifié. Pour plus d’informations, veuillez consulter Autorisations pour l'utilisation de runbooks.

  7. Développez Input parameters (Paramètres d'entrée) et procédez comme suit.

    1. Dans Parameter name (Nom du paramètre), entrez imageId.

    2. Dans le champ Type, sélectionnez String.

    3. Pour Required (Obligatoire), sélectionnez No.

    4. Pour Default value (Valeur par défaut), entrez ce qui suit.

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

      Cette valeur lance une EC2 instance Amazon utilisant la dernière version d'Amazon Linux 1. Amazon Machine Image (AMI) IDENTIFIANT. Si vous souhaitez utiliser un autre AMI, remplacez la valeur par votre AMI IDENTIFIANT.

    5. Pour Description, entrez ce qui suit.

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

  8. Sélectionnez Add a parameter (Ajouter un paramètre) pour créer le second paramètre tagValue, puis entrez ce qui suit.

    1. Dans Parameter name (Nom du paramètre), entrez tagValue.

    2. Dans le champ Type, sélectionnez String.

    3. Pour Required (Obligatoire), sélectionnez No.

    4. Pour Default value (Valeur par défaut), entrez LaunchedBySsmAutomation. La paire clé-valeur de balise Name:LaunchedBySsmAutomation est ajoutée à l'instance.

    5. Pour Description, entrez ce qui suit.

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

  9. Sélectionnez Add a parameter (Ajouter un paramètre) pour créer le troisième paramètre instanceType, puis entrez les informations suivantes.

    1. Dans Parameter name (Nom du paramètre), entrez instanceType.

    2. Dans le champ Type, sélectionnez String.

    3. Pour Required (Obligatoire), sélectionnez No.

    4. Pour Default value (Valeur par défaut), entrez t2.micro.

    5. Pour Parameter description (Description du paramètre), entrez ce qui suit.

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

  10. Développez Target type (Type de cible) et sélectionnez "/".

  11. (Facultatif) Développez les Document tags (Balises de document) pour appliquer des balises de ressources à votre runbook. Pour la Tag key (Clé de balise), entrez Purpose, et pour Tag value (Valeur de balise), entrez LaunchInstanceAndCheckState.

  12. Dans la section Step 1 (Étape 1) procédez comme suit.

    1. Pour Step name (Nom de l'étape), entrez un nom descriptif pour la première étape de l'automatisation : LaunchEc2Instance.

    2. Pour Action type (Type d'action), sélectionnez Run a script (Exécuter un script= (aws:executeScript).

    3. Dans Description, entrez une description de l'étape d'automatisation, telle que la suivante.

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

    4. Développez Inputs (Entrées).

    5. Dans Runtime, sélectionnez le langage d'exécution à utiliser pour exécuter le script fourni.

    6. Pour Handler (Gestionnaire), entrez launch_instance. Il s'agit du nom de la fonction déclaré dans le script suivant.

      Note

      Cela n'est pas obligatoire pour PowerShell.

    7. Pour Script, remplacez le contenu par défaut par ce qui suit. Veillez à faire correspondre le script avec la valeur d'exécution correspondante.

      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. Développer Additional inputs (Entrées supplémentaires).

    9. Dans Nom de l'entrée, choisissez InputPayload. Pour Valeur d'entrée, entrez les YAML données suivantes. 

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

  13. Développez Outputs (Sorties) et procédez comme suit :

    • Pour Name (Nom), saisissez payload.

    • Pour Selector (Sélecteur), entrez $.Payload.

    • Dans le champ Type, sélectionnez StringMap.

  14. Sélectionnez Add step (Ajouter une étape) pour ajouter une deuxième étape au runbook. La deuxième étape interroge l'état de l'instance lancée à l'étape 1 et attend que l'état renvoyé soit ok.

  15. Dans la section Step 2 (Étape 2) procédez comme suit.

    1. Pour Step name (Nom de l'étape), entrez un nom descriptif pour la deuxième étape de l'automatisation : WaitForInstanceStatusOk.

    2. Pour Action type (Type d'action), sélectionnez Run a script (Exécuter un script= (aws:executeScript).

    3. Dans Description, entrez une description de l'étape d'automatisation, telle que la suivante.

      **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. Pour Exécution, sélectionnez le langage d'exécution à utiliser pour exécuter le script fourni.

    5. Pour Handler (Gestionnaire), entrez poll_instance. Il s'agit du nom de la fonction déclaré dans le script suivant.

      Note

      Cela n'est pas obligatoire pour PowerShell.

    6. Pour Script, remplacez le contenu par défaut par ce qui suit. Veillez à faire correspondre le script avec la valeur d'exécution correspondante.

      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. Développer Additional inputs (Entrées supplémentaires).

    8. Dans Nom de l'entrée, choisissez InputPayload. Pour Input value (Valeur d'entrée), entrez ce qui suit.

      {{ LaunchEc2Instance.payload }}

  16. Sélectionnez Create automation (Créer une automatisation) pour enregistrer le runbook.