Resumen Requisitos previos y limitaciones Arquitectura Herramientas Epics Recursos relacionados Información adicional

Ejecute las tareas de AWS Systems Manager Automation de forma sincrónica desde AWS Step Functions

Creado por Elie El khoury (AWS)

Repositorio de código: amazon-stepfunctions-ssm-waitfortasktoken	Entorno: producción	Tecnologías: sin servidor DevOps; informática para el usuario final; operaciones
Servicios de AWS: AWS Step Functions; AWS Systems Manager

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 startAutomationExecutionAPI 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 contenedor de documentos de automatización (runbook) alrededor del documento o y se utiliza .waitForTaskToken para llamar a AWS-RunShellScript o AWS-RunPowerShellScript de forma sincrónica. AWS-RunShellScript 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.

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

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 instancia EC2 con el agente Systems Manager (SSM Agent) instalado en la instancia
Un perfil de instancia de IAM para Systems Manager adjunto a la instancia en la que planea ejecutar el manual de procedimientos
Un rol de Step Functions que tiene los siguientes permisos de IAM (que siguen el principio de privilegios mínimos):


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

Automatizar y escalar

Este patrón proporciona una AWS CloudFormation plantilla que puede utilizar para implementar los manuales de ejecución en varias instancias. (Consulte el repositorio de implementación de GitHub Step Functions y Systems Manager).

Herramientas

Servicios de AWS

AWS CloudFormationle 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) 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 Functionses 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 le 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.

Epics

Tarea Descripción Habilidades requeridas

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 AWS Management Console, abra la AWS CloudFormation consola e implemente la plantilla. Para obtener más información sobre la implementación de CloudFormation plantillas, consulte Crear una pila en la AWS CloudFormation consola en la CloudFormation documentación. La CloudFormation plantilla implementa tres recursos: `SfnRunCommandByInstanceIds`— Runbook que permite ejecutar `AWS-RunShellScript` o usar identificadores `AWS-RunPowerShellScript` de instancia. `SfnRunCommandByTargets`— Manual de ejecución que te permite correr `AWS-RunShellScript` o usar `AWS-RunPowerShellScript` objetivos. `SSMSyncRole`— La función de IAM que asumen los manuales.	AWS DevOps

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 AWS Management Console, abra la AWS CloudFormation consola e implemente la plantilla. Para obtener más información sobre la implementación de CloudFormation plantillas, consulte Crear una pila en la AWS CloudFormation consola en la CloudFormation documentación.

La CloudFormation plantilla implementa tres recursos:

SfnRunCommandByInstanceIds— Runbook que permite ejecutar AWS-RunShellScript o usar identificadores AWS-RunPowerShellScript de instancia.
SfnRunCommandByTargets— Manual de ejecución que te permite correr AWS-RunShellScript o usar AWS-RunPowerShellScript objetivos.
SSMSyncRole— La función de IAM que asumen los manuales.

AWS DevOps

Tarea Descripción Habilidades requeridas

Tarea	Descripción	Habilidades requeridas
Crear una máquina de estado de prueba.	Siga las instrucciones de la guía para AWS Step Functions desarrolladores para crear y ejecutar 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 `shell` parámetro (`Shell`o`PowerShell`) determina si el documento de automatización se ejecuta `AWS-RunShellScript` o`AWS-RunPowerShellScript`. La tarea escribe «Se trata de un waitForTask token de automatización en ejecución de pruebas» en el `/home/ssm-user/automation.log` archivo y, a continuación, permanece en reposo 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.	AWS DevOps

Crear una máquina de estado de prueba.

Siga las instrucciones de la guía para AWS Step Functions desarrolladores para crear y ejecutar 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 shell parámetro (ShelloPowerShell) determina si el documento de automatización se ejecuta AWS-RunShellScript oAWS-RunPowerShellScript.

La tarea escribe «Se trata de un waitForTask token de automatización en ejecución de pruebas» en el /home/ssm-user/automation.log archivo y, a continuación, permanece en reposo 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.

AWS DevOps

Recursos relacionados

Cómo empezar con AWS Step Functions (Guía para AWS Step Functions desarrolladores)
Espere a que le devuelvan la llamada con el token de la tarea (guía para AWS Step Functions desarrolladores, patrones de integración de servicios)
Llamadas a las API send_task_success y send_task_failure (documentación de Boto3)
AWS Systems Manager Automatización (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:

SfnRunCommandByInstanceIdsejecuta el AWS-RunPowerShellScript comando AWS-RunShellScript o mediante los identificadores de instancia.
SfnRunCommandByTargetsejecuta el AWS-RunPowerShellScript comando AWS-RunShellScript o mediante objetivos.

Cada runbook implementa cuatro pasos para lograr una llamada sincrónica cuando se usa la .waitForTaskToken opción de Step Functions.

Paso	Action	Descripción
1	`Branch`	Comprueba el valor (`Shell`o`PowerShell`) del `shell` parámetro para decidir si se va a ejecutar `AWS-RunShellScript` en Linux o `AWS-RunPowerShellScript` en Windows.
2	`RunCommand_Shell` o `RunCommand_PowerShell`	Toma varias entradas y ejecuta el `RunPowerShellScript` comando `RunShellScript` o. Para obtener más información, consulte la pestaña Detalles del documento `RunCommand_Shell` o `RunCommand_PowerShell` 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 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 de Step Functions, que acepta el token pasado por la máquina de estados como entrada.

Parámetros del manual de procedimientos

SfnRunCommandByInstanceIdsmanual de instrucciones:

Nombre del parámetro	Tipo	Opcional u obligatorio	Descripción
`shell`	Cadena	Obligatoria	El shell de instancias para decidir si se va a ejecutar `AWS-RunShellScript` para Linux o `AWS-RunPowerShellScript` para Windows.
`deliveryTimeout`	Entero	Opcional	El tiempo, en segundos, que se tarda en esperar a que se entregue un comando al agente SSM de una instancia. Este parámetro tiene un valor mínimo de 30 (0,5 minutos) y un valor máximo de 2592000 (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 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	Obligatoria	El script o comando del intérprete de comandos que se va a ejecutar.
`InstanceIds`	StringList	Obligatoria	Los ID de las instancias en las que desea ejecutar el comando.
`taskToken`	Cadena	Obligatoria	El token de tarea que se utilizará para las respuestas de devolución de llamada.

SfnRunCommandByTargetsmanual de ejecución:

Nombre	Tipo	Opcional u obligatorio	Descripción
`shell`	Cadena	Obligatoria	El shell de instancias para decidir si se va a ejecutar `AWS-RunShellScript` para Linux o `AWS-RunPowerShellScript` para Windows.
`deliveryTimeout`	Entero	Opcional	El tiempo, en segundos, que se tarda en esperar a que se entregue un comando al agente SSM de una instancia. Este parámetro tiene un valor mínimo de 30 (0,5 minutos) y un valor máximo de 2592000 (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 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	Obligatoria	El script o comando del intérprete de comandos que se va a ejecutar.
`Targets`	MapList	Obligatoria	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	Obligatoria	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 step esperó a que finalizara el sleep 100 comando antes de pasar a la siguiente tarea del flujo de trabajo.

ID	Tipo	Paso	Resource	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.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Procese las API de forma asíncrona con Amazon SQS

Ejecute lecturas paralelas de objetos de S3 con AWS Lambda