Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Puesta en marcha de las tareas de Automatización de AWS Systems Manager de forma sincrónica desde AWS Step Functions *Elie El khoury, Amazon Web Services* ## Resumen Este patrón explica cómo integrarse AWS Step Functions con AWS Systems Manager. Utiliza las integraciones de servicios del AWS SDK para llamar a la **startAutomationExecution**API de Systems Manager con un token de tarea de un flujo de trabajo de una máquina de estado y se detiene hasta que el token regresa con una llamada correcta o errónea. Para demostrar la integración, este patrón implementa un encapsulador de documentos (manuales de procedimientos) de Automatización en torno a los documentos `AWS-RunShellScript` o `AWS-RunPowerShellScript`; además, usa `.waitForTaskToken` para llamar de forma sincrónica a `AWS-RunShellScript` o `AWS-RunPowerShellScript`. Para obtener más información sobre las integraciones de servicios del AWS SDK en Step Functions, consulta la [Guía para AWS Step Functions desarrolladores](https://docs.aws.amazon.com/step-functions/latest/dg/supported-services-awssdk.html). Step Functions**** es un servicio de flujo de trabajo visual de bajo código que puede utilizar para crear aplicaciones distribuidas, automatizar los procesos empresariales y de TI y crear canalizaciones de datos y aprendizaje automático mediante AWS el uso de servicios. Los flujos de trabajo gestionan los errores, los reintentos, la paralelización, las integraciones de servicios y la observabilidad para que pueda centrarse en una lógica empresarial de mayor valor. La automatización, una capacidad de AWS Systems Manager, simplifica las tareas comunes de mantenimiento, implementación y corrección para empresas Servicios de AWS como Amazon Elastic Compute Cloud (Amazon EC2), Amazon Relational Database Service (Amazon RDS), Amazon Redshift y Amazon Simple Storage Service (Amazon S3). Automation le ofrece un control granular sobre la concurrencia de sus automatizaciones. Por ejemplo, puede especificar a cuántos recursos desea dirigirse simultáneamente y cuántos errores pueden producirse antes de que se detenga una automatización. Para obtener detalles sobre la implementación, incluidos los pasos, parámetros y ejemplos del manual de procedimientos, consulte la sección [Información adicional](#run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions-additional). ## Requisitos previos y limitaciones **Requisitos previos ** + AWS Una cuenta activa + AWS Identity and Access Management (IAM) para acceder a Step Functions y Systems Manager + Una EC2 instancia con el Agente Systems Manager (SSM Agent) [instalado](https://docs.aws.amazon.com/systems-manager/latest/userguide/sysman-install-ssm-agent.html) en la instancia + [Un perfil de instancia de IAM para Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-instance-profile.html) adjunto a la instancia en la que planea ejecutar el manual de procedimientos + Un rol de Step Functions que tenga los siguientes permisos de IAM (que sigan el principio de privilegio mínimo): ``` { "Effect": "Allow", "Action": "ssm:StartAutomationExecution", "Resource": "*" } ``` **Versiones de producto** + Versión de esquema de documento de SSM 0.3 o posterior + SSM Agent versión 2.3.672.0 o posterior ## Arquitectura **Pila de tecnología de destino** + AWS Step Functions + AWS Systems Manager Automation **Arquitectura de destino** ![Arquitectura para ejecutar tareas de automatización de Systems Manager de forma sincrónica desde Step Functions](http://docs.aws.amazon.com/es_es/prescriptive-guidance/latest/patterns/images/pattern-img/47c19e4f-d68d-4f91-bb68-202098757529/images/2d248aae-d858-4565-8af2-593cde0da780.png) **Automatización y escala** + Este patrón proporciona una AWS CloudFormation plantilla que puede usar para implementar los manuales de ejecución en varias instancias. (Consulte el repositorio de [implementación de GitHub Step Functions y Systems Manager](https://github.com/aws-samples/amazon-stepfunctions-ssm-waitfortasktoken)). ## Tools (Herramientas) **Servicios de AWS** + [AWS CloudFormation](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html)le ayuda a configurar AWS los recursos, aprovisionarlos de forma rápida y coherente y administrarlos a lo largo de su ciclo de vida en todas Cuentas de AWS las regiones. + [AWS Identity and Access Management (IAM)](https://docs.aws.amazon.com/IAM/latest/UserGuide/introduction.html) lo ayuda a administrar de forma segura el acceso a sus AWS recursos al controlar quién está autenticado y autorizado a usarlos. + [AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)es un servicio de organización sin servidor que le ayuda a combinar AWS Lambda funciones y otras Servicios de AWS para crear aplicaciones esenciales para la empresa. + [AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/what-is-systems-manager.html) lo ayuda a administrar las aplicaciones y la infraestructura que se ejecutan en la Nube de AWS. Simplifica la administración de aplicaciones y recursos, reduce el tiempo necesario para detectar y resolver problemas operativos y le ayuda a administrar sus recursos de forma segura y a escala. AWS **Código** El código de este patrón está disponible en el repositorio de [implementación de GitHub Step Functions y Systems Manager](https://github.com/aws-samples/amazon-stepfunctions-ssm-waitfortasktoken).  ## Epics ### Creación de manuales de procedimientos | Tarea | Descripción | Habilidades requeridas | | --- | --- | --- | | Descargue la CloudFormation plantilla. | Descarga la `ssm-automation-documents.cfn.json` plantilla de la `cloudformation ` carpeta del GitHub repositorio. | AWS DevOps | | Cree manuales de procedimientos. | Inicie sesión en Consola de administración de AWS, abra la [CloudFormation consola](https://console.aws.amazon.com/cloudformation/) e implemente la plantilla. Para obtener más información sobre la implementación de CloudFormation plantillas, consulte [Crear una pila en la CloudFormation consola](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-create-stack.html) en la CloudFormation documentación. La CloudFormation plantilla implementa tres recursos:[See the AWS documentation website for more details](http://docs.aws.amazon.com/es_es/prescriptive-guidance/latest/patterns/run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions.html) | AWS DevOps | ### Crear una máquina de estado de muestra | Tarea | Descripción | Habilidades requeridas | | --- | --- | --- | | Crear una máquina de estado de prueba. | Siga las instrucciones de la [Guía para desarrolladores de AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html) para crear y poner en marcha una máquina de estados. Para la definición, utilice el siguiente código. Asegúrese de actualizar el valor `InstanceIds` con el ID de una instancia válida habilitada para Systems Manager en su cuenta.
{
  "Comment": "A description of my state machine",
  "StartAt": "StartAutomationWaitForCallBack",
  "States": {
    "StartAutomationWaitForCallBack": {
      "Type": "Task",
      "Resource": "arn:aws:states:::aws-sdk:ssm:startAutomationExecution.waitForTaskToken",
      "Parameters": {
        "DocumentName": "SfnRunCommandByInstanceIds",
        "Parameters": {
          "InstanceIds": [
            "i-1234567890abcdef0"
          ],
          "taskToken.$": "States.Array($$.Task.Token)",
          "workingDirectory": [
            "/home/ssm-user/"
          ],
          "Commands": [
            "echo \"This is a test running automation waitForTaskToken\" >> automation.log",
            "sleep 100"
          ],
          "executionTimeout": [
              "10800"
          ],
          "deliveryTimeout": [
              "30"
          ],
          "shell": [
              "Shell"
          ]
            }
      },
      "End": true
    }
  }
}
Este código llama al manual de procedimientos para ejecutar dos comandos que demuestran la llamada `waitForTaskToken` a Systems Manager Automation.El valor del parámetro `shell` (`Shell` o `PowerShell`) determina si el documento de Automatización se pone en marcha en `AWS-RunShellScript` o `AWS-RunPowerShellScript`.La tarea escribe en el `/home/ssm-user/automation.log` archivo «Se trata de un waitForTask token de automatización en ejecución de pruebas» y, a continuación, se suspende durante 100 segundos antes de responder con el token de la tarea y lanzar la siguiente tarea del flujo de trabajo.Si, en vez de eso, quiere llamar al manual de procedimientos `SfnRunCommandByTargets`, sustituya la sección `Parameters` del código anterior por la siguiente:
"Parameters": {
          "Targets": [
            {
              "Key": "InstanceIds",
              "Values": [
                "i-02573cafcfEXAMPLE",
                "i-0471e04240EXAMPLE"
              ]
            }
          ],
| AWS DevOps | | Actualice el rol de IAM de la máquina de estado. | El paso anterior crea automáticamente un rol de IAM dedicado para la máquina de estados. Sin embargo, no concede permisos para llamar al manual de procedimientos. Actualice el rol añadiendo los permisos siguientes:
{
      "Effect": "Allow",
      "Action": "ssm:StartAutomationExecution",
      "Resource": "*"
 }
| AWS DevOps | | Valide las llamadas sincrónicas. | Ejecute la máquina de estados para validar la llamada sincrónica entre Step Functions y Systems Manager Automation. Para ver un ejemplo de salida, consulte la sección [Información adicional](#run-aws-systems-manager-automation-tasks-synchronously-from-aws-step-functions-additional).  | AWS DevOps | ## Recursos relacionados + [Cómo empezar con AWS Step Functions](https://docs.aws.amazon.com/step-functions/latest/dg/getting-started-with-sfn.html) (*Guía para AWS Step Functions desarrolladores*) + [Espere a que le devuelvan la llamada con el token de la tarea](https://docs.aws.amazon.com/step-functions/latest/dg/connect-to-resource.html#connect-wait-token) (*guía para AWS Step Functions desarrolladores*, patrones de integración de servicios) + Llamadas a las API [send\_task\_success](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_success.html) y [send\_task\_failure](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_failure.html) (documentación de Boto3)  + [AWS Systems Manager Automatización](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-automation.html) (*guía AWS Systems Manager del usuario*) ## Información adicional **Detalles de la implementación** Este patrón proporciona una CloudFormation plantilla que despliega dos manuales de ejecución de Systems Manager: + `SfnRunCommandByInstanceIds`ejecuta el `AWS-RunPowerShellScript` comando `AWS-RunShellScript` o mediante la instancia. IDs + `SfnRunCommandByTargets` pone en marcha el comando `AWS-RunShellScript` o `AWS-RunPowerShellScript` usando destinos. Cada manual de procedimientos implementa cuatro pasos para lograr una llamada sincrónica cuando se usa la opción `.waitForTaskToken` de Step Functions. | | | Paso | Action | Description (Descripción) | | --- |--- |--- | | **1** | `Branch` | Comprueba el valor del parámetro `shell` (`Shell` o `PowerShell`) para decidir si poner en marcha `AWS-RunShellScript` en Linux o `AWS-RunPowerShellScript` en Windows. | | **2** | `RunCommand_Shell` o `RunCommand_PowerShell` | Recibe varias entradas y pone en marcha el comando `RunShellScript` o `RunPowerShellScript`. Para obtener más información, consulte la pestaña **Detalles** de `RunCommand_Shell` o `RunCommand_PowerShell` del documento de Automatización en la consola de Systems Manager. | | **3** | `SendTaskFailure` | Se ejecuta cuando se anula o cancela el paso 2. Llama a la API [send\_task\_failure](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_failure.html) de Step Functions, que acepta tres parámetros como entrada: el token pasado por la máquina de estados, el error de error y una descripción de la causa del error. | | **4** | `SendTaskSuccess` | Se ejecuta cuando el paso 2 se realiza correctamente. Llama a la API [send\_task\_success](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/stepfunctions/client/send_task_success.html) de Step Functions, que acepta el token pasado por la máquina de estados como entrada. | **Parámetros del manual de procedimientos** Manual de procedimientos `SfnRunCommandByInstanceIds`: | | | Nombre del parámetro | Tipo | Opcional u obligatorio | Description (Descripción) | | --- |--- |--- |--- | | `shell` | Cadena | Obligatorio | El intérprete de comandos de las instancias para decidir si poner en marcha `AWS-RunShellScript` para Linux o `AWS-RunPowerShellScript` para Windows. | | `deliveryTimeout` | Entero | Opcional | La cantidad, en segundos, de espera para que un comando se envíe a SSM Agent de una instancia. Este parámetro tiene un valor mínimo de 30 (0,5 minutos) y un valor máximo de 2 592 000 (720 horas). | | `executionTimeout` | Cadena | Opcional | El tiempo, en segundos, para que un comando se complete antes de considerar que se ha producido un error. El valor predeterminado es de 3600 (1 hora). El valor máximo es 172800 (48 horas). | | `workingDirectory` | Cadena | Opcional | La ruta al directorio de trabajo en la instancia. | | `Commands` | StringList | Obligatorio | El script o comando del intérprete de comandos que se va a ejecutar. | | `InstanceIds` | StringList | Obligatorio | La IDs de las instancias en las que desea ejecutar el comando. | | `taskToken` | Cadena | Obligatorio | El token de tarea que se utilizará para las respuestas de devolución de llamada. | Manual de procedimientos `SfnRunCommandByTargets`: | | | Name | Tipo | Opcional u obligatorio | Description (Descripción) | | --- |--- |--- |--- | | `shell` | Cadena | Obligatorio | El intérprete de comandos de las instancias para decidir si poner en marcha `AWS-RunShellScript` para Linux o `AWS-RunPowerShellScript` para Windows. | | `deliveryTimeout` | Entero | Opcional | La cantidad, en segundos, de espera para que un comando se envíe a SSM Agent de una instancia. Este parámetro tiene un valor mínimo de 30 (0,5 minutos) y un valor máximo de 2 592 000 (720 horas). | | `executionTimeout` | Entero | Opcional | El tiempo, en segundos, para que un comando se complete antes de considerar que se ha producido un error. El valor predeterminado es de 3600 (1 hora). El valor máximo es 172800 (48 horas). | | `workingDirectory` | Cadena | Opcional | La ruta al directorio de trabajo en la instancia. | | `Commands` | StringList | Obligatorio | El script o comando del intérprete de comandos que se va a ejecutar. | | `Targets` | MapList | Obligatorio | Una matriz de criterios de búsqueda que identifica las instancias utilizando los pares clave-valor que usted especifique. Por ejemplo: `[{"Key":"InstanceIds","Values":["i-02573cafcfEXAMPLE","i-0471e04240EXAMPLE"]}]` | | `taskToken` | Cadena | Obligatorio | El token de tarea que se utilizará para las respuestas de devolución de llamada. | **Resultados de ejemplo** La siguiente tabla proporciona un ejemplo de salida de la función step. Muestra que el tiempo total de ejecución es superior a 100 segundos entre el paso 5 (`TaskSubmitted`) y el paso 6 (`TaskSucceeded`). Esto demuestra que la función de Step Functions esperó a que finalizara el comando `sleep 100` antes de pasar a la siguiente tarea del flujo de trabajo. | | | ID | Tipo | Paso | Recurso | Tiempo transcurrido (ms) | Timestamp | | --- |--- |--- |--- |--- |--- | | **1** | `ExecutionStarted` | | - | 0 | 11 de marzo de 2022 02:50:34.303 p.m. | | **2** | `TaskStateEntered` | `StartAutomationWaitForCallBack` | - | 40 | 11 de marzo de 2022 02:50:34.343 p.m. | | **3** | `TaskScheduled` | `StartAutomationWaitForCallBack` | - | 40 | 11 de marzo de 2022 02:50:34.343 p.m. | | **4** | `TaskStarted` | `StartAutomationWaitForCallBack` | - | 154 | 11 de marzo de 2022 02:50:34.457 p.m. | | **5** | `TaskSubmitted` | `StartAutomationWaitForCallBack` | - | 657 | 11 de marzo de 2022 02:50:34.960 p.m. | | **6** | `TaskSucceeded` | `StartAutomationWaitForCallBack` | - | 103835 | 11 de marzo de 2022 02:52:18.138 p.m. | | **7** | `TaskStateExited` | `StartAutomationWaitForCallBack` | - | 103860 | 11 de marzo de 2022 02:52:18.163 p.m. | | **8** | `ExecutionSucceeded` | | - | 103897 | 11 de marzo de 2022 02:52:18.200 p.m. |