Ejecute las tareas de automatización de AWS Systems Manager 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
AWSservicios: AWS Step Functions; AWS Systems Manager

Resumen

Este patrón explica cómo integrarse AWS Step Functions con AWS Systems Manager. Utiliza integraciones de AWS SDK servicios para llamar al Systems Manager startAutomationExecutionAPIcon un token de tarea de un flujo de trabajo de una máquina de estado y hace una pausa hasta que el token regresa con una llamada correcta o fallida. 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 AWS SDK servicios en Step Functions, consulte 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 (AmazonEC2), Amazon Relational Database Service (Amazon), Amazon Redshift y RDS 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.

Requisitos previos y limitaciones

Requisitos previos 

• AWS Una cuenta activa

• AWS Identity and Access Management (IAM) permisos para acceder a Step Functions y Systems Manager

• Una EC2 instancia con el Agente de Systems Manager (SSMAgente) instalado en la instancia

• Un perfil de IAM instancia para Systems Manager adjunto a la instancia en la que planea ejecutar el runbook

• Un rol de Step Functions que tiene los siguientes IAM permisos (que siguen el principio de privilegios mínimos):

{
             "Effect": "Allow",
             "Action": "ssm:StartAutomationExecution",
             "Resource": "*"
 }

Versiones de producto

• SSMesquema de documento, versión 0.3 o posterior

• SSMAgente, 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

Automatizar y escalar

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

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) le 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 críticas 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

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 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 te permite ejecutar AWS-RunShellScript o usar una AWS-RunPowerShellScript instancia. IDs SfnRunCommandByTargets— Runbook que te permite correr AWS-RunShellScript o usar AWS-RunPowerShellScript objetivos. SSMSyncRole— El IAM papel que asumen los manuales de ejecución.	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 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
Actualiza el IAM rol de la máquina de estados.	El paso anterior crea automáticamente un IAM rol 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 send_task_success y send_task_failure (documentación de Boto3) API 

• AWS Systems Manager Automatización (AWS Systems Managerguía 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 la instancia. IDs

• 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 (ShelloPowerShell) 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. Denomina a Step Functions send_task_failureAPI, que acepta tres parámetros como entrada: el token pasado por la máquina de estados, el error de falla y una descripción de la causa de la falla.
4	SendTaskSuccess	Se ejecuta cuando el paso 2 se realiza correctamente. Llama a Step Functions send_task_successAPI, 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 SSM agente 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	La IDs 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 instrucciones:

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