Récapitulatif Conditions préalables et limitations Architecture Outils Épopées Ressources connexes Informations supplémentaires

Exécutez les tâches d'automatisation d'AWS Systems Manager de manière synchrone depuis AWS Step Functions

Créée par Elie El khoury (AWS)

Référentiel de code : amazon-stepfunctions-ssm-waitfortasktoken	Environnement : Production	Technologies : sans serveur DevOps ; informatique pour l'utilisateur final ; opérations
Services AWS : AWS Step Functions ; AWS Systems Manager

Récapitulatif

Ce modèle explique comment intégrer AWS Step Functions à AWS Systems Manager. Il utilise les intégrations de services du AWS SDK pour appeler l'startAutomationExecutionAPI Systems Manager à l'aide d'un jeton de tâche issu d'un flux de travail basé sur une machine à états, et fait une pause jusqu'à ce que le jeton revienne en cas de réussite ou d'échec d'un appel. Pour démontrer l'intégration, ce modèle implémente un wrapper de document d'automatisation (runbook) autour du AWS-RunPowerShellScript document AWS-RunShellScript or, et l'utilise .waitForTaskToken pour appeler ou de manière synchrone. AWS-RunShellScript AWS-RunPowerShellScript Pour plus d'informations sur les intégrations de services AWS SDK dans Step Functions, consultez le guide du AWS Step Functions développeur.

Step Functions est un service de flux de travail visuel à faible code que vous pouvez utiliser pour créer des applications distribuées, automatiser les processus informatiques et commerciaux, et créer des pipelines de données et d'apprentissage automatique à l'aide de AWS services. Les flux de travail gèrent les échecs, les nouvelles tentatives, la parallélisation, les intégrations de services et l'observabilité afin que vous puissiez vous concentrer sur une logique métier à plus forte valeur ajoutée.

L'automatisation, une fonctionnalité de AWS Systems Manager, simplifie les tâches courantes de maintenance, de déploiement et de correction pour Services AWS Amazon Elastic Compute Cloud (Amazon EC2), Amazon Relational Database Service (Amazon RDS), Amazon Redshift et Amazon Simple Storage Service (Amazon S3). L'automatisation vous permet de contrôler de manière précise la simultanéité de vos automatisations. Par exemple, vous pouvez spécifier le nombre de ressources à cibler simultanément et le nombre d'erreurs susceptibles de se produire avant l'arrêt d'une automatisation.

Pour les détails de mise en œuvre, y compris les étapes du runbook, les paramètres et les exemples, consultez la section Informations supplémentaires.

Conditions préalables et limitations

Prérequis

Un AWS compte actif
AWS Identity and Access Management Autorisations (IAM) pour accéder à Step Functions et Systems Manager
Une instance EC2 avec l'agent Systems Manager (agent SSM) installé sur l'instance
Un profil d'instance IAM pour Systems Manager attaché à l'instance sur laquelle vous prévoyez d'exécuter le runbook
Un rôle Step Functions doté des autorisations IAM suivantes (selon le principe du moindre privilège) :


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

Versions du produit

Schéma de document SSM version 0.3 ou ultérieure
Agent SSM version 2.3.672.0 ou ultérieure

Architecture

Pile technologique cible

AWS Step Functions
AWS Systems Manager Automatisation

Architecture cible

Architecture permettant d'exécuter les tâches d'automatisation de Systems Manager de manière synchrone à partir de Step Functions

Automatisation et mise à l'échelle

