AWS Step Functions から AWS Systems Manager Automation タスクを同期的に実行する AWS Step Functions - AWS 規範ガイダンス
[概要]前提条件と制限アーキテクチャツールエピック関連リソース追加情報

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

AWS Step Functions から AWS Systems Manager Automation タスクを同期的に実行する AWS Step Functions

作成者: Elie El khoury (AWS)

コードリポジトリ: amazon-stepfunctions-ssm-waitfortasktoken

環境:本稼働

テクノロジー: サーバーレス DevOps、エンドユーザーコンピューティング、オペレーション

AWS サービス: AWS Step FunctionsAWS Systems Manager

[概要]

このパターンでは、 AWS Step Functions と統合する方法を説明します AWS Systems Manager。 AWS SDK サービス統合を使用して、ステートマシンワークフローからタスクトークンを使用して Systems Manager startAutomationExecution API を呼び出し、トークンが成功または失敗の呼び出しで返されるまで一時停止します。統合を実証するために、このパターンでは AWS-RunShellScriptまたは ドキュメントの周囲にオートメーションAWS-RunPowerShellScriptドキュメント (ランブック) ラッパーを実装し、 を使用して AWS-RunShellScriptまたは .waitForTaskTokenを同期的に呼び出しますAWS-RunPowerShellScript。Step Functions での AWS SDK サービス統合の詳細については、「 AWS Step Functions デベロッパーガイド」を参照してください。

Step Functions は、分散アプリケーションの構築、IT およびビジネスプロセスの自動化、サービスを使用したデータおよび機械学習パイプラインの構築に使用できる、ローコードの視覚的なワークフロー AWS サービスです。ワークフローは失敗、再試行、並列化、サービス統合、オブザーバビリティを管理するので、より価値の高いビジネスロジックに集中できます。

の一機能であるオートメーションは、Amazon Elastic Compute Cloud (Amazon EC2)、Amazon Relational Database Service (Amazon RDS)、Amazon Redshift、Amazon Simple Storage Service (Amazon S3) AWS のサービス などの の一般的なメンテナンス、デプロイ、修復タスク AWS Systems Managerを簡素化します。オートメーションを使用すると、自動化の同時実行性をきめ細かく制御できます。例えば、同時実行のターゲットにするリソースの数や、オートメーションを停止する前に許容可能なエラーの発生数を指定することが可能です。

ランブックのステップ、パラメータ、例など、実装の詳細については、「追加情報」セクションを参照してください。

前提条件と制限

