Uso de instrucciones condicionales en manuales de procedimientos

De forma predeterminada, los pasos que defina en la sección mainSteps de un manual de procedimientos se ejecutan en orden secuencial. Cuando finaliza una acción, comienza la siguiente acción especificada en la sección mainSteps. Asimismo, si una acción no se ejecuta, falla toda la automatización (de forma predeterminada). Puede utilizar la acción de automatización aws:branch y las opciones de manual de procedimientos que se describen en esta sección para crear automatizaciones que aplican la bifurcación condicional. Esto significa que puede crear automatizaciones que salten a otro paso después de evaluar diferentes elecciones o de responder de forma dinámica a los cambios cuando se completa un paso. A continuación, se muestra una lista de las opciones que puede utilizar para crear automatizaciones dinámicas:

En la siguiente sección, se describe la acción de automatización aws:branch. Para obtener más información acerca de las opciones nextStep, isEnd, isCritical y onFailure, consulte Manuales de procedimientos aws:branch de ejemplo.

Uso de la acción aws:branch

La acción aws:branch ofrece las opciones de bifurcación condicional más dinámicas para las automatizaciones. Como se ha indicado anteriormente, esta acción permite que la automatización evalúe varias condiciones en un solo paso y, a continuación, salte a un nuevo paso en función de los resultados de dicha evaluación. La acción aws:branch funciona como una instrucción IF-ELIF-ELSE en programación.

A continuación, se muestra un ejemplo YAML de un paso 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

Cuando se especifica la acción aws:branch para un paso, se especifican Choices que la automatización debe evaluar. La automatización puede evaluar Choices según el valor de un parámetro que especificó en la sección Parameters del manual de procedimientos. La automatización también puede evaluar Choices en función de la salida de un paso anterior.

La automatización evalúa cada elección mediante una expresión booleana. Si la evaluación determina que la primera elección es true, la automatización saltará al paso designado para esa elección. Si la evaluación determina que la primera elección es false, entonces la automatización evaluará la siguiente elección. Si el paso incluye tres o más Choices, la automatización evalúa cada elección en orden secuencial hasta que evalúa una que sea true. A continuación, la automatización saltará al paso designado para la elección true.

Si ninguna de las Choices es true, la automatización comprueba si el paso contiene un valor Default. Un valor Default define un paso al cual la automatización debe saltar si ninguna de las elecciones es true. Si no se especifica un valor Default para el paso, la automatización procesará el siguiente paso en el manual de procedimientos.

A continuación, se muestra un paso aws:branch en YAML llamado chooseOSfromParameter. Este paso incluye dos Choices: (NextStep: runWindowsCommand) y (NextStep: runLinuxCommand). La automatización evalúa estas Choices a fin de determinar qué comando ejecutar para el sistema operativo adecuado. La Variable para cada elección utiliza {{OSName}}, que es un parámetro que el autor del manual de procedimientos definió en la sección Parameters del manual.

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

A continuación, se muestra un paso aws:branch en YAML llamado chooseOSfromOutput. Este paso incluye dos Choices: (NextStep: runPowerShellCommand) y (NextStep: runShellCommand). La automatización evalúa estas Choices a fin de determinar qué comando ejecutar para el sistema operativo adecuado. La Variable para cada elección utiliza {{GetInstance.platform}}, que es la salida de un paso anterior en el manual de procedimientos. En este ejemplo también se incluye una opción llamada Default. Si la automatización evalúa ambas Choices y ninguna de ellas es true, saltará a un paso llamado 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

Creación de un paso aws:branch en un manual de procedimientos

Al crear un paso aws:branch en un manual de procedimientos, debe definir las Choices que la automatización deberá evaluar para determinar a qué paso debe pasar a continuación. Tal y como se ha mencionado anteriormente, las Choices se evalúan mediante una expresión booleana. Cada elección debe definir las siguientes opciones:

Utilice las siguientes plantillas para construir el paso aws:branch en los manuales de procedimientos. Reemplace cada example resource placeholder con su propia información.

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

Acerca de la creación de la variable de salida

Para crear una elección aws:branch que haga referencia a la salida de un paso anterior, debe identificar el nombre del paso anterior y el nombre del campo de salida. A continuación, combine los nombres del paso y el campo con el siguiente formato.

Variable: "{{previousStepName.outputName}}"

Por ejemplo, el primer paso del siguiente ejemplo se denomina GetInstance. Y, a continuación, debajo de outputs, hay un campo llamado platform. En el segundo paso (ChooseOSforCommands), el autor quiere hacer referencia a la salida del campo platform como una variable. Para crear la variable, solo tiene que combinar el nombre del paso (GetInstance) y el nombre del campo de salida (platform) para crear Variable: "{{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

En este ejemplo, se muestra cómo se crea "Variable": "{{ describeInstance.Platform }}" a partir del paso anterior y el resultado.

- 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

Manuales de procedimientos aws:branch de ejemplo

A continuación, se muestran algunos ejemplos de manuales de procedimientos que utilizan aws:branch.

Ejemplo 1: uso de aws:branch con una variable de salida para ejecutar comandos según el tipo de sistema operativo

En el primer paso de este ejemplo (GetInstance), el autor del manual de procedimientos utiliza la acción aws:executeAwsApi para llamar la operación ssm DescribeInstanceInformation de la API. El autor utiliza esta acción para determinar el tipo de sistema operativo que utiliza una instancia. La acción aws:executeAwsApi devuelve el ID de instancia y el tipo de plataforma.

