Thorough explanation of the aws:executeScript action for SSM Automation

Created date: 2025/01/04, Update date: 2025/01/04

SSM automation can execute Python or PowerShell script by using aws:executeScript action.
When automating system operation with a script, it is common to perform regular processing with lambda or develop a script and execute locally.
By using SSM automation, the authority of the system operator can be minimized.
You can prepare a dedicated input field required to execute the process on the management console, or provide an approval phase.
A function specialized in system operation is available.
In this article, we will explain the aws:executeScript action of SSM automation.

Table of Contents

What is Automation?
Overview of aws:executeScript Action
Explanation
開発時のポイント

What is Automation?

Automation is a feature of AWS Systems Manager that allows you to automate operational tasks.
You can automate various operations using runbooks, which define the tasks executed by automation.
AWS provides many runbooks, and you can execute tasks by providing the required parameters.
- Reference: Systems Manager Automation runbook reference - AWS Systems Manager Automation runbook reference
You can also define your own runbooks, implement custom processing by combining actions, or call multiple AWS-provided runbooks to create an operational workflow.
- Reference: Systems Manager Automation actions reference - AWS Systems Manager

Overview of aws:executeScript Action

This action allows you to run a Python or PowerShell script that you provide.

Explanation

CloudFormation Example

The following is a sample defined only in CloudFormation with an aws:executeScript step. Properties with values like ${variable name} are explained later.

AWSTemplateFormatVersion: 2010-09-09
Description: template.automation.yml
Resources:
  Document:
    Type: AWS::SSM::Document
    Properties:
      Name: "${Document name}"
      DocumentType: Automation
      Attachments:
        - Key: "S3FileUrl"
          Name: "${ZIP file name}"
          Values:
            - !Sub "s3://${S3 bucket name}/${ZIP file name}"
      Content:
        schemaVersion: "0.3"
        assumeRole: "${Delegation role ARN}"
        mainSteps:
          - action: aws:executeScript
            name: RunSetupScript
            inputs:
              Runtime: "${Runtime name}"
              Handler: "${Python file name}.${Function name}"
              InputPayload:
                "${Payload}"
        files:
          ${ZIP file name}:
            checksums:
              sha256: "${The hash value of the zip file}"

Property: Name
Value type: string
Description:
- Specifies the name of the runbook.
- If you specify a Name and a replacement occurs when updating the runbook, you cannot create another runbook with the same name, which will result in an error.
- Use an automatically generated runbook name or specify a unique name each time you deploy.
Property: Attachments
Type: List of AttachmentSource
Description: Specify the files required to execute the runbook.
Property: Content -> assumeRole
Value type: string
Description: Specify the role required to execute the runbook.
Property: Content -> mainSteps -> inputs -> Runtime
Value type: string
Description:
- Specify the runtime for the script to run.
- Currently, only python3.x or PowerShell Core X.X can be specified.
- For available runtimes, see:
  - Systems Manager Automation actions reference - AWS Systems Manager
Property: Content -> mainSteps -> inputs -> Handler
Value type: string
Description:
- Specify the function name of the script to execute.
- For example, if you want to run the main function in runbook.py , specify main .
- For PowerShell, this property is not required.
Property: Content -> mainSteps -> inputs -> InputPayload
Value type: string
Description:
- Specify the parameters to pass to the script in JSON format.
- The parameters can be accessed in the script as sys.argv .
- 例えば、 InputPayload に以下のように指定した場合、スクリプト内で sys.argv を取得すると、 ['runbook.py', '{"key1": "value1", "key2": "value2"}'] となります。

InputPayload:
  key1: value1
  key2: value2

プロパティ名: Content -> files -> ${ZIP file name} -> checksums -> sha256
値の型: 文字列
解説:
- 実行するスクリプトを含む ZIP ファイルのハッシュ値を指定します。ハッシュ値は sha256 のみ指定可能です。Windows の場合は certutil -hashfile ${ZIP file name} SHA256 、Mac の場合は shasum -a 256 ${ZIP file name} でハッシュ値を取得できます。

ランブックの定義（Terraform）

以下は Terraform で aws:executeScript ステップのみ定義した場合のサンプルです。値が ${変数名} を利用しているプロパティは説明を後述します。
- Terraform では null_resource や data.archive_file を利用して、ZIP ファイルを作成し S3 にアップロードすることが可能です。

resource "null_resource" "install_requirements" {
  triggers = {
    always_run = "${timestamp()}"
  }

  provisioner "local-exec" {
    command = "pip install -r ${path.root}/src/requirements.txt -t ${path.root}/src/modules"
  }
}

data "archive_file" "file" {
  depends_on = [ null_resource.install_requirements ]
  type        = "zip"
  source_dir  = "${path.root}/src/modules"
  output_path = "${path.root}/src/modules.zip"
}

resource "aws_s3_object" "object" {
  bucket = "${S3 bucket name}"
  key    = "modules.zip"
  source = data.archive_file.file.output_path
}