前提条件

  • アクティブな AWS アカウント

  • AWS Identity and Access Management Step Functions と Systems Manager にアクセスするための (IAM) アクセス許可

  • インスタンスに Systems Manager Agent (SSM Agent) がインストールされている EC2 インスタンス

  • ランブックを実行する予定のインスタンスにアタッチされた Systems Manager の IAM インスタンスプロファイル

  • 以下の IAM アクセス許可を持つ Step Functions ロール (最小特権の原則に従います）。

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

製品バージョン

  • SSM ドキュメントスキーマバージョン 0.3 以降

  • SSM エージェントバージョン 2.3.672.0 以降。

アーキテクチャ

ターゲットテクノロジースタック

  • AWS Step Functions

  • AWS Systems Manager Automation

ターゲットアーキテクチャ

Systems Manager 自動化タスクを Step Functions から同期的に実行するためのアーキテクチャ

自動化とスケール

  • このパターンは、ランブックを複数のインスタンスにデプロイするために使用できる AWS CloudFormation テンプレートを提供します。（ GitHub Step Functions と Systems Manager の実装リポジトリを参照してください）。

ツール

AWS のサービス

  • AWS CloudFormation は、 AWS リソースをセットアップし、迅速かつ一貫してプロビジョニングし、 AWS アカウント およびリージョン全体でライフサイクル全体を通じてリソースを管理するのに役立ちます。

  • AWS Identity and Access Management (IAM) は、誰を認証し、誰に使用を認可するかを制御することで、 AWS リソースへのアクセスを安全に管理できます。

  • AWS Step Functions は、 AWS Lambda 関数と他の を組み合わせてビジネスクリティカルなアプリケーション AWS のサービス を構築するのに役立つサーバーレスオーケストレーションサービスです。

  • 「AWS Systems Manager」は、 AWS クラウドで実行されるアプリケーションとインフラストラクチャの管理に役立ちます。アプリケーションとリソースの管理を簡素化し、運用上の問題を検出して解決する時間を短縮し、 AWS リソースを大規模に安全に管理できるようにします。

コード

このパターンのコードは、 GitHub Step Functions と Systems Manager の実装リポジトリにあります。 

エピック

タスク説明必要なスキル

CloudFormation テンプレートをダウンロードします。

GitHub リポジトリの cloudformation フォルダからssm-automation-documents.cfn.jsonテンプレートをダウンロードします。

AWS DevOps

ランブックを作成します。

にサインインし AWS Management Console、AWS CloudFormation コンソール を開き、テンプレートをデプロイします。 CloudFormation テンプレートのデプロイの詳細については、 CloudFormation ドキュメントの「 AWS CloudFormation コンソールでのスタックの作成」を参照してください。 

CloudFormation テンプレートは 3 つのリソースをデプロイします。

  • SfnRunCommandByInstanceIds – インスタンス ID AWS-RunPowerShellScriptを使用して または を実行AWS-RunShellScriptできるようにするランブック。 IDs

  • SfnRunCommandByTargets - ターゲットAWS-RunPowerShellScriptを使用して AWS-RunShellScriptまたは を実行できるランブック。

  • SSMSyncRole – ランブックが引き受ける IAM ロール。

AWS DevOps
タスク説明必要なスキル

テストステートマシンを作成します。

「 AWS Step Functions デベロッパーガイド」の手順に従って、ステートマシンを作成して実行します。定義には、次のコードを使用します。必ず、アカウント内の有効な Systems Manager 対応インスタンスの ID で InstanceIds 値を更新してください。

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

このコードはランブックを呼び出して、Systems Manager Automation への waitForTaskToken 呼び出しを示す 2 つのコマンドを実行します。

shell パラメータ値 (Shell または PowerShell) は、オートメーションドキュメントが AWS-RunShellScriptまたは を実行するかどうかを決定しますAWS-RunPowerShellScript。

タスクは「これはテスト実行中のオートメーショントークン」を/home/ssm-user/automation.logファイルに書き込み、タスクトークンで応答し、ワークフロー内の次のタスクを解放する前に 100 waitForTask秒間スリープします。

代わりに SfnRunCommandByTargets ランブックを呼び出したい場合は、前のコードの Parameters セクションを以下のコードに置き換えてください。

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

ステートマシンの IAM ロールを更新します。

前のステップでは、ステートマシンの専用の IAM ロールが自動的に作成されます。ただし、ランブックを呼び出すアクセス許可は付与されません。以下のアクセス許可を追加して、ロールを更新します。

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

同期呼び出しを検証します。

ステートマシンを実行して、Step Functions と Systems Manager オートメーション間の同期呼び出しを検証します。 

出力例については、「追加情報」セクションを参照してください。 

AWS DevOps

関連リソース

追加情報

実装の詳細

このパターンは、2 つの Systems Manager ランブックをデプロイする CloudFormation テンプレートを提供します。

  • SfnRunCommandByInstanceIdsは、インスタンス IDsを使用して AWS-RunShellScriptまたは AWS-RunPowerShellScript コマンドを実行します。

  • SfnRunCommandByTargetsは、ターゲットを使用して AWS-RunShellScriptまたは AWS-RunPowerShellScript コマンドを実行します。

各ランブックは、Step Functions で .waitForTaskTokenオプションを使用するときに同期呼び出しを実現する 4 つのステップを実装します。

[ステップ]

[アクション]

説明

1

Branch

shell パラメータ値 (Shell または PowerShell) をチェックして、Linux または Windows AWS-RunShellScriptのどちらで AWS-RunPowerShellScript を実行するかを決定します。

2

RunCommand_Shell または RunCommand_PowerShell

複数の入力を受け取り、 RunShellScriptまたは RunPowerShellScript コマンドを実行します。詳細については、Systems Manager コンソールの RunCommand_Shellまたは RunCommand_PowerShell Automation ドキュメントの詳細タブを確認してください。

3

SendTaskFailure

ステップ 2 が中止またはキャンセルされたときに実行されます。Step Functions send_task_failure API を呼び出し、ステートマシンから渡されたトークン、障害エラー、障害の原因の説明の 3 つのパラメータを入力として受け入れます。

4

SendTaskSuccess

ステップ 2 が成功したときに実行されます。ステートマシンから渡されたトークンを入力として受け入れる Step Functions send_task_success API を呼び出します。

ランブックパラメータ

SfnRunCommandByInstanceIds ランブック：

パラメータ名

タイプ

オプションまたは必須

説明

shell

文字列

必須

インスタンスは、Linux または Windows AWS-RunShellScriptのどちらで を実行するかを決定するAWS-RunPowerShellScriptシェルです。

deliveryTimeout

整数

オプションです。

コマンドがインスタンスの SSM エージェントに配信されるまで待機する秒単位の時間。このパラメータの最小値は 30 (0.5 分）、最大値は 2592000 (720 時間) です。

executionTimeout

文字列

オプションです。

コマンドが失敗したと見なされるまでに完了するまでの時間 (秒単位)。デフォルト値は 3600 (1 時間) です。最大値は 172800 (48 時間) です。

workingDirectory

文字列

オプションです。

インスタンスの作業ディレクトリへのパス。

Commands

StringList

必須

実行するシェルスクリプトまたはコマンド。

InstanceIds

StringList

必須

コマンドを実行するインスタンス ID です。

taskToken

文字列

必須

コールバックレスポンスに使用するタスクトークン。

SfnRunCommandByTargetsランブック：

名前

タイプ

オプションまたは必須

説明

shell

文字列

必須

インスタンスは、Linux または Windows AWS-RunShellScriptのどちらで を実行するかを決定するAWS-RunPowerShellScriptシェルです。

deliveryTimeout

整数

オプションです。

コマンドがインスタンスの SSM エージェントに配信されるまで待機する秒単位の時間。このパラメータの最小値は 30 (0.5 分）、最大値は 2592000 (720 時間) です。

executionTimeout

整数

オプションです。

コマンドが失敗したと見なされるまでに完了するまでの時間 (秒単位)。デフォルト値は 3600 (1 時間) です。最大値は 172800 (48 時間) です。

workingDirectory

文字列

オプションです。

インスタンスの作業ディレクトリへのパス。

Commands

StringList

必須

実行するシェルスクリプトまたはコマンド。

Targets

MapList

必須

指定したキーと値のペアを使用してインスタンスを識別する検索条件の配列。例：[{"Key":"InstanceIds","Values":["i-02573cafcfEXAMPLE","i-0471e04240EXAMPLE"]}]

taskToken

文字列

必須

コールバックレスポンスに使用するタスクトークン。

出力例

次の表に、ステップ関数からの出力例を示します。ステップ 5 (TaskSubmitted) からステップ 6 (TaskSucceeded) までの合計実行時間が 100 秒を超えていることがわかります。これは、ステップ関数がsleep 100コマンドが終了するのを待ってから、ワークフロー内の次のタスクに移行したことを示しています。

ID

タイプ

[ステップ]

[リソース]

経過時間 (ミリ秒)

タイムスタンプ

1

ExecutionStarted

-

0

2022 年 3 月 11 日午後 2 時 50 分 34.303 秒

2

TaskStateEntered

StartAutomationWaitForCallBack

-

40

2022 年 3 月 11 日午後 2 時 50 分 34.343 秒

3

TaskScheduled

StartAutomationWaitForCallBack

-

40

2022 年 3 月 11 日午後 2 時 50 分 34.343 秒

4

TaskStarted

StartAutomationWaitForCallBack

-

154

2022 年 3 月 11 日午後 2 時 50 分 34.457 秒

5

TaskSubmitted

StartAutomationWaitForCallBack

-

657

2022 年 3 月 11 日午後 2 時 50 分 34.960 秒

6

TaskSucceeded

StartAutomationWaitForCallBack

-

103835

2022 年 3 月 11 日午後 2 時 52 分 18.138 秒

7

TaskStateExited

StartAutomationWaitForCallBack

-

103860

2022 年 3 月 11 日午後 2 時 52 分 18.163 秒

8

ExecutionSucceeded

-

103897

2022 年 3 月 11 日午後 2 時 52 分 18.200 秒