En el segundo paso (ChooseOSforCommands), el autor utiliza la acción aws:branch con dos Choices (NextStep: runPowerShellCommand) y (NextStep: runShellCommand). La automatización evalúa el sistema operativo de la instancia a través de la salida del paso anterior (Variable: "{{GetInstance.platform}}"). La automatización salta a un paso para el sistema operativo designado.

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

Ejemplo 2: uso de aws:branch con una variable de parámetro para ejecutar comandos según el tipo de sistema operativo

El autor del manual de procedimientos define varias opciones de parámetros al principio del manual, en la sección parameters. Un parámetro se llama OperatingSystemName. En el primer paso (ChooseOS), el autor utiliza la acción aws:branch con dos Choices (NextStep: runWindowsCommand) y (NextStep: runLinuxCommand). La variable para estas Choices hace referencia a la opción del parámetro especificada en la sección de parámetros (Variable: "{{OperatingSystemName}}"). Cuando el usuario ejecuta este manual de procedimientos, especifica un valor en el tiempo de ejecución para OperatingSystemName. La automatización utiliza el parámetro de tiempo de ejecución durante la evaluación de Choices. La automatización salta a un paso para el sistema operativo designado según el parámetro de tiempo de ejecución especificado para 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

Creación de automatizaciones con bifurcación complejas a través de operadores

Puede crear automatizaciones con bifurcación complejas mediante el uso de los operadores And, Or y Not en los pasos aws:branch.

El operador “And”

Utilice el operador And cuando desee que varias variables sean true para una elección. En el siguiente ejemplo, la primera elección evalúa si una instancia está en ejecución, running, y utiliza el sistema operativo Windows. Si la evaluación de ambas variables es da como resultado true, la automatización salta al paso runPowerShellCommand. Si una o más de las variables es false, la automatización evaluará las variables de la segunda elección.

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

El operador “Or”

Utilice el operador Or cuando desee que cualquiera de entre varias variables sea verdadera para una elección. En el siguiente ejemplo, la primera elección evalúa si una cadena de parámetro es Windows y si la salida de un paso AWS Lambda es verdadera. Si la evaluación determina que alguna de estas variables es true, la automatización salta al paso RunPowerShellCommand. Si las dos variables son false, la automatización evaluará las variables de la segunda elección.

- Or:
  - Variable: "{{parameter1}}"
    StringEquals: Windows
  - Variable: "{{BooleanParam1}}"
    BooleanEquals: true
  NextStep: RunPowershellCommand
- Or:
  - Variable: "{{parameter2}}"
    StringEquals: Linux
  - Variable: "{{BooleanParam2}}"
    BooleanEquals: true
  NextStep: RunShellScript

El operador “Not”

Utilice el operador Not cuando desee saltar a un paso definido cuando una variable no sea verdadera. En el siguiente ejemplo, la primera elección evalúa si una cadena de parámetro es Not Linux. Si la evaluación determina que la variable no es Linux, la automatización salta al paso sleep2. Si la evaluación de la primera elección determina que es Linux, entonces la automatización evaluará la siguiente elección.

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

Ejemplos de cómo usar opciones condicionales

En esta sección, se incluyen diferentes ejemplos de cómo utilizar opciones dinámicas en un manual de procedimientos. Cada ejemplo de esta sección amplía el siguiente manual de procedimientos. Este manual de procedimientos tiene dos acciones. La primera acción se denomina InstallMsiPackage. Utiliza la aws:runCommand acción para instalar una aplicación en una Windows Server instancia. La segunda acción se denomina TestInstall. Utiliza la acción aws:invokeLambdaFunction para probar la aplicación instalada si esta se instala correctamente. El paso uno especifica onFailure: Abort. Esto significa que, si la aplicación no se instala correctamente, la automatización se detiene antes del paso dos.

Ejemplo 1: manual de procedimientos con dos acciones lineales

---
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
...

Creación de una automatización dinámica que salta a diferentes pasos con la opción onFailure

En el siguiente ejemplo, se utilizan las opciones onFailure: step:step name, nextStep e isEnd para crear una automatización dinámica. En este ejemplo, si la acción InstallMsiPackage produce un error, la automatización salta a una acción denominada PostFailure (onFailure: step:PostFailure) para ejecutar una función de AWS Lambda con la que se realiza alguna acción en caso de que se produzca un error durante la instalación. Si la instalación se realiza correctamente, la automatización salta a la acción TestInstall (nextStep: TestInstall). Tanto el paso TestInstall como el paso PostFailure utilizan la opción isEnd (isEnd: true) de modo que la automatización se finaliza cuando se haya completado alguno de esos pasos.

Ejemplo 2: una automatización dinámica que salta a diferentes pasos

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
...

Creación de una automatización dinámica que define pasos críticos

Puede especificar que un paso es de importancia crítica para el éxito general de la automatización. Si un paso crítico presenta error, Automation informa que el estado de la automatización es Failed, incluso aunque uno o más pasos se hayan ejecutado correctamente. En el siguiente ejemplo, se indica que debe ejecutarse el paso VerifyDependencies si se produce un error en el paso InstallMsiPackage (onFailure: step:VerifyDependencies). También se indica que el paso InstallMsiPackage no es crítico (isCritical: false). En este ejemplo, si la aplicación no se instala correctamente, la Automation procesa el paso VerifyDependencies para determinar si faltan una o varias dependencias, lo que ha provocado que la aplicación no se instale.

Ejemplo 3: definición de pasos críticos para la automatización

---
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
...