resource "aws_ssm_document" "document" {
  depends_on = [ aws_s3_object.object ]

  name            = "${ドキュメント名}"
  document_type   = "Automation"
  document_format = "JSON"
  attachments_source {
    key = "S3FileUrl"
    name = "modules.zip"
    values = [
      "https://"${S3 bucket name}".s3.amazonaws.com/modules.zip"
    ]
  }

  content = jsonencode({
    assumeRole      = "${Delegation Roll ARN}"
    schemaVersion = "0.3"
    mainSteps = [
      {
        action = "aws:executeScript"
        name   = "RunSetupScript"
        inputs = {
          Runtime = "${Runtime name}"
          Handler = "${関数名}"
          Script  = "${file("${path.root}/src/runbook.py")}"
          Attachment = "modules.zip"
        }
      }
    ]
    files = {
      "modules.zip" = {
        checksums = {
          sha256 = filesha256(data.archive_file.file.output_path)
        }
      }
    }
  })
}

プロパティ名: aws_s3_object -> bucket , aws_ssm_document -> attachments_source -> values
値の型: 文字列
解説:
- aws_s3_object の bucket には ZIP ファイルをアップロードする S3 バケット名を指定します。
- aws_ssm_document の attachments_source の values には ZIP ファイルの URL を指定します。
プロパティ名: aws_ssm_document -> name
値の型: 文字列
解説:
- ランブックの名前を指定します。
- ランブックの名前は一意である必要があります。
プロパティ名: aws_ssm_document -> content -> assumeRole
値の型: 文字列
解説:
- ランブックの実行に必要な権限を持つロールを指定します。
プロパティ名: aws_ssm_document -> content -> mainSteps -> inputs -> Runtime
値の型: 文字列
解説:
- 実行するスクリプトのランタイムを指定します。
- 現在は Python3.x または PowerShell Core x.x のみ指定可能です。
- 利用可能なランタイムは、以下のリンク先を参照してください。
  - Systems Manager Automation アクションのリファレンス - AWS Systems Manager
プロパティ名: aws_ssm_document -> content -> mainSteps -> inputs -> Handler
値の型: 文字列
解説:
- 実行するスクリプトの関数名を指定します。
- 後述するスクリプトの定義（Python）の例では、 runbook.py の main 関数を実行する場合は main と指定します。
- PowerShell の場合は、このプロパティは不要です。
プロパティ名: aws_ssm_document -> content -> mainSteps -> inputs -> Script
値の型: 文字列
解説:
- 実行するスクリプトのファイルパスを指定します。
- Terraform の場合は、 file() 関数を利用してファイルパスを指定することで、ファイル内容を文字列として取得することが可能です。

スクリプトの定義（Python）

以下のファイル構成で Python スクリプトを定義し、ZIP ファイルに圧縮して S3 にアップロードします。

${Zipファイル対象のフォルダ名}/
${Zipファイル対象のフォルダ名}/runbook.py
${Zipファイル対象のフォルダ名}/requirements.txt

# ファイル構成例
runbook/
runbook/runbook.py
runbook/requirements.txt

Zip 化する際は以下の2つのコマンドの実行が必要です。
- Lambda のように requirements.txt に記載されたパッケージが自動でインストールされるわけではないため、 requirements.txt に記載されたパッケージをインストールしてから ZIP 化する必要があります。

pip install -r ${Zipファイル対象のフォルダ名}/requirements.txt -t ${Zipファイル対象のフォルダ名}
zip -rq ${ZIP file name} ${Zipファイル対象のフォルダ名}

オートメーション実行時のアクション許可

オートメーションを実行するには以下のアクションの許可が必要です。

No	アクション名	必要となる操作	リソースセクションで指定する ARN
01	ssm:StartAutomationExecution	オートメーションの実行	AutomationDefinitionName
02	ssm:StopAutomationExecution	オートメーションの停止	AutomationExecutionId
03	ssm:SendAutomationSignal	一時停止したオートメーションの再開	AutomationExecutionId
04	iam:PassRole	継承ロールを利用したオートメーションの実行	RoleNameWithPath

ssm:StartAutomationExecution および iam:PassRole はリソースセクションで固定の AWS リソースを含む ARN を指定することが可能なため、実行ユーザーに特定のランブックのみ実行可能な権限のみ付与することが可能です。

スクリプト実行時の環境情報（Python）

以下の JSON はランタイム Python 3.8 で環境変数をログ出力したものです。
環境変数から分かる通り、内部的に Lambda が実行されていますね。
Lambda の環境変数の詳細は Lambda 環境変数の使用 - AWS Lambda を参照してください。

