• The AWS Systems Manager CloudWatch Dashboard will no longer be available after April 30, 2026. Customers can continue to use Amazon CloudWatch console to view, create, and manage their Amazon CloudWatch dashboards, just as they do today. For more information, see [Amazon CloudWatch Dashboard documentation](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch_Dashboards.html). # 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 tool in 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](automation-actions.md). 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](automation-setup-iam.md#add-inline-policy). For information about the actions that you can specify in a runbook, see [Systems Manager Automation actions reference](automation-actions.md). For information about using the AWS Toolkit for Visual Studio Code to create runbooks, see [Working with Systems Manager Automation documents](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html) 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](automation-visual-designer.md). **Contents** + [ # Visual design experience for Automation runbooks ](automation-visual-designer.md) + [ # Overview of the visual design experience interface ](visual-designer-interface-overview.md) + [ ## Actions browser ](visual-designer-interface-overview.md#visual-designer-actions) + [ ## Canvas ](visual-designer-interface-overview.md#visual-designer-canvas) + [ ## Form ](visual-designer-interface-overview.md#visual-designer-form) + [ ## Keyboard shortcuts ](visual-designer-interface-overview.md#visual-designer-keyboard-shortcuts) + [ # Using the visual design experience ](visual-designer-use.md) + [ ## Create a runbook workflow ](visual-designer-use.md#visual-designer-create-runbook-workflow) + [ ## Design a runbook ](visual-designer-use.md#visual-designer-build) + [ ## Update your runbook ](visual-designer-use.md#visual-designer-update-runbook) + [ ## Export your runbook ](visual-designer-use.md#visual-designer-export-runbook) + [ # Configuring inputs and outputs for your actions ](visual-designer-action-inputs-outputs.md) + [ ## Provide input data for an action ](visual-designer-action-inputs-outputs.md#providing-input) + [ ## Define output data for an action ](visual-designer-action-inputs-outputs.md#defining-output) + [ # Error handling with the visual design experience ](visual-designer-error-handling.md) + [ ## Retry action on error ](visual-designer-error-handling.md#retry-actions) + [ ## Timeouts ](visual-designer-error-handling.md#timeout-seconds) + [ ## Failed actions ](visual-designer-error-handling.md#failure-actions) + [ ## Canceled actions ](visual-designer-error-handling.md#cancel-actions) + [ ## Critical actions ](visual-designer-error-handling.md#critical-actions) + [ ## Ending actions ](visual-designer-error-handling.md#end-actions) + [ # Tutorial: Create a runbook using the visual design experience ](visual-designer-tutorial.md) + [ ## Step 1: Navigate to the visual design experience ](visual-designer-tutorial.md#navigate-console) + [ ## Step 2: Create a workflow ](visual-designer-tutorial.md#create-workflow) + [ ## Step 3: Review the auto-generated code ](visual-designer-tutorial.md#view-generated-code) + [ ## Step 4: Run your new runbook ](visual-designer-tutorial.md#use-tutorial-runbook) + [ ## Step 5: Clean up ](visual-designer-tutorial.md#cleanup-tutorial-runbook) + [ # Authoring Automation runbooks ](automation-authoring-runbooks.md) + [ ## Identify your use case ](automation-authoring-runbooks.md#automation-authoring-runbooks-use-case) + [ ## Set up your development environment ](automation-authoring-runbooks.md#automation-authoring-runbooks-environment) + [ ## Develop runbook content ](automation-authoring-runbooks.md#automation-authoring-runbooks-developing-content) + [ # Example 1: Creating parent-child runbooks ](automation-authoring-runbooks-parent-child-example.md) + [ ## Create the child runbook ](automation-authoring-runbooks-parent-child-example.md#automation-authoring-runbooks-child-runbook) + [ ## Create the parent runbook ](automation-authoring-runbooks-parent-child-example.md#automation-authoring-runbooks-parent-runbook) + [ # Example 2: Scripted runbook ](automation-authoring-runbooks-scripted-example.md) + [ # Additional runbook examples ](automation-document-examples.md) + [ # Deploy VPC architecture and Microsoft Active Directory domain controllers ](automation-document-architecture-deployment-example.md) + [ # Restore a root volume from the latest snapshot ](automation-document-instance-recovery-example.md) + [ # Create an AMI and cross-Region copy ](automation-document-backup-maintenance-example.md) + [ # Creating input parameters that populate AWS resources ](populating-input-parameters.md) + [ # Using Document Builder to create runbooks ](automation-document-builder.md) + [ ## Create a runbook using Document Builder ](automation-document-builder.md#create-runbook) + [ ## Create a runbook that runs scripts ](automation-document-builder.md#create-runbook-scripts) + [ # Using scripts in runbooks ](automation-document-script-considerations.md) + [ ## Permissions for using runbooks ](automation-document-script-considerations.md#script-permissions) + [ ## Adding scripts to runbooks ](automation-document-script-considerations.md#adding-scripts) + [ ## Script constraints for runbooks ](automation-document-script-considerations.md#script-constraints) + [ # Using conditional statements in runbooks ](automation-branch-condition.md) + [ ## Working with the `aws:branch` action ](automation-branch-condition.md#branch-action-explained) + [ ### Creating an `aws:branch` step in a runbook ](automation-branch-condition.md#create-branch-action) + [ #### About creating the output variable ](automation-branch-condition.md#branch-action-output) + [ ### Example `aws:branch` runbooks ](automation-branch-condition.md#branch-runbook-examples) + [ ### Creating complex branching automations with operators ](automation-branch-condition.md#branch-operators) + [ ## Examples of how to use conditional options ](automation-branch-condition.md#conditional-examples) + [ # Using action outputs as inputs ](automation-action-outputs-inputs.md) + [ ## Using JSONPath in runbooks ](automation-action-outputs-inputs.md#automation-action-json-path) + [ # Creating webhook integrations for Automation ](creating-webhook-integrations.md) + [ ## Creating integrations (console) ](creating-webhook-integrations.md#creating-integrations-console) + [ ## Creating integrations (command line) ](creating-webhook-integrations.md#creating-integrations-commandline) + [ ## Creating webhooks for integrations ](creating-webhook-integrations.md#creating-webhooks) + [ # Handling timeouts in runbooks ](automation-handling-timeouts.md) # Visual design experience for Automation runbooks AWS Systems Manager Automation provides a low-code visual design experience that helps you create automation runbooks. The visual design experience provides a drag-and-drop interface with the option to add your own code so you can create and edit runbooks more easily. With the visual design experience, you can do the following: + Control conditional statements. + Control how input and output is filtered or transformed for each action. + Configure error handling. + Prototype new runbooks. + Use your prototype runbooks as the starting point for local development with the AWS Toolkit for Visual Studio Code. When you create or edit a runbook, you can access the visual design experience from the [Automation console](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/). As you create a runbook, the visual design experience validates your work and auto-generates code. You can review the generated code, or export it for local development. When you're finished, you can save your runbook, run it, and examine the results in the Systems Manager Automation console. **Topics** + [Interface overview](visual-designer-interface-overview.md) + [ # Using the visual design experience ](visual-designer-use.md) + [Configure inputs and outputs](visual-designer-action-inputs-outputs.md) + [ # Error handling with the visual design experience ](visual-designer-error-handling.md) + [ # Tutorial: Create a runbook using the visual design experience ](visual-designer-tutorial.md) # Overview of the visual design experience interface Interface overview The visual design experience for Systems Manager Automation is a low-code visual workflow designer that helps you create automation runbooks. Get to know the visual design experience with an overview of the interface components: ![\[Visual design experience components\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_overview.png) + The **Actions** browser contains the **Actions**, **AWS APIs**, and **Runbooks** tabs. + The *canvas* is where you drag and drop actions into your workflow graph, change the order of actions, and select actions to configure or view. + The **Form** panel is where you can view and edit the properties of any action that you selected on the canvas. Select the **Content** toggle to view the YAML or JSON for your runbook, with the currently selected action highlighted. **Info** links open a panel with contextual information when you need help. These panels also include links to related topics in the Systems Manager Automation documentation. ## Actions browser From the **Actions** browser, you can select actions to drag and drop into your workflow graph. You can search all actions using the search field at the top of the **Actions** browser. The **Actions** browser contains the following tabs: + The **Actions** tab provides a list of automation actions that you can drag and drop into your runbook's workflow graph in the canvas. + The **AWS APIs** tab provides a list of AWS APIs that you can drag and drop into your runbook's workflow graph in the canvas. + The **Runbooks** tab provides several ready-to-use, reusable runbooks as building blocks that you can use for a variety of use cases. For example, you can use runbooks to perform common remediation tasks on Amazon EC2 instances in your workflow without having to re-create the same actions. ![\[Visual design experience actions browser\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_actions_multi_view.png) ## Canvas After you choose an action to add to your automation, drag it to the canvas and drop it into your workflow graph. You can also drag and drop actions to move them to different places in your runbook's workflow. If your workflow is complex, you might not be able to view all of it in the canvas panel. Use the controls at the top of the canvas to zoom in or out. To view different parts of a workflow, you can drag the workflow graph in the canvas. Drag an action from the **Actions** browser, and drop it into your runbook's workflow graph. A line shows where it will be placed in your workflow. To change the order of an action, you can drag it to a different place in your workflow. The new action has been added to your workflow, and its code is auto-generated. ![\[Visual design experience canvas\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_canvas.png) ## Form After you add an action to your runbook workflow, you can configure it to meet your use case. Choose the action that you want to configure, and you will see its parameters and options in the **Form** panel. You can also see the YAML or JSON code by choosing the **Content** toggle. The code associated with the action you have selected is highlighted. ![\[Visual design experience form panel\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_form.png) ![\[Visual design experience content panel\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_content.png) ## Keyboard shortcuts The visual design experience supports the keyboard shortcuts shown in the following table. | Keyboard shortcut | Function | | --- | --- | | Ctrl\$1Z | Undo the last operation. | | Ctrl\$1Shift\$1Z | Redo the last operation. | | Alt\$1C | Center the workflow in the canvas. | | Backspace | Remove all selected states. | | Delete | Remove all selected states. | | Ctrl\$1D | Duplicate the selected state. | # Using the visual design experience Learn to create, edit and run runbook workflows using the visual design experience. After your workflow is ready, you can save it or export it. You can also use the visual design experience for rapid prototyping. ## Create a runbook workflow 1. Sign in to the [Systems Manager Automation console](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/). 1. Choose **Create runbook**. 1. In the **Name** box, enter a name for your runbook, for example, `MyNewRunbook`. 1. Next to the **Design** and **Code** toggle, select the pencil icon and enter a name for your runbook. You can now design a workflow for your new runbook. ## Design a runbook To design a runbook workflow using the visual design experience, you drag an automation action from the **Actions** browser into the canvas, placing it where you want it in your runbook's workflow. You can also re-order actions in your workflow by dragging them to a different location. As you drag an action onto the canvas, a line appears wherever you can drop the action in your workflow. After an action is dropped onto the canvas, its code is auto-generated and added inside your runbook's content. If you know the name of the action you want to add, use the search box at the top of the **Actions** browser to find the action. After you drop an action onto the canvas, configure it using the **Form** panel on the right. This panel contains the **General**, **Inputs**, **Outputs**, and **Configuration** tabs for each automation action or API action that you place on the canvas. For example, the **General** tab consists of the following sections: + The **Step name** identifies the step. Specify a unique value for the step name. + The **Description** helps you describe what the action is doing in your runbook's workflow. The **Inputs** tab contains fields that vary based on the action. For example, the `aws:executeScript` automation action consists of the following sections: + The **Runtime** is the language to use for running the provided script. + The **Handler** is the name of your function. You must ensure that the function defined in the handler has two parameters: `events` and `context`. The PowerShell runtime doesn't support this parameter. + The **Script** is an embedded script that you want to run during the workflow. + (Optional) The **Attachment** is for standalone scripts or .zip files that can be invoked by the action. This parameter is required for JSON runbooks. The **Outputs** tab helps you specify the values that you want to output from an action. You can reference output values in later actions of your workflow, or generate output from actions for logging purposes. Not all actions will have an **Outputs** tab because not all actions support outputs. For example, the `aws:pause` action doesn't support outputs. For actions that do support outputs, the **Outputs** tab consists of the following sections: + The **Name** is the name to be used for the output value. You can reference outputs in later actions of your workflow. + The **Selector** is a JSONPath expression string beginning with `"$."` that is used to select one or more components within a JSON element. + The **Type** is the data type for the output value. For example, a `String` or `Integer` data type. The **Configuration** tab contains properties and options that all automation actions can use. The action consists of the following sections: + The **Max attempts** property is the number of times an action retries if it fails. + The **Timeout seconds** property specifies the timeout value for an action. + The **Is critical** property determines if the action failure stops the entire automation. + The **Next step** property determines which action the automation goes to next in the runbook. + The **On failure** property determines which action the automation goes to next in the runbook if the action fails. + The **On cancel** property determines which action the automation goes to next in the runbook if the action is canceled by a user. To delete an action, you can use backspace, the toolbar above the canvas, or right-click and choose **Delete action**. As your workflow grows, it might not fit in the canvas. To help make the workflow fit in the canvas, try one of the following options: + Use the controls on the side panels to resize or close the panels. + Use the toolbar at the top of the canvas to zoom the workflow graph in or out. ## Update your runbook You can update an existing runbook workflow by creating a new version of your runbook. Updates to your runbooks can be made by using the visual design experience, or by editing the code directly. To update an existing runbook, use the following procedure: 1. Sign in to the [Systems Manager Automation console](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/). 1. Choose the runbook that you want to update. 1. Choose **Create new version**. 1. The visual design experience has two panes: A code pane and a visual workflow pane. Choose **Design** in the visual workflow pane to edit your workflow with the visual design experience. When you're done, choose **Create new version** to save your changes and exit. 1. (Optional) Use the code pane to edit the runbook content in YAML or JSON. ## Export your runbook To export your runbook's workflow YAML or JSON code, and also a graph of your workflow, use the following procedure: 1. Choose your runbook in the **Documents** console. 1. Choose **Create new version**. 1. In the **Actions** dropdown, choose whether you want to export the graph or runbook, and which format you prefer. # Configuring inputs and outputs for your actions Configure inputs and outputs Each automation action responds based on input that it receives. In most cases, you then pass output to the subsequent actions. In the visual design experience, you can configure an action's input and output data in the **Inputs** and **Outputs** tabs of the **Form** panel. For detailed information about how to define and use output for automation actions, see [Using action outputs as inputs](automation-action-outputs-inputs.md). ## Provide input data for an action Each automation action has one or more inputs that you must provide a value for. The value you provide for an action's input is determined by the data type and format that's accepted by the action. For example, the `aws:sleep` actions requires an ISO 8601 formatted string value for the `Duration` input. Generally, you use actions in your runbook's workflow that return output that you want to use in subsequent actions. It's important to make sure your input values are correct to avoid errors in your runbook's workflow. Input values are also important because they determine whether the action returns the expected output. For example, when using the `aws:executeAwsApi` action, you want to make sure that you're providing the right value for the API operation. ## Define output data for an action Some automation actions return output after performing their defined operations. Actions that return output either have predefined outputs, or allow you to define the outputs yourself. For example, the `aws:createImage` action has predefined outputs that return an `ImageId` and `ImageState`. Comparatively, with the `aws:executeAwsApi` action, you can define the outputs you that want from the specified API operation. As a result, you can return one or more values from a single API operation to use in subsequent actions. Defining your own outputs for an automation action requires that you specify a name of the output, the data type, and the output value. To continue using the `aws:executeAwsApi` action as an example, let's say you're calling the `DescribeInstances` API operation from Amazon EC2. In this example, you want to return, or output, the `State` of an Amazon EC2 instance and branch your runbook's workflow based on the output. You choose to name the output **InstanceState**, and use the **String** data type. The process to define the actual value of the output differs, depending on the action. For example, if you're using the `aws:executeScript` action, you must use `return` statements in your functions to provide data to your outputs. With other actions like `aws:executeAwsApi`, `aws:waitForAwsResourceProperty`, and `aws:assertAwsResourceProperty`, a `Selector` is required. The `Selector`, or `PropertySelector` as some actions refer to it, is a JSONPath string that is used to process the JSON response from an API operation. It's important to understand how the JSON response object from an API operation is structured so you can select the correct value for your output. Using the `DescribeInstances` API operation mentioned earlier, see the following example JSON response: ``` { "reservationSet": { "item": { "reservationId": "r-1234567890abcdef0", "ownerId": 123456789012, "groupSet": "", "instancesSet": { "item": { "instanceId": "i-1234567890abcdef0", "imageId": "ami-bff32ccc", "instanceState": { "code": 16, "name": "running" }, "privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal", "dnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com", "reason": "", "keyName": "my_keypair", "amiLaunchIndex": 0, "productCodes": "", "instanceType": "t2.micro", "launchTime": "2018-05-08T16:46:19.000Z", "placement": { "availabilityZone": "eu-west-1c", "groupName": "", "tenancy": "default" }, "monitoring": { "state": "disabled" }, "subnetId": "subnet-56f5f000", "vpcId": "vpc-11112222", "privateIpAddress": "192.168.1.88", "ipAddress": "54.194.252.215", "sourceDestCheck": true, "groupSet": { "item": { "groupId": "sg-e4076000", "groupName": "SecurityGroup1" } }, "architecture": "x86_64", "rootDeviceType": "ebs", "rootDeviceName": "/dev/xvda", "blockDeviceMapping": { "item": { "deviceName": "/dev/xvda", "ebs": { "volumeId": "vol-1234567890abcdef0", "status": "attached", "attachTime": "2015-12-22T10:44:09.000Z", "deleteOnTermination": true } } }, "virtualizationType": "hvm", "clientToken": "xMcwG14507example", "tagSet": { "item": { "key": "Name", "value": "Server_1" } }, "hypervisor": "xen", "networkInterfaceSet": { "item": { "networkInterfaceId": "eni-551ba000", "subnetId": "subnet-56f5f000", "vpcId": "vpc-11112222", "description": "Primary network interface", "ownerId": 123456789012, "status": "in-use", "macAddress": "02:dd:2c:5e:01:69", "privateIpAddress": "192.168.1.88", "privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal", "sourceDestCheck": true, "groupSet": { "item": { "groupId": "sg-e4076000", "groupName": "SecurityGroup1" } }, "attachment": { "attachmentId": "eni-attach-39697adc", "deviceIndex": 0, "status": "attached", "attachTime": "2018-05-08T16:46:19.000Z", "deleteOnTermination": true }, "association": { "publicIp": "54.194.252.215", "publicDnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com", "ipOwnerId": "amazon" }, "privateIpAddressesSet": { "item": { "privateIpAddress": "192.168.1.88", "privateDnsName": "ip-192-168-1-88.eu-west-1.compute.internal", "primary": true, "association": { "publicIp": "54.194.252.215", "publicDnsName": "ec2-54-194-252-215.eu-west-1.compute.amazonaws.com", "ipOwnerId": "amazon" } } }, "ipv6AddressesSet": { "item": { "ipv6Address": "2001:db8:1234:1a2b::123" } } } }, "iamInstanceProfile": { "arn": "arn:aws:iam::123456789012:instance-profile/AdminRole", "id": "ABCAJEDNCAA64SSD123AB" }, "ebsOptimized": false, "cpuOptions": { "coreCount": 1, "threadsPerCore": 1 } } } } } } ``` In the JSON response object, the instance `State` is nested in an `Instances` object, which is nested in the `Reservations` object. To return the value of the instance `State`, use the following string for the `Selector` so the value can be used in our output: **\$1.Reservations[0].Instances[0].State.Name**. To reference an output value in subsequent actions of your runbook's workflow, the following format is used: `{{ StepName.NameOfOutput }}`. For example, **\$1\$1 GetInstanceState.InstanceState \$1\$1**. In the visual design experience, you can choose output values to use in subsequent actions using the dropdown for the input. When using outputs in subsequent actions, the data type of the output must match the data type for the input. In this example, the `InstanceState` output is a `String`. Therefore, to use the value in a subsequent action's input, the input must accept a `String`. # Error handling with the visual design experience By default, when an action reports an error, Automation stops the runbook's workflow entirely. This is because the default value for the `onFailure` property on all actions is `Abort`. You can configure how Automation handles errors in your runbook's workflow. Even if you have configured error handling, some errors might still cause an automation to fail. For more information, see [Troubleshooting Systems Manager Automation](automation-troubleshooting.md). In the visual design experience, you configure error handling in the **Configuration** panel. ![\[Error handling options\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_error_handling.png) ## Retry action on error To retry an action in case of an error, specify a value for the **Max attempts** property. The default value is 1. If you specify a value greater than 1, the action isn't considered to have failed until all of the retry attempts have failed. ## Timeouts You can configure a timeout for actions to set the maximum number of seconds your action can run before it fails. To configure a timeout, enter the number of seconds that your action should wait before the action fails in the **Timeout seconds** property. If the timeout is reached and the action has a value of `Max attempts` that is greater than 1, the step isn't considered to have timed out until the retries complete. ## Failed actions By default, when an action fails, Automation stops the runbook's workflow entirely. You can modify this behavior by specifying an alternative value for the **On failure** property of the actions in your runbook. If you want the workflow to continue to the next step in the runbook, choose **Continue**. If you want the workflow to jump to a different subsequent step in the runbook, choose **Step** and then enter the name of the step. ## Canceled actions By default, when an action is canceled by a user, Automation stops the runbook's workflow entirely. You can modify this behavior by specifying an alternative value for the **On cancel** property of the actions in your runbook. If you want the workflow to jump to a different subsequent step in the runbook, choose **Step** and then enter the name of the step. ## Critical actions You can designate an action as *critical*, meaning it determines the overall reporting status of your automation. If a step with this designation fails, Automation reports the final status as `Failed` regardless of the success of other actions. To configure an action as critical, leave the default value as **True** for the **Is critical** property. ## Ending actions The **Is end** property stops an automation at the end of the specified action. The default value for this property is `false`. If you configure this property for an action, the automation stops whether the action succeeds or fails. This property is most often used with `aws:branch` actions to handle unexpected or undefined input values. The following example shows a runbook that is expecting an instance state of either `running`, `stopping`, or `stopped`. If an instance is in a different state, the automation ends. ![\[Visual design experience is end example\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_is_end_example.png) # Tutorial: Create a runbook using the visual design experience In this tutorial, you will learn the basics of working with the visual design experience provided by Systems Manager Automation. In the visual design experience, you can create a runbook that uses multiple actions. You use the drag and drop feature to arrange actions on the canvas. You also search for, select, and configure these actions. Then, you can view the auto-generated YAML code for your runbook's workflow, exit the visual design experience, run the runbook, and review the execution details. This tutorial also shows you how to update the runbook and view the new version. At the end of the tutorial, you perform a clean-up step and delete your runbook. After you complete this tutorial, you'll know how to use the visual design experience to create a runbook. You'll also know how to update, run, and delete your runbook. **Note** Before you start this tutorial, make sure to complete [Setting up Automation](automation-setup.md). **Topics** + [ ## Step 1: Navigate to the visual design experience ](#navigate-console) + [ ## Step 2: Create a workflow ](#create-workflow) + [ ## Step 3: Review the auto-generated code ](#view-generated-code) + [ ## Step 4: Run your new runbook ](#use-tutorial-runbook) + [ ## Step 5: Clean up ](#cleanup-tutorial-runbook) ## Step 1: Navigate to the visual design experience 1. Sign in to the [Systems Manager Automation console](https://console.aws.amazon.com/systems-manager/automation/home?region=us-east-1#/). 1. Choose **Create automation runbook**. ## Step 2: Create a workflow In the visual design experience, a workflow is a graphical representation of your runbook on the canvas. You can use the visual design experience to define, configure, and examine the individual actions of your runbook. **To create a workflow** 1. Next to the **Design** and **Code** toggle, select the pencil icon and enter a name for your runbook. For this tutorial, enter **VisualDesignExperienceTutorial**. ![\[Visual design experience name your runbook\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_tutorial_name.png) 1. In the **Document attributes** section of the **Form** panel, expand the **Input parameters** dropdown, and select **Add a parameter**. 1. In the **Parameter name** field, enter **InstanceId**. 1. In the **Type** dropdown, choose **AWS::EC2::Instance**. 1. Select the **Required** toggle. ![\[Create a parameter for your runbook\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_actions_tutorial_parameter.png) 1. In the **AWS APIs** browser, enter **DescribeInstances** in the search bar. 1. Drag an **Amazon EC2 – DescribeInstances** action to the empty canvas. 1. For **Step name**, enter a value. For this tutorial, you can use the name **GetInstanceState**. ![\[Choose an Amazon EC2 describe instances API action.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_tutorial_api_action.png) 1. Expand the **Additional inputs** dropdown, and in the **Input name** field, enter **InstanceIds**. 1. Choose the **Inputs** tab. 1. In the **Input value** field, choose the **InstanceId** document input. This references the value of the input parameter that you created at the beginning of the procedure. Since the **InstanceIds** input for the `DescribeInstances` action accepts `StringList` values, you must wrap the **InstanceId** input in square brackets. The YAML for the **Input value** should match the following: **['\$1\$1 InstanceId \$1\$1']**. 1. In the **Outputs** tab, select **Add an output** and enter **InstanceState** in the **Name** field. 1. In the **Selector** field, enter **\$1.Reservations[0].Instances[0].State.Name**. 1. In the **Type** dropdown, choose **String**. 1. Drag a **Branch** action from the **Actions** browser, and drop it below the **`GetInstanceState`** step. 1. For **Step name**, enter a value. For this tutorial, use the name `BranchOnInstanceState`. To define the branching logic, do the following: 1. Choose the **`Branch`** state on the canvas. Then, under **Inputs** and **Choices**, select the pencil icon to edit **Rule \$11**. 1. Choose **Add conditions**. 1. In the **Conditions for rule \$11** dialog box, choose the **GetInstanceState.InstanceState** step output from the **Variable** dropdown. 1. For **Operator**, choose **is equal to**. 1. For **Value**, choose **String** from the dropdown list. Enter **stopped**. ![\[Define a condition for a branch action.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_tutorial_condition.png) 1. Select **Save conditions**. 1. Choose **Add new choice rule**. 1. Choose **Add conditions** for **Rule \$12**. 1. In the **Conditions for rule \$12** dialog box, choose the **GetInstanceState.InstanceState** step output from the **Variable** dropdown. 1. For **Operator**, choose **is equal to**. 1. For **Value**, choose **String** from the dropdown list. Enter **stopping**. 1. Select **Save conditions**. 1. Choose **Add new choice rule**. 1. For **Rule \$13**, choose **Add conditions**. 1. In the **Conditions for rule \$13** dialog box, choose the **GetInstanceState.InstanceState** step output from the **Variable** dropdown. 1. For **Operator**, choose **is equal to**. 1. For **Value**, choose **String** from the dropdown list. Enter **running**. 1. Select **Save conditions**. 1. In the **Default rule**, choose **Go to end** for the **Default step**. 1. Drag a **Change an instance state** action to the empty **Drag action here** box under the **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "stopped"** condition. 1. For the **Step name**, enter **StartInstance**. 1. In the **Inputs** tab, under **Instance IDs**, choose the **InstanceId** document input value from the dropdown. 1. For the **Desired state**, specify **`running`**. 1. Drag a **Wait on AWS resource** action to the empty **Drag action here** box under the **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "stopping"** condition. 1. For **Step name**, enter a value. For this tutorial, use the name `WaitForInstanceStop`. 1. For the **Service** field, choose **Amazon EC2**. 1. For the **API** field, choose **DescribeInstances**. 1. For the **Property selector** field, enter **\$1.Reservations[0].Instances[0].State.Name**. 1. For the **Desired values** parameter, enter **`["stopped"]`**. 1. In the **Configuration** tab of the **WaitForInstanceStop** action, choose **StartInstance** from the **Next step** dropdown. 1. Drag a **Run command on instances** action to the empty **Drag action here** box under the **\$1\$1 GetInstanceState.InstanceState \$1\$1 == "running"** condition. 1. For the **Step name**, enter **SayHello**. 1. In the **Inputs** tab, enter **AWS-RunShellScript** for the **Document name** parameter. 1. For **InstanceIds**, choose the **InstanceId** document input value from the dropdown. 1. Expand the **Additional inputs** dropdown, and in the **Input name** dropdown, choose **Parameters**. 1. In the **Input value** field, enter **`{"commands": "echo 'Hello World'"}`**. 1. Review the completed runbook in the canvas and select **Create runbook** to save the tutorial runbook. ![\[Review and create the runbook.\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/visual_designer_tutorial_complete.png) ## Step 3: Review the auto-generated code As you drag and drop actions from the **Actions** browser onto the canvas, the visual design experience automatically composes the YAML or JSON content of your runbook in real-time. You can view and edit this code. To view the auto-generated code, select **Code** for the **Design** and **Code** toggle. ## Step 4: Run your new runbook After creating your runbook, you can run the automation. **To run your new automation runbook** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Automation**, and then choose **Execute automation**. 1. In the **Automation document** list, choose a runbook. Choose one or more options in the **Document categories** pane to filter SSM documents according to their purpose. To view a runbook that you own, choose the **Owned by me** tab. To view a runbook that is shared with your account, choose the **Shared with me** tab. To view all runbooks, choose the **All documents** tab. **Note** You can view information about a runbook by choosing the runbook name. 1. In the **Document details** section, verify that **Document version** is set to the version that you want to run. The system includes the following version options: + **Default version at runtime** – Choose this option if the Automation runbook is updated periodically and a new default version is assigned. + **Latest version at runtime** – Choose this option if the Automation runbook is updated periodically, and you want to run the version that was most recently updated. + **1 (Default)** – Choose this option to run the first version of the document, which is the default. 1. Choose **Next**. 1. In the **Execute automation runbook** section, choose **Simple execution**. 1. In the **Input parameters** section, specify the required inputs. Optionally, you can choose an IAM service role from the **AutomationAssumeRole** list. 1. (Optional) Choose an Amazon CloudWatch alarm to apply to your automation for monitoring. To attach a CloudWatch alarm to your automation, the IAM principal that starts the automation must have permission for the `iam:createServiceLinkedRole` action. For more information about CloudWatch alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). If your alarm activates, the automation is stopped. If you use AWS CloudTrail, you will see the API call in your trail. 1. Choose **Execute**. ## Step 5: Clean up **To delete your runbook** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Documents**. 1. Select the **Owned by me** tab. 1. Locate the **VisualDesignExperienceTutorial** runbook. 1. Select the button on the document card page, and then choose **Delete document** from the **Actions** dropdown. # Authoring Automation runbooks Each runbook in Automation, a tool in AWS Systems Manager, defines an automation. Automation runbooks define the actions that are performed during an automation. In the runbook content, you define the input parameters, outputs, and actions that Systems Manager performs on your managed instances and AWS resources. Automation includes several pre-defined runbooks 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). However, your use cases might extend beyond the capabilities of the pre-defined runbooks. If this is the case, you can create your own runbooks and modify them to your needs. A runbook consists of automation actions, parameters for those actions, and input parameters that you specify. A runbook's content is written in either YAML or JSON. If you're not familiar with either YAML or JSON, we recommend using the visual designer, or learning more about either markup language before attempting to author your own runbook. For more information about the visual designer, see [Visual design experience for Automation runbooks](automation-visual-designer.md). The following sections will help you author your first runbook. ## Identify your use case The first step in authoring a runbook is identifying your use case. For example, you scheduled the `AWS-CreateImage` runbook to run daily on all of your production Amazon EC2 instances. At the end of the month, you decide you have more images than are necessary for recovery points. Going forward, you want to automatically delete the oldest AMI of an Amazon EC2 instance when a new AMI is created. To accomplish this, you create a new runbook that does the following: 1. Runs the `aws:createImage` action and specifies the instance ID in the image description. 1. Runs the `aws:waitForAwsResourceProperty` action to poll the state of the image until it's `available`. 1. After the image state is `available`, the `aws:executeScript` action runs a custom Python script that gathers the IDs of all images associated with your Amazon EC2 instance. The script does this by filtering, using the instance ID in the image description you specified at creation. Then, the script sorts the list of image IDs based on the `creationDate` of the image and outputs the ID of the oldest AMI. 1. Lastly, the `aws:deleteImage` action runs to delete the oldest AMI using the ID from the output of the previous step. In this scenario, you were already using the `AWS-CreateImage` runbook but found that your use case required greater flexibility. This is a common situation because there can be overlap between runbooks and automation actions. As a result, you might have to adjust which runbooks or actions you use to address your use case. For example, the `aws:executeScript` and `aws:invokeLambdaFunction` actions both allow you to run custom scripts as part of your automation. To choose between them, you might prefer `aws:invokeLambdaFunction` because of the additional supported runtime languages. However, you might prefer `aws:executeScript` because it allows you to author your script content directly in YAML runbooks and provide script content as attachments for JSON runbooks. You might also consider `aws:executeScript` to be simpler in terms of AWS Identity and Access Management (IAM) setup. Because it uses the permissions provided in the `AutomationAssumeRole`, `aws:executeScript` doesn't require an additional AWS Lambda function execution role. In any given scenario, one action might provide more flexibility, or added functionality, over another. Therefore, we recommend that you review the available input parameters for the runbook or action you want to use to determine which best fits your use case and preferences. ## Set up your development environment After you've identified your use case and the pre-defined runbooks or automation actions you want to use in your runbook, it's time to set up your development environment for the content of your runbook. To develop your runbook content, we recommend using the AWS Toolkit for Visual Studio Code instead of the Systems Manager Documents console. The Toolkit for VS Code is an open-source extension for Visual Studio Code (VS Code) that offers more features than the Systems Manager Documents console. Helpful features include schema validation for both YAML and JSON, snippets for automation action types, and auto-complete support for various options in both YAML and JSON. For more information about installing the Toolkit for VS Code, see [Installing the AWS Toolkit for Visual Studio Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/setup-toolkit.html). For more information about using the Toolkit for VS Code to develop runbooks, see [Working with Systems Manager Automation documents](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/systems-manager-automation-docs.html) in the *AWS Toolkit for Visual Studio Code User Guide*. ## Develop runbook content With your use case identified and environment set up, you're ready to develop the content for your runbook. Your use case and preferences will largely dictate the automation actions or runbooks you use in your runbook content. Some actions support only a subset of input parameters when compared to another action that allows you to accomplish a similar task. Other actions have specific outputs, such as `aws:createImage`, where some actions allow you to define your own outputs, such as `aws:executeAwsApi`. If you're unsure how to use a particular action in your runbook, we recommend reviewing the corresponding entry for the action in the [Systems Manager Automation actions reference](automation-actions.md). We also recommend reviewing the content of pre-defined runbooks to see real-world examples of how these actions are used. For more examples of real-world applications of runbooks, see [Additional runbook examples](automation-document-examples.md). To demonstrate the differences in simplicity and flexibility that runbook content provides, the following tutorials provide an example of how to patch groups of Amazon EC2 instances in stages: + [Example 1: Creating parent-child runbooks](automation-authoring-runbooks-parent-child-example.md) – In this example, two runbooks are used in a parent-child relationship. The parent runbook initiates a rate control automation of the child runbook. + [Example 2: Scripted runbook](automation-authoring-runbooks-scripted-example.md) – This example demonstrates how you can accomplish the same tasks of Example 1 by condensing the content into a single runbook and using scripts in your runbook. # Example 1: Creating parent-child runbooks The following example demonstrates how to create two runbooks that patch tagged groups of Amazon Elastic Compute Cloud (Amazon EC2) instances in stages. These runbooks are used in a parent-child relationship with the parent runbook used to initiate a rate control automation of the child runbook. For more information about rate control automations, see [Run automated operations at scale](running-automations-scale.md). For more information about the automation actions used in this example, see the [Systems Manager Automation actions reference](automation-actions.md). ## Create the child runbook This example runbook addresses the following scenario. Emily is a Systems Engineer at AnyCompany Consultants, LLC. She needs to configure patching for groups of Amazon Elastic Compute Cloud (Amazon EC2) instances that host primary and secondary databases. Applications access these databases 24 hours a day, so one of the database instances must always be available. She decides that patching the instances in stages is the best approach. The primary group of database instances will be patched first, followed by the secondary group of database instances. Also, to avoid incurring additional costs by leaving instances running that were previously stopped, Emily wants the patched instances to be returned to their original state before the patching occurred. Emily identifies the primary and secondary groups of database instances by the tags associated with the instances. She decides to create a parent runbook that starts a rate control automation of a child runbook. By doing that, she can target the tags associated with the primary and secondary groups of database instances and manage the concurrency of the child automations. After reviewing the available Systems Manager (SSM) documents for patching, she chooses the `AWS-RunPatchBaseline` document. By using this SSM document, her colleagues can review the associated patch compliance information after the patching operation completes. To start creating her runbook content, Emily reviews the available automation actions and begins authoring the content for the child runbook as follows: 1. First, she provides values for the schema and description of the runbook, and defines the input parameters for the child runbook. By using the `AutomationAssumeRole` parameter, Emily and her colleagues can use an existing IAM role that allows Automation to perform the actions in the runbook on their behalf. Emily uses the `InstanceId` parameter to determine the instance that should be patched. Optionally, the `Operation`, `RebootOption`, and `SnapshotId` parameters can be used to provide values to document parameters for `AWS-RunPatchBaseline`. To prevent invalid values from being provided to those document parameters, she defines the `allowedValues` as needed. ------ #### [ YAML ] ``` schemaVersion: '0.3' description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: >- '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' default: '' InstanceId: type: String description: >- '(Required) The instance you want to patch.' SnapshotId: type: String description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.' default: '' RebootOption: type: String description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.' allowedValues: - NoReboot - RebootIfNeeded default: RebootIfNeeded Operation: type: String description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.' allowedValues: - Install - Scan default: Install ``` ------ #### [ JSON ] ``` { "schemaVersion":"0.3", "description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.", "assumeRole":"{{AutomationAssumeRole}}", "parameters":{ "AutomationAssumeRole":{ "type":"String", "description":"(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.", "default":"" }, "InstanceId":{ "type":"String", "description":"(Required) The instance you want to patch." }, "SnapshotId":{ "type":"String", "description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.", "default":"" }, "RebootOption":{ "type":"String", "description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.", "allowedValues":[ "NoReboot", "RebootIfNeeded" ], "default":"RebootIfNeeded" }, "Operation":{ "type":"String", "description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.", "allowedValues":[ "Install", "Scan" ], "default":"Install" } } }, ``` ------ 1. With the top-level elements defined, Emily proceeds with authoring the actions that make up the `mainSteps` of the runbook. The first step outputs the current state of the target instance specified in the `InstanceId` input parameter using the `aws:executeAwsApi` action. The output of this action is used in later actions. ------ #### [ YAML ] ``` mainSteps: - name: getInstanceState action: 'aws:executeAwsApi' onFailure: Abort inputs: inputs: Service: ec2 Api: DescribeInstances InstanceIds: - '{{InstanceId}}' outputs: - Name: instanceState Selector: '$.Reservations[0].Instances[0].State.Name' Type: String nextStep: branchOnInstanceState ``` ------ #### [ JSON ] ``` "mainSteps":[ { "name":"getInstanceState", "action":"aws:executeAwsApi", "onFailure":"Abort", "inputs":{ "inputs":null, "Service":"ec2", "Api":"DescribeInstances", "InstanceIds":[ "{{InstanceId}}" ] }, "outputs":[ { "Name":"instanceState", "Selector":"$.Reservations[0].Instances[0].State.Name", "Type":"String" } ], "nextStep":"branchOnInstanceState" }, ``` ------ 1. Rather than manually starting and keeping track of the original state of every instance that needs to be patched, Emily uses the output from the previous action to branch the automation based on the state of the target instance. This allows the automation to run different steps depending on the conditions defined in the `aws:branch` action and improves the overall efficiency of the automation without manual intervention. If the instance state is already `running`, the automation proceeds with patching the instance with the `AWS-RunPatchBaseline` document using the `aws:runCommand` action. If the instance state is `stopping`, the automation polls for the instance to reach the `stopped` state using the `aws:waitForAwsResourceProperty` action, starts the instance using the `executeAwsApi` action, and polls for the instance to reach a `running` state before patching the instance. If the instance state is `stopped`, the automation starts the instance and polls for the instance to reach a `running` state before patching the instance using the same actions. ------ #### [ YAML ] ``` - name: branchOnInstanceState action: 'aws:branch' onFailure: Abort inputs: Choices: - NextStep: startInstance Variable: '{{getInstanceState.instanceState}}' StringEquals: stopped - NextStep: verifyInstanceStopped Variable: '{{getInstanceState.instanceState}}' StringEquals: stopping - NextStep: patchInstance Variable: '{{getInstanceState.instanceState}}' StringEquals: running isEnd: true - name: startInstance action: 'aws:executeAwsApi' onFailure: Abort inputs: Service: ec2 Api: StartInstances InstanceIds: - '{{InstanceId}}' nextStep: verifyInstanceRunning - name: verifyInstanceRunning action: 'aws:waitForAwsResourceProperty' timeoutSeconds: 120 inputs: Service: ec2 Api: DescribeInstances InstanceIds: - '{{InstanceId}}' PropertySelector: '$.Reservations[0].Instances[0].State.Name' DesiredValues: - running nextStep: patchInstance - name: verifyInstanceStopped action: 'aws:waitForAwsResourceProperty' timeoutSeconds: 120 inputs: Service: ec2 Api: DescribeInstances InstanceIds: - '{{InstanceId}}' PropertySelector: '$.Reservations[0].Instances[0].State.Name' DesiredValues: - stopped nextStep: startInstance - name: patchInstance action: 'aws:runCommand' onFailure: Abort timeoutSeconds: 5400 inputs: DocumentName: 'AWS-RunPatchBaseline' InstanceIds: - '{{InstanceId}}' Parameters: SnapshotId: '{{SnapshotId}}' RebootOption: '{{RebootOption}}' Operation: '{{Operation}}' ``` ------ #### [ JSON ] ``` { "name":"branchOnInstanceState", "action":"aws:branch", "onFailure":"Abort", "inputs":{ "Choices":[ { "NextStep":"startInstance", "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"stopped" }, { "Or":[ { "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"stopping" } ], "NextStep":"verifyInstanceStopped" }, { "NextStep":"patchInstance", "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"running" } ] }, "isEnd":true }, { "name":"startInstance", "action":"aws:executeAwsApi", "onFailure":"Abort", "inputs":{ "Service":"ec2", "Api":"StartInstances", "InstanceIds":[ "{{InstanceId}}" ] }, "nextStep":"verifyInstanceRunning" }, { "name":"verifyInstanceRunning", "action":"aws:waitForAwsResourceProperty", "timeoutSeconds":120, "inputs":{ "Service":"ec2", "Api":"DescribeInstances", "InstanceIds":[ "{{InstanceId}}" ], "PropertySelector":"$.Reservations[0].Instances[0].State.Name", "DesiredValues":[ "running" ] }, "nextStep":"patchInstance" }, { "name":"verifyInstanceStopped", "action":"aws:waitForAwsResourceProperty", "timeoutSeconds":120, "inputs":{ "Service":"ec2", "Api":"DescribeInstances", "InstanceIds":[ "{{InstanceId}}" ], "PropertySelector":"$.Reservations[0].Instances[0].State.Name", "DesiredValues":[ "stopped" ], "nextStep":"startInstance" } }, { "name":"patchInstance", "action":"aws:runCommand", "onFailure":"Abort", "timeoutSeconds":5400, "inputs":{ "DocumentName":"AWS-RunPatchBaseline", "InstanceIds":[ "{{InstanceId}}" ], "Parameters":{ "SnapshotId":"{{SnapshotId}}", "RebootOption":"{{RebootOption}}", "Operation":"{{Operation}}" } } }, ``` ------ 1. After the patching operation completes, Emily wants the automation to return the target instance to the same state it was in before the automation started. She does this by again using the output from the first action. The automation branches based on the original state of the target instance using the `aws:branch` action. If the instance was previously in any state other than `running`, the instance is stopped. Otherwise, if the instance state is `running`, the automation ends. ------ #### [ YAML ] ``` - name: branchOnOriginalInstanceState action: 'aws:branch' onFailure: Abort inputs: Choices: - NextStep: stopInstance Not: Variable: '{{getInstanceState.instanceState}}' StringEquals: running isEnd: true - name: stopInstance action: 'aws:executeAwsApi' onFailure: Abort inputs: Service: ec2 Api: StopInstances InstanceIds: - '{{InstanceId}}' ``` ------ #### [ JSON ] ``` { "name":"branchOnOriginalInstanceState", "action":"aws:branch", "onFailure":"Abort", "inputs":{ "Choices":[ { "NextStep":"stopInstance", "Not":{ "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"running" } } ] }, "isEnd":true }, { "name":"stopInstance", "action":"aws:executeAwsApi", "onFailure":"Abort", "inputs":{ "Service":"ec2", "Api":"StopInstances", "InstanceIds":[ "{{InstanceId}}" ] } } ] } ``` ------ 1. Emily reviews the completed child runbook content and creates the runbook in the same AWS account and AWS Region as the target instances. Now she's ready to continue with the creation of the parent runbook's content. The following is the completed child runbook content. ------ #### [ YAML ] ``` schemaVersion: '0.3' description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: >- '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' default: '' InstanceId: type: String description: >- '(Required) The instance you want to patch.' SnapshotId: type: String description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.' default: '' RebootOption: type: String description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.' allowedValues: - NoReboot - RebootIfNeeded default: RebootIfNeeded Operation: type: String description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.' allowedValues: - Install - Scan default: Install mainSteps: - name: getInstanceState action: 'aws:executeAwsApi' onFailure: Abort inputs: inputs: Service: ec2 Api: DescribeInstances InstanceIds: - '{{InstanceId}}' outputs: - Name: instanceState Selector: '$.Reservations[0].Instances[0].State.Name' Type: String nextStep: branchOnInstanceState - name: branchOnInstanceState action: 'aws:branch' onFailure: Abort inputs: Choices: - NextStep: startInstance Variable: '{{getInstanceState.instanceState}}' StringEquals: stopped - Or: - Variable: '{{getInstanceState.instanceState}}' StringEquals: stopping NextStep: verifyInstanceStopped - NextStep: patchInstance Variable: '{{getInstanceState.instanceState}}' StringEquals: running isEnd: true - name: startInstance action: 'aws:executeAwsApi' onFailure: Abort inputs: Service: ec2 Api: StartInstances InstanceIds: - '{{InstanceId}}' nextStep: verifyInstanceRunning - name: verifyInstanceRunning action: 'aws:waitForAwsResourceProperty' timeoutSeconds: 120 inputs: Service: ec2 Api: DescribeInstances InstanceIds: - '{{InstanceId}}' PropertySelector: '$.Reservations[0].Instances[0].State.Name' DesiredValues: - running nextStep: patchInstance - name: verifyInstanceStopped action: 'aws:waitForAwsResourceProperty' timeoutSeconds: 120 inputs: Service: ec2 Api: DescribeInstances InstanceIds: - '{{InstanceId}}' PropertySelector: '$.Reservations[0].Instances[0].State.Name' DesiredValues: - stopped nextStep: startInstance - name: patchInstance action: 'aws:runCommand' onFailure: Abort timeoutSeconds: 5400 inputs: DocumentName: 'AWS-RunPatchBaseline' InstanceIds: - '{{InstanceId}}' Parameters: SnapshotId: '{{SnapshotId}}' RebootOption: '{{RebootOption}}' Operation: '{{Operation}}' - name: branchOnOriginalInstanceState action: 'aws:branch' onFailure: Abort inputs: Choices: - NextStep: stopInstance Not: Variable: '{{getInstanceState.instanceState}}' StringEquals: running isEnd: true - name: stopInstance action: 'aws:executeAwsApi' onFailure: Abort inputs: Service: ec2 Api: StopInstances InstanceIds: - '{{InstanceId}}' ``` ------ #### [ JSON ] ``` { "schemaVersion":"0.3", "description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.", "assumeRole":"{{AutomationAssumeRole}}", "parameters":{ "AutomationAssumeRole":{ "type":"String", "description":"'(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.'", "default":"" }, "InstanceId":{ "type":"String", "description":"'(Required) The instance you want to patch.'" }, "SnapshotId":{ "type":"String", "description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.", "default":"" }, "RebootOption":{ "type":"String", "description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.", "allowedValues":[ "NoReboot", "RebootIfNeeded" ], "default":"RebootIfNeeded" }, "Operation":{ "type":"String", "description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.", "allowedValues":[ "Install", "Scan" ], "default":"Install" } }, "mainSteps":[ { "name":"getInstanceState", "action":"aws:executeAwsApi", "onFailure":"Abort", "inputs":{ "inputs":null, "Service":"ec2", "Api":"DescribeInstances", "InstanceIds":[ "{{InstanceId}}" ] }, "outputs":[ { "Name":"instanceState", "Selector":"$.Reservations[0].Instances[0].State.Name", "Type":"String" } ], "nextStep":"branchOnInstanceState" }, { "name":"branchOnInstanceState", "action":"aws:branch", "onFailure":"Abort", "inputs":{ "Choices":[ { "NextStep":"startInstance", "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"stopped" }, { "Or":[ { "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"stopping" } ], "NextStep":"verifyInstanceStopped" }, { "NextStep":"patchInstance", "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"running" } ] }, "isEnd":true }, { "name":"startInstance", "action":"aws:executeAwsApi", "onFailure":"Abort", "inputs":{ "Service":"ec2", "Api":"StartInstances", "InstanceIds":[ "{{InstanceId}}" ] }, "nextStep":"verifyInstanceRunning" }, { "name":"verifyInstanceRunning", "action":"aws:waitForAwsResourceProperty", "timeoutSeconds":120, "inputs":{ "Service":"ec2", "Api":"DescribeInstances", "InstanceIds":[ "{{InstanceId}}" ], "PropertySelector":"$.Reservations[0].Instances[0].State.Name", "DesiredValues":[ "running" ] }, "nextStep":"patchInstance" }, { "name":"verifyInstanceStopped", "action":"aws:waitForAwsResourceProperty", "timeoutSeconds":120, "inputs":{ "Service":"ec2", "Api":"DescribeInstances", "InstanceIds":[ "{{InstanceId}}" ], "PropertySelector":"$.Reservations[0].Instances[0].State.Name", "DesiredValues":[ "stopped" ], "nextStep":"startInstance" } }, { "name":"patchInstance", "action":"aws:runCommand", "onFailure":"Abort", "timeoutSeconds":5400, "inputs":{ "DocumentName":"AWS-RunPatchBaseline", "InstanceIds":[ "{{InstanceId}}" ], "Parameters":{ "SnapshotId":"{{SnapshotId}}", "RebootOption":"{{RebootOption}}", "Operation":"{{Operation}}" } } }, { "name":"branchOnOriginalInstanceState", "action":"aws:branch", "onFailure":"Abort", "inputs":{ "Choices":[ { "NextStep":"stopInstance", "Not":{ "Variable":"{{getInstanceState.instanceState}}", "StringEquals":"running" } } ] }, "isEnd":true }, { "name":"stopInstance", "action":"aws:executeAwsApi", "onFailure":"Abort", "inputs":{ "Service":"ec2", "Api":"StopInstances", "InstanceIds":[ "{{InstanceId}}" ] } } ] } ``` ------ For more information about the automation actions used in this example, see the [Systems Manager Automation actions reference](automation-actions.md). ## Create the parent runbook This example runbook continues the scenario described in the previous section. Now that Emily has created the child runbook, she begins authoring the content for the parent runbook as follows: 1. First, she provides values for the schema and description of the runbook, and defines the input parameters for the parent runbook. By using the `AutomationAssumeRole` parameter, Emily and her colleagues can use an existing IAM role that allows Automation to perform the actions in the runbook on their behalf. Emily uses the `PatchGroupPrimaryKey` and `PatchGroupPrimaryValue` parameters to specify the tag associated with the primary group of database instances that will be patched. She uses the `PatchGroupSecondaryKey` and `PatchGroupSecondaryValue` parameters to specify the tag associated with the secondary group of database instances that will be patched. ------ #### [ YAML ] ``` description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.' schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' default: '' PatchGroupPrimaryKey: type: String description: '(Required) The key of the tag for the primary group of instances you want to patch.'' PatchGroupPrimaryValue: type: String description: '(Required) The value of the tag for the primary group of instances you want to patch.' PatchGroupSecondaryKey: type: String description: '(Required) The key of the tag for the secondary group of instances you want to patch.' PatchGroupSecondaryValue: type: String description: '(Required) The value of the tag for the secondary group of instances you want to patch.' ``` ------ #### [ JSON ] ``` { "schemaVersion": "0.3", "description": "An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.", "assumeRole": "{{AutomationAssumeRole}}", "parameters": { "AutomationAssumeRole": { "type": "String", "description": "(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.", "default": "" }, "PatchGroupPrimaryKey": { "type": "String", "description": "(Required) The key of the tag for the primary group of instances you want to patch." }, "PatchGroupPrimaryValue": { "type": "String", "description": "(Required) The value of the tag for the primary group of instances you want to patch." }, "PatchGroupSecondaryKey": { "type": "String", "description": "(Required) The key of the tag for the secondary group of instances you want to patch." }, "PatchGroupSecondaryValue": { "type": "String", "description": "(Required) The value of the tag for the secondary group of instances you want to patch." } } }, ``` ------ 1. With the top-level elements defined, Emily proceeds with authoring the actions that make up the `mainSteps` of the runbook. The first action starts a rate control automation using the child runbook she just created that targets instances associated with the tag specified in the `PatchGroupPrimaryKey` and `PatchGroupPrimaryValue` input parameters. She uses the values provided to the input parameters to specify the key and value of the tag associated with the primary group of database instances she wants to patch. After the first automation completes, the second action starts another rate control automation using the child runbook that targets instances associated with the tag specified in the `PatchGroupSecondaryKey` and `PatchGroupSecondaryValue` input parameters. She uses the values provided to the input parameters to specify the key and value of the tag associated with the secondary group of database instances she wants to patch. ------ #### [ YAML ] ``` mainSteps: - name: patchPrimaryTargets action: 'aws:executeAutomation' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: RunbookTutorialChildAutomation Targets: - Key: 'tag:{{PatchGroupPrimaryKey}}' Values: - '{{PatchGroupPrimaryValue}}' TargetParameterName: 'InstanceId' - name: patchSecondaryTargets action: 'aws:executeAutomation' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: RunbookTutorialChildAutomation Targets: - Key: 'tag:{{PatchGroupSecondaryKey}}' Values: - '{{PatchGroupSecondaryValue}}' TargetParameterName: 'InstanceId' ``` ------ #### [ JSON ] ``` "mainSteps":[ { "name":"patchPrimaryTargets", "action":"aws:executeAutomation", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"RunbookTutorialChildAutomation", "Targets":[ { "Key":"tag:{{PatchGroupPrimaryKey}}", "Values":[ "{{PatchGroupPrimaryValue}}" ] } ], "TargetParameterName":"InstanceId" } }, { "name":"patchSecondaryTargets", "action":"aws:executeAutomation", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"RunbookTutorialChildAutomation", "Targets":[ { "Key":"tag:{{PatchGroupSecondaryKey}}", "Values":[ "{{PatchGroupSecondaryValue}}" ] } ], "TargetParameterName":"InstanceId" } } ] } ``` ------ 1. Emily reviews the completed parent runbook content and creates the runbook in the same AWS account and AWS Region as the target instances. Now, she is ready to test her runbooks to make sure the automation operates as desired before implementing them into her production environment. The following is the completed parent runbook content. ------ #### [ YAML ] ``` description: An example of an Automation runbook that patches groups of Amazon EC2 instances in stages. schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: '(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' default: '' PatchGroupPrimaryKey: type: String description: (Required) The key of the tag for the primary group of instances you want to patch. PatchGroupPrimaryValue: type: String description: '(Required) The value of the tag for the primary group of instances you want to patch. ' PatchGroupSecondaryKey: type: String description: (Required) The key of the tag for the secondary group of instances you want to patch. PatchGroupSecondaryValue: type: String description: '(Required) The value of the tag for the secondary group of instances you want to patch. ' mainSteps: - name: patchPrimaryTargets action: 'aws:executeAutomation' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: RunbookTutorialChildAutomation Targets: - Key: 'tag:{{PatchGroupPrimaryKey}}' Values: - '{{PatchGroupPrimaryValue}}' TargetParameterName: 'InstanceId' - name: patchSecondaryTargets action: 'aws:executeAutomation' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: RunbookTutorialChildAutomation Targets: - Key: 'tag:{{PatchGroupSecondaryKey}}' Values: - '{{PatchGroupSecondaryValue}}' TargetParameterName: 'InstanceId' ``` ------ #### [ JSON ] ``` { "description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.", "schemaVersion":"0.3", "assumeRole":"{{AutomationAssumeRole}}", "parameters":{ "AutomationAssumeRole":{ "type":"String", "description":"(Optional) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.", "default":"" }, "PatchGroupPrimaryKey":{ "type":"String", "description":"(Required) The key of the tag for the primary group of instances you want to patch." }, "PatchGroupPrimaryValue":{ "type":"String", "description":"(Required) The value of the tag for the primary group of instances you want to patch. " }, "PatchGroupSecondaryKey":{ "type":"String", "description":"(Required) The key of the tag for the secondary group of instances you want to patch." }, "PatchGroupSecondaryValue":{ "type":"String", "description":"(Required) The value of the tag for the secondary group of instances you want to patch. " } }, "mainSteps":[ { "name":"patchPrimaryTargets", "action":"aws:executeAutomation", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"RunbookTutorialChildAutomation", "Targets":[ { "Key":"tag:{{PatchGroupPrimaryKey}}", "Values":[ "{{PatchGroupPrimaryValue}}" ] } ], "TargetParameterName":"InstanceId" } }, { "name":"patchSecondaryTargets", "action":"aws:executeAutomation", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"RunbookTutorialChildAutomation", "Targets":[ { "Key":"tag:{{PatchGroupSecondaryKey}}", "Values":[ "{{PatchGroupSecondaryValue}}" ] } ], "TargetParameterName":"InstanceId" } } ] } ``` ------ For more information about the automation actions used in this example, see the [Systems Manager Automation actions reference](automation-actions.md). # Example 2: Scripted runbook This example runbook addresses the following scenario. Emily is a Systems Engineer at AnyCompany Consultants, LLC. She previously created two runbooks that are used in a parent-child relationship to patch groups of Amazon Elastic Compute Cloud (Amazon EC2) instances that host primary and secondary databases. Applications access these databases 24 hours a day, so one of the database instances must always be available. Based on this requirement, she built a solution that patches the instances in stages using the `AWS-RunPatchBaseline` Systems Manager (SSM) document. By using this SSM document, her colleagues can review the associated patch compliance information after the patching operation completes. The primary group of database instances are patched first, followed by the secondary group of database instances. Also, to avoid incurring additional costs by leaving instances running that were previously stopped, Emily made sure that the automation returned the patched instances to their original state before the patching occurred. Emily used tags that are associated with the primary and secondary groups of database instances to identify which instances should be patched in her desired order. Her existing automated solution works, but she wants to improve her solution if possible. To help with the maintenance of the runbook content and to ease troubleshooting efforts, she would like to condense the automation into a single runbook and simplify the number of input parameters. Also, she would like to avoid creating multiple child automations. After Emily reviews the available automation actions, she determines that she can improve her solution by using the `aws:executeScript` action to run her custom Python scripts. She now begins authoring the content for the runbook as follows: 1. First, she provides values for the schema and description of the runbook, and defines the input parameters for the parent runbook. By using the `AutomationAssumeRole` parameter, Emily and her colleagues can use an existing IAM role that allows Automation to perform the actions in the runbook on their behalf. Unlike [Example 1](automation-authoring-runbooks-parent-child-example.md), the `AutomationAssumeRole` parameter is now required rather than optional. Because this runbook includes `aws:executeScript` actions, an AWS Identity and Access Management (IAM) service role (or assume role) is always required. This requirement is necessary because some of the Python scripts specified for the actions call AWS API operations. Emily uses the `PrimaryPatchGroupTag` and `SecondaryPatchGroupTag` parameters to specify the tags associated with the primary and secondary group of database instances that will be patched. To simplify the required input parameters, she decides to use `StringMap` parameters rather than using multiple `String` parameters as she used in the Example 1 runbook. Optionally, the `Operation`, `RebootOption`, and `SnapshotId` parameters can be used to provide values to document parameters for `AWS-RunPatchBaseline`. To prevent invalid values from being provided to those document parameters, she defines the `allowedValues` as needed. ------ #### [ YAML ] ``` description: 'An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.' schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' PrimaryPatchGroupTag: type: StringMap description: '(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}' SecondaryPatchGroupTag: type: StringMap description: '(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}' SnapshotId: type: String description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.' default: '' RebootOption: type: String description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.' allowedValues: - NoReboot - RebootIfNeeded default: RebootIfNeeded Operation: type: String description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.' allowedValues: - Install - Scan default: Install ``` ------ #### [ JSON ] ``` { "description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.", "schemaVersion":"0.3", "assumeRole":"{{AutomationAssumeRole}}", "parameters":{ "AutomationAssumeRole":{ "type":"String", "description":"(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook." }, "PrimaryPatchGroupTag":{ "type":"StringMap", "description":"(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}" }, "SecondaryPatchGroupTag":{ "type":"StringMap", "description":"(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}" }, "SnapshotId":{ "type":"String", "description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.", "default":"" }, "RebootOption":{ "type":"String", "description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.", "allowedValues":[ "NoReboot", "RebootIfNeeded" ], "default":"RebootIfNeeded" }, "Operation":{ "type":"String", "description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.", "allowedValues":[ "Install", "Scan" ], "default":"Install" } } }, ``` ------ 1. With the top-level elements defined, Emily proceeds with authoring the actions that make up the `mainSteps` of the runbook. The first step gathers the IDs of all instances associated with the tag specified in the `PrimaryPatchGroupTag` parameter and outputs a `StringMap` parameter containing the instance ID and the current state of the instance. The output of this action is used in later actions. Note that the `script` input parameter isn't supported for JSON runbooks. JSON runbooks must provide script content using the `attachment` input parameter. ------ #### [ YAML ] ``` mainSteps: - name: getPrimaryInstanceState action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: getInstanceStates InputPayload: primaryTag: '{{PrimaryPatchGroupTag}}' Script: |- def getInstanceStates(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') tag = events['primaryTag'] tagKey, tagValue = list(tag.items())[0] instanceQuery = ec2.describe_instances( Filters=[ { "Name": "tag:" + tagKey, "Values": [tagValue] }] ) if not instanceQuery['Reservations']: noInstancesForTagString = "No instances found for specified tag." return({ 'noInstancesFound' : noInstancesForTagString }) else: queryResponse = instanceQuery['Reservations'] originalInstanceStates = {} for results in queryResponse: instanceSet = results['Instances'] for instance in instanceSet: instanceId = instance['InstanceId'] originalInstanceStates[instanceId] = instance['State']['Name'] return originalInstanceStates outputs: - Name: originalInstanceStates Selector: $.Payload Type: StringMap nextStep: verifyPrimaryInstancesRunning ``` ------ #### [ JSON ] ``` "mainSteps":[ { "name":"getPrimaryInstanceState", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"getInstanceStates", "InputPayload":{ "primaryTag":"{{PrimaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"originalInstanceStates", "Selector":"$.Payload", "Type":"StringMap" } ], "nextStep":"verifyPrimaryInstancesRunning" }, ``` ------ 1. Emily uses the output from the previous action in another `aws:executeScript` action to verify all instances associated with the tag specified in the `PrimaryPatchGroupTag` parameter are in a `running` state. If the instance state is already `running` or `shutting-down`, the script continues to loop through the remaining instances. If the instance state is `stopping`, the script polls for the instance to reach the `stopped` state and starts the instance. If the instance state is `stopped`, the script starts the instance. ------ #### [ YAML ] ``` - name: verifyPrimaryInstancesRunning action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: verifyInstancesRunning InputPayload: targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}' Script: |- def verifyInstancesRunning(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped': print("The target instance " + instance + " is stopped. The instance will now be started.") ec2.start_instances( InstanceIds=[instance] ) elif instanceDict[instance] == 'stopping': print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.") while instanceDict[instance] != 'stopped': poll = ec2.get_waiter('instance_stopped') poll.wait( InstanceIds=[instance] ) ec2.start_instances( InstanceIds=[instance] ) else: pass nextStep: waitForPrimaryRunningInstances ``` ------ #### [ JSON ] ``` { "name":"verifyPrimaryInstancesRunning", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"verifyInstancesRunning", "InputPayload":{ "targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"waitForPrimaryRunningInstances" }, ``` ------ 1. Emily verifies that all instances associated with the tag specified in the `PrimaryPatchGroupTag` parameter were started or already in a `running` state. Then she uses another script to verify that all instances, including those that were started in the previous action, have reached the `running` state. ------ #### [ YAML ] ``` - name: waitForPrimaryRunningInstances action: 'aws:executeScript' timeoutSeconds: 300 onFailure: Abort inputs: Runtime: python3.11 Handler: waitForRunningInstances InputPayload: targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}' Script: |- def waitForRunningInstances(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: poll = ec2.get_waiter('instance_running') poll.wait( InstanceIds=[instance] ) nextStep: returnPrimaryTagKey ``` ------ #### [ JSON ] ``` { "name":"waitForPrimaryRunningInstances", "action":"aws:executeScript", "timeoutSeconds":300, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"waitForRunningInstances", "InputPayload":{ "targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"returnPrimaryTagKey" }, ``` ------ 1. Emily uses two more scripts to return individual `String` values of the key and value of the tag specified in the `PrimaryPatchGroupTag` parameter. The values returned by these actions allows her to provide values directly to the `Targets` parameter for the `AWS-RunPatchBaseline` document. The automation then proceeds with patching the instance with the `AWS-RunPatchBaseline` document using the `aws:runCommand` action. ------ #### [ YAML ] ``` - name: returnPrimaryTagKey action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: primaryTag: '{{PrimaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['primaryTag'] tagKey = list(tag)[0] stringKey = "tag:" + tagKey return {'tagKey' : stringKey} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: primaryPatchGroupKey Selector: $.Payload.tagKey Type: String nextStep: returnPrimaryTagValue - name: returnPrimaryTagValue action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: primaryTag: '{{PrimaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['primaryTag'] tagKey = list(tag)[0] tagValue = tag[tagKey] return {'tagValue' : tagValue} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: primaryPatchGroupValue Selector: $.Payload.tagValue Type: String nextStep: patchPrimaryInstances - name: patchPrimaryInstances action: 'aws:runCommand' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: AWS-RunPatchBaseline Parameters: SnapshotId: '{{SnapshotId}}' RebootOption: '{{RebootOption}}' Operation: '{{Operation}}' Targets: - Key: '{{returnPrimaryTagKey.primaryPatchGroupKey}}' Values: - '{{returnPrimaryTagValue.primaryPatchGroupValue}}' MaxConcurrency: 10% MaxErrors: 10% nextStep: returnPrimaryToOriginalState ``` ------ #### [ JSON ] ``` { "name":"returnPrimaryTagKey", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "primaryTag":"{{PrimaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"primaryPatchGroupKey", "Selector":"$.Payload.tagKey", "Type":"String" } ], "nextStep":"returnPrimaryTagValue" }, { "name":"returnPrimaryTagValue", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "primaryTag":"{{PrimaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"primaryPatchGroupValue", "Selector":"$.Payload.tagValue", "Type":"String" } ], "nextStep":"patchPrimaryInstances" }, { "name":"patchPrimaryInstances", "action":"aws:runCommand", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"AWS-RunPatchBaseline", "Parameters":{ "SnapshotId":"{{SnapshotId}}", "RebootOption":"{{RebootOption}}", "Operation":"{{Operation}}" }, "Targets":[ { "Key":"{{returnPrimaryTagKey.primaryPatchGroupKey}}", "Values":[ "{{returnPrimaryTagValue.primaryPatchGroupValue}}" ] } ], "MaxConcurrency":"10%", "MaxErrors":"10%" }, "nextStep":"returnPrimaryToOriginalState" }, ``` ------ 1. After the patching operation completes, Emily wants the automation to return the target instances associated with the tag specified in the `PrimaryPatchGroupTag` parameter to the same state they were before the automation started. She does this by again using the output from the first action in a script. Based on the original state of the target instance, if the instance was previously in any state other than `running`, the instance is stopped. Otherwise, if the instance state is `running`, the script continues to loop through the remaining instances. ------ #### [ YAML ] ``` - name: returnPrimaryToOriginalState action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: returnToOriginalState InputPayload: targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}' Script: |- def returnToOriginalState(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping': ec2.stop_instances( InstanceIds=[instance] ) else: pass nextStep: getSecondaryInstanceState ``` ------ #### [ JSON ] ``` { "name":"returnPrimaryToOriginalState", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnToOriginalState", "InputPayload":{ "targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"getSecondaryInstanceState" }, ``` ------ 1. The patching operation is completed for the instances associated with the tag specified in the `PrimaryPatchGroupTag` parameter. Now Emily duplicates all of the previous actions in her runbook content to target the instances associated with the tag specified in the `SecondaryPatchGroupTag` parameter. ------ #### [ YAML ] ``` - name: getSecondaryInstanceState action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: getInstanceStates InputPayload: secondaryTag: '{{SecondaryPatchGroupTag}}' Script: |- def getInstanceStates(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') tag = events['secondaryTag'] tagKey, tagValue = list(tag.items())[0] instanceQuery = ec2.describe_instances( Filters=[ { "Name": "tag:" + tagKey, "Values": [tagValue] }] ) if not instanceQuery['Reservations']: noInstancesForTagString = "No instances found for specified tag." return({ 'noInstancesFound' : noInstancesForTagString }) else: queryResponse = instanceQuery['Reservations'] originalInstanceStates = {} for results in queryResponse: instanceSet = results['Instances'] for instance in instanceSet: instanceId = instance['InstanceId'] originalInstanceStates[instanceId] = instance['State']['Name'] return originalInstanceStates outputs: - Name: originalInstanceStates Selector: $.Payload Type: StringMap nextStep: verifySecondaryInstancesRunning - name: verifySecondaryInstancesRunning action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: verifyInstancesRunning InputPayload: targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}' Script: |- def verifyInstancesRunning(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped': print("The target instance " + instance + " is stopped. The instance will now be started.") ec2.start_instances( InstanceIds=[instance] ) elif instanceDict[instance] == 'stopping': print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.") while instanceDict[instance] != 'stopped': poll = ec2.get_waiter('instance_stopped') poll.wait( InstanceIds=[instance] ) ec2.start_instances( InstanceIds=[instance] ) else: pass nextStep: waitForSecondaryRunningInstances - name: waitForSecondaryRunningInstances action: 'aws:executeScript' timeoutSeconds: 300 onFailure: Abort inputs: Runtime: python3.11 Handler: waitForRunningInstances InputPayload: targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}' Script: |- def waitForRunningInstances(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: poll = ec2.get_waiter('instance_running') poll.wait( InstanceIds=[instance] ) nextStep: returnSecondaryTagKey - name: returnSecondaryTagKey action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: secondaryTag: '{{SecondaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['secondaryTag'] tagKey = list(tag)[0] stringKey = "tag:" + tagKey return {'tagKey' : stringKey} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: secondaryPatchGroupKey Selector: $.Payload.tagKey Type: String nextStep: returnSecondaryTagValue - name: returnSecondaryTagValue action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: secondaryTag: '{{SecondaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['secondaryTag'] tagKey = list(tag)[0] tagValue = tag[tagKey] return {'tagValue' : tagValue} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: secondaryPatchGroupValue Selector: $.Payload.tagValue Type: String nextStep: patchSecondaryInstances - name: patchSecondaryInstances action: 'aws:runCommand' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: AWS-RunPatchBaseline Parameters: SnapshotId: '{{SnapshotId}}' RebootOption: '{{RebootOption}}' Operation: '{{Operation}}' Targets: - Key: '{{returnSecondaryTagKey.secondaryPatchGroupKey}}' Values: - '{{returnSecondaryTagValue.secondaryPatchGroupValue}}' MaxConcurrency: 10% MaxErrors: 10% nextStep: returnSecondaryToOriginalState - name: returnSecondaryToOriginalState action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: returnToOriginalState InputPayload: targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}' Script: |- def returnToOriginalState(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping': ec2.stop_instances( InstanceIds=[instance] ) else: pass ``` ------ #### [ JSON ] ``` { "name":"getSecondaryInstanceState", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"getInstanceStates", "InputPayload":{ "secondaryTag":"{{SecondaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"originalInstanceStates", "Selector":"$.Payload", "Type":"StringMap" } ], "nextStep":"verifySecondaryInstancesRunning" }, { "name":"verifySecondaryInstancesRunning", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"verifyInstancesRunning", "InputPayload":{ "targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"waitForSecondaryRunningInstances" }, { "name":"waitForSecondaryRunningInstances", "action":"aws:executeScript", "timeoutSeconds":300, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"waitForRunningInstances", "InputPayload":{ "targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"returnSecondaryTagKey" }, { "name":"returnSecondaryTagKey", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "secondaryTag":"{{SecondaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"secondaryPatchGroupKey", "Selector":"$.Payload.tagKey", "Type":"String" } ], "nextStep":"returnSecondaryTagValue" }, { "name":"returnSecondaryTagValue", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "secondaryTag":"{{SecondaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"secondaryPatchGroupValue", "Selector":"$.Payload.tagValue", "Type":"String" } ], "nextStep":"patchSecondaryInstances" }, { "name":"patchSecondaryInstances", "action":"aws:runCommand", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"AWS-RunPatchBaseline", "Parameters":{ "SnapshotId":"{{SnapshotId}}", "RebootOption":"{{RebootOption}}", "Operation":"{{Operation}}" }, "Targets":[ { "Key":"{{returnSecondaryTagKey.secondaryPatchGroupKey}}", "Values":[ "{{returnSecondaryTagValue.secondaryPatchGroupValue}}" ] } ], "MaxConcurrency":"10%", "MaxErrors":"10%" }, "nextStep":"returnSecondaryToOriginalState" }, { "name":"returnSecondaryToOriginalState", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnToOriginalState", "InputPayload":{ "targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}" }, "Script":"..." } } ] } ``` ------ 1. Emily reviews the completed scripted runbook content and creates the runbook in the same AWS account and AWS Region as the target instances. Now she's ready to test her runbook to make sure the automation operates as desired before implementing it into her production environment. The following is the completed scripted runbook content. ------ #### [ YAML ] ``` description: An example of an Automation runbook that patches groups of Amazon EC2 instances in stages. schemaVersion: '0.3' assumeRole: '{{AutomationAssumeRole}}' parameters: AutomationAssumeRole: type: String description: '(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook.' PrimaryPatchGroupTag: type: StringMap description: '(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}' SecondaryPatchGroupTag: type: StringMap description: '(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {"key" : "value"}' SnapshotId: type: String description: '(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.' default: '' RebootOption: type: String description: '(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.' allowedValues: - NoReboot - RebootIfNeeded default: RebootIfNeeded Operation: type: String description: '(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.' allowedValues: - Install - Scan default: Install mainSteps: - name: getPrimaryInstanceState action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: getInstanceStates InputPayload: primaryTag: '{{PrimaryPatchGroupTag}}' Script: |- def getInstanceStates(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') tag = events['primaryTag'] tagKey, tagValue = list(tag.items())[0] instanceQuery = ec2.describe_instances( Filters=[ { "Name": "tag:" + tagKey, "Values": [tagValue] }] ) if not instanceQuery['Reservations']: noInstancesForTagString = "No instances found for specified tag." return({ 'noInstancesFound' : noInstancesForTagString }) else: queryResponse = instanceQuery['Reservations'] originalInstanceStates = {} for results in queryResponse: instanceSet = results['Instances'] for instance in instanceSet: instanceId = instance['InstanceId'] originalInstanceStates[instanceId] = instance['State']['Name'] return originalInstanceStates outputs: - Name: originalInstanceStates Selector: $.Payload Type: StringMap nextStep: verifyPrimaryInstancesRunning - name: verifyPrimaryInstancesRunning action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: verifyInstancesRunning InputPayload: targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}' Script: |- def verifyInstancesRunning(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped': print("The target instance " + instance + " is stopped. The instance will now be started.") ec2.start_instances( InstanceIds=[instance] ) elif instanceDict[instance] == 'stopping': print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.") while instanceDict[instance] != 'stopped': poll = ec2.get_waiter('instance_stopped') poll.wait( InstanceIds=[instance] ) ec2.start_instances( InstanceIds=[instance] ) else: pass nextStep: waitForPrimaryRunningInstances - name: waitForPrimaryRunningInstances action: 'aws:executeScript' timeoutSeconds: 300 onFailure: Abort inputs: Runtime: python3.11 Handler: waitForRunningInstances InputPayload: targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}' Script: |- def waitForRunningInstances(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: poll = ec2.get_waiter('instance_running') poll.wait( InstanceIds=[instance] ) nextStep: returnPrimaryTagKey - name: returnPrimaryTagKey action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: primaryTag: '{{PrimaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['primaryTag'] tagKey = list(tag)[0] stringKey = "tag:" + tagKey return {'tagKey' : stringKey} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: primaryPatchGroupKey Selector: $.Payload.tagKey Type: String nextStep: returnPrimaryTagValue - name: returnPrimaryTagValue action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: primaryTag: '{{PrimaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['primaryTag'] tagKey = list(tag)[0] tagValue = tag[tagKey] return {'tagValue' : tagValue} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: primaryPatchGroupValue Selector: $.Payload.tagValue Type: String nextStep: patchPrimaryInstances - name: patchPrimaryInstances action: 'aws:runCommand' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: AWS-RunPatchBaseline Parameters: SnapshotId: '{{SnapshotId}}' RebootOption: '{{RebootOption}}' Operation: '{{Operation}}' Targets: - Key: '{{returnPrimaryTagKey.primaryPatchGroupKey}}' Values: - '{{returnPrimaryTagValue.primaryPatchGroupValue}}' MaxConcurrency: 10% MaxErrors: 10% nextStep: returnPrimaryToOriginalState - name: returnPrimaryToOriginalState action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: returnToOriginalState InputPayload: targetInstances: '{{getPrimaryInstanceState.originalInstanceStates}}' Script: |- def returnToOriginalState(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping': ec2.stop_instances( InstanceIds=[instance] ) else: pass nextStep: getSecondaryInstanceState - name: getSecondaryInstanceState action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: getInstanceStates InputPayload: secondaryTag: '{{SecondaryPatchGroupTag}}' Script: |- def getInstanceStates(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') tag = events['secondaryTag'] tagKey, tagValue = list(tag.items())[0] instanceQuery = ec2.describe_instances( Filters=[ { "Name": "tag:" + tagKey, "Values": [tagValue] }] ) if not instanceQuery['Reservations']: noInstancesForTagString = "No instances found for specified tag." return({ 'noInstancesFound' : noInstancesForTagString }) else: queryResponse = instanceQuery['Reservations'] originalInstanceStates = {} for results in queryResponse: instanceSet = results['Instances'] for instance in instanceSet: instanceId = instance['InstanceId'] originalInstanceStates[instanceId] = instance['State']['Name'] return originalInstanceStates outputs: - Name: originalInstanceStates Selector: $.Payload Type: StringMap nextStep: verifySecondaryInstancesRunning - name: verifySecondaryInstancesRunning action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: verifyInstancesRunning InputPayload: targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}' Script: |- def verifyInstancesRunning(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped': print("The target instance " + instance + " is stopped. The instance will now be started.") ec2.start_instances( InstanceIds=[instance] ) elif instanceDict[instance] == 'stopping': print("The target instance " + instance + " is stopping. Polling for instance to reach stopped state.") while instanceDict[instance] != 'stopped': poll = ec2.get_waiter('instance_stopped') poll.wait( InstanceIds=[instance] ) ec2.start_instances( InstanceIds=[instance] ) else: pass nextStep: waitForSecondaryRunningInstances - name: waitForSecondaryRunningInstances action: 'aws:executeScript' timeoutSeconds: 300 onFailure: Abort inputs: Runtime: python3.11 Handler: waitForRunningInstances InputPayload: targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}' Script: |- def waitForRunningInstances(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: poll = ec2.get_waiter('instance_running') poll.wait( InstanceIds=[instance] ) nextStep: returnSecondaryTagKey - name: returnSecondaryTagKey action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: secondaryTag: '{{SecondaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['secondaryTag'] tagKey = list(tag)[0] stringKey = "tag:" + tagKey return {'tagKey' : stringKey} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: secondaryPatchGroupKey Selector: $.Payload.tagKey Type: String nextStep: returnSecondaryTagValue - name: returnSecondaryTagValue action: 'aws:executeScript' timeoutSeconds: 120 onFailure: Abort inputs: Runtime: python3.11 Handler: returnTagValues InputPayload: secondaryTag: '{{SecondaryPatchGroupTag}}' Script: |- def returnTagValues(events,context): tag = events['secondaryTag'] tagKey = list(tag)[0] tagValue = tag[tagKey] return {'tagValue' : tagValue} outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: secondaryPatchGroupValue Selector: $.Payload.tagValue Type: String nextStep: patchSecondaryInstances - name: patchSecondaryInstances action: 'aws:runCommand' onFailure: Abort timeoutSeconds: 7200 inputs: DocumentName: AWS-RunPatchBaseline Parameters: SnapshotId: '{{SnapshotId}}' RebootOption: '{{RebootOption}}' Operation: '{{Operation}}' Targets: - Key: '{{returnSecondaryTagKey.secondaryPatchGroupKey}}' Values: - '{{returnSecondaryTagValue.secondaryPatchGroupValue}}' MaxConcurrency: 10% MaxErrors: 10% nextStep: returnSecondaryToOriginalState - name: returnSecondaryToOriginalState action: 'aws:executeScript' timeoutSeconds: 600 onFailure: Abort inputs: Runtime: python3.11 Handler: returnToOriginalState InputPayload: targetInstances: '{{getSecondaryInstanceState.originalInstanceStates}}' Script: |- def returnToOriginalState(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') instanceDict = events['targetInstances'] for instance in instanceDict: if instanceDict[instance] == 'stopped' or instanceDict[instance] == 'stopping': ec2.stop_instances( InstanceIds=[instance] ) else: pass ``` ------ #### [ JSON ] ``` { "description":"An example of an Automation runbook that patches groups of Amazon EC2 instances in stages.", "schemaVersion":"0.3", "assumeRole":"{{AutomationAssumeRole}}", "parameters":{ "AutomationAssumeRole":{ "type":"String", "description":"(Required) The Amazon Resource Name (ARN) of the IAM role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to operate this runbook." }, "PrimaryPatchGroupTag":{ "type":"StringMap", "description":"(Required) The tag for the primary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}" }, "SecondaryPatchGroupTag":{ "type":"StringMap", "description":"(Required) The tag for the secondary group of instances you want to patch. Specify a key-value pair. Example: {\"key\" : \"value\"}" }, "SnapshotId":{ "type":"String", "description":"(Optional) The snapshot ID to use to retrieve a patch baseline snapshot.", "default":"" }, "RebootOption":{ "type":"String", "description":"(Optional) Reboot behavior after a patch Install operation. If you choose NoReboot and patches are installed, the instance is marked as non-compliant until a subsequent reboot and scan.", "allowedValues":[ "NoReboot", "RebootIfNeeded" ], "default":"RebootIfNeeded" }, "Operation":{ "type":"String", "description":"(Optional) The update or configuration to perform on the instance. The system checks if patches specified in the patch baseline are installed on the instance. The install operation installs patches missing from the baseline.", "allowedValues":[ "Install", "Scan" ], "default":"Install" } }, "mainSteps":[ { "name":"getPrimaryInstanceState", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"getInstanceStates", "InputPayload":{ "primaryTag":"{{PrimaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"originalInstanceStates", "Selector":"$.Payload", "Type":"StringMap" } ], "nextStep":"verifyPrimaryInstancesRunning" }, { "name":"verifyPrimaryInstancesRunning", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"verifyInstancesRunning", "InputPayload":{ "targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"waitForPrimaryRunningInstances" }, { "name":"waitForPrimaryRunningInstances", "action":"aws:executeScript", "timeoutSeconds":300, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"waitForRunningInstances", "InputPayload":{ "targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"returnPrimaryTagKey" }, { "name":"returnPrimaryTagKey", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "primaryTag":"{{PrimaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"primaryPatchGroupKey", "Selector":"$.Payload.tagKey", "Type":"String" } ], "nextStep":"returnPrimaryTagValue" }, { "name":"returnPrimaryTagValue", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "primaryTag":"{{PrimaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"primaryPatchGroupValue", "Selector":"$.Payload.tagValue", "Type":"String" } ], "nextStep":"patchPrimaryInstances" }, { "name":"patchPrimaryInstances", "action":"aws:runCommand", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"AWS-RunPatchBaseline", "Parameters":{ "SnapshotId":"{{SnapshotId}}", "RebootOption":"{{RebootOption}}", "Operation":"{{Operation}}" }, "Targets":[ { "Key":"{{returnPrimaryTagKey.primaryPatchGroupKey}}", "Values":[ "{{returnPrimaryTagValue.primaryPatchGroupValue}}" ] } ], "MaxConcurrency":"10%", "MaxErrors":"10%" }, "nextStep":"returnPrimaryToOriginalState" }, { "name":"returnPrimaryToOriginalState", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnToOriginalState", "InputPayload":{ "targetInstances":"{{getPrimaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"getSecondaryInstanceState" }, { "name":"getSecondaryInstanceState", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"getInstanceStates", "InputPayload":{ "secondaryTag":"{{SecondaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"originalInstanceStates", "Selector":"$.Payload", "Type":"StringMap" } ], "nextStep":"verifySecondaryInstancesRunning" }, { "name":"verifySecondaryInstancesRunning", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"verifyInstancesRunning", "InputPayload":{ "targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"waitForSecondaryRunningInstances" }, { "name":"waitForSecondaryRunningInstances", "action":"aws:executeScript", "timeoutSeconds":300, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"waitForRunningInstances", "InputPayload":{ "targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}" }, "Script":"..." }, "nextStep":"returnSecondaryTagKey" }, { "name":"returnSecondaryTagKey", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "secondaryTag":"{{SecondaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"secondaryPatchGroupKey", "Selector":"$.Payload.tagKey", "Type":"String" } ], "nextStep":"returnSecondaryTagValue" }, { "name":"returnSecondaryTagValue", "action":"aws:executeScript", "timeoutSeconds":120, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnTagValues", "InputPayload":{ "secondaryTag":"{{SecondaryPatchGroupTag}}" }, "Script":"..." }, "outputs":[ { "Name":"Payload", "Selector":"$.Payload", "Type":"StringMap" }, { "Name":"secondaryPatchGroupValue", "Selector":"$.Payload.tagValue", "Type":"String" } ], "nextStep":"patchSecondaryInstances" }, { "name":"patchSecondaryInstances", "action":"aws:runCommand", "onFailure":"Abort", "timeoutSeconds":7200, "inputs":{ "DocumentName":"AWS-RunPatchBaseline", "Parameters":{ "SnapshotId":"{{SnapshotId}}", "RebootOption":"{{RebootOption}}", "Operation":"{{Operation}}" }, "Targets":[ { "Key":"{{returnSecondaryTagKey.secondaryPatchGroupKey}}", "Values":[ "{{returnSecondaryTagValue.secondaryPatchGroupValue}}" ] } ], "MaxConcurrency":"10%", "MaxErrors":"10%" }, "nextStep":"returnSecondaryToOriginalState" }, { "name":"returnSecondaryToOriginalState", "action":"aws:executeScript", "timeoutSeconds":600, "onFailure":"Abort", "inputs":{ "Runtime":"python3.11", "Handler":"returnToOriginalState", "InputPayload":{ "targetInstances":"{{getSecondaryInstanceState.originalInstanceStates}}" }, "Script":"..." } } ] } ``` ------ For more information about the automation actions used in this example, see the [Systems Manager Automation actions reference](automation-actions.md). # Additional runbook examples The following example runbook demonstrate how you can use AWS Systems Manager automation actions to automate common deployment, troubleshooting, and maintenance tasks. **Note** The example runbooks in this section are provided to demonstrate how you can create custom runbooks to support your specific operational needs. These runbooks aren't meant for use in production environments as is. However, you can customize them for your own use. **Topics** + [ # Deploy VPC architecture and Microsoft Active Directory domain controllers ](automation-document-architecture-deployment-example.md) + [ # Restore a root volume from the latest snapshot ](automation-document-instance-recovery-example.md) + [ # Create an AMI and cross-Region copy ](automation-document-backup-maintenance-example.md) # Deploy VPC architecture and Microsoft Active Directory domain controllers To increase efficiency and standardize common tasks, you might choose to automate deployments. This is useful if you regularly deploy the same architecture across multiple accounts and AWS Regions. Automating architecture deployments can also reduce the potential for human error that can occur when deploying architecture manually. AWS Systems Manager Automation actions can help you accomplish this. Automation is a tool in AWS Systems Manager. The following example AWS Systems Manager runbook performs these actions: + Retrieves the latest Windows Server 2016 Amazon Machine Image (AMI) using Systems Manager Parameter Store to use when launching the EC2 instances that will be configured as domain controllers. Parameter Store is a tool in AWS Systems Manager. + Uses the `aws:executeAwsApi` automation action to call several AWS API operations to create the VPC architecture. The domain controller instances are launched in private subnets, and connect to the internet using a NAT gateway. This allows the SSM Agent on the instances to access the requisite Systems Manager endpoints. + Uses the `aws:waitForAwsResourceProperty` automation action to confirm the instances launched by the previous action are `Online` for AWS Systems Manager. + Uses the `aws:runCommand` automation action to configure the instances launched as Microsoft Active Directory domain controllers. ------ #### [ YAML ] ``` --- description: Custom Automation Deployment Example schemaVersion: '0.3' parameters: AutomationAssumeRole: type: String default: '' description: >- (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook. mainSteps: - name: getLatestWindowsAmi action: aws:executeAwsApi onFailure: Abort inputs: Service: ssm Api: GetParameter Name: >- /aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base outputs: - Name: amiId Selector: $.Parameter.Value Type: String nextStep: createSSMInstanceRole - name: createSSMInstanceRole action: aws:executeAwsApi onFailure: Abort inputs: Service: iam Api: CreateRole AssumeRolePolicyDocument: >- {"Version": "2012-10-17", "Statement":[{"Effect":"Allow","Principal":{"Service":["ec2.amazonaws.com"]},"Action":["sts:AssumeRole"]}]} RoleName: sampleSSMInstanceRole nextStep: attachManagedSSMPolicy - name: attachManagedSSMPolicy action: aws:executeAwsApi onFailure: Abort inputs: Service: iam Api: AttachRolePolicy PolicyArn: 'arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore' RoleName: sampleSSMInstanceRole nextStep: createSSMInstanceProfile - name: createSSMInstanceProfile action: aws:executeAwsApi onFailure: Abort inputs: Service: iam Api: CreateInstanceProfile InstanceProfileName: sampleSSMInstanceRole outputs: - Name: instanceProfileArn Selector: $.InstanceProfile.Arn Type: String nextStep: addSSMInstanceRoleToProfile - name: addSSMInstanceRoleToProfile action: aws:executeAwsApi onFailure: Abort inputs: Service: iam Api: AddRoleToInstanceProfile InstanceProfileName: sampleSSMInstanceRole RoleName: sampleSSMInstanceRole nextStep: createVpc - name: createVpc action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateVpc CidrBlock: 10.0.100.0/22 outputs: - Name: vpcId Selector: $.Vpc.VpcId Type: String nextStep: getMainRtb - name: getMainRtb action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: DescribeRouteTables Filters: - Name: vpc-id Values: - '{{ createVpc.vpcId }}' outputs: - Name: mainRtbId Selector: '$.RouteTables[0].RouteTableId' Type: String nextStep: verifyMainRtb - name: verifyMainRtb action: aws:assertAwsResourceProperty onFailure: Abort inputs: Service: ec2 Api: DescribeRouteTables RouteTableIds: - '{{ getMainRtb.mainRtbId }}' PropertySelector: '$.RouteTables[0].Associations[0].Main' DesiredValues: - 'True' nextStep: createPubSubnet - name: createPubSubnet action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateSubnet CidrBlock: 10.0.103.0/24 AvailabilityZone: us-west-2c VpcId: '{{ createVpc.vpcId }}' outputs: - Name: pubSubnetId Selector: $.Subnet.SubnetId Type: String nextStep: createPubRtb - name: createPubRtb action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateRouteTable VpcId: '{{ createVpc.vpcId }}' outputs: - Name: pubRtbId Selector: $.RouteTable.RouteTableId Type: String nextStep: createIgw - name: createIgw action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateInternetGateway outputs: - Name: igwId Selector: $.InternetGateway.InternetGatewayId Type: String nextStep: attachIgw - name: attachIgw action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: AttachInternetGateway InternetGatewayId: '{{ createIgw.igwId }}' VpcId: '{{ createVpc.vpcId }}' nextStep: allocateEip - name: allocateEip action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: AllocateAddress Domain: vpc outputs: - Name: eipAllocationId Selector: $.AllocationId Type: String nextStep: createNatGw - name: createNatGw action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateNatGateway AllocationId: '{{ allocateEip.eipAllocationId }}' SubnetId: '{{ createPubSubnet.pubSubnetId }}' outputs: - Name: natGwId Selector: $.NatGateway.NatGatewayId Type: String nextStep: verifyNatGwAvailable - name: verifyNatGwAvailable action: aws:waitForAwsResourceProperty timeoutSeconds: 150 inputs: Service: ec2 Api: DescribeNatGateways NatGatewayIds: - '{{ createNatGw.natGwId }}' PropertySelector: '$.NatGateways[0].State' DesiredValues: - available nextStep: createNatRoute - name: createNatRoute action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateRoute DestinationCidrBlock: 0.0.0.0/0 NatGatewayId: '{{ createNatGw.natGwId }}' RouteTableId: '{{ getMainRtb.mainRtbId }}' nextStep: createPubRoute - name: createPubRoute action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateRoute DestinationCidrBlock: 0.0.0.0/0 GatewayId: '{{ createIgw.igwId }}' RouteTableId: '{{ createPubRtb.pubRtbId }}' nextStep: setPubSubAssoc - name: setPubSubAssoc action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: AssociateRouteTable RouteTableId: '{{ createPubRtb.pubRtbId }}' SubnetId: '{{ createPubSubnet.pubSubnetId }}' - name: createDhcpOptions action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateDhcpOptions DhcpConfigurations: - Key: domain-name-servers Values: - '10.0.100.50,10.0.101.50' - Key: domain-name Values: - sample.com outputs: - Name: dhcpOptionsId Selector: $.DhcpOptions.DhcpOptionsId Type: String nextStep: createDCSubnet1 - name: createDCSubnet1 action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateSubnet CidrBlock: 10.0.100.0/24 AvailabilityZone: us-west-2a VpcId: '{{ createVpc.vpcId }}' outputs: - Name: firstSubnetId Selector: $.Subnet.SubnetId Type: String nextStep: createDCSubnet2 - name: createDCSubnet2 action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateSubnet CidrBlock: 10.0.101.0/24 AvailabilityZone: us-west-2b VpcId: '{{ createVpc.vpcId }}' outputs: - Name: secondSubnetId Selector: $.Subnet.SubnetId Type: String nextStep: createDCSecGroup - name: createDCSecGroup action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateSecurityGroup GroupName: SampleDCSecGroup Description: Security Group for Sample Domain Controllers VpcId: '{{ createVpc.vpcId }}' outputs: - Name: dcSecGroupId Selector: $.GroupId Type: String nextStep: authIngressDCTraffic - name: authIngressDCTraffic action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: AuthorizeSecurityGroupIngress GroupId: '{{ createDCSecGroup.dcSecGroupId }}' IpPermissions: - FromPort: -1 IpProtocol: '-1' IpRanges: - CidrIp: 0.0.0.0/0 Description: Allow all traffic between Domain Controllers nextStep: verifyInstanceProfile - name: verifyInstanceProfile action: aws:waitForAwsResourceProperty maxAttempts: 5 onFailure: Abort inputs: Service: iam Api: ListInstanceProfilesForRole RoleName: sampleSSMInstanceRole PropertySelector: '$.InstanceProfiles[0].Arn' DesiredValues: - '{{ createSSMInstanceProfile.instanceProfileArn }}' nextStep: iamEventualConsistency - name: iamEventualConsistency action: aws:sleep inputs: Duration: PT2M nextStep: launchDC1 - name: launchDC1 action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: RunInstances BlockDeviceMappings: - DeviceName: /dev/sda1 Ebs: DeleteOnTermination: true VolumeSize: 50 VolumeType: gp2 - DeviceName: xvdf Ebs: DeleteOnTermination: true VolumeSize: 100 VolumeType: gp2 IamInstanceProfile: Arn: '{{ createSSMInstanceProfile.instanceProfileArn }}' ImageId: '{{ getLatestWindowsAmi.amiId }}' InstanceType: t2.micro MaxCount: 1 MinCount: 1 PrivateIpAddress: 10.0.100.50 SecurityGroupIds: - '{{ createDCSecGroup.dcSecGroupId }}' SubnetId: '{{ createDCSubnet1.firstSubnetId }}' TagSpecifications: - ResourceType: instance Tags: - Key: Name Value: SampleDC1 outputs: - Name: pdcInstanceId Selector: '$.Instances[0].InstanceId' Type: String nextStep: launchDC2 - name: launchDC2 action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: RunInstances BlockDeviceMappings: - DeviceName: /dev/sda1 Ebs: DeleteOnTermination: true VolumeSize: 50 VolumeType: gp2 - DeviceName: xvdf Ebs: DeleteOnTermination: true VolumeSize: 100 VolumeType: gp2 IamInstanceProfile: Arn: '{{ createSSMInstanceProfile.instanceProfileArn }}' ImageId: '{{ getLatestWindowsAmi.amiId }}' InstanceType: t2.micro MaxCount: 1 MinCount: 1 PrivateIpAddress: 10.0.101.50 SecurityGroupIds: - '{{ createDCSecGroup.dcSecGroupId }}' SubnetId: '{{ createDCSubnet2.secondSubnetId }}' TagSpecifications: - ResourceType: instance Tags: - Key: Name Value: SampleDC2 outputs: - Name: adcInstanceId Selector: '$.Instances[0].InstanceId' Type: String nextStep: verifyDCInstanceState - name: verifyDCInstanceState action: aws:waitForAwsResourceProperty inputs: Service: ec2 Api: DescribeInstanceStatus IncludeAllInstances: true InstanceIds: - '{{ launchDC1.pdcInstanceId }}' - '{{ launchDC2.adcInstanceId }}' PropertySelector: '$.InstanceStatuses..InstanceState.Name' DesiredValues: - running nextStep: verifyInstancesOnlineSSM - name: verifyInstancesOnlineSSM action: aws:waitForAwsResourceProperty timeoutSeconds: 600 inputs: Service: ssm Api: DescribeInstanceInformation InstanceInformationFilterList: - key: InstanceIds valueSet: - '{{ launchDC1.pdcInstanceId }}' - '{{ launchDC2.adcInstanceId }}' PropertySelector: '$.InstanceInformationList..PingStatus' DesiredValues: - Online nextStep: installADRoles - name: installADRoles action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - '{{ launchDC1.pdcInstanceId }}' - '{{ launchDC2.adcInstanceId }}' Parameters: commands: |- try { Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools } catch { Write-Error "Failed to install ADDS Role." } nextStep: setAdminPassword - name: setAdminPassword action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - '{{ launchDC1.pdcInstanceId }}' Parameters: commands: - net user Administrator "sampleAdminPass123!" nextStep: createForest - name: createForest action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - '{{ launchDC1.pdcInstanceId }}' Parameters: commands: |- $dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force try { Install-ADDSForest -DomainName "sample.com" -DomainMode 6 -ForestMode 6 -InstallDNS -DatabasePath "D:\NTDS" -SysvolPath "D:\SYSVOL" -SafeModeAdministratorPassword $dsrmPass -Force } catch { Write-Error $_ } try { Add-DnsServerForwarder -IPAddress "10.0.100.2" } catch { Write-Error $_ } nextStep: associateDhcpOptions - name: associateDhcpOptions action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: AssociateDhcpOptions DhcpOptionsId: '{{ createDhcpOptions.dhcpOptionsId }}' VpcId: '{{ createVpc.vpcId }}' nextStep: waitForADServices - name: waitForADServices action: aws:sleep inputs: Duration: PT1M nextStep: promoteADC - name: promoteADC action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - '{{ launchDC2.adcInstanceId }}' Parameters: commands: |- ipconfig /renew $dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force $domAdminUser = "sample\Administrator" $domAdminPass = "sampleAdminPass123!" | ConvertTo-SecureString -asPlainText -Force $domAdminCred = New-Object System.Management.Automation.PSCredential($domAdminUser,$domAdminPass) try { Install-ADDSDomainController -DomainName "sample.com" -InstallDNS -DatabasePath "D:\NTDS" -SysvolPath "D:\SYSVOL" -SafeModeAdministratorPassword $dsrmPass -Credential $domAdminCred -Force } catch { Write-Error $_ } ``` ------ #### [ JSON ] ``` { "description": "Custom Automation Deployment Example", "schemaVersion": "0.3", "assumeRole": "{{ AutomationAssumeRole }}", "parameters": { "AutomationAssumeRole": { "type": "String", "description": "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook.", "default": "" } }, "mainSteps": [ { "name": "getLatestWindowsAmi", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ssm", "Api": "GetParameter", "Name": "/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base" }, "outputs": [ { "Name": "amiId", "Selector": "$.Parameter.Value", "Type": "String" } ], "nextStep": "createSSMInstanceRole" }, { "name": "createSSMInstanceRole", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "iam", "Api": "CreateRole", "AssumeRolePolicyDocument": "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Principal\":{\"Service\":[\"ec2.amazonaws.com\"]},\"Action\":[\"sts:AssumeRole\"]}]}", "RoleName": "sampleSSMInstanceRole" }, "nextStep": "attachManagedSSMPolicy" }, { "name": "attachManagedSSMPolicy", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "iam", "Api": "AttachRolePolicy", "PolicyArn": "arn:aws:iam::aws:policy/service-role/AmazonSSMManagedInstanceCore", "RoleName": "sampleSSMInstanceRole" }, "nextStep": "createSSMInstanceProfile" }, { "name": "createSSMInstanceProfile", "action":"aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "iam", "Api": "CreateInstanceProfile", "InstanceProfileName": "sampleSSMInstanceRole" }, "outputs": [ { "Name": "instanceProfileArn", "Selector": "$.InstanceProfile.Arn", "Type": "String" } ], "nextStep": "addSSMInstanceRoleToProfile" }, { "name": "addSSMInstanceRoleToProfile", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "iam", "Api": "AddRoleToInstanceProfile", "InstanceProfileName": "sampleSSMInstanceRole", "RoleName": "sampleSSMInstanceRole" }, "nextStep": "createVpc" }, { "name": "createVpc", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateVpc", "CidrBlock": "10.0.100.0/22" }, "outputs": [ { "Name": "vpcId", "Selector": "$.Vpc.VpcId", "Type": "String" } ], "nextStep": "getMainRtb" }, { "name": "getMainRtb", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "DescribeRouteTables", "Filters": [ { "Name": "vpc-id", "Values": ["{{ createVpc.vpcId }}"] } ] }, "outputs": [ { "Name": "mainRtbId", "Selector": "$.RouteTables[0].RouteTableId", "Type": "String" } ], "nextStep": "verifyMainRtb" }, { "name": "verifyMainRtb", "action": "aws:assertAwsResourceProperty", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "DescribeRouteTables", "RouteTableIds": ["{{ getMainRtb.mainRtbId }}"], "PropertySelector": "$.RouteTables[0].Associations[0].Main", "DesiredValues": ["True"] }, "nextStep": "createPubSubnet" }, { "name": "createPubSubnet", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateSubnet", "CidrBlock": "10.0.103.0/24", "AvailabilityZone": "us-west-2c", "VpcId": "{{ createVpc.vpcId }}" }, "outputs":[ { "Name": "pubSubnetId", "Selector": "$.Subnet.SubnetId", "Type": "String" } ], "nextStep": "createPubRtb" }, { "name": "createPubRtb", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateRouteTable", "VpcId": "{{ createVpc.vpcId }}" }, "outputs": [ { "Name": "pubRtbId", "Selector": "$.RouteTable.RouteTableId", "Type": "String" } ], "nextStep": "createIgw" }, { "name": "createIgw", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateInternetGateway" }, "outputs": [ { "Name": "igwId", "Selector": "$.InternetGateway.InternetGatewayId", "Type": "String" } ], "nextStep": "attachIgw" }, { "name": "attachIgw", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "AttachInternetGateway", "InternetGatewayId": "{{ createIgw.igwId }}", "VpcId": "{{ createVpc.vpcId }}" }, "nextStep": "allocateEip" }, { "name": "allocateEip", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "AllocateAddress", "Domain": "vpc" }, "outputs": [ { "Name": "eipAllocationId", "Selector": "$.AllocationId", "Type": "String" } ], "nextStep": "createNatGw" }, { "name": "createNatGw", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateNatGateway", "AllocationId": "{{ allocateEip.eipAllocationId }}", "SubnetId": "{{ createPubSubnet.pubSubnetId }}" }, "outputs":[ { "Name": "natGwId", "Selector": "$.NatGateway.NatGatewayId", "Type": "String" } ], "nextStep": "verifyNatGwAvailable" }, { "name": "verifyNatGwAvailable", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 150, "inputs": { "Service": "ec2", "Api": "DescribeNatGateways", "NatGatewayIds": [ "{{ createNatGw.natGwId }}" ], "PropertySelector": "$.NatGateways[0].State", "DesiredValues": [ "available" ] }, "nextStep": "createNatRoute" }, { "name": "createNatRoute", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateRoute", "DestinationCidrBlock": "0.0.0.0/0", "NatGatewayId": "{{ createNatGw.natGwId }}", "RouteTableId": "{{ getMainRtb.mainRtbId }}" }, "nextStep": "createPubRoute" }, { "name": "createPubRoute", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateRoute", "DestinationCidrBlock": "0.0.0.0/0", "GatewayId": "{{ createIgw.igwId }}", "RouteTableId": "{{ createPubRtb.pubRtbId }}" }, "nextStep": "setPubSubAssoc" }, { "name": "setPubSubAssoc", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "AssociateRouteTable", "RouteTableId": "{{ createPubRtb.pubRtbId }}", "SubnetId": "{{ createPubSubnet.pubSubnetId }}" } }, { "name": "createDhcpOptions", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateDhcpOptions", "DhcpConfigurations": [ { "Key": "domain-name-servers", "Values": ["10.0.100.50,10.0.101.50"] }, { "Key": "domain-name", "Values": ["sample.com"] } ] }, "outputs": [ { "Name": "dhcpOptionsId", "Selector": "$.DhcpOptions.DhcpOptionsId", "Type": "String" } ], "nextStep": "createDCSubnet1" }, { "name": "createDCSubnet1", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateSubnet", "CidrBlock": "10.0.100.0/24", "AvailabilityZone": "us-west-2a", "VpcId": "{{ createVpc.vpcId }}" }, "outputs": [ { "Name": "firstSubnetId", "Selector": "$.Subnet.SubnetId", "Type": "String" } ], "nextStep": "createDCSubnet2" }, { "name": "createDCSubnet2", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateSubnet", "CidrBlock": "10.0.101.0/24", "AvailabilityZone": "us-west-2b", "VpcId": "{{ createVpc.vpcId }}" }, "outputs": [ { "Name": "secondSubnetId", "Selector": "$.Subnet.SubnetId", "Type": "String" } ], "nextStep": "createDCSecGroup" }, { "name": "createDCSecGroup", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateSecurityGroup", "GroupName": "SampleDCSecGroup", "Description": "Security Group for Example Domain Controllers", "VpcId": "{{ createVpc.vpcId }}" }, "outputs": [ { "Name": "dcSecGroupId", "Selector": "$.GroupId", "Type": "String" } ], "nextStep": "authIngressDCTraffic" }, { "name": "authIngressDCTraffic", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "AuthorizeSecurityGroupIngress", "GroupId": "{{ createDCSecGroup.dcSecGroupId }}", "IpPermissions": [ { "FromPort": -1, "IpProtocol": "-1", "IpRanges": [ { "CidrIp": "0.0.0.0/0", "Description": "Allow all traffic between Domain Controllers" } ] } ] }, "nextStep": "verifyInstanceProfile" }, { "name": "verifyInstanceProfile", "action": "aws:waitForAwsResourceProperty", "maxAttempts": 5, "onFailure": "Abort", "inputs": { "Service": "iam", "Api": "ListInstanceProfilesForRole", "RoleName": "sampleSSMInstanceRole", "PropertySelector": "$.InstanceProfiles[0].Arn", "DesiredValues": [ "{{ createSSMInstanceProfile.instanceProfileArn }}" ] }, "nextStep": "iamEventualConsistency" }, { "name": "iamEventualConsistency", "action": "aws:sleep", "inputs": { "Duration": "PT2M" }, "nextStep": "launchDC1" }, { "name": "launchDC1", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "RunInstances", "BlockDeviceMappings": [ { "DeviceName": "/dev/sda1", "Ebs": { "DeleteOnTermination": true, "VolumeSize": 50, "VolumeType": "gp2" } }, { "DeviceName": "xvdf", "Ebs": { "DeleteOnTermination": true, "VolumeSize": 100, "VolumeType": "gp2" } } ], "IamInstanceProfile": { "Arn": "{{ createSSMInstanceProfile.instanceProfileArn }}" }, "ImageId": "{{ getLatestWindowsAmi.amiId }}", "InstanceType": "t2.micro", "MaxCount": 1, "MinCount": 1, "PrivateIpAddress": "10.0.100.50", "SecurityGroupIds": [ "{{ createDCSecGroup.dcSecGroupId }}" ], "SubnetId": "{{ createDCSubnet1.firstSubnetId }}", "TagSpecifications": [ { "ResourceType": "instance", "Tags": [ { "Key": "Name", "Value": "SampleDC1" } ] } ] }, "outputs": [ { "Name": "pdcInstanceId", "Selector": "$.Instances[0].InstanceId", "Type": "String" } ], "nextStep": "launchDC2" }, { "name": "launchDC2", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "RunInstances", "BlockDeviceMappings": [ { "DeviceName": "/dev/sda1", "Ebs": { "DeleteOnTermination": true, "VolumeSize": 50, "VolumeType": "gp2" } }, { "DeviceName": "xvdf", "Ebs": { "DeleteOnTermination": true, "VolumeSize": 100, "VolumeType": "gp2" } } ], "IamInstanceProfile": { "Arn": "{{ createSSMInstanceProfile.instanceProfileArn }}" }, "ImageId": "{{ getLatestWindowsAmi.amiId }}", "InstanceType": "t2.micro", "MaxCount": 1, "MinCount": 1, "PrivateIpAddress": "10.0.101.50", "SecurityGroupIds": [ "{{ createDCSecGroup.dcSecGroupId }}" ], "SubnetId": "{{ createDCSubnet2.secondSubnetId }}", "TagSpecifications": [ { "ResourceType": "instance", "Tags": [ { "Key": "Name", "Value": "SampleDC2" } ] } ] }, "outputs": [ { "Name": "adcInstanceId", "Selector": "$.Instances[0].InstanceId", "Type": "String" } ], "nextStep": "verifyDCInstanceState" }, { "name": "verifyDCInstanceState", "action": "aws:waitForAwsResourceProperty", "inputs": { "Service": "ec2", "Api": "DescribeInstanceStatus", "IncludeAllInstances": true, "InstanceIds": [ "{{ launchDC1.pdcInstanceId }}", "{{ launchDC2.adcInstanceId }}" ], "PropertySelector": "$.InstanceStatuses[0].InstanceState.Name", "DesiredValues": [ "running" ] }, "nextStep": "verifyInstancesOnlineSSM" }, { "name": "verifyInstancesOnlineSSM", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 600, "inputs": { "Service": "ssm", "Api": "DescribeInstanceInformation", "InstanceInformationFilterList": [ { "key": "InstanceIds", "valueSet": [ "{{ launchDC1.pdcInstanceId }}", "{{ launchDC2.adcInstanceId }}" ] } ], "PropertySelector": "$.InstanceInformationList[0].PingStatus", "DesiredValues": [ "Online" ] }, "nextStep": "installADRoles" }, { "name": "installADRoles", "action": "aws:runCommand", "inputs": { "DocumentName": "AWS-RunPowerShellScript", "InstanceIds": [ "{{ launchDC1.pdcInstanceId }}", "{{ launchDC2.adcInstanceId }}" ], "Parameters": { "commands": [ "try {", " Install-WindowsFeature -Name AD-Domain-Services -IncludeManagementTools", "}", "catch {", " Write-Error \"Failed to install ADDS Role.\"", "}" ] } }, "nextStep": "setAdminPassword" }, { "name": "setAdminPassword", "action": "aws:runCommand", "inputs": { "DocumentName": "AWS-RunPowerShellScript", "InstanceIds": [ "{{ launchDC1.pdcInstanceId }}" ], "Parameters": { "commands": [ "net user Administrator \"sampleAdminPass123!\"" ] } }, "nextStep": "createForest" }, { "name": "createForest", "action": "aws:runCommand", "inputs": { "DocumentName": "AWS-RunPowerShellScript", "InstanceIds": [ "{{ launchDC1.pdcInstanceId }}" ], "Parameters": { "commands": [ "$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force", "try {", " Install-ADDSForest -DomainName \"sample.com\" -DomainMode 6 -ForestMode 6 -InstallDNS -DatabasePath \"D:\\NTDS\" -SysvolPath \"D:\\SYSVOL\" -SafeModeAdministratorPassword $dsrmPass -Force", "}", "catch {", " Write-Error $_", "}", "try {", " Add-DnsServerForwarder -IPAddress \"10.0.100.2\"", "}", "catch {", " Write-Error $_", "}" ] } }, "nextStep": "associateDhcpOptions" }, { "name": "associateDhcpOptions", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "AssociateDhcpOptions", "DhcpOptionsId": "{{ createDhcpOptions.dhcpOptionsId }}", "VpcId": "{{ createVpc.vpcId }}" }, "nextStep": "waitForADServices" }, { "name": "waitForADServices", "action": "aws:sleep", "inputs": { "Duration": "PT1M" }, "nextStep": "promoteADC" }, { "name": "promoteADC", "action": "aws:runCommand", "inputs": { "DocumentName": "AWS-RunPowerShellScript", "InstanceIds": [ "{{ launchDC2.adcInstanceId }}" ], "Parameters": { "commands": [ "ipconfig /renew", "$dsrmPass = 'sample123!' | ConvertTo-SecureString -asPlainText -Force", "$domAdminUser = \"sample\\Administrator\"", "$domAdminPass = \"sampleAdminPass123!\" | ConvertTo-SecureString -asPlainText -Force", "$domAdminCred = New-Object System.Management.Automation.PSCredential($domAdminUser,$domAdminPass)", "try {", " Install-ADDSDomainController -DomainName \"sample.com\" -InstallDNS -DatabasePath \"D:\\NTDS\" -SysvolPath \"D:\\SYSVOL\" -SafeModeAdministratorPassword $dsrmPass -Credential $domAdminCred -Force", "}", "catch {", " Write-Error $_", "}" ] } } } ] } ``` ------ # Restore a root volume from the latest snapshot The operating system on a root volume can become corrupted for various reasons. For example, following a patching operation, instances might fail to boot successfully due to a corrupted kernel or registry. Automating common troubleshooting tasks, like restoring a root volume from the latest snapshot taken before the patching operation, can reduce downtime and expedite your troubleshooting efforts. AWS Systems Manager Automation actions can help you accomplish this. Automation is a tool in AWS Systems Manager. The following example AWS Systems Manager runbook performs these actions: + Uses the `aws:executeAwsApi` automation action to retrieve details from the root volume of the instance. + Uses the `aws:executeScript` automation action to retrieve the latest snapshot for the root volume. + Uses the `aws:branch` automation action to continue the automation if a snapshot is found for the root volume. ------ #### [ YAML ] ``` --- description: Custom Automation Troubleshooting Example schemaVersion: '0.3' assumeRole: "{{ AutomationAssumeRole }}" parameters: AutomationAssumeRole: type: String description: "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to use this runbook." default: '' InstanceId: type: String description: "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot." default: '' mainSteps: - name: getInstanceDetails action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: DescribeInstances InstanceIds: - "{{ InstanceId }}" outputs: - Name: availabilityZone Selector: "$.Reservations[0].Instances[0].Placement.AvailabilityZone" Type: String - Name: rootDeviceName Selector: "$.Reservations[0].Instances[0].RootDeviceName" Type: String nextStep: getRootVolumeId - name: getRootVolumeId action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: DescribeVolumes Filters: - Name: attachment.device Values: ["{{ getInstanceDetails.rootDeviceName }}"] - Name: attachment.instance-id Values: ["{{ InstanceId }}"] outputs: - Name: rootVolumeId Selector: "$.Volumes[0].VolumeId" Type: String nextStep: getSnapshotsByStartTime - name: getSnapshotsByStartTime action: aws:executeScript timeoutSeconds: 45 onFailure: Abort inputs: Runtime: python3.11 Handler: getSnapshotsByStartTime InputPayload: rootVolumeId : "{{ getRootVolumeId.rootVolumeId }}" Script: |- def getSnapshotsByStartTime(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2') rootVolumeId = events['rootVolumeId'] snapshotsQuery = ec2.describe_snapshots( Filters=[ { "Name": "volume-id", "Values": [rootVolumeId] } ] ) if not snapshotsQuery['Snapshots']: noSnapshotFoundString = "NoSnapshotFound" return { 'noSnapshotFound' : noSnapshotFoundString } else: jsonSnapshots = snapshotsQuery['Snapshots'] sortedSnapshots = sorted(jsonSnapshots, key=lambda k: k['StartTime'], reverse=True) latestSortedSnapshotId = sortedSnapshots[0]['SnapshotId'] return { 'latestSnapshotId' : latestSortedSnapshotId } outputs: - Name: Payload Selector: $.Payload Type: StringMap - Name: latestSnapshotId Selector: $.Payload.latestSnapshotId Type: String - Name: noSnapshotFound Selector: $.Payload.noSnapshotFound Type: String nextStep: branchFromResults - name: branchFromResults action: aws:branch onFailure: Abort inputs: Choices: - NextStep: createNewRootVolumeFromSnapshot Not: Variable: "{{ getSnapshotsByStartTime.noSnapshotFound }}" StringEquals: "NoSnapshotFound" isEnd: true - name: createNewRootVolumeFromSnapshot action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateVolume AvailabilityZone: "{{ getInstanceDetails.availabilityZone }}" SnapshotId: "{{ getSnapshotsByStartTime.latestSnapshotId }}" outputs: - Name: newRootVolumeId Selector: "$.VolumeId" Type: String nextStep: stopInstance - name: stopInstance action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: StopInstances InstanceIds: - "{{ InstanceId }}" nextStep: verifyVolumeAvailability - name: verifyVolumeAvailability action: aws:waitForAwsResourceProperty timeoutSeconds: 120 inputs: Service: ec2 Api: DescribeVolumes VolumeIds: - "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}" PropertySelector: "$.Volumes[0].State" DesiredValues: - "available" nextStep: verifyInstanceStopped - name: verifyInstanceStopped action: aws:waitForAwsResourceProperty timeoutSeconds: 120 inputs: Service: ec2 Api: DescribeInstances InstanceIds: - "{{ InstanceId }}" PropertySelector: "$.Reservations[0].Instances[0].State.Name" DesiredValues: - "stopped" nextStep: detachRootVolume - name: detachRootVolume action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: DetachVolume VolumeId: "{{ getRootVolumeId.rootVolumeId }}" nextStep: verifyRootVolumeDetached - name: verifyRootVolumeDetached action: aws:waitForAwsResourceProperty timeoutSeconds: 30 inputs: Service: ec2 Api: DescribeVolumes VolumeIds: - "{{ getRootVolumeId.rootVolumeId }}" PropertySelector: "$.Volumes[0].State" DesiredValues: - "available" nextStep: attachNewRootVolume - name: attachNewRootVolume action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: AttachVolume Device: "{{ getInstanceDetails.rootDeviceName }}" InstanceId: "{{ InstanceId }}" VolumeId: "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}" nextStep: verifyNewRootVolumeAttached - name: verifyNewRootVolumeAttached action: aws:waitForAwsResourceProperty timeoutSeconds: 30 inputs: Service: ec2 Api: DescribeVolumes VolumeIds: - "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}" PropertySelector: "$.Volumes[0].Attachments[0].State" DesiredValues: - "attached" nextStep: startInstance - name: startInstance action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: StartInstances InstanceIds: - "{{ InstanceId }}" ``` ------ #### [ JSON ] ``` { "description": "Custom Automation Troubleshooting Example", "schemaVersion": "0.3", "assumeRole": "{{ AutomationAssumeRole }}", "parameters": { "AutomationAssumeRole": { "type": "String", "description": "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to run this runbook.", "default": "" }, "InstanceId": { "type": "String", "description": "(Required) The Instance Id whose root EBS volume you want to restore the latest Snapshot.", "default": "" } }, "mainSteps": [ { "name": "getInstanceDetails", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "DescribeInstances", "InstanceIds": [ "{{ InstanceId }}" ] }, "outputs": [ { "Name": "availabilityZone", "Selector": "$.Reservations[0].Instances[0].Placement.AvailabilityZone", "Type": "String" }, { "Name": "rootDeviceName", "Selector": "$.Reservations[0].Instances[0].RootDeviceName", "Type": "String" } ], "nextStep": "getRootVolumeId" }, { "name": "getRootVolumeId", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "DescribeVolumes", "Filters": [ { "Name": "attachment.device", "Values": [ "{{ getInstanceDetails.rootDeviceName }}" ] }, { "Name": "attachment.instance-id", "Values": [ "{{ InstanceId }}" ] } ] }, "outputs": [ { "Name": "rootVolumeId", "Selector": "$.Volumes[0].VolumeId", "Type": "String" } ], "nextStep": "getSnapshotsByStartTime" }, { "name": "getSnapshotsByStartTime", "action": "aws:executeScript", "timeoutSeconds": 45, "onFailure": "Continue", "inputs": { "Runtime": "python3.11", "Handler": "getSnapshotsByStartTime", "InputPayload": { "rootVolumeId": "{{ getRootVolumeId.rootVolumeId }}" }, "Attachment": "getSnapshotsByStartTime.py" }, "outputs": [ { "Name": "Payload", "Selector": "$.Payload", "Type": "StringMap" }, { "Name": "latestSnapshotId", "Selector": "$.Payload.latestSnapshotId", "Type": "String" }, { "Name": "noSnapshotFound", "Selector": "$.Payload.noSnapshotFound", "Type": "String" } ], "nextStep": "branchFromResults" }, { "name": "branchFromResults", "action": "aws:branch", "onFailure": "Abort", "inputs": { "Choices": [ { "NextStep": "createNewRootVolumeFromSnapshot", "Not": { "Variable": "{{ getSnapshotsByStartTime.noSnapshotFound }}", "StringEquals": "NoSnapshotFound" } } ] }, "isEnd": true }, { "name": "createNewRootVolumeFromSnapshot", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateVolume", "AvailabilityZone": "{{ getInstanceDetails.availabilityZone }}", "SnapshotId": "{{ getSnapshotsByStartTime.latestSnapshotId }}" }, "outputs": [ { "Name": "newRootVolumeId", "Selector": "$.VolumeId", "Type": "String" } ], "nextStep": "stopInstance" }, { "name": "stopInstance", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "StopInstances", "InstanceIds": [ "{{ InstanceId }}" ] }, "nextStep": "verifyVolumeAvailability" }, { "name": "verifyVolumeAvailability", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 120, "inputs": { "Service": "ec2", "Api": "DescribeVolumes", "VolumeIds": [ "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}" ], "PropertySelector": "$.Volumes[0].State", "DesiredValues": [ "available" ] }, "nextStep": "verifyInstanceStopped" }, { "name": "verifyInstanceStopped", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 120, "inputs": { "Service": "ec2", "Api": "DescribeInstances", "InstanceIds": [ "{{ InstanceId }}" ], "PropertySelector": "$.Reservations[0].Instances[0].State.Name", "DesiredValues": [ "stopped" ] }, "nextStep": "detachRootVolume" }, { "name": "detachRootVolume", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "DetachVolume", "VolumeId": "{{ getRootVolumeId.rootVolumeId }}" }, "nextStep": "verifyRootVolumeDetached" }, { "name": "verifyRootVolumeDetached", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 30, "inputs": { "Service": "ec2", "Api": "DescribeVolumes", "VolumeIds": [ "{{ getRootVolumeId.rootVolumeId }}" ], "PropertySelector": "$.Volumes[0].State", "DesiredValues": [ "available" ] }, "nextStep": "attachNewRootVolume" }, { "name": "attachNewRootVolume", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "AttachVolume", "Device": "{{ getInstanceDetails.rootDeviceName }}", "InstanceId": "{{ InstanceId }}", "VolumeId": "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}" }, "nextStep": "verifyNewRootVolumeAttached" }, { "name": "verifyNewRootVolumeAttached", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 30, "inputs": { "Service": "ec2", "Api": "DescribeVolumes", "VolumeIds": [ "{{ createNewRootVolumeFromSnapshot.newRootVolumeId }}" ], "PropertySelector": "$.Volumes[0].Attachments[0].State", "DesiredValues": [ "attached" ] }, "nextStep": "startInstance" }, { "name": "startInstance", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "StartInstances", "InstanceIds": [ "{{ InstanceId }}" ] } } ], "files": { "getSnapshotsByStartTime.py": { "checksums": { "sha256": "sampleETagValue" } } } } ``` ------ # Create an AMI and cross-Region copy Creating an Amazon Machine Image (AMI) of an instance is a common process used in backup and recovery. You might also choose to copy an AMI to another AWS Region as part of a disaster recovery architecture. Automating common maintenance tasks can reduce downtime if an issue requires failover. AWS Systems Manager Automation actions can help you accomplish this. Automation is a tool in AWS Systems Manager. The following example AWS Systems Manager runbook performs these actions: + Uses the `aws:executeAwsApi` automation action to create an AMI. + Uses the `aws:waitForAwsResourceProperty` automation action to confirm the availability of the AMI. + Uses the `aws:executeScript` automation action to copy the AMI to the destination Region. ------ #### [ YAML ] ``` --- description: Custom Automation Backup and Recovery Example schemaVersion: '0.3' assumeRole: "{{ AutomationAssumeRole }}" parameters: AutomationAssumeRole: type: String description: "(Required) The ARN of the role that allows Automation to perform the actions on your behalf. If no role is specified, Systems Manager Automation uses your IAM permissions to use this runbook." default: '' InstanceId: type: String description: "(Required) The ID of the EC2 instance." default: '' mainSteps: - name: createImage action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: CreateImage InstanceId: "{{ InstanceId }}" Name: "Automation Image for {{ InstanceId }}" NoReboot: false outputs: - Name: newImageId Selector: "$.ImageId" Type: String nextStep: verifyImageAvailability - name: verifyImageAvailability action: aws:waitForAwsResourceProperty timeoutSeconds: 600 inputs: Service: ec2 Api: DescribeImages ImageIds: - "{{ createImage.newImageId }}" PropertySelector: "$.Images[0].State" DesiredValues: - available nextStep: copyImage - name: copyImage action: aws:executeScript timeoutSeconds: 45 onFailure: Abort inputs: Runtime: python3.11 Handler: crossRegionImageCopy InputPayload: newImageId : "{{ createImage.newImageId }}" Script: |- def crossRegionImageCopy(events,context): import boto3 #Initialize client ec2 = boto3.client('ec2', region_name='us-east-1') newImageId = events['newImageId'] ec2.copy_image( Name='DR Copy for ' + newImageId, SourceImageId=newImageId, SourceRegion='us-west-2' ) ``` ------ #### [ JSON ] ``` { "description": "Custom Automation Backup and Recovery Example", "schemaVersion": "0.3", "assumeRole": "{{ AutomationAssumeRole }}", "parameters": { "AutomationAssumeRole": { "type": "String", "description": "(Required) The ARN of the role that allows Automation to perform\nthe actions on your behalf. If no role is specified, Systems Manager Automation\nuses your IAM permissions to run this runbook.", "default": "" }, "InstanceId": { "type": "String", "description": "(Required) The ID of the EC2 instance.", "default": "" } }, "mainSteps": [ { "name": "createImage", "action": "aws:executeAwsApi", "onFailure": "Abort", "inputs": { "Service": "ec2", "Api": "CreateImage", "InstanceId": "{{ InstanceId }}", "Name": "Automation Image for {{ InstanceId }}", "NoReboot": false }, "outputs": [ { "Name": "newImageId", "Selector": "$.ImageId", "Type": "String" } ], "nextStep": "verifyImageAvailability" }, { "name": "verifyImageAvailability", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 600, "inputs": { "Service": "ec2", "Api": "DescribeImages", "ImageIds": [ "{{ createImage.newImageId }}" ], "PropertySelector": "$.Images[0].State", "DesiredValues": [ "available" ] }, "nextStep": "copyImage" }, { "name": "copyImage", "action": "aws:executeScript", "timeoutSeconds": 45, "onFailure": "Abort", "inputs": { "Runtime": "python3.11", "Handler": "crossRegionImageCopy", "InputPayload": { "newImageId": "{{ createImage.newImageId }}" }, "Attachment": "crossRegionImageCopy.py" } } ], "files": { "crossRegionImageCopy.py": { "checksums": { "sha256": "sampleETagValue" } } } } ``` ------ # Creating input parameters that populate AWS resources Automation, a tool in Systems Manager, populates AWS resources in the AWS Management Console that match the resource type you define for an input parameter. Resources in your AWS account that match the resource type are displayed in a dropdown list for you to choose. You can define input parameter types for Amazon Elastic Compute Cloud (Amazon EC2) instances, Amazon Simple Storage Service (Amazon S3) buckets, and AWS Identity and Access Management (IAM) roles. The supported type definitions and the regular expressions used to locate matching resources are as follows: + `AWS::EC2::Instance::Id` - `^m?i-([a-z0-9]{8}|[a-z0-9]{17})$` + `List` - `^m?i-([a-z0-9]{8}|[a-z0-9]{17})$` + `AWS::S3::Bucket::Name` - `^[0-9a-z][a-z0-9\\-\\.]{3,63}$` + `List` - `^[0-9a-z][a-z0-9\\-\\.]{3,63}$` + `AWS::IAM::Role::Arn` - `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):iam::[0-9]{12}:role/.*$` + `List` - `^arn:(aws|aws-cn|aws-us-gov|aws-iso|aws-iso-b):iam::[0-9]{12}:role/.*$` The following is an example of input parameter types defined in runbook content. ------ #### [ YAML ] ``` description: Enables encryption on an Amazon S3 bucket schemaVersion: '0.3' assumeRole: '{{ AutomationAssumeRole }}' parameters: BucketName: type: 'AWS::S3::Bucket::Name' description: (Required) The name of the Amazon S3 bucket you want to encrypt. SSEAlgorithm: type: String description: (Optional) The server-side encryption algorithm to use for the default encryption. default: AES256 AutomationAssumeRole: type: 'AWS::IAM::Role::Arn' description: (Optional) The Amazon Resource Name (ARN) of the role that allows Automation to perform the actions on your behalf. default: '' mainSteps: - name: enableBucketEncryption action: 'aws:executeAwsApi' inputs: Service: s3 Api: PutBucketEncryption Bucket: '{{BucketName}}' ServerSideEncryptionConfiguration: Rules: - ApplyServerSideEncryptionByDefault: SSEAlgorithm: '{{SSEAlgorithm}}' isEnd: true ``` ------ #### [ JSON ] ``` { "description": "Enables encryption on an Amazon S3 bucket", "schemaVersion": "0.3", "assumeRole": "{{ AutomationAssumeRole }}", "parameters": { "BucketName": { "type": "AWS::S3::Bucket::Name", "description": "(Required) The name of the Amazon S3 bucket you want to encrypt." }, "SSEAlgorithm": { "type": "String", "description": "(Optional) The server-side encryption algorithm to use for the default encryption.", "default": "AES256" }, "AutomationAssumeRole": { "type": "AWS::IAM::Role::Arn", "description": "(Optional) The Amazon Resource Name (ARN) of the role that allows Automation to perform the actions on your behalf.", "default": "" } }, "mainSteps": [ { "name": "enableBucketEncryption", "action": "aws:executeAwsApi", "inputs": { "Service": "s3", "Api": "PutBucketEncryption", "Bucket": "{{BucketName}}", "ServerSideEncryptionConfiguration": { "Rules": [ { "ApplyServerSideEncryptionByDefault": { "SSEAlgorithm": "{{SSEAlgorithm}}" } } ] } }, "isEnd": true } ] } ``` ------ # Using Document Builder to create runbooks If the AWS Systems Manager public runbooks don't support all the actions you want to perform on your AWS resources, you can create your own runbooks. To create a custom runbook, you can manually create a local YAML or JSON format file with the appropriate automation actions. Alternatively, you can use Document Builder in the Systems Manager Automation console to build a custom runbook. Using Document Builder, you can add automation actions to your custom runbook and provide the required parameters without having to use JSON or YAML syntax. After you add steps and create the runbook, the system converts the actions you've added into the YAML format that Systems Manager can use to run automation. Runbooks support the use of Markdown, a markup language, which allows you to add wiki-style descriptions to runbooks and individual steps within the runbook. For more information about using Markdown, see [Using Markdown in AWS](https://docs.aws.amazon.com/general/latest/gr/aws-markdown.html). ## Create a runbook using Document Builder **Before you begin** We recommend that you read about the different actions that you can use within a runbook. For more information, see [Systems Manager Automation actions reference](automation-actions.md). **To create a runbook using Document Builder** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Documents**. 1. Choose **Create automation**. 1. For **Name**, enter a descriptive name for the runbook. 1. For **Document description**, provide the markdown style description for the runbook. You can provide instructions for using the runbook, numbered steps, or any other type of information to describe the runbook. Refer to the default text for information about formatting your content. **Tip** Toggle between **Hide preview** and **Show preview** to see what your description content looks like as you compose. 1. (Optional) For **Assume role**, enter the name or ARN of a service role to perform actions on your behalf. If you don't specify a role, Automation uses the access permissions of the user who runs the automation. **Important** For runbooks not owned by Amazon that use the `aws:executeScript` action, a role must be specified. For information, see [Permissions for using runbooks](automation-document-script-considerations.md#script-permissions). 1. (Optional) For **Outputs**, enter any outputs for the automation of this runbook to make available for other processes. For example, if your runbook creates a new AMI, you might specify ["CreateImage.ImageId"], and then use this output to create new instances in a subsequent automation. 1. (Optional) Expand the **Input parameters** section and do the following. 1. For **Parameter name**, enter a descriptive name for the runbook parameter you're creating. 1. For **Type**, choose a type for the parameter, such as `String` or `MapList`. 1. For **Required**, do one of the following: + Choose **Yes** if a value for this runbook parameter must be supplied at runtime. + Choose **No** if the parameter isn't required, and (optional) enter a default parameter value in **Default value**. 1. For **Description**, enter a description for the runbook parameter. **Note** To add more runbook parameters, choose **Add a parameter**. To remove a runbook parameter, choose the **X** (Remove) button. 1. (Optional) Expand the **Target type** section and choose a target type to define the kinds of resources the automation can run on. For example, to use a runbook on EC2 instances, choose `/AWS::EC2::Instance`. **Note** If you specify a value of '`/`', the runbook can run on all types of resources. For a list of valid resource types, see [AWS Resource Types Reference](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-template-resource-type-ref.html) in the *AWS CloudFormation User Guide*. 1. (Optional) Expand the **Document tags** section and enter one or more tag key-value pairs to apply to the runbook. Tags make it easier to identify, organize, and search for resources. 1. In the **Step 1** section, provide the following information. + For **Step name**, enter a descriptive name for the first step of the automation. + For **Action type**, select the action type to use for this step. For a list and information about the available action types, see [Systems Manager Automation actions reference](automation-actions.md). + For **Description**, enter a description for the automation step. You can use Markdown to format your text. + Depending on the **Action type** selected, enter the required inputs for the action type in the **Step inputs** section. For example, if you selected the action `aws:approve`, you must specify a value for the `Approvers` property. For information about the step input fields, see the entry in [Systems Manager Automation actions reference](automation-actions.md) for the action type you selected. For example: [`aws:executeStateMachine` – Run an AWS Step Functions state machine](automation-action-executeStateMachine.md). + (Optional) For **Additional inputs**, provide any additional input values needed for your runbook. The available input types depend on the action type you selected for the step. (Note that some action types require input values.) **Note** To add more inputs, choose **Add optional input**. To remove an input, choose the **X** (Remove) button. + (Optional) For **Outputs**, enter any outputs for this step to make available for other processes. **Note** **Outputs** isn't available for all action types. + (Optional) Expand the **Common properties** section and specify properties for the actions that are common to all automation actions. For example, for **Timeout seconds**, you can provide a value in seconds to specify how long the step can run before it's stopped. For more information, see [Properties shared by all actions](automation-actions.md#automation-common). **Note** To add more steps, select **Add step** and repeat the procedure for creating a step. To remove a step, choose **Remove step**. 1. Choose **Create automation** to save the runbook. ## Create a runbook that runs scripts The following procedure shows how to use Document Builder in the AWS Systems Manager Automation console to create a custom runbook that runs a script. The first step of the runbook you create runs a script to launch an Amazon Elastic Compute Cloud (Amazon EC2) instance. The second step runs another script to monitor for the instance status check to change to `ok`. Then, an overall status of `Success` is reported for the automation. **Before you begin** Make sure you have completed the following steps: + Verify that you have administrator privileges, or that you have been granted the appropriate permissions to access Systems Manager in AWS Identity and Access Management (IAM). For information, see [Verifying user access for runbooks](automation-setup.md#automation-setup-user-access). + Verify that you have an IAM service role for Automation (also known as an *assume role*) in your AWS account. The role is required because this walkthrough uses the `aws:executeScript` action. For information about creating this role, see [Configuring a service role (assume role) access for automations](automation-setup.md#automation-setup-configure-role). For information about the IAM service role requirement for running `aws:executeScript`, see [Permissions for using runbooks](automation-document-script-considerations.md#script-permissions). + Verify that you have permission to launch EC2 instances. For information, see [IAM and Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/UsingIAM.html#intro-to-iam) in the *Amazon EC2 User Guide*. **To create a custom runbook that runs scripts using Document Builder** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Documents**. 1. Choose **Create automation**. 1. For **Name**, type this descriptive name for the runbook: **LaunchInstanceAndCheckStatus**. 1. (Optional) For **Document description**, replace the default text with a description for this runbook, using Markdown. The following is an example. ``` ##Title: LaunchInstanceAndCheckState ----- **Purpose**: This runbook first launches an EC2 instance using the AMI ID provided in the parameter ```imageId```. The second step of this runbook continuously checks the instance status check value for the launched instance until the status ```ok``` is returned. ##Parameters: ----- Name | Type | Description | Default Value ------------- | ------------- | ------------- | ------------- assumeRole | String | (Optional) The ARN of the role that allows Automation to perform the actions on your behalf. | - imageId | String | (Optional) The AMI ID to use for launching the instance. The default value uses the latest Amazon Linux 2023 AMI ID available. | {{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }} ``` 1. For **Assume role**, enter the ARN of the IAM service role for Automation (Assume role) for the automation, in the format **arn:aws:iam::111122223333:role/AutomationServiceRole**. Substitute your AWS account ID for 111122223333. The role you specify is used to provide the permissions needed to start the automation. **Important** For runbooks not owned by Amazon that use the `aws:executeScript` action, a role must be specified. For information, see [Permissions for using runbooks](automation-document-script-considerations.md#script-permissions). 1. Expand **Input parameters** and do the following. 1. For **Parameter name**, enter **imageId**. 1. For **Type**, choose **String**. 1. For **Required**, choose `No`. 1. For **Default value**, enter the following. ``` {{ ssm:/aws/service/ami-amazon-linux-latest/al2023-ami-kernel-6.1-arm64 }} ``` **Note** This value launches an Amazon EC2 instance using the latest Amazon Linux 2023 Amazon Machine Image (AMI) ID. If you want to use a different AMI, replace the value with your AMI ID. 1. For **Description**, enter the following. ``` (Optional) The AMI ID to use for launching the instance. The default value uses the latest released Amazon Linux 2023 AMI ID. ``` 1. Choose **Add a parameter** to create the second parameter, **tagValue**, and enter the following. 1. For **Parameter name**, enter **tagValue**. 1. For **Type**, choose **String**. 1. For **Required**, choose `No`. 1. For **Default value**, enter **LaunchedBySsmAutomation**. This adds the tag key-pair value `Name:LaunchedBySsmAutomation` to the instance. 1. For **Description**, enter the following. ``` (Optional) The tag value to add to the instance. The default value is LaunchedBySsmAutomation. ``` 1. Choose **Add a parameter** to create the third parameter, **instanceType**, and enter the following information. 1. For **Parameter name**, enter **instanceType**. 1. For **Type**, choose **String**. 1. For **Required**, choose `No`. 1. For **Default value**, enter **t2.micro**. 1. For **Parameter description**, enter the following. ``` (Optional) The instance type to use for the instance. The default value is t2.micro. ``` 1. Expand **Target type** and choose **"/"**. 1. (Optional) Expand **Document tags** to apply resource tags to your runbook. For **Tag key**, enter **Purpose**, and for **Tag value**, enter **LaunchInstanceAndCheckState**. 1. In the **Step 1** section, complete the following steps. 1. For **Step name**, enter this descriptive step name for the first step of the automation: **LaunchEc2Instance**. 1. For **Action type**, choose **Run a script** (**aws:executeScript**). 1. For **Description**, enter a description for the automation step, such as the following. ``` **About This Step** This step first launches an EC2 instance using the ```aws:executeScript``` action and the provided script. ``` 1. Expand **Inputs**. 1. For **Runtime**, choose the runtime language to use to run the provided script. 1. For **Handler**, enter **launch\$1instance**. This is the function name declared in the following script. **Note** This is not required for PowerShell. 1. For **Script**, replace the default contents with the following. Be sure to match the script with the corresponding runtime value. ------ #### [ Python ] ``` def launch_instance(events, context): import boto3 ec2 = boto3.client('ec2') image_id = events['image_id'] tag_value = events['tag_value'] instance_type = events['instance_type'] tag_config = {'ResourceType': 'instance', 'Tags': [{'Key':'Name', 'Value':tag_value}]} res = ec2.run_instances(ImageId=image_id, InstanceType=instance_type, MaxCount=1, MinCount=1, TagSpecifications=[tag_config]) instance_id = res['Instances'][0]['InstanceId'] print('[INFO] 1 EC2 instance is successfully launched', instance_id) return { 'InstanceId' : instance_id } ``` ------ #### [ PowerShell ] ``` Install-Module AWS.Tools.EC2 -Force Import-Module AWS.Tools.EC2 $payload = $env:InputPayload | ConvertFrom-Json $imageid = $payload.image_id $tagvalue = $payload.tag_value $instanceType = $payload.instance_type $type = New-Object Amazon.EC2.InstanceType -ArgumentList $instanceType $resource = New-Object Amazon.EC2.ResourceType -ArgumentList 'instance' $tag = @{Key='Name';Value=$tagValue} $tagSpecs = New-Object Amazon.EC2.Model.TagSpecification $tagSpecs.ResourceType = $resource $tagSpecs.Tags.Add($tag) $res = New-EC2Instance -ImageId $imageId -MinCount 1 -MaxCount 1 -InstanceType $type -TagSpecification $tagSpecs return @{'InstanceId'=$res.Instances.InstanceId} ``` ------ 1. Expand **Additional inputs**. 1. For **Input name**, choose **InputPayload**. For **Input value**, enter the following YAML data. ``` image_id: "{{ imageId }}" tag_value: "{{ tagValue }}" instance_type: "{{ instanceType }}" ``` 1. Expand **Outputs** and do the following: + For **Name**, enter **payload**. + For **Selector**, enter **\$1.Payload**. + For **Type**, choose `StringMap`. 1. Choose **Add step** to add a second step to the runbook. The second step queries the status of the instance launched in Step 1 and waits until the status returned is `ok`. 1. In the **Step 2** section, do the following. 1. For **Step name**, enter this descriptive name for the second step of the automation: **WaitForInstanceStatusOk**. 1. For **Action type**, choose **Run a script** (**aws:executeScript**). 1. For **Description**, enter a description for the automation step, such as the following. ``` **About This Step** The script continuously polls the instance status check value for the instance launched in Step 1 until the ```ok``` status is returned. ``` 1. For **Runtime**, choose the runtime language to be used for executing the provided script. 1. For **Handler**, enter **poll\$1instance**. This is the function name declared in the following script. **Note** This is not required for PowerShell. 1. For **Script**, replace the default contents with the following. Be sure to match the script with the corresponding runtime value. ------ #### [ Python ] ``` def poll_instance(events, context): import boto3 import time ec2 = boto3.client('ec2') instance_id = events['InstanceId'] print('[INFO] Waiting for instance status check to report ok', instance_id) instance_status = "null" while True: res = ec2.describe_instance_status(InstanceIds=[instance_id]) if len(res['InstanceStatuses']) == 0: print("Instance status information is not available yet") time.sleep(5) continue instance_status = res['InstanceStatuses'][0]['InstanceStatus']['Status'] print('[INFO] Polling to get status of the instance', instance_status) if instance_status == 'ok': break time.sleep(10) return {'Status': instance_status, 'InstanceId': instance_id} ``` ------ #### [ PowerShell ] ``` Install-Module AWS.Tools.EC2 -Force $inputPayload = $env:InputPayload | ConvertFrom-Json $instanceId = $inputPayload.payload.InstanceId $status = Get-EC2InstanceStatus -InstanceId $instanceId while ($status.Status.Status -ne 'ok'){ Write-Host 'Polling get status of the instance', $instanceId Start-Sleep -Seconds 5 $status = Get-EC2InstanceStatus -InstanceId $instanceId } return @{Status = $status.Status.Status; InstanceId = $instanceId} ``` ------ 1. Expand **Additional inputs**. 1. For **Input name**, choose **InputPayload**. For **Input value**, enter the following: ``` {{ LaunchEc2Instance.payload }} ``` 1. Choose **Create automation** to save the runbook. # Using scripts in runbooks Automation runbooks support running scripts as part of the automation. Automation is a tool in 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](automation-action-logging.md). ## 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 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. ## 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. For more information about the `aws:executeScript` action and how to use attachments for scripts, see [`aws:executeScript` – Run a script](automation-action-executeScript.md). ## Script constraints for runbooks 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. # Using conditional statements in runbooks By default, the steps that you define in the `mainSteps` section of a runbook run in sequential order. After one action is completed, the next action specified in the `mainSteps` section begins. Furthermore, if an action fails to run, the entire automation fails (by default). You can use the `aws:branch` automation action and the runbook options described in this section to create automations that perform *conditional branching*. This means that you can create automations that jump to a different step after evaluating different choices or that dynamically respond to changes when a step is complete. Here is a list of options that you can use to create dynamic automations: + **`aws:branch`**: This automation action allows you to create a dynamic automation that evaluates multiple choices in a single step and then jumps to a different step in the runbook based on the results of that evaluation. + **`nextStep`**: This option specifies which step in an automation to process next after successfully completing a step. + **`isEnd`**: This option stops an automation at the end of a specific step. The default value for this option is false. + **`isCritical`**: This option designates a step as critical for the successful completion of the automation. If a step with this designation fails, then Automation reports the final status of the automation as `Failed`. The default value for this option is `true`. + **`onFailure`**: This option indicates whether the automation should stop, continue, or go to a different step on failure. The default value for this option is abort. The following section describes the `aws:branch` automation action. For more information about the `nextStep`, `isEnd`, `isCritical`, and `onFailure` options, see [Example `aws:branch` runbooks](#branch-runbook-examples). ## Working with the `aws:branch` action The `aws:branch` action offers the most dynamic conditional branching options for automations. As noted earlier, this action allows your automation to evaluate multiple conditions in a single step and then jump to a new step based on the results of that evaluation. The `aws:branch` action functions like an `IF-ELIF-ELSE` statement in programming. Here is a YAML example of an `aws:branch` step. ``` - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: PostProcessing ``` When you specify the `aws:branch` action for a step, you specify `Choices` that the automation must evaluate. The automation can evaluate `Choices` based on the value of a parameter that you specified in the `Parameters` section of the runbook. The automation can also evaluate `Choices` based on output from a previous step. The automation evaluates each choice by using a Boolean expression. If the evaluation determines that the first choice is `true`, then the automation jumps to the step designated for that choice. If the evaluation determines that the first choice is `false`, then the automation evaluates the next choice. If your step includes three or more `Choices`, then the automation evaluates each choice in sequential order until it evaluates a choice that is `true`. The automation then jumps to the designated step for the `true` choice. If none of the `Choices` are `true`, the automation checks to see if the step contains a `Default` value. A `Default` value defines a step that the automation should jump to if none of the choices are `true`. If no `Default` value is specified for the step, then the automation processes the next step in the runbook. Here is an `aws:branch` step in YAML named **chooseOSfromParameter**. The step includes two `Choices`: (`NextStep: runWindowsCommand`) and (`NextStep: runLinuxCommand`). The automation evaluates these `Choices` to determine which command to run for the appropriate operating system. The `Variable` for each choice uses `{{OSName}}`, which is a parameter that the runbook author defined in the `Parameters` section of the runbook. ``` mainSteps: - name: chooseOSfromParameter action: aws:branch inputs: Choices: - NextStep: runWindowsCommand Variable: "{{OSName}}" StringEquals: Windows - NextStep: runLinuxCommand Variable: "{{OSName}}" StringEquals: Linux ``` Here is an `aws:branch` step in YAML named **chooseOSfromOutput**. The step includes two `Choices`: (`NextStep: runPowerShellCommand`) and (`NextStep: runShellCommand`). The automation evaluates these `Choices` to determine which command to run for the appropriate operating system. The `Variable` for each choice uses `{{GetInstance.platform}}`, which is the output from an earlier step in the runbook. This example also includes an option called `Default`. If the automation evaluates both `Choices`, and neither choice is `true`, then the automation jumps to a step called `PostProcessing`. ``` mainSteps: - name: chooseOSfromOutput action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: PostProcessing ``` ### Creating an `aws:branch` step in a runbook When you create an `aws:branch` step in a runbook, you define the `Choices` the automation should evaluate to determine which step the automation should jump to next. As noted earlier, `Choices` are evaluated by using a Boolean expression. Each choice must define the following options: + **NextStep**: The next step in the runbook to process if the designated choice is `true`. + **Variable**: Specify either the name of a parameter that is defined in the `Parameters` section of the runbook, a variable defined in the `Variables` section, or specify an output object from a previous step. Specify variable values by using the following form. `Variable: "{{variable name}}"` Specify parameter values by using the following form. `Variable: "{{parameter name}}"` Specify output object variables by using the following form. `Variable: "{{previousStepName.outputName}}"` **Note** Creating the output variable is described in more detail in the next section, [About creating the output variable](#branch-action-output). + **Operation**: The criteria used to evaluate the choice, such as `StringEquals: Linux`. The `aws:branch` action supports the following operations: **String operations** + StringEquals + EqualsIgnoreCase + StartsWith + EndsWith + Contains **Numeric operations** + NumericEquals + NumericGreater + NumericLesser + NumericGreaterOrEquals + NumericLesser + NumericLesserOrEquals **Boolean operation** + BooleanEquals **Important** When you create a runbook, the system validates each operation in the runbook. If an operation isn't supported, the system returns an error when you try to create the runbook. + **Default**: Specify a fallback step that the automation should jump to if none of the `Choices` are `true`. **Note** If you don't want to specify a `Default` value, then you can specify the `isEnd` option. If none of the `Choices` are `true` and no `Default` value is specified, then the automation stops at the end of the step. Use the following templates to help you construct the `aws:branch` step in your runbook. Replace each *example resource placeholder* with your own information. ------ #### [ YAML ] ``` mainSteps: - name: step name action: aws:branch inputs: Choices: - NextStep: step to jump to if evaluation for this choice is true Variable: "{{parameter name or output from previous step}}" Operation type: Operation value - NextStep: step to jump to if evaluation for this choice is true Variable: "{{parameter name or output from previous step}}" Operation type: Operation value Default: step to jump to if all choices are false ``` ------ #### [ JSON ] ``` { "mainSteps":[ { "name":"a name for the step", "action":"aws:branch", "inputs":{ "Choices":[ { "NextStep":"step to jump to if evaluation for this choice is true", "Variable":"{{parameter name or output from previous step}}", "Operation type":"Operation value" }, { "NextStep":"step to jump to if evaluation for this choice is true", "Variable":"{{parameter name or output from previous step}}", "Operation type":"Operation value" } ], "Default":"step to jump to if all choices are false" } } ] } ``` ------ #### About creating the output variable To create an `aws:branch` choice that references the output from a previous step, you need to identify the name of the previous step and the name of the output field. You then combine the names of the step and the field by using the following format. `Variable: "{{previousStepName.outputName}}"` For example, the first step in the following example is named `GetInstance`. And then, under `outputs`, there is a field called `platform`. In the second step (`ChooseOSforCommands`), the author wants to reference the output from the platform field as a variable. To create the variable, simply combine the step name (GetInstance) and the output field name (platform) to create `Variable: "{{GetInstance.platform}}"`. ``` mainSteps: - Name: GetInstance action: aws:executeAwsApi inputs: Service: ssm Api: DescribeInstanceInformation Filters: - Key: InstanceIds Values: ["{{ InstanceId }}"] outputs: - Name: myInstance Selector: "$.InstanceInformationList[0].InstanceId" Type: String - Name: platform Selector: "$.InstanceInformationList[0].PlatformType" Type: String - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: Sleep ``` Here is an example that shows how *"Variable": "\$1\$1 describeInstance.Platform \$1\$1"* is created from the previous step and the output. ``` - name: describeInstance action: aws:executeAwsApi onFailure: Abort inputs: Service: ec2 Api: DescribeInstances InstanceIds: - "{{ InstanceId }}" outputs: - Name: Platform Selector: "$.Reservations[0].Instances[0].Platform" Type: String nextStep: branchOnInstancePlatform - name: branchOnInstancePlatform action: aws:branch inputs: Choices: - NextStep: runEC2RescueForWindows Variable: "{{ describeInstance.Platform }}" StringEquals: windows Default: runEC2RescueForLinux ``` ### Example `aws:branch` runbooks Here are some example runbooks that use `aws:branch`. **Example 1: Using `aws:branch` with an output variable to run commands based on the operating system type** In the first step of this example (`GetInstance`), the runbook author uses the `aws:executeAwsApi` action to call the `ssm` `DescribeInstanceInformation` API operation. The author uses this action to determine the type of operating system being used by an instance. The `aws:executeAwsApi` action outputs the instance ID and the platform type. In the second step (`ChooseOSforCommands`), the author uses the `aws:branch` action with two `Choices` (`NextStep: runPowerShellCommand`) and (`NextStep: runShellCommand`). The automation evaluates the operating system of the instance by using the output from the previous step (`Variable: "{{GetInstance.platform}}"`). The automation jumps to a step for the designated operating system. ``` --- schemaVersion: '0.3' assumeRole: "{{AutomationAssumeRole}}" parameters: AutomationAssumeRole: default: "" type: String mainSteps: - name: GetInstance action: aws:executeAwsApi inputs: Service: ssm Api: DescribeInstanceInformation outputs: - Name: myInstance Selector: "$.InstanceInformationList[0].InstanceId" Type: String - Name: platform Selector: "$.InstanceInformationList[0].PlatformType" Type: String - name: ChooseOSforCommands action: aws:branch inputs: Choices: - NextStep: runPowerShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Windows - NextStep: runShellCommand Variable: "{{GetInstance.platform}}" StringEquals: Linux Default: Sleep - name: runShellCommand action: aws:runCommand inputs: DocumentName: AWS-RunShellScript InstanceIds: - "{{GetInstance.myInstance}}" Parameters: commands: - ls isEnd: true - name: runPowerShellCommand action: aws:runCommand inputs: DocumentName: AWS-RunPowerShellScript InstanceIds: - "{{GetInstance.myInstance}}" Parameters: commands: - ls isEnd: true - name: Sleep action: aws:sleep inputs: Duration: PT3S ``` **Example 2: Using `aws:branch` with a parameter variable to run commands based on the operating system type** The runbook author defines several parameter options at the beginning of the runbook in the `parameters` section. One parameter is named `OperatingSystemName`. In the first step (`ChooseOS`), the author uses the `aws:branch` action with two `Choices` (`NextStep: runWindowsCommand`) and (`NextStep: runLinuxCommand`). The variable for these `Choices` references the parameter option specified in the parameters section (`Variable: "{{OperatingSystemName}}"`). When the user runs this runbook, they specify a value at runtime for `OperatingSystemName`. The automation uses the runtime parameter during the `Choices` evaluation. The automation jumps to a step for the designated operating system based on the runtime parameter specified for `OperatingSystemName`. ``` --- schemaVersion: '0.3' assumeRole: "{{AutomationAssumeRole}}" parameters: AutomationAssumeRole: default: "" type: String OperatingSystemName: type: String LinuxInstanceId: type: String WindowsInstanceId: type: String mainSteps: - name: ChooseOS action: aws:branch inputs: Choices: - NextStep: runWindowsCommand Variable: "{{OperatingSystemName}}" StringEquals: windows - NextStep: runLinuxCommand Variable: "{{OperatingSystemName}}" StringEquals: linux Default: Sleep - name: runLinuxCommand action: aws:runCommand inputs: DocumentName: "AWS-RunShellScript" InstanceIds: - "{{LinuxInstanceId}}" Parameters: commands: - ls isEnd: true - name: runWindowsCommand action: aws:runCommand inputs: DocumentName: "AWS-RunPowerShellScript" InstanceIds: - "{{WindowsInstanceId}}" Parameters: commands: - date isEnd: true - name: Sleep action: aws:sleep inputs: Duration: PT3S ``` ### Creating complex branching automations with operators You can create complex branching automations by using the `And`, `Or`, and `Not` operators in your `aws:branch` steps. **The 'And' operator** Use the `And` operator when you want multiple variables to be `true` for a choice. In the following example, the first choice evaluates if an instance is `running` and uses the `Windows` operating system. If the evaluation of *both* of these variables is true, then the automation jumps to the `runPowerShellCommand` step. If one or more of the variables is `false`, then the automation evaluates the variables for the second choice. ``` mainSteps: - name: switch2 action: aws:branch inputs: Choices: - And: - Variable: "{{GetInstance.pingStatus}}" StringEquals: running - Variable: "{{GetInstance.platform}}" StringEquals: Windows NextStep: runPowerShellCommand - And: - Variable: "{{GetInstance.pingStatus}}" StringEquals: running - Variable: "{{GetInstance.platform}}" StringEquals: Linux NextStep: runShellCommand Default: sleep3 ``` **The 'Or' operator** Use the `Or` operator when you want *any* of multiple variables to be true for a choice. In the following example, the first choice evaluates if a parameter string is `Windows` and if the output from an AWS Lambda step is true. If the evaluation determines that *either* of these variables is true, then the automation jumps to the `RunPowerShellCommand` step. If both variables are false, then the automation evaluates the variables for the second choice. ``` - Or: - Variable: "{{parameter1}}" StringEquals: Windows - Variable: "{{BooleanParam1}}" BooleanEquals: true NextStep: RunPowershellCommand - Or: - Variable: "{{parameter2}}" StringEquals: Linux - Variable: "{{BooleanParam2}}" BooleanEquals: true NextStep: RunShellScript ``` **The 'Not' operator** Use the `Not` operator when you want to jump to a step defined when a variable is *not* true. In the following example, the first choice evaluates if a parameter string is `Not Linux`. If the evaluation determines that the variable isn't Linux, then the automation jumps to the `sleep2` step. If the evaluation of the first choice determines that it *is* Linux, then the automation evaluates the next choice. ``` mainSteps: - name: switch action: aws:branch inputs: Choices: - NextStep: sleep2 Not: Variable: "{{testParam}}" StringEquals: Linux - NextStep: sleep1 Variable: "{{testParam}}" StringEquals: Windows Default: sleep3 ``` ## Examples of how to use conditional options This section includes different examples of how to use dynamic options in a runbook. Each example in this section extends the following runbook. This runbook has two actions. The first action is named `InstallMsiPackage`. It uses the `aws:runCommand` action to install an application on a Windows Server instance. The second action is named `TestInstall`. It uses the `aws:invokeLambdaFunction` action to perform a test of the installed application if the application installed successfully. Step one specifies `onFailure: Abort`. This means that if the application didn't install successfully, the automation stops before step two. **Example 1: Runbook with two linear actions** ``` --- schemaVersion: '0.3' description: Install MSI package and run validation. assumeRole: "{{automationAssumeRole}}" parameters: automationAssumeRole: type: String description: "(Required) Assume role." packageName: type: String description: "(Required) MSI package to be installed." instanceIds: type: String description: "(Required) Comma separated list of instances." mainSteps: - name: InstallMsiPackage action: aws:runCommand maxAttempts: 2 onFailure: Abort inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} - name: TestInstall action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: TestLambdaFunction ... ``` **Creating a dynamic automation that jumps to different steps by using the `onFailure` option** The following example uses the `onFailure: step:step name`, `nextStep`, and `isEnd` options to create a dynamic automation. With this example, if the `InstallMsiPackage` action fails, then the automation jumps to an action called *PostFailure* (`onFailure: step:PostFailure`) to run an AWS Lambda function to perform some action in the event the install failed. If the install succeeds, then the automation jumps to the TestInstall action (`nextStep: TestInstall`). Both the `TestInstall` and the `PostFailure` steps use the `isEnd` option (`isEnd: true`) so that the automation finishes when either of those steps is completed. **Note** Using the `isEnd` option in the last step of the `mainSteps` section is optional. If the last step doesn't jump to other steps, then the automation stops after running the action in the last step. **Example 2: A dynamic automation that jumps to different steps** ``` mainSteps - name: InstallMsiPackage action: aws:runCommand onFailure: step:PostFailure maxAttempts: 2 inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} nextStep: TestInstall - name: TestInstall action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: TestLambdaFunction isEnd: true - name: PostFailure action: aws:invokeLambdaFunction maxAttempts: 1 timeoutSeconds: 500 inputs: FunctionName: PostFailureRecoveryLambdaFunction isEnd: true ... ``` **Note** Before processing a runbook, the system verifies that the runbook doesn't create an infinite loop. If an infinite loop is detected, Automation returns an error and a circle trace showing which steps create the loop. **Creating a dynamic automation that defines critical steps** You can specify that a step is critical for the overall success of the automation. If a critical step fails, then Automation reports the status of the automation as `Failed`, even if one or more steps ran successfully. In the following example, the user identifies the *VerifyDependencies* step if the *InstallMsiPackage* step fails (`onFailure: step:VerifyDependencies`). The user specifies that the `InstallMsiPackage` step isn't critical (`isCritical: false`). In this example, if the application failed to install, Automation processes the `VerifyDependencies` step to determine if one or more dependencies is missing, which therefore caused the application install to fail. **Example 3: Defining critical steps for the automation ** ``` --- name: InstallMsiPackage action: aws:runCommand onFailure: step:VerifyDependencies isCritical: false maxAttempts: 2 inputs: InstanceIds: - "{{instanceIds}}" DocumentName: AWS-RunPowerShellScript Parameters: commands: - msiexec /i {{packageName}} nextStep: TestPackage ... ``` # Using action outputs as inputs Several automation actions return pre-defined outputs. You can pass these outputs as inputs to later steps in your runbook using the format `{{stepName.outputName}}`. You can also define custom outputs for automation actions in your runbooks. This allows you to run scripts, or invoke API operations for other AWS services once so you can reuse the values as inputs in later actions. Parameter types in runbooks are static. This means the parameter type can't be changed after it's defined. To define a step output provide the following fields: + Name: (Required) The output name which is used to reference the output value in later steps. + Selector: (Required) The JSONPath expression that is used to determine the output value. + Type: (Optional) The data type of the value returned by the selector field. Valid type values are `String`, `Integer`, `Boolean`, `StringList`, `StringMap`, `MapList`. The default value is `String`. If the value of an output doesn't match the data type you've specified, Automation tries to convert the data type. For example, if the value returned is an `Integer`, but the `Type` specified is `String`, the final output value is a `String` value. The following type conversions are supported: + `String` values can be converted to `StringList`, `Integer` and `Boolean`. + `Integer` values can be converted to `String` and `StringList`. + `Boolean` values can be converted to `String` and `StringList`. + `StringList`, `IntegerList`, or `BooleanList` values containing one element can be converted to `String`, `Integer`, or `Boolean`. When using parameters or outputs with automation actions, the data type can't be dynamically changed within an action's input. Here is an example runbook that demonstrates how to define action outputs, and reference the value as input for a later action. The runbooks does the following: + Uses the `aws:executeAwsApi` action to call the Amazon EC2 DescribeImages API operation to get the name of a specific Windows Server 2016 AMI. It outputs the image ID as `ImageId`. + Uses the `aws:executeAwsApi` action to call the Amazon EC2 RunInstances API operation to launch one instance that uses the `ImageId` from the previous step. It outputs the instance ID as `InstanceId`. + Uses the` aws:waitForAwsResourceProperty` action to poll the Amazon EC2 DescribeInstanceStatus API operation to wait for the instance to reach the `running` state. The action times out in 60 seconds. The step times out if the instance state failed to reach `running` after 60 seconds of polling. + Uses the `aws:assertAwsResourceProperty` action to call the Amazon EC2 `DescribeInstanceStatus` API operation to assert that the instance is in the `running` state. The step fails if the instance state isn't `running`. ``` --- description: Sample runbook using AWS API operations schemaVersion: '0.3' assumeRole: "{{ AutomationAssumeRole }}" parameters: AutomationAssumeRole: type: String description: "(Optional) The ARN of the role that allows Automation to perform the actions on your behalf." default: '' ImageName: type: String description: "(Optional) Image Name to launch EC2 instance with." default: "Windows_Server-2022-English-Full-Base*" mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ ImageName }}" outputs: - Name: ImageId Selector: "$.Images[0].ImageId" Type: "String" - name: launchOneInstance action: aws:executeAwsApi inputs: Service: ec2 Api: RunInstances ImageId: "{{ getImageId.ImageId }}" MaxCount: 1 MinCount: 1 outputs: - Name: InstanceId Selector: "$.Instances[0].InstanceId" Type: "String" - name: waitUntilInstanceStateRunning action: aws:waitForAwsResourceProperty timeoutSeconds: 60 inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running - name: assertInstanceStateRunning action: aws:assertAwsResourceProperty inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running outputs: - "launchOneInstance.InstanceId" ... ``` Each of the previously described automation actions allows you to call a specific API operation by specifying the service namespace, the API operation name, the input parameters, and the output parameters. Inputs are defined by the API operation that you choose. You can view the API operations (also called methods) by choosing a service in the left navigation on the following [Services Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html) page. Choose a method in the **Client** section for the service that you want to invoke. For example, all API operations (methods) for Amazon Relational Database Service (Amazon RDS) are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). You can view the schema for each automation action in the following locations: + [`aws:assertAwsResourceProperty` – Assert an AWS resource state or event state](automation-action-assertAwsResourceProperty.md) + [`aws:executeAwsApi` – Call and run AWS API operations](automation-action-executeAwsApi.md) + [`aws:waitForAwsResourceProperty` – Wait on an AWS resource property](automation-action-waitForAwsResourceProperty.md) The schemas include descriptions of the required fields for using each action. **Using the Selector/PropertySelector fields** Each Automation action requires that you specify either an output `Selector` (for `aws:executeAwsApi`) or a `PropertySelector` (for `aws:assertAwsResourceProperty` and `aws:waitForAwsResourceProperty`). These fields are used to process the JSON response from an AWS API operation. These fields use the JSONPath syntax. Here is an example to help illustrate this concept for the `aws:executeAwsAPi` action. ``` --- mainSteps: - name: getImageId action: aws:executeAwsApi inputs: Service: ec2 Api: DescribeImages Filters: - Name: "name" Values: - "{{ ImageName }}" outputs: - Name: ImageId Selector: "$.Images[0].ImageId" Type: "String" ... ``` In the `aws:executeAwsApi` step `getImageId`, the automation invokes the `DescribeImages` API operation and receives a response from `ec2`. The automation then applies `Selector - "$.Images[0].ImageId"` to the API response and assigns the selected value to the output `ImageId` variable. Other steps in the same automation can use the value of `ImageId` by specifying `"{{ getImageId.ImageId }}"`. Here is an example to help illustrate this concept for the `aws:waitForAwsResourceProperty` action. ``` --- - name: waitUntilInstanceStateRunning action: aws:waitForAwsResourceProperty # timeout is strongly encouraged for action - aws:waitForAwsResourceProperty timeoutSeconds: 60 inputs: Service: ec2 Api: DescribeInstanceStatus InstanceIds: - "{{ launchOneInstance.InstanceId }}" PropertySelector: "$.InstanceStatuses[0].InstanceState.Name" DesiredValues: - running ... ``` In the `aws:waitForAwsResourceProperty` step `waitUntilInstanceStateRunning`, the automation invokes the `DescribeInstanceStatus` API operation and receives a response from `ec2`. The automation then applies `PropertySelector - "$.InstanceStatuses[0].InstanceState.Name"` to the response and checks if the specified returned value matches a value in the `DesiredValues` list (in this case `running`). The step repeats the process until the response returns an instance state of `running`. ## Using JSONPath in runbooks A JSONPath expression is a string beginning with "\$1." that is used to select one of more components within a JSON element. The following list includes information about JSONPath operators that are supported by Systems Manager Automation: + **Dot-notated child (.)**: Use with a JSON object. This operator selects the value of a specific key. + **Deep-scan (..)**: Use with a JSON element. This operator scans the JSON element level by level and selects a list of values with the specific key. The return type of this operator is always a JSON array. In the context of an automation action output type, the operator can be either StringList or MapList. + **Array-Index ([ ])**: Use with a JSON array. This operator gets the value of a specific index. + **Filter ([?(*expression*)])**: Use with a JSON array. This operator filters JSON array values that match the criteria defined in the filter expression. Filter expressions can only use the following operators: ==, \$1=, >, <, >=, or <=. Combining multiple filter expressions with AND (&&) or OR (\$1\$1) is not supported. The return type of this operator is always a JSON array. To better understand JSONPath operators, review the following JSON response from the ec2 `DescribeInstances` API operation. Following this response are several examples that show different results by applying different JSONPath expressions to the response from the `DescribeInstances` API operation. ``` { "NextToken": "abcdefg", "Reservations": [ { "OwnerId": "123456789012", "ReservationId": "r-abcd12345678910", "Instances": [ { "ImageId": "ami-12345678", "BlockDeviceMappings": [ { "Ebs": { "DeleteOnTermination": true, "Status": "attached", "VolumeId": "vol-000000000000" }, "DeviceName": "/dev/xvda" } ], "State": { "Code": 16, "Name": "running" } } ], "Groups": [] }, { "OwnerId": "123456789012", "ReservationId": "r-12345678910abcd", "Instances": [ { "ImageId": "ami-12345678", "BlockDeviceMappings": [ { "Ebs": { "DeleteOnTermination": true, "Status": "attached", "VolumeId": "vol-111111111111" }, "DeviceName": "/dev/xvda" } ], "State": { "Code": 80, "Name": "stopped" } } ], "Groups": [] } ] } ``` **JSONPath Example 1: Get a specific String from a JSON response** ``` JSONPath: $.Reservations[0].Instances[0].ImageId Returns: "ami-12345678" Type: String ``` **JSONPath Example 2: Get a specific Boolean from a JSON response** ``` JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0].Ebs.DeleteOnTermination Returns: true Type: Boolean ``` **JSONPath Example 3: Get a specific Integer from a JSON response** ``` JSONPath: $.Reservations[0].Instances[0].State.Code Returns: 16 Type: Integer ``` **JSONPath Example 4: Deep scan a JSON response, then get all of the values for VolumeId as a StringList** ``` JSONPath: $.Reservations..BlockDeviceMappings..VolumeId Returns: [ "vol-000000000000", "vol-111111111111" ] Type: StringList ``` **JSONPath Example 5: Get a specific BlockDeviceMappings object as a StringMap** ``` JSONPath: $.Reservations[0].Instances[0].BlockDeviceMappings[0] Returns: { "Ebs" : { "DeleteOnTermination" : true, "Status" : "attached", "VolumeId" : "vol-000000000000" }, "DeviceName" : "/dev/xvda" } Type: StringMap ``` **JSONPath Example 6: Deep scan a JSON response, then get all of the State objects as a MapList** ``` JSONPath: $.Reservations..Instances..State Returns: [ { "Code" : 16, "Name" : "running" }, { "Code" : 80, "Name" : "stopped" } ] Type: MapList ``` **JSONPath Example 7: Filter for instances in the `running` state** ``` JSONPath: $.Reservations..Instances[?(@.State.Name == 'running')] Returns: [ { "ImageId": "ami-12345678", "BlockDeviceMappings": [ { "Ebs": { "DeleteOnTermination": true, "Status": "attached", "VolumeId": "vol-000000000000" }, "DeviceName": "/dev/xvda" } ], "State": { "Code": 16, "Name": "running" } } ] Type: MapList ``` **JSONPath Example 8: Return the `ImageId` of instances which aren't in the `running` state** ``` JSONPath: $.Reservations..Instances[?(@.State.Name != 'running')].ImageId Returns: [ "ami-12345678" ] Type: StringList | String ``` # Creating webhook integrations for Automation To send messages using webhooks during an automation, create an integration. Integrations can be invoked during an automation by using the `aws:invokeWebhook` action in your runbook. If you haven't already created a webhook, see [Creating webhooks for integrations](#creating-webhooks). To learn more about the `aws:invokeWebhook` action, see [`aws:invokeWebhook` – Invoke an Automation webhook integration](invoke-webhook.md). As shown in the following procedures, you can create an integration by using either the Systems Manager Automation console or your preferred command line tool. ## Creating integrations (console) **To create an integration for Automation (console)** 1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/). 1. In the navigation pane, choose **Automation**. 1. Choose the **Integrations** tab. 1. Select **Add integration**, and choose **Webhook**. 1. Enter the required values and any optional values you want to include for the integration. 1. Choose **Add** to create the integration. ## Creating integrations (command line) To create an integration using command line tools, you must create the required `SecureString` parameter for an integration. Automation uses a reserved namespace in Parameter Store, a tool in Systems Manager, to store information about your integration. If you create an integration using the AWS Management Console, Automation handles this process for you. Following the namespace, you must specify the type of integration you want to create and then the name of your integration. Currently, Automation supports `webhook` type integrations. The supported fields for `webhook` type integrations are as follows: + Description + headers + payload + URL **Before you begin** If you haven't already, install and configure the AWS Command Line Interface (AWS CLI) or the AWS Tools for PowerShell. For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html). **To create an integration for Automation (command line)** + Run the following commands to create the required `SecureString` parameter for an integration. Replace each *example resource placeholder* with your own information. The `/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/` namespace is reserved in Parameter Store for integrations. The name of your parameter must use this namespace followed by the name of your integration. For example `/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration`. ------ #### [ Linux & macOS ] ``` aws ssm put-parameter \ --name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" \ --type "SecureString" \ --data-type "aws:ssm:integration" \ --value '{"description": "My first webhook integration for Automation.", "url": "myWebHookURL"}' ``` ------ #### [ Windows ] ``` aws ssm put-parameter ^ --name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" ^ --type "SecureString" ^ --data-type "aws:ssm:integration" ^ --value "{\"description\":\"My first webhook integration for Automation.\",\"url\":\"myWebHookURL\"}" ``` ------ #### [ PowerShell ] ``` Write-SSMParameter ` -Name "/d9d01087-4a3f-49e0-b0b4-d568d7826553/ssm/integrations/webhook/myWebhookIntegration" ` -Type "SecureString" -DataType "aws:ssm:integration" -Value '{"description": "My first webhook integration for Automation.", "url": "myWebHookURL"}' ``` ------ ## Creating webhooks for integrations When creating webhooks with your provider, note the following: + Protocol must be HTTPS. + Custom request headers are supported. + A default request body can be specified. + The default request body can be overridden when an integration is invoked by using the `aws:invokeWebhook` action. # Handling timeouts in runbooks The `timeoutSeconds` property is shared by all automation actions. You can use this property to specify the execution timeout value for an action. Further, you can change how an action timing out affects the automation and overall execution status. You can accomplish this by also defining the `onFailure` and `isCritical` shared properties for an action. For example, depending on your use case, you might want your automation to continue to a different action and not affect the overall status of the automation if an action times out. In this example, you specify the length of time to wait before the action times out using the `timeoutSeconds` property. Then you specify the action, or step, the automation should go to if there is a timeout. Specify a value using the format `step:step name` for the `onFailure` property rather than the default value of `Abort`. By default, if an action times out, the automation execution status will be `Timed Out`. To prevent a timeout from affecting the automation execution status, specify `false` for the `isCritical` property. The following example shows how to define the shared properties for an action described in this scenario. ------ #### [ YAML ] ``` - name: verifyImageAvailability action: 'aws:waitForAwsResourceProperty' timeoutSeconds: 600 isCritical: false onFailure: 'step:getCurrentImageState' inputs: Service: ec2 Api: DescribeImages ImageIds: - '{{ createImage.newImageId }}' PropertySelector: '$.Images[0].State' DesiredValues: - available nextStep: copyImage ``` ------ #### [ JSON ] ``` { "name": "verifyImageAvailability", "action": "aws:waitForAwsResourceProperty", "timeoutSeconds": 600, "isCritical": false, "onFailure": "step:getCurrentImageState", "inputs": { "Service": "ec2", "Api": "DescribeImages", "ImageIds": [ "{{ createImage.newImageId }}" ], "PropertySelector": "$.Images[0].State", "DesiredValues": [ "available" ] }, "nextStep": "copyImage" } ``` ------ For more information about properties shared by all automation actions, see [Properties shared by all actions](automation-actions.md#automation-common).