Ce modèle fournit un AWS CloudFormation modèle que vous pouvez utiliser pour déployer les runbooks sur plusieurs instances. (Voir le référentiel d'implémentation de GitHub Step Functions et Systems Manager.)

Outils

Services AWS

AWS CloudFormationvous aide à configurer les AWS ressources, à les approvisionner rapidement et de manière cohérente, et à les gérer tout au long de leur cycle de vie dans toutes Comptes AWS les régions.
AWS Identity and Access Management (IAM) vous aide à gérer en toute sécurité l'accès à vos AWS ressources en contrôlant qui est authentifié et autorisé à les utiliser.
AWS Step Functionsest un service d'orchestration sans serveur qui vous aide à combiner des AWS Lambda fonctions et autres Services AWS pour créer des applications critiques pour l'entreprise.
AWS Systems Managervous aide à gérer vos applications et votre infrastructure exécutées dans le AWS Cloud. Il simplifie la gestion des applications et des ressources, réduit le délai de détection et de résolution des problèmes opérationnels et vous aide à gérer vos AWS ressources en toute sécurité à grande échelle.

Code

Le code de ce modèle est disponible dans le référentiel d'implémentation de GitHub Step Functions and Systems Manager.

Épopées

Tâche Description Compétences requises

Tâche	Description	Compétences requises
Téléchargez le CloudFormation modèle.	Téléchargez le `ssm-automation-documents.cfn.json` modèle depuis le `cloudformation` dossier du GitHub référentiel.	AWS DevOps
Créez des runbooks.	Connectez-vous au AWS Management Console, ouvrez la AWS CloudFormation console et déployez le modèle. Pour plus d'informations sur le déploiement CloudFormation de modèles, consultez la section Création d'une pile sur la AWS CloudFormation console dans la CloudFormation documentation. Le CloudFormation modèle déploie trois ressources : `SfnRunCommandByInstanceIds`— Runbook qui vous permet d'exécuter `AWS-RunShellScript` ou `AWS-RunPowerShellScript` en utilisant des identifiants d'instance. `SfnRunCommandByTargets`— Runbook qui vous permet de courir `AWS-RunShellScript` ou d'utiliser `AWS-RunPowerShellScript` des cibles. `SSMSyncRole`— Le rôle IAM assumé par les runbooks.	AWS DevOps

Téléchargez le CloudFormation modèle.

Téléchargez le ssm-automation-documents.cfn.json modèle depuis le cloudformation dossier du GitHub référentiel.

AWS DevOps

Créez des runbooks.

Connectez-vous au AWS Management Console, ouvrez la AWS CloudFormation console et déployez le modèle. Pour plus d'informations sur le déploiement CloudFormation de modèles, consultez la section Création d'une pile sur la AWS CloudFormation console dans la CloudFormation documentation.

Le CloudFormation modèle déploie trois ressources :

SfnRunCommandByInstanceIds— Runbook qui vous permet d'exécuter AWS-RunShellScript ou AWS-RunPowerShellScript en utilisant des identifiants d'instance.
SfnRunCommandByTargets— Runbook qui vous permet de courir AWS-RunShellScript ou d'utiliser AWS-RunPowerShellScript des cibles.
SSMSyncRole— Le rôle IAM assumé par les runbooks.

AWS DevOps

Tâche Description Compétences requises

Tâche	Description	Compétences requises
Créez une machine à états de test.	Suivez les instructions du guide du AWS Step Functions développeur pour créer et exécuter une machine à états. Pour la définition, utilisez le code suivant. Assurez-vous de mettre à jour la `InstanceIds` valeur avec l'ID d'une instance valide compatible avec Systems Manager dans votre compte. { "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 } } } Ce code appelle le runbook pour exécuter deux commandes illustrant l'`waitForTaskToken`appel à Systems Manager Automation. La valeur du `shell` paramètre (`Shell`ou`PowerShell`) détermine si le document d'automatisation s'exécute `AWS-RunShellScript` ou`AWS-RunPowerShellScript`. La tâche écrit « Ceci est un waitForTask jeton d'automatisation de test » dans le `/home/ssm-user/automation.log` fichier, puis s'arrête pendant 100 secondes avant de répondre avec le jeton de tâche et de libérer la tâche suivante dans le flux de travail. Si vous souhaitez plutôt appeler le `SfnRunCommandByTargets` runbook, remplacez la `Parameters` section du code précédent par la suivante : `"Parameters": { "Targets": [ { "Key": "InstanceIds", "Values": [ "i-02573cafcfEXAMPLE", "i-0471e04240EXAMPLE" ] } ],`	AWS DevOps
Mettez à jour le rôle IAM pour la machine d'état.	L'étape précédente crée automatiquement un rôle IAM dédié pour la machine à états. Cependant, il n'accorde pas l'autorisation d'appeler le runbook. Mettez à jour le rôle en ajoutant les autorisations suivantes : `{ "Effect": "Allow", "Action": "ssm:StartAutomationExecution", "Resource": "*" }`	AWS DevOps
Validez les appels synchrones.	Exécutez la machine d'état pour valider l'appel synchrone entre Step Functions et Systems Manager Automation. Pour un exemple de sortie, consultez la section Informations supplémentaires.	AWS DevOps

Créez une machine à états de test.

Suivez les instructions du guide du AWS Step Functions développeur pour créer et exécuter une machine à états. Pour la définition, utilisez le code suivant. Assurez-vous de mettre à jour la InstanceIds valeur avec l'ID d'une instance valide compatible avec Systems Manager dans votre compte.


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

Ce code appelle le runbook pour exécuter deux commandes illustrant l'waitForTaskTokenappel à Systems Manager Automation.

La valeur du shell paramètre (ShellouPowerShell) détermine si le document d'automatisation s'exécute AWS-RunShellScript ouAWS-RunPowerShellScript.

La tâche écrit « Ceci est un waitForTask jeton d'automatisation de test » dans le /home/ssm-user/automation.log fichier, puis s'arrête pendant 100 secondes avant de répondre avec le jeton de tâche et de libérer la tâche suivante dans le flux de travail.

Si vous souhaitez plutôt appeler le SfnRunCommandByTargets runbook, remplacez la Parameters section du code précédent par la suivante :


"Parameters": {
          "Targets": [
            {
              "Key": "InstanceIds",
              "Values": [
                "i-02573cafcfEXAMPLE",
                "i-0471e04240EXAMPLE"
              ]
            }
          ],

AWS DevOps

Mettez à jour le rôle IAM pour la machine d'état.

L'étape précédente crée automatiquement un rôle IAM dédié pour la machine à états. Cependant, il n'accorde pas l'autorisation d'appeler le runbook. Mettez à jour le rôle en ajoutant les autorisations suivantes :


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

AWS DevOps

Validez les appels synchrones.

Exécutez la machine d'état pour valider l'appel synchrone entre Step Functions et Systems Manager Automation.

Pour un exemple de sortie, consultez la section Informations supplémentaires.

AWS DevOps

Ressources connexes

Mise en route avec AWS Step Functions (Guide AWS Step Functions du développeur)
Attendez un rappel avec le jeton de tâche (guide du AWS Step Functions développeur, modèles d'intégration des services)
Appels d'API send_task_success et send_task_failure (documentation Boto3)
AWS Systems Manager Automatisation (guide de AWS Systems Manager l'utilisateur)

Informations supplémentaires

Détails de l'implémentation

Ce modèle fournit un CloudFormation modèle qui déploie deux runbooks de Systems Manager :

SfnRunCommandByInstanceIdsexécute la AWS-RunPowerShellScript commande AWS-RunShellScript or en utilisant les ID d'instance.
SfnRunCommandByTargetsexécute la AWS-RunPowerShellScript commande AWS-RunShellScript or en utilisant des cibles.

Chaque runbook met en œuvre quatre étapes pour obtenir un appel synchrone lors de l'utilisation de l'.waitForTaskTokenoption dans Step Functions.

Step (Étape)	Action	Description
1	`Branch`	Vérifie la valeur du `shell` paramètre (`Shell`ou`PowerShell`) pour décider s'il convient de l'exécuter `AWS-RunShellScript` pour Linux ou `AWS-RunPowerShellScript` pour Windows.
2	`RunCommand_Shell` ou `RunCommand_PowerShell`	Prend plusieurs entrées et exécute la `RunPowerShellScript` commande `RunShellScript` or. Pour plus d'informations, consultez l'onglet Détails du document `RunCommand_Shell` ou `RunCommand_PowerShell` Automation sur la console Systems Manager.
3	`SendTaskFailure`	S'exécute lorsque l'étape 2 est abandonnée ou annulée. Il appelle l'API send_task_failure de Step Functions, qui accepte trois paramètres en entrée : le jeton transmis par la machine d'état, l'erreur d'échec et une description de la cause de l'échec.
4	`SendTaskSuccess`	S'exécute lorsque l'étape 2 est réussie. Il appelle l'API send_task_success de Step Functions, qui accepte le jeton transmis par la machine d'état en entrée.

Paramètres du Runbook

SfnRunCommandByInstanceIdscarnet de course :

Nom du paramètre	Type	Facultatif ou obligatoire	Description
`shell`	Chaîne	Obligatoire	L'interpréteur de commandes des instances permet de décider s'ils `AWS-RunShellScript` doivent être exécutés sous Linux ou `AWS-RunPowerShellScript` sous Windows.
`deliveryTimeout`	Entier	Facultatif	Temps d'attente, en secondes, avant qu'une commande soit délivrée à l'agent SSM sur une instance. Ce paramètre a une valeur minimale de 30 (0,5 minute) et une valeur maximale de 2592000 (720 heures).
`executionTimeout`	Chaîne	Facultatif	Durée, en secondes, nécessaire à l'exécution d'une commande avant qu'elle ne soit considérée comme ayant échoué. La valeur par défaut est 3 600 (1 heure). La valeur maximale est 172800 (48 heures).
`workingDirectory`	Chaîne	Facultatif	Chemin d'accès au répertoire de travail sur votre instance.
`Commands`	StringList	Obligatoire	Le script ou la commande shell à exécuter.
`InstanceIds`	StringList	Obligatoire	Les ID des instances sur lesquelles vous souhaitez exécuter la commande.
`taskToken`	Chaîne	Obligatoire	Le jeton de tâche à utiliser pour les réponses de rappel.

SfnRunCommandByTargetscarnet de course :

Nom	Type	Facultatif ou obligatoire	Description
`shell`	Chaîne	Obligatoire	L'interpréteur de commandes des instances permet de décider s'ils `AWS-RunShellScript` doivent être exécutés sous Linux ou `AWS-RunPowerShellScript` sous Windows.
`deliveryTimeout`	Entier	Facultatif	Temps d'attente, en secondes, avant qu'une commande soit délivrée à l'agent SSM sur une instance. Ce paramètre a une valeur minimale de 30 (0,5 minute) et une valeur maximale de 2592000 (720 heures).
`executionTimeout`	Entier	Facultatif	Durée, en secondes, nécessaire à l'exécution d'une commande avant qu'elle ne soit considérée comme ayant échoué. La valeur par défaut est 3 600 (1 heure). La valeur maximale est 172800 (48 heures).
`workingDirectory`	Chaîne	Facultatif	Chemin d'accès au répertoire de travail sur votre instance.
`Commands`	StringList	Obligatoire	Le script ou la commande shell à exécuter.
`Targets`	MapList	Obligatoire	Tableau de critères de recherche qui identifie les instances à l'aide de paires clé-valeur que vous spécifiez. Par exemple : `[{"Key":"InstanceIds","Values":["i-02573cafcfEXAMPLE","i-0471e04240EXAMPLE"]}]`
`taskToken`	Chaîne	Obligatoire	Le jeton de tâche à utiliser pour les réponses de rappel.

Exemple de sortie

Le tableau suivant fournit un exemple de sortie de la fonction step. Cela montre que le temps d'exécution total est supérieur à 100 secondes entre l'étape 5 (TaskSubmitted) et l'étape 6 (TaskSucceeded). Cela montre que la fonction step a attendu la fin de la sleep 100 commande avant de passer à la tâche suivante du flux de travail.

ID	Type	Step (Étape)	Ressource	Temps écoulé (ms)	Horodatage
1	`ExecutionStarted`		-	0	11 mars 2022 14h50:34 ,303
2	`TaskStateEntered`	`StartAutomationWaitForCallBack`	-	40	11 mars 2022 14 h 50 : 34 .343
3	`TaskScheduled`	`StartAutomationWaitForCallBack`	-	40	11 mars 2022 14 h 50 : 34 .343
4	`TaskStarted`	`StartAutomationWaitForCallBack`	-	154	11 mars 2022 14 h 50 : 34 .457
5	`TaskSubmitted`	`StartAutomationWaitForCallBack`	-	657	11 mars 2022 14 h 50 : 34 960
6	`TaskSucceeded`	`StartAutomationWaitForCallBack`	-	103835	11 mars 2022 14h52:18 138
7	`TaskStateExited`	`StartAutomationWaitForCallBack`	-	103860	11 mars 2022 14h52:18 163
8	`ExecutionSucceeded`		-	103897	11 mars 2022 14h52:18 200

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Traitez les API de manière asynchrone avec Amazon SQS

Exécutez des lectures parallèles d'objets S3 avec AWS Lambda