Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

aws:executeScript – Run a script

Runs the Python or PowerShell script provided using the specified runtime and handler. Each aws:executeScript action can run up to a maximum duration of 600 seconds (10 minutes). You can limit the timeout by specifying the timeoutSeconds parameter for an aws:executeScript step.

Use return statements in your function to add outputs to your output payload. For examples of defining outputs for your aws:executeScript action, see Example 2: Scripted runbook. You can also send the output from aws:executeScript actions in your runbooks to the Amazon CloudWatch Logs log group you specify. For more information, see Logging Automation action output with CloudWatch Logs.

If you want to send output from aws:executeScript actions to CloudWatch Logs, or if the scripts you specify for aws:executeScript actions call Amazon API operations, an Amazon Identity and Access Management (IAM) service role (or assume role) is always required to run the runbook.

The aws:executeScript action contains the following preinstalled PowerShell Core modules:

To use PowerShell Core modules that aren't preinstalled, your script must install the module with the -Force flag, as shown in the following command. The AWSPowerShell.NetCore module isn't supported. Replace ModuleName with the module you want to install.

Install-Module ModuleName -Force

To use PowerShell Core cmdlets in your script, we recommend using the AWS.Tools modules, as shown in the following commands. Replace each example resource placeholder with your own information.

If your script initializes new objects in addition to using PowerShell Core cmdlets, you must also import the module as shown in the following command.

Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2

$tag = New-Object Amazon.EC2.Model.Tag
$tag.Key = "Tag"
$tag.Value = "TagValue"

New-EC2Tag -Resource i-02573cafcfEXAMPLE -Tag $tag

For examples of installing and importing AWS.Tools modules, and using PowerShell Core cmdlets in runbooks, see Visual design experience for Automation runbooks.

Input

Provide the information required to run your script. Replace each example resource placeholder with your own information.

YAML

action: "aws:executeScript"
inputs: 
 Runtime: runtime
 Handler: "functionName"
 InputPayload: 
  scriptInput: '{{parameterValue}}'
 Script: |-
   def functionName(events, context):
   ...
 Attachment: "scriptAttachment.zip"

JSON

{
    "action": "aws:executeScript",
    "inputs": {
        "Runtime": "runtime",
        "Handler": "functionName",
        "InputPayload": {
            "scriptInput": "{{parameterValue}}"
        },
        "Attachment": "scriptAttachment.zip"
    }
}

Using attachments with aws:executeScript

Attachments provide a powerful way to package and reuse complex scripts, multiple modules, and external dependencies with your aws:executeScript actions. Use attachments when you need to:

Attachment structure and packaging

You can attach either single files or zip packages containing multiple files. The structure depends on your use case:

Single file attachments

For simple scripts, you can attach a single .py file (Python) or a .zip file containing a single PowerShell script.

Multi-module packages

For complex automation that requires multiple modules, create a zip package with the following recommended structure:

my-automation-package.zip
├── main.py                    # Entry point script
├── utils/
│   ├── __init__.py           # Required for Python module imports
│   ├── helper_functions.py   # Utility functions
│   └── aws_operations.py     # AWS-specific operations
├── config/
│   ├── __init__.py
│   └── settings.py           # Configuration settings
└── requirements.txt          # Optional: document dependencies

PowerShell package structure

PowerShell attachments must be packaged in zip files with the following structure:

my-powershell-package.zip
├── Main.ps1                  # Entry point script
├── Modules/
│   ├── HelperFunctions.ps1   # Utility functions
│   └── AWSOperations.ps1     # AWS-specific operations
└── Config/
    └── Settings.ps1          # Configuration settings

Creating runbooks with attachments

Follow these steps to create runbooks that use attachments:

aws:executeScript attachment examples

The following examples demonstrate different ways to use attachments with the aws:executeScript action.

Example 1: Single file attachment

This example shows how to use a single Python file as an attachment to process EC2 instance data.

Attachment file: process_instance.py

Create a Python file with the following content:

import boto3
import json

def process_instance_data(events, context):
    """Process EC2 instance data and return formatted results."""
    try:
        instance_id = events.get('instanceId')
        if not instance_id:
            raise ValueError("instanceId is required")
        
        ec2 = boto3.client('ec2')
        
        # Get instance details
        response = ec2.describe_instances(InstanceIds=[instance_id])
        instance = response['Reservations'][0]['Instances'][0]
        
        # Format the response
        result = {
            'instanceId': instance_id,
            'instanceType': instance['InstanceType'],
            'state': instance['State']['Name'],
            'availabilityZone': instance['Placement']['AvailabilityZone'],
            'tags': {tag['Key']: tag['Value'] for tag in instance.get('Tags', [])}
        }
        
        print(f"Successfully processed instance {instance_id}")
        return result
        
    except Exception as e:
        print(f"Error processing instance: {str(e)}")
        raise

Complete runbook

Here's the complete runbook that uses the single file attachment:

description: Process EC2 instance data using single file attachment
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
  AutomationAssumeRole:
    type: String
    description: (Required) IAM role for automation execution
  InstanceId:
    type: String
    description: (Required) EC2 instance ID to process

files:
  process_instance.py:
    sourceType: "S3"
    sourceInfo:
      path: "s3://my-automation-bucket/scripts/process_instance.py"
      checksums:
        sha256: "abc123def456..."

mainSteps:
  - name: processInstance
    action: aws:executeScript
    inputs:
      Runtime: python3.11
      Handler: process_instance.process_instance_data
      Attachment: process_instance.py
      InputPayload:
        instanceId: '{{InstanceId}}'
    outputs:
      - Type: StringMap
        Name: InstanceData
        Selector: $.Payload

outputs:
  - processInstance.InstanceData

Example 2: Multi-module package

This example demonstrates using a zip package containing multiple Python modules for complex S3 bucket operations.

Package structure

Create a zip package with the following structure:

s3-operations.zip
├── main.py
├── utils/
│   ├── __init__.py
│   ├── s3_helper.py
│   └── validation.py
└── config/
    ├── __init__.py
    └── settings.py

main.py (entry point)

The main script that orchestrates the operations:

from utils.s3_helper import S3Operations
from utils.validation import validate_bucket_name
from config.settings import get_default_settings

def cleanup_s3_bucket(events, context):
    """Clean up S3 bucket based on specified criteria."""
    try:
        bucket_name = events.get('bucketName')
        max_age_days = events.get('maxAgeDays', 30)
        
        # Validate inputs
        if not validate_bucket_name(bucket_name):
            raise ValueError(f"Invalid bucket name: {bucket_name}")
        
        # Initialize S3 operations
        s3_ops = S3Operations()
        settings = get_default_settings()
        
        # Perform cleanup
        deleted_objects = s3_ops.delete_old_objects(
            bucket_name, 
            max_age_days,
            settings['dry_run']
        )
        
        result = {
            'bucketName': bucket_name,
            'deletedCount': len(deleted_objects),
            'deletedObjects': deleted_objects[:10],  # Return first 10 for brevity
            'dryRun': settings['dry_run']
        }
        
        print(f"Cleanup completed for bucket {bucket_name}")
        return result
        
    except Exception as e:
        print(f"Error during S3 cleanup: {str(e)}")
        raise

Troubleshooting aws:executeScript attachments

Use the following guidance to resolve common issues with aws:executeScript attachments:

Module import errors

If you receive import errors when using multi-module packages:

Attachment not found errors

If your automation fails to find the attachment:

Handler function errors

If you receive handler-related errors:

Script execution failures

If your script fails during execution:

Exit codes and error handling

To properly handle errors and return exit codes: