Utilisation d'instructions conditionnelles dans les runbooks - AWS Systems Manager
Utilisation de l'action aws:branchExemples d'utilisation des options conditionnelles

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.

Utilisation d'instructions conditionnelles dans les runbooks

Par défaut, les étapes que vous définissez dans la section mainSteps d'un runbook sont exécutées par ordre séquentiel. Lorsqu'une action est terminée, la prochaine action spécifiée dans la section mainSteps commence. En outre, si l'exécution d'une action échoue, l'intégralité de l'automatisation échoue (par défaut). Vous pouvez utiliser les options d'action d'automatisation aws:branch et de runbook décrites dans cette section pour créer des automatisations qui effectuent des ramifications conditionnelles. Autrement dit, vous pouvez créer des automatisations qui passent à une autre étape après avoir évalué différentes possibilités ou qui répondent aux modifications de manière dynamique à la fin d'une étape. Voici la liste des options que vous pouvez utiliser pour créer des automatisations dynamiques :

  • aws:branch: cette action d'automatisation vous permet de créer une automatisation dynamique qui évalue plusieurs options en une seule étape, puis passe à une autre étape dans le runbook Automation en fonction des résultats de cette évaluation.

  • nextStep: cette option spécifie l'étape d'une automatisation à traiter immédiatement après la fin d'une étape.

  • isEnd: cette option arrête une exécution d'automatisation à la fin d'une étape spécifique. La valeur par défaut de cette option est false.

  • isCritical: cette option désigne une étape comme étant critique pour la réussite de l'exécution de l'automatisation. Si une étape portant cette désignation échoue, l'automatisation signale l'état final de l'automatisation comme Failed. La valeur par défaut de cette option est true.

  • onFailure: cette option indique si l'automatisation doit être arrêtée, poursuivie ou changer d'étape en cas d'échec. La valeur par défaut de cette option est abort.

La section suivante décrit l'action de l'automatisation aws:branch. Pour de plus amples informations sur les options de nextStep, isEnd, isCritical et onFailure, veuillez consulter Exemple de runbooks aws:branch.

Utilisation de l'action aws:branch

L'action aws:branch propose les options les plus dynamiques des ramifications conditionnelles pour les automatisations. Comme noté précédemment, cette action permet à vos automatisations d'évaluer plusieurs conditions en une seule étape, puis de passer à une nouvelle étape en fonction des résultats de cette évaluation. L'action aws:branch fonctionne comme une instruction de programmation IF-ELIF-ELSE.

Voici un exemple YAML d'étape aws:branch.

- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

Lorsque vous spécifiez l'action aws:branch pour une étape, vous définissez des Choices que l'automatisation doit évaluer. L'automatisation peut évaluer ces Choices en fonction de la valeur d'un paramètre que vous avez spécifiée dans la section Parameters du runbook. L'automatisation peut également évaluer ces Choices en fonction de la sortie d'une étape précédente.

L'automatisation évalue chaque choix à l'aide d'une expression booléenne. Si l'évaluation détermine que le premier choix est true, l'automatisation accède à l'étape désignée pour ce choix. Si l'évaluation détermine que le premier choix est false, l'automatisation évalue le choix suivant. Si l'étape inclut au moins Choices, l'automatisation évalue chaque choix par ordre séquentiel jusqu'à ce qu'il en identifie un possédant la valeur true. L'automatisation accède ensuite à l'étape désignée correspondant au choix défini sur true.

Si aucun des Choices n'est true, l'automatisation vérifie si l'étape contient une valeur Default. La valeur Default définit une étape à laquelle l'automatisation doit passer si aucun des choix n'est défini sur true. Si aucune valeur Default n'est spécifiée pour l'étape, l'automatisation traite l'étape suivante du runbook.

Voici une aws:branch étape en YAML nommée SfromParameterChooSEO. Cette étape inclut deux Choices : (NextStep: runWindowsCommand) et (NextStep: runLinuxCommand). L'automatisation évalue ces Choices pour déterminer quelle commande exécuter pour le système d'exploitation approprié. La Variable pour chaque choix utilise {{OSName}}, qui est un paramètre défini par l'auteur dans la section Parameters du runbook.

