Creating your own runbooks

An Automation runbook defines the actions that Systems Manager performs on your managed instances and other AWS resources when an automation runs. Automation is a capability of AWS Systems Manager. A runbook contains one or more steps that run in sequential order. Each step is built around a single action. Output from one step can be used as input in a later step.

The process of running these actions and their steps is called the automation.

Action types supported for runbooks let you automate a wide variety of operations in your AWS environment. For example, using the executeScript action type, you can embed a python or PowerShell script directly in your runbook. (When you create a custom runbook, you can add your script inline, or attach it from an S3 bucket or from your local machine.) You can automate management of your AWS CloudFormation resources by using the createStack and deleteStack action types. In addition, using the executeAwsApi action type, a step can run any API operation in any AWS service, including creating or deleting AWS resources, starting other processes, initiating notifications, and many more.

For a list of all 20 supported action types for Automation, see Systems Manager Automation actions reference.

AWS Systems Manager Automation provides several runbooks with pre-defined steps that you can use to perform common tasks like restarting one or more Amazon Elastic Compute Cloud (Amazon EC2) instances or creating an Amazon Machine Image (AMI). You can also create your own runbooks and share them with other AWS accounts, or make them public for all Automation users.

Runbooks are written using YAML or JSON. Using the Document Builder in the Systems Manager Automation console, however, you can create a runbook without having to author in native JSON or YAML.

Important

If you run an automation workflow that invokes other services by using an AWS Identity and Access Management (IAM) service role, be aware that the service role must be configured with permission to invoke those services. This requirement applies to all AWS Automation runbooks (AWS-* runbooks) such as the AWS-ConfigureS3BucketLogging, AWS-CreateDynamoDBBackup, and AWS-RestartEC2Instance runbooks, to name a few. This requirement also applies to any custom Automation runbooks you create that invoke other AWS services by using actions that call other services. For example, if you use the aws:executeAwsApi, aws:createStack, or aws:copyImage actions, configure the service role with permission to invoke those services. You can give permissions to other AWS services by adding an IAM inline policy to the role. For more information, see (Optional) Add an Automation inline policy or customer managed policy to invoke other AWS services.

For information about the actions that you can specify in a runbook, see Systems Manager Automation actions reference.

For information about using the AWS Toolkit for Visual Studio Code to create runbooks, see Working with Systems Manager Automation documents in the AWS Toolkit for Visual Studio Code User Guide.

For information about using the visual designer to create a custom runbook, see Visual design experience for Automation runbooks.

Contents

• Visual design experience for Automation runbooks
  • Before you begin
  • Overview of the visual design experience interface
    • Actions browser
    • Canvas
    • Form
    • Keyboard shortcuts
  • Using the visual design experience
    • Create a runbook workflow
    • Design a runbook
    • Update your runbook
    • Export your runbook
  • Configuring inputs and outputs for your actions
    • Provide input data for an action
    • Define output data for an action
  • Error handling with the visual design experience
    • Retry action on error
    • Timeouts
    • Failed actions
    • Canceled actions
    • Critical actions
    • Ending actions
  • Tutorial: Create a runbook using the visual design experience
    • Step 1: Navigate to the visual design experience
    • Step 2: Create a workflow
    • Step 3: Review the auto-generated code
    • Step 4: Run your new runbook
    • Step 5: Clean up
• Authoring Automation runbooks
  • Identify your use case
  • Set up your development environment
  • Develop runbook content
  • Example 1: Creating parent-child runbooks
    • Create the child runbook
    • Create the parent runbook
  • Example 2: Scripted runbook
  • Additional runbook examples
    • Deploy VPC architecture and Microsoft Active Directory domain controllers
    • Restore a root volume from the latest snapshot
    • Create an AMI and cross-Region copy
• Creating input parameters that populate AWS resources
• Using Document Builder to create runbooks
  • Create a runbook using Document Builder
  • Create a runbook that runs scripts
• Using scripts in runbooks
  • Permissions for using runbooks
  • Adding scripts to runbooks
  • Script constraints for runbooks
• Using conditional statements in runbooks
  • Working with the aws:branch action
    • Creating an aws:branch step in a runbook
      • About creating the output variable
    • Example aws:branch runbooks
    • Creating complex branching automations with operators
  • Examples of how to use conditional options
• Using action outputs as inputs
  • Using JSONPath in runbooks
• Creating webhook integrations for Automation
  • Creating integrations (console)
  • Creating integrations (command line)
  • Creating webhooks for integrations
• Handling timeouts in runbooks