{
    "_AWS_XRAY_DAEMON_ADDRESS": "169.254.79.129",
    "_AWS_XRAY_DAEMON_PORT": "2000",
    "_HANDLER": "FalconPythonWrapper.lambda_handler",
    "_X_AMZN_TRACE_ID": "Root=x-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx;Parent=xxxxxxxxxxxxxxxx;Sampled=1;Lineage=xxxxxxxx:x|xxxxxxxx:x|xxxxxxxx:x",
    "AWS_ACCESS_KEY_ID": "xxxxxxxxxx",
    "AWS_DEFAULT_REGION": "us-east-2",
    "AWS_EXECUTION_ENV": "AWS_Lambda_python3.8",
    "AWS_LAMBDA_FUNCTION_MEMORY_SIZE": "512",
    "AWS_LAMBDA_FUNCTION_NAME": "Falcon-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AWS_LAMBDA_FUNCTION_VERSION": "$LATEST",
    "AWS_LAMBDA_INITIALIZATION_TYPE": "on-demand",
    "AWS_LAMBDA_LOG_GROUP_NAME": "/aws/lambda/Falcon-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "AWS_LAMBDA_LOG_STREAM_NAME": "2023/12/14/[$LATEST]xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "AWS_LAMBDA_RUNTIME_API": "127.0.0.1:9001",
    "AWS_REGION": "us-east-2",
    "AWS_SECRET_ACCESS_KEY": "xxxxxxxxxx",
    "AWS_SECURITY_TOKEN": "xxxxxxxxxx",
    "AWS_SESSION_TOKEN": "xxxxxxxxxx",
    "AWS_XRAY_CONTEXT_MISSING": "LOG_ERROR",
    "AWS_XRAY_DAEMON_ADDRESS": "169.254.79.129:2000",
    "LAMBDA_RUNTIME_DIR": "/var/runtime",
    "LAMBDA_TASK_ROOT": "/var/task",
    "LANG": "en_US.UTF-8",
    "LD_LIBRARY_PATH": "/var/lang/lib:/lib64:/usr/lib64:/var/runtime:/var/runtime/lib:/var/task:/var/task/lib:/opt/lib",
    "PATH": "/var/lang/bin:/usr/local/bin:/usr/bin/:/bin:/opt/bin",
    "PWD": "/var/task",
    "PYTHONPATH": "/var/runtime:/tmp/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx-2023-12-14-10-36-37",
    "SHLVL": "0",
    "TZ": ":UTC"
}

開発時のポイント

ポイント ① 開発前に Systems Manager Automation runbook reference で使えるランブックがないか確認

Systems Manager Automation runbook reference - AWS Systems Manager Automation runbook reference では、AWS がマネージドで提供しているランブックが公開されています。
独自に Python をコーディングして処理を定義するのも良いですが、まずはマネージドに機能を実装できるか検討することが重要です。

ポイント ② 実行時間を可能な限り短縮するために並列実行や待機処理を検討する

aws:executeScript ステップでは内部的に Lambda が動作しているため、並列実行用のモジュールさえ利用すれば並列実行が可能です。
- concurrent.futures モジュールを利用することで、並列実行で処理時間を短縮することを検討しましょう。
aws:executeScript ステップの中で待機処理を実行してしまうと、待機している時間も課金が発生してしまうため、ランブックで定義するステップを分割することで待機ステップを追加いたします。
- 待機処理としては aws:waitForAwsResourceProperty ステップで AWS リソースのステータスを待機したり、 aws:sleep ステップでスリープを挟む選択肢があります。
  - aws:waitForAwsResourceProperty – Wait on an AWS resource property - AWS Systems Manager
- 待機時間の長いものは、EventBridge Scheduler を利用することで、特定の日時に再度オートメーションを実行することも検討します。
aws:executeScript ステップの最大実行時間は 15 分ではなく 10 分なのでご注意ください。
- aws:executeScript – スクリプトを実行する - AWS Systems Manager

ポイント ③ Output 出力を最適化し、デバッグができるようにする

aws:executeScript ステップで実行した際のログは、ログを外部出力して CloudWatch Logs などへ出力しない限り簡単に見ることができません。
- エラーが発生した場合、エラー出力を見ることはできます。
正常終了時のデバックログを SSM オートメーションの実行画面で表示させる場合、エントリーポイントとなる関数の返り値へデバッグレベルの情報を含めることで SSM オートメーションの実行画面に表示させることができます。

ポイント ④ ファイルの出力が必要な場合、 `/tmp` ディレクトリを利用すること

前述した通り、SSM オートメーションの実行環境は内部的に Lambda が実行されています。何かファイルを処理する場合、 /tmp ディレクトリを利用しましょう。
- 参考: Lambda 分離テクノロジー - AWS Lambda のセキュリティの概要

ポイント ⑤ AWS API の `Describe` `List` を実行する際には `paginator` を利用すること

SSM オートメーションならではというより、AWS の自動化処理を行うスクリプトを開発するうえでのポイントとなりますが、読み取りのAPIのうち、 Describe* List* を実行する場合、返り値のサイズ制限に注意する必要があります。
paginator を利用することで、pagination が発生する API の処理をシンプルに定義することが可能です。
- 参考： boto3 で pagination が発生する API を良い感じに処理する #Python - Qiita