mainSteps:
- name: chooseOSfromParameter
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OSName}}"
      StringEquals: Windows
    - NextStep: runLinuxCommand
      Variable: "{{OSName}}"
      StringEquals: Linux

Voici une aws:branch étape en YAML nommée SfromOutputChooSEO. Cette étape inclut deux Choices : (NextStep: runPowerShellCommand) et (NextStep: runShellCommand). L'automatisation évalue ces Choices pour déterminer quelle commande exécuter pour le système d'exploitation approprié. La Variable pour chaque choix utilise {{GetInstance.platform}}, qui est la sortie d'une étape antérieure dans le runbook. Cet exemple inclut également une option appelée Default. Si l'automatisation évalue les deux Choices, et si aucun choix n'est true, l'automatisation accède à une étape nommée PostProcessing.

mainSteps:
- name: chooseOSfromOutput
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      PostProcessing

Création d'une étape aws:branch dans un runbook

Lorsque vous créez une étape aws:branch dans un runbook, vous définissez les Choices que l'automatisation doit évaluer pour déterminer l'étape suivante à laquelle elle doit passer. Comme indiqué précédemment, l'évaluation des Choices repose sur une expression booléenne. Chaque choix doit définir les options suivantes :

  • NextStep: étape suivante du runbook à traiter si le choix indiqué esttrue.

  • Variable : Spécifiez soit le nom d'un paramètre défini dans la Parameters section du runbook, soit une variable définie dans la Variables section, soit un objet de sortie issu d'une étape précédente.

    Spécifiez les valeurs des variables à l'aide du formulaire suivant.

    Variable: "{{variable name}}"

    Spécifiez les valeurs des paramètres à l'aide du formulaire suivant.

    Variable: "{{parameter name}}"

    Spécifiez les variables d'objet de sortie sous la forme suivante.

    Variable: "{{previousStepName.outputName}}"

    Note

    La création de la variable de sortie est décrite plus en détail dans la section suivante, À propos de la création de la variable de sortie.

  • Opération : critères utilisés pour évaluer le choix, par exemple StringEquals: Linux. L'action aws:branch prend en charge les opérations suivantes :

    Opérations de chaîne

    • StringEquals

    • EqualsIgnoreCase

    • StartsWith

    • EndsWith

    • Contains

    Opérations numériques

    • NumericEquals

    • NumericGreater

    • NumericLesser

    • NumericGreaterOrEquals

    • NumericLesser

    • NumericLesserOrEquals

    Opération booléenne

    • BooleanEquals

    Important

    Lorsque vous créez un runbook, le système valide chaque opération dans le runbook. Si une opération n'est pas prise en charge, le système renvoie une erreur lorsque vous tentez de créer le runbook.

  • Default : spécifiez une étape de rechange à laquelle l'automatisation doit passer si aucun des Choices n'est défini sur true.

    Note

    Si vous ne voulez pas spécifier de valeur Default, vous pouvez spécifier l'option isEnd. Si aucun des Choices n'est true et qu'aucune valeur Default n'est spécifiée, l'automatisation s'arrête à la fin de l'étape.

Utilisez les modèles suivants pour vous aider à construire l'étape aws:branch dans votre runbook : Remplacez chaque example resource placeholder (espace réservé pour les ressources) avec vos propres informations.

YAML
mainSteps:
- name: step name
  action: aws:branch
  inputs:
    Choices:
    - NextStep: step to jump to if evaluation for this choice is true
      Variable: "{{parameter name or output from previous step}}"
      Operation type: Operation value
    - NextStep: step to jump to if evaluation for this choice is true
      Variable: "{{parameter name or output from previous step}}"
      Operation type: Operation value
    Default:
      step to jump to if all choices are false
JSON
{
   "mainSteps":[
      {
         "name":"a name for the step",
         "action":"aws:branch",
         "inputs":{
            "Choices":[
               {
                  "NextStep":"step to jump to if evaluation for this choice is true",
                  "Variable":"{{parameter name or output from previous step}}",
                  "Operation type":"Operation value"
               },
               {
                  "NextStep":"step to jump to if evaluation for this choice is true",
                  "Variable":"{{parameter name or output from previous step}}",
                  "Operation type":"Operation value"
               }
            ],
            "Default":"step to jump to if all choices are false"
         }
      }
   ]
}

