Creating runbooks that run scripts - AWS Systems Manager
Permissions for using runbooksAdding scripts to runbooksScript constraints for runbooks

Creating runbooks that run scripts

Automation runbooks support running scripts as part of the automation. Automation is a capability of AWS Systems Manager. By using runbooks, you can run scripts directly in AWS without creating a separate compute environment to run your scripts. Because runbooks can run script steps along with other automation step types, such as approvals, you can manually intervene in critical or ambiguous situations. You can send the output from aws:executeScript actions in your runbooks to Amazon CloudWatch Logs. For more information, see Logging Automation action output with CloudWatch Logs.

Permissions for using runbooks

To use a runbook, Systems Manager must use the permissions of an AWS Identity and Access Management (IAM) role. The method that Automation uses to determine which role's permissions to use depends on a few factors, and whether a step uses the aws:executeScript action.

For runbooks that don't use aws:executeScript, Automation uses one of two sources of permissions:

  • The permissions of an IAM service role, or Assume role, that is specified in the runbook or passed in as a parameter.

  • If no IAM service role is specified, the permissions of the IAM user who started the automation.

When a step in a runbook includes the aws:executeScript action, however, an IAM service role (Assume role) is always required if the Python or PowerShell script specified for the action is calling any AWS API operations. Automation checks for this role in the following order:

  • The permissions of an IAM service role, or Assume role, that is specified in the runbook or passed in as a parameter.

  • If no role is found, Automation attempts to run the Python or PowerShell script specified for aws:executeScript without any permissions. If the script is calling an AWS API operation (for example the Amazon EC2 CreateImage operation), or attempting to act on an AWS resource (such as an EC2 instance), the step containing the script fails, and Systems Manager returns an error message reporting the failure.

For more information about how to use a runbook that uses an IAM service role or more advanced forms of delegated administration instead, see Running an automation by using an IAM service role.

Adding scripts to runbooks

You can add scripts to your runbooks by including the script inline as part of a step in the runbook. You can also attach scripts to the runbook by uploading the scripts from your local machine or by specifying an Amazon Simple Storage Service (Amazon S3) bucket where the scripts are located. After a step that runs a script is complete, the output of the script is available as a JSON object, which you can then use as input for subsequent steps in your runbook.

Script constraints for runbooks

The automation action aws:executeScript supports running Python 3.6, Python 3.7, and PowerShell Core 6.0 scripts.

Runbooks enforce a limit of five file attachments. Scripts can either be in the form of a Python script (.py), a PowerShell Core script (.ps1), or attached as contents within a .zip file.

Your account is charged for running scripts using Automation. Automation steps that use the action aws:executeScript are considered special steps. There is no step limit for special steps, but your account is charged based on the number of steps and duration of your script execution. For more information, see the AWS Systems Manager Pricing page.

The following topics describe how to create runbooks that run scripts.

Topics