À propos de la création de la variable de sortie

Pour créer un choix aws:branch qui fait référence à la sortie d'une étape précédente, vous devez identifier le nom de l'étape précédente et le nom du champ de sortie. Vous devez ensuite combiner les noms de l'étape et du champ en utilisant le format suivant.

Variable: "{{previousStepName.outputName}}"

Par exemple, dans l'exemple suivant, la première étape est nommée GetInstance. Ensuite, sous outputs, figure un champ appelé platform. Dans la deuxième étape (ChooseOSforCommands), l'auteur souhaite référencer la sortie du champ de la plateforme en tant que variable. Pour créer la variable, il suffit de combiner le nom de l'étape (GetInstance) et le nom du champ de sortie (plateforme) à créerVariable: "{{GetInstance.platform}}".

mainSteps:
- Name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
    Filters:
    - Key: InstanceIds
      Values: ["{{ InstanceId }}"]
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep

Voici un exemple qui montre comment "Variable": "{{ describeInstance.Platform }}" est créée à partir de l'étape précédente et du résultat.

- name: describeInstance
  action: aws:executeAwsApi
  onFailure: Abort
  inputs:
    Service: ec2
    Api: DescribeInstances
    InstanceIds:
    - "{{ InstanceId }}"
  outputs:
  - Name: Platform
    Selector: "$.Reservations[0].Instances[0].Platform"
    Type: String
  nextStep: branchOnInstancePlatform
- name: branchOnInstancePlatform
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runEC2RescueForWindows
      Variable: "{{ describeInstance.Platform }}"
      StringEquals: windows
    Default: runEC2RescueForLinux

Exemple de runbooks aws:branch

Voici quelques exemples de runbooks utilisant aws:branch.

Exemple 1 : utilisation d'aws:branch avec une variable de sortie pour exécuter des commandes en fonction du type de système d'exploitation

Dans la première étape de cet exemple (GetInstance), le créateur du runbook utilise l'action aws:executeAwsApi pour appeler l'opération d'API DescribeInstanceInformation de ssm. L'auteur utilise cette action pour déterminer le type de système d'exploitation utilisé par une instance. L'action aws:executeAwsApi génère l'ID d'instance et le type de plateforme.

Dans la deuxième étape (ChooseOSforCommands), l'auteur utilise l'action aws:branch avec deux Choices (NextStep: runPowerShellCommand) et (NextStep: runShellCommand). L'automatisation évalue le système d'exploitation de l'instance en utilisant la sortie de l'étape précédente (Variable: "{{GetInstance.platform}}"). L'automatisation accède à une étape pour le système d'exploitation désigné.

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
mainSteps:
- name: GetInstance
  action: aws:executeAwsApi
  inputs:
    Service: ssm
    Api: DescribeInstanceInformation
  outputs:
  - Name: myInstance
    Selector: "$.InstanceInformationList[0].InstanceId"
    Type: String
  - Name: platform
    Selector: "$.InstanceInformationList[0].PlatformType"
    Type: String
- name: ChooseOSforCommands
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runPowerShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Windows
    - NextStep: runShellCommand
      Variable: "{{GetInstance.platform}}"
      StringEquals: Linux
    Default:
      Sleep
- name: runShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runPowerShellCommand
  action: aws:runCommand
  inputs:
    DocumentName: AWS-RunPowerShellScript
    InstanceIds:
    - "{{GetInstance.myInstance}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

Exemple 2 : utilisation d'aws:branch avec une variable de paramètre pour exécuter des commandes en fonction du type de système d'exploitation

L'auteur définit plusieurs options de paramètres au début du runbook dans la section parameters. Un paramètre est nommé OperatingSystemName. Dans la première étape (ChooseOS), l'auteur utilise l'action aws:branch avec deux Choices (NextStep: runWindowsCommand) et (NextStep: runLinuxCommand). La variable pour ces Choices référence l'option de paramètre spécifiée dans la section Paramètres (Variable: "{{OperatingSystemName}}"). Lorsque l'utilisateur exécute ce runbook, il spécifie une valeur au moment de l'exécution pour OperatingSystemName. L'automatisation utilise le paramètre d'exécution lors de l'évaluation Choices. L'automatisation accède à une étape pour le système d'exploitation désigné en fonction du paramètre d'exécution spécifié pour OperatingSystemName.

---
schemaVersion: '0.3'
assumeRole: "{{AutomationAssumeRole}}"
parameters:
  AutomationAssumeRole:
    default: ""
    type: String
  OperatingSystemName:
    type: String
  LinuxInstanceId:
    type: String
  WindowsInstanceId:
    type: String
mainSteps:
- name: ChooseOS
  action: aws:branch
  inputs:
    Choices:
    - NextStep: runWindowsCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: windows
    - NextStep: runLinuxCommand
      Variable: "{{OperatingSystemName}}"
      StringEquals: linux
    Default:
      Sleep
- name: runLinuxCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunShellScript"
    InstanceIds:
    - "{{LinuxInstanceId}}"
    Parameters:
      commands:
      - ls
  isEnd: true
- name: runWindowsCommand
  action: aws:runCommand
  inputs:
    DocumentName: "AWS-RunPowerShellScript"
    InstanceIds:
    - "{{WindowsInstanceId}}"
    Parameters:
      commands:
      - date
  isEnd: true
- name: Sleep
  action: aws:sleep
  inputs:
    Duration: PT3S

Création d'automatisations à ramifications complexes avec des opérateurs

Vous pouvez créer des automatisations à ramifications complexes avec les opérateurs And, Or et Not dans les étapes aws:branch.

L'opérateur 'And'

Utilisez l'opérateur And lorsque vous voulez que plusieurs variables soient true pour un choix. Dans l'exemple suivant, le premier choix évalue si une instance est running et utilise le système d'exploitation Windows. Si l'évaluation de ces deux variables a la valeur true, l'automatisation accède à l'étape runPowerShellCommand. Si une ou plusieurs des variables sont false, l'automatisation évalue les variables du deuxième choix.

mainSteps:
- name: switch2
  action: aws:branch
  inputs:
    Choices:
    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Windows
      NextStep: runPowerShellCommand

    - And:
      - Variable: "{{GetInstance.pingStatus}}"
        StringEquals: running
      - Variable: "{{GetInstance.platform}}"
        StringEquals: Linux
      NextStep: runShellCommand
    Default:
      sleep3
L'opérateur 'Or'

Utilisez l'opérateur Or lorsque vous voulez qu'au moins une des variables soient true pour un choix. Dans l'exemple suivant, le premier choix évalue si un paramètre de chaîne est Windows et si la sortie d'une étape AWS Lambda est true. Si l'évaluation détermine que l'une de ces variables a la valeur true, l'automatisation accède à l'étape RunPowerShellCommand. Si les deux variables sont false, l'automatisation évalue les variables du deuxième choix.

- Or:
  - Variable: "{{parameter1}}"
    StringEquals: Windows
  - Variable: "{{BooleanParam1}}"
    BooleanEquals: true
  NextStep: RunPowershellCommand
- Or:
  - Variable: "{{parameter2}}"
    StringEquals: Linux
  - Variable: "{{BooleanParam2}}"
    BooleanEquals: true
  NextStep: RunShellScript
L'opérateur 'Not'

Utilisez l'opérateur Not lorsque vous souhaitez accéder à une étape définie lorsqu'une variable n'est pas true. Dans l'exemple suivant, le premier choix évalue si un paramètre de chaîne est Not Linux. Si l'évaluation détermine que la variable ne correspond pas à Linux, l'automatisation accède à l'étape sleep2. Si l'évaluation du premier choix détermine que la variable est Linux, l'automatisation évalue le choix suivant.

mainSteps:
- name: switch
  action: aws:branch
  inputs:
    Choices:
    - NextStep: sleep2
      Not:
        Variable: "{{testParam}}"
        StringEquals: Linux
    - NextStep: sleep1
      Variable: "{{testParam}}"
      StringEquals: Windows
    Default:
      sleep3

Exemples d'utilisation des options conditionnelles

Cette section inclut différents exemples d'utilisation des options dynamiques dans un runbook. Chaque exemple présenté dans cette section étend le runbook suivant. Ce runbook comporte deux actions. La première action se nomme InstallMsiPackage. Il utilise l'action aws:runCommand pour installer une application sur une instance Windows Server. La deuxième action se nomme TestInstall. Elle utilise l'action aws:invokeLambdaFunction pour effectuer un test de l'application installée si l'application a été installée correctement. La première étape spécifie onFailure: Abort. Ainsi, si l'application ne s'est pas installée correctement, l'automatisation s'arrête avant la deuxième étape.

Exemple 1 : runbook comportant deux actions linéaires

---
schemaVersion: '0.3'
description: Install MSI package and run validation.
assumeRole: "{{automationAssumeRole}}"
parameters:
  automationAssumeRole:
    type: String
    description: "(Required) Assume role."
  packageName:
    type: String
    description: "(Required) MSI package to be installed."
  instanceIds:
    type: String
    description: "(Required) Comma separated list of instances."
mainSteps:
- name: InstallMsiPackage
  action: aws:runCommand
  maxAttempts: 2
  onFailure: Abort
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
...

Création d'une automatisation dynamique qui passe à différentes étapes à l'aide de l'option onFailure

L'exemple suivant utilise les options onFailure: step:step name, nextStep et isEnd pour créer une automatisation dynamique. Dans cet exemple, si l'InstallMsiPackageaction échoue, l'automatisation passe à une action appelée PostFailure(onFailure: step:PostFailure) pour exécuter une AWS Lambda fonction afin d'effectuer une action en cas d'échec de l'installation. Si l'installation réussit, l'automatisation passe à l' TestInstall action ()nextStep: TestInstall. Les étapes TestInstall et PostFailure utilisent l'option isEnd (isEnd: true) pour que l'automatisation se termine lorsque l'une de ces étapes est terminée.

Note

L'utilisation de l'option isEnd à la dernière étape de la section mainSteps est facultative. Si la dernière étape ne fait pas passer à d'autres étapes, l'automatisation s'arrête après l'exécution de l'action effectuée à la dernière étape.

Exemple 2 : automatisation dynamique qui passe à différentes étapes

mainSteps
- name: InstallMsiPackage
  action: aws:runCommand
  onFailure: step:PostFailure
  maxAttempts: 2
  inputs:
    InstanceIds:
    - "{{instanceIds}}"
    DocumentName: AWS-RunPowerShellScript
    Parameters:
      commands:
      - msiexec /i {{packageName}}
  nextStep: TestInstall
- name: TestInstall
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: TestLambdaFunction
  isEnd: true
- name: PostFailure
  action: aws:invokeLambdaFunction
  maxAttempts: 1
  timeoutSeconds: 500
  inputs:
    FunctionName: PostFailureRecoveryLambdaFunction
  isEnd: true
...
Note

Avant de traiter un runbook, le système vérifie que le runbook ne crée pas une boucle infinie. Si une boucle infinie est détectée, Automation renvoie une erreur, avec un cercle qui entoure les étapes qui créent la boucle.

Création d'une automatisation dynamique qui définit des étapes critiques

Vous pouvez spécifier qu'une étape est critique pour la réussite globale de l'automatisation. Si une étape critique échoue, Automation signale l'état Failed pour l'automatisation, même si une ou plusieurs étapes se sont déroulées correctement. Dans l'exemple suivant, l'utilisateur identifie l'VerifyDependenciesétape en cas d'échec (onFailure: step:VerifyDependencies). InstallMsiPackage L'utilisateur spécifie que l'étape InstallMsiPackage n'est pas critique (isCritical: false). Dans cet exemple, si l'installation de l'application a échoué, Automation traite l'étape VerifyDependencies pour déterminer si une ou plusieurs dépendances sont manquantes, ce qui aurait provoqué l'échec de l'installation.

Exemple 3 : définition des étapes critiques de l'automatisation 

---
name: InstallMsiPackage
action: aws:runCommand
onFailure: step:VerifyDependencies
isCritical: false
maxAttempts: 2
inputs:
  InstanceIds:
  - "{{instanceIds}}"
  DocumentName: AWS-RunPowerShellScript
  Parameters:
    commands:
    - msiexec /i {{packageName}}
nextStep: TestPackage
...