• 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).
# Systems Manager Automation actions reference
This reference describes the Automation actions that you can specify in an Automation runbook. Automation is a tool in AWS Systems Manager. These actions can't be used in other types of Systems Manager (SSM) documents. For information about plugins for other types of SSM documents, see [Command document plugin reference](documents-command-ssm-plugin-reference.md).
Systems Manager Automation runs steps defined in Automation runbooks. Each step is associated with a particular action. The action determines the inputs, behavior, and outputs of the step. Steps are defined in the `mainSteps` section of your runbook.
You don't need to specify the outputs of an action or step. The outputs are predetermined by the action associated with the step. When you specify step inputs in your runbooks, you can reference one or more outputs from an earlier step. For example, you can make the output of `aws:runInstances` available for a subsequent `aws:runCommand` action. You can also reference outputs from earlier steps in the `Output` section of the runbook.
**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).
**Topics**
+ [Properties shared by all actions](#automation-common)
+ [`aws:approve` – Pause an automation for manual approval](automation-action-approve.md)
+ [`aws:assertAwsResourceProperty` – Assert an AWS resource state or event state](automation-action-assertAwsResourceProperty.md)
+ [`aws:branch` – Run conditional automation steps](automation-action-branch.md)
+ [`aws:changeInstanceState` – Change or assert instance state](automation-action-changestate.md)
+ [`aws:copyImage` – Copy or encrypt an Amazon Machine Image](automation-action-copyimage.md)
+ [`aws:createImage` – Create an Amazon Machine Image](automation-action-create.md)
+ [`aws:createStack` – Create an CloudFormation stack](automation-action-createstack.md)
+ [`aws:createTags` – Create tags for AWS resources](automation-action-createtag.md)
+ [`aws:deleteImage` – Delete an Amazon Machine Image](automation-action-delete.md)
+ [`aws:deleteStack` – Delete an CloudFormation stack](automation-action-deletestack.md)
+ [`aws:executeAutomation` – Run another automation](automation-action-executeAutomation.md)
+ [`aws:executeAwsApi` – Call and run AWS API operations](automation-action-executeAwsApi.md)
+ [`aws:executeScript` – Run a script](automation-action-executeScript.md)
+ [`aws:executeStateMachine` – Run an AWS Step Functions state machine](automation-action-executeStateMachine.md)
+ [`aws:invokeWebhook` – Invoke an Automation webhook integration](invoke-webhook.md)
+ [`aws:invokeLambdaFunction` – Invoke an AWS Lambda function](automation-action-lamb.md)
+ [`aws:loop` – Iterate over steps in an automation](automation-action-loop.md)
+ [`aws:pause` – Pause an automation](automation-action-pause.md)
+ [`aws:runCommand` – Run a command on a managed instance](automation-action-runcommand.md)
+ [`aws:runInstances` – Launch an Amazon EC2 instance](automation-action-runinstance.md)
+ [`aws:sleep` – Delay an automation](automation-action-sleep.md)
+ [`aws:updateVariable` – Updates a value for a runbook variable](automation-action-update-variable.md)
+ [`aws:waitForAwsResourceProperty` – Wait on an AWS resource property](automation-action-waitForAwsResourceProperty.md)
+ [Automation system variables](automation-variables.md)
## Properties shared by all actions
Common properties are parameters or options that are found in all actions. Some options define behavior for a step, such as how long to wait for a step to complete and what to do if the step fails. The following properties are common to all actions.
[description](#descriptProp)
Information you provide to describe the purpose of a runbook or a step.
Type: String
Required: No
[name](#nameProp)
An identifier that must be unique across all step names in the runbook.
Type: String
Allowed pattern: [a-zA-Z0-9\$1]\$1\$1
Required: Yes
[action](#actProp)
The name of the action the step is to run. [`aws:runCommand` – Run a command on a managed instance](automation-action-runcommand.md) is an example of an action you can specify here. This document provides detailed information about all available actions.
Type: String
Required: Yes
[maxAttempts](#maxProp)
The number of times the step should be retried in case of failure. If the value is greater than 1, the step isn't considered to have failed until all retry attempts have failed. The default value is 1.
Type: Integer
Required: No
[timeoutSeconds](#timeProp)
The timeout value for the step. If the timeout is reached and the value of `maxAttempts` is greater than 1, then the step isn't considered to have timed out until all retries have been attempted.
Type: Integer
Required: No
[onFailure](#failProp)
Indicates whether the automation should stop, continue, or go to a different step on failure. The default value for this option is abort.
Type: String
Valid values: Abort \$1 Continue \$1 step:*step\$1name*
Required: No
[onCancel](#canProp)
Indicates which step the automation should go to in the event that a user cancels the automation. Automation runs the cancellation workflow for a maximum of two minutes.
Type: String
Valid values: Abort \$1 step:*step\$1name*
Required: No
The `onCancel` property doesn't support moving to the following actions:
+ `aws:approve`
+ `aws:copyImage`
+ `aws:createImage`
+ `aws:createStack`
+ `aws:createTags`
+ `aws:loop`
+ `aws:pause`
+ `aws:runInstances`
+ `aws:sleep`
[isEnd](#endProp)
This option stops an automation at the end of a specific step. The automation stops if the step failed or succeeded. The default value is false.
Type: Boolean
Valid values: true \$1 false
Required: No
[nextStep](#nextProp)
Specifies which step in an automation to process next after successfully completing a step.
Type: String
Required: No
[isCritical](#critProp)
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. This property is only evaluated if you explicitly define it in your step. If the `onFailure` property is set to `Continue` in a step, the value defaults to false. Otherwise, the default value for this option is true.
Type: Boolean
Valid values: true \$1 false
Required: No
[inputs](#inProp)
The properties specific to the action.
Type: Map
Required: Yes
### Example
```
---
description: "Custom Automation 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
maxAttempts: 3
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.8
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
onCancel: step:startInstance
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
isCritical: true
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 }}"
```
# `aws:approve` – Pause an automation for manual approval
Temporarily pauses an automation until designated principals either approve or reject the action. After the required number of approvals is reached, the automation resumes. You can insert the approval step any place in the `mainSteps` section of your runbook.
**Note**
This action doesn't support multi-account and Region automations. The default timeout for this action is 7 days (604800 seconds) and the maximum value is 30 days (2592000 seconds). You can limit or extend the timeout by specifying the `timeoutSeconds` parameter for an `aws:approve` step.
In the following example, the `aws:approve` action temporarily pauses the automation until one approver either accepts or rejects the automation. Upon approval, the automation runs a simple PowerShell command.
------
#### [ YAML ]
```
---
description: RunInstancesDemo1
schemaVersion: '0.3'
assumeRole: "{{ assumeRole }}"
parameters:
assumeRole:
type: String
message:
type: String
mainSteps:
- name: approve
action: aws:approve
timeoutSeconds: 1000
onFailure: Abort
inputs:
NotificationArn: arn:aws:sns:us-east-2:12345678901:AutomationApproval
Message: "{{ message }}"
MinRequiredApprovals: 1
Approvers:
- arn:aws:iam::12345678901:user/AWS-User-1
- name: run
action: aws:runCommand
inputs:
InstanceIds:
- i-1a2b3c4d5e6f7g
DocumentName: AWS-RunPowerShellScript
Parameters:
commands:
- date
```
------
#### [ JSON ]
```
{
"description":"RunInstancesDemo1",
"schemaVersion":"0.3",
"assumeRole":"{{ assumeRole }}",
"parameters":{
"assumeRole":{
"type":"String"
},
"message":{
"type":"String"
}
},
"mainSteps":[
{
"name":"approve",
"action":"aws:approve",
"timeoutSeconds":1000,
"onFailure":"Abort",
"inputs":{
"NotificationArn":"arn:aws:sns:us-east-2:12345678901:AutomationApproval",
"Message":"{{ message }}",
"MinRequiredApprovals":1,
"Approvers":[
"arn:aws:iam::12345678901:user/AWS-User-1"
]
}
},
{
"name":"run",
"action":"aws:runCommand",
"inputs":{
"InstanceIds":[
"i-1a2b3c4d5e6f7g"
],
"DocumentName":"AWS-RunPowerShellScript",
"Parameters":{
"commands":[
"date"
]
}
}
}
]
}
```
------
You can approve or deny Automations that are waiting for approval in the console.
**To approve or deny waiting Automations**
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 option next to an Automation with a status of **Waiting**.
![\[Accessing the Approve/Deny Automation page\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/automation-approve-action-aws.png)
1. Choose **Approve/Deny**.
1. Review the details of the Automation.
1. Choose either **Approve** or **Deny**, type an optional comment, and then choose **Submit**.
**Input example**
------
#### [ YAML ]
```
NotificationArn: arn:aws:sns:us-west-1:12345678901:Automation-ApprovalRequest
Message: Please approve this step of the Automation.
MinRequiredApprovals: 3
Approvers:
- IamUser1
- IamUser2
- arn:aws:iam::12345678901:user/IamUser3
- arn:aws:iam::12345678901:role/IamRole
```
------
#### [ JSON ]
```
{
"NotificationArn":"arn:aws:sns:us-west-1:12345678901:Automation-ApprovalRequest",
"Message":"Please approve this step of the Automation.",
"MinRequiredApprovals":3,
"Approvers":[
"IamUser1",
"IamUser2",
"arn:aws:iam::12345678901:user/IamUser3",
"arn:aws:iam::12345678901:role/IamRole"
]
}
```
------
NotificationArn
The Amazon Resource Name (ARN of an Amazon Simple Notification Service (Amazon SNS) topic for Automation approvals. When you specify an `aws:approve` step in a runbook, Automation sends a message to this topic letting principals know that they must either approve or reject an Automation step. The title of the Amazon SNS topic must be prefixed with "Automation".
Type: String
Required: No
Message
The information you want to include in the Amazon SNS topic when the approval request is sent. The maximum message length is 4096 characters.
Type: String
Required: No
MinRequiredApprovals
The minimum number of approvals required to resume the automation. If you don't specify a value, the system defaults to one. The value for this parameter must be a positive number. The value for this parameter can't exceed the number of approvers defined by the `Approvers` parameter.
Type: Integer
Required: No
Approvers
A list of AWS authenticated principals who are able to either approve or reject the action. The maximum number of approvers is 10. You can specify principals by using any of the following formats:
+ A user name
+ A user ARN
+ An IAM role ARN
+ An IAM assume role ARN
Type: StringList
Required: Yes
EnhancedApprovals
This input is only used for Change Manager templates. A list of AWS authenticated principals who are able to either approve or reject the action, the type of IAM principal, and the minimum number of approvers. The following is an example:
```
schemaVersion: "0.3"
emergencyChange: false
autoApprovable: false
mainSteps:
- name: ApproveAction1
action: aws:approve
timeoutSeconds: 604800
inputs:
Message: Please approve this change request
MinRequiredApprovals: 3
EnhancedApprovals:
Approvers:
- approver: John Stiles
type: IamUser
minRequiredApprovals: 0
- approver: Ana Carolina Silva
type: IamUser
minRequiredApprovals: 0
- approver: GroupOfThree
type: IamGroup
minRequiredApprovals: 0
- approver: RoleOfTen
type: IamRole
minRequiredApprovals: 0
```
Type: StringList
Required: Yes
**Output**
ApprovalStatus
The approval status of the step. The status can be one of the following: Approved, Rejected, or Waiting. Waiting means that Automation is waiting for input from approvers.
Type: String
ApproverDecisions
A JSON map that includes the approval decision of each approver.
Type: MapList
# `aws:assertAwsResourceProperty` – Assert an AWS resource state or event state
The `aws:assertAwsResourceProperty` action allows you to assert a specific resource state or event state for a specific Automation step.
**Note**
The `aws:assertAwsResourceProperty` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
For more examples of how to use this action, see [Additional runbook examples](automation-document-examples.md).
**Input**
Inputs are defined by the API operation that you choose.
------
#### [ YAML ]
```
action: aws:assertAwsResourceProperty
inputs:
Service: The official namespace of the service
Api: The API operation or method name
API operation inputs or parameters: A value
PropertySelector: Response object
DesiredValues:
- Desired property values
```
------
#### [ JSON ]
```
{
"action": "aws:assertAwsResourceProperty",
"inputs": {
"Service":"The official namespace of the service",
"Api":"The API operation or method name",
"API operation inputs or parameters":"A value",
"PropertySelector": "Response object",
"DesiredValues": [
"Desired property values"
]
}
}
```
------
Service
The AWS service namespace that contains the API operation that you want to run. For example, the namespace for Systems Manager is `ssm`. The namespace for Amazon EC2 is `ec2`. You can view a list of supported AWS service namespaces in the [Available Services](https://docs.aws.amazon.com/cli/latest/reference/#available-services) section of the *AWS CLI Command Reference*.
Type: String
Required: Yes
Api
The name of the API operation that you want to run. 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).
Type: String
Required: Yes
API operation inputs
One or more API operation inputs. You can view the available inputs (also called parameters) 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 methods for Amazon RDS are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Choose the [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) method and scroll down to see the available parameters, such as **DBInstanceIdentifier**, **Name**, and **Values**. Use the following format to specify more than one input.
```
inputs:
Service: The official namespace of the service
Api: The API operation name
API input 1: A value
API Input 2: A value
API Input 3: A value
```
```
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}
```
Type: Determined by chosen API operation
Required: Yes
PropertySelector
The JSONPath to a specific attribute in the response object. You can view the response objects 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 methods for Amazon RDS are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Choose the [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) method and scroll down to the **Response Structure** section. **DBInstances** is listed as a response object.
Type: String
Required: Yes
DesiredValues
The expected status or state on which to continue the automation. If you specify a Boolean value, you must use a capital letter such as True or False.
Type: StringList
Required: Yes
# `aws:branch` – Run conditional automation steps
The `aws:branch` action allows you to create a dynamic automation that evaluates different choices in a single step and then jumps to a different step in the runbook based on the results of that evaluation.
When you specify the `aws:branch` action for a step, you specify `Choices` that the automation must evaluate. The `Choices` can be based on either a value that you specified in the `Parameters` section of the runbook, or a dynamic value generated as the output from the previous step. The automation evaluates each choice by using a Boolean expression. If the first choice is true, then the automation jumps to the step designated for that choice. If the first choice is false, the automation evaluates the next choice. The automation continues evaluating each choice until it process a true choice. 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.
The `aws:branch` action supports complex choice evaluations by using a combination of `And`, `Not`, and `Or` operators. For more information about how to use `aws:branch`, including example runbooks and examples that use different operators, see [Using conditional statements in runbooks](automation-branch-condition.md).
**Input**
Specify one or more `Choices` in a step. The `Choices` can be based on either a value that you specified in the `Parameters` section of the runbook, or a dynamic value generated as the output from the previous step. Here is a YAML sample that evaluates a parameter.
```
mainSteps:
- name: chooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runWindowsCommand
Variable: "{{Name of a parameter defined in the Parameters section. For example: OS_name}}"
StringEquals: windows
- NextStep: runLinuxCommand
Variable: "{{Name of a parameter defined in the Parameters section. For example: OS_name}}"
StringEquals: linux
Default:
sleep3
```
Here is a YAML sample that evaluates output from a previous step.
```
mainSteps:
- name: chooseOS
action: aws:branch
inputs:
Choices:
- NextStep: runPowerShellCommand
Variable: "{{Name of a response object. For example: GetInstance.platform}}"
StringEquals: Windows
- NextStep: runShellCommand
Variable: "{{Name of a response object. For example: GetInstance.platform}}"
StringEquals: Linux
Default:
sleep3
```
Choices
One or more expressions that the Automation should evaluate when determining the next step to process. 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. Or specify an output object from a previous step in the runbook. For more information about creating variables for `aws:branch`, see [About creating the output variable](automation-branch-condition.md#branch-action-output).
+ **Operation**: The criteria used to evaluate the choice. 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
The name of a step the automation should jump to if none of the `Choices` are true.
Type: String
Required: No
**Note**
The `aws:branch` action supports `And`, `Or`, and `Not` operators. For examples of `aws:branch` that use operators, see [Using conditional statements in runbooks](automation-branch-condition.md).
# `aws:changeInstanceState` – Change or assert instance state
Changes or asserts the state of the instance.
This action can be used in assert mode (doesn't run the API to change the state but verifies the instance is in the desired state.) To use assert mode, set the `CheckStateOnly` parameter to true. This mode is useful when running the Sysprep command on Windows Server, which is an asynchronous command that can run in the background for a long time. You can ensure that the instance is stopped before you create an Amazon Machine Image (AMI).
**Note**
The default timeout value for this action is 3600 seconds (one hour). You can limit or extend the timeout by specifying the `timeoutSeconds` parameter for an `aws:changeInstanceState` step.
**Note**
The `aws:changeInstanceState` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
------
#### [ YAML ]
```
name: stopMyInstance
action: aws:changeInstanceState
maxAttempts: 3
timeoutSeconds: 3600
onFailure: Abort
inputs:
InstanceIds:
- i-1234567890abcdef0
CheckStateOnly: true
DesiredState: stopped
```
------
#### [ JSON ]
```
{
"name":"stopMyInstance",
"action": "aws:changeInstanceState",
"maxAttempts": 3,
"timeoutSeconds": 3600,
"onFailure": "Abort",
"inputs": {
"InstanceIds": ["i-1234567890abcdef0"],
"CheckStateOnly": true,
"DesiredState": "stopped"
}
}
```
------
InstanceIds
The IDs of the instances.
Type: StringList
Required: Yes
CheckStateOnly
If false, sets the instance state to the desired state. If true, asserts the desired state using polling.
Default: `false`
Type: Boolean
Required: No
DesiredState
The desired state. When set to `running`, this action waits for the Amazon EC2 state to be `Running`, the Instance Status to be `OK`, and the System Status to be `OK` before completing.
Type: String
Valid values: `running` \$1 `stopped` \$1 `terminated`
Required: Yes
Force
If set, forces the instances to stop. The instances don't have an opportunity to flush file system caches or file system metadata. If you use this option, you must perform file system check and repair procedures. This option isn't recommended for EC2 instances for Windows Server.
Type: Boolean
Required: No
AdditionalInfo
Reserved.
Type: String
Required: No
**Output**
None
# `aws:copyImage` – Copy or encrypt an Amazon Machine Image
Copies an Amazon Machine Image (AMI) from any AWS Region into the current Region. This action can also encrypt the new AMI.
**Note**
The `aws:copyImage` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
This action supports most `CopyImage` parameters. For more information, see [CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CopyImage.html).
The following example creates a copy of an AMI in the Seoul region (`SourceImageID`: ami-0fe10819. `SourceRegion`: ap-northeast-2). The new AMI is copied to the region where you initiated the Automation action. The copied AMI will be encrypted because the optional `Encrypted` flag is set to `true`.
------
#### [ YAML ]
```
name: createEncryptedCopy
action: aws:copyImage
maxAttempts: 3
onFailure: Abort
inputs:
SourceImageId: ami-0fe10819
SourceRegion: ap-northeast-2
ImageName: Encrypted Copy of LAMP base AMI in ap-northeast-2
Encrypted: true
```
------
#### [ JSON ]
```
{
"name": "createEncryptedCopy",
"action": "aws:copyImage",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"SourceImageId": "ami-0fe10819",
"SourceRegion": "ap-northeast-2",
"ImageName": "Encrypted Copy of LAMP base AMI in ap-northeast-2",
"Encrypted": true
}
}
```
------
SourceRegion
The region where the source AMI exists.
Type: String
Required: Yes
SourceImageId
The AMI ID to copy from the source Region.
Type: String
Required: Yes
ImageName
The name for the new image.
Type: String
Required: Yes
ImageDescription
A description for the target image.
Type: String
Required: No
Encrypted
Encrypt the target AMI.
Type: Boolean
Required: No
KmsKeyId
The full Amazon Resource Name (ARN) of the AWS KMS key to use when encrypting the snapshots of an image during a copy operation. For more information, see [CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_copyimage.html).
Type: String
Required: No
ClientToken
A unique, case-sensitive identifier that you provide to ensure request idempotency. For more information, see [CopyImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_copyimage.html).
Type: String
Required: NoOutput
ImageId
The ID of the copied image.
ImageState
The state of the copied image.
Valid values: `available` \$1 `pending` \$1 `failed`
# `aws:createImage` – Create an Amazon Machine Image
Creates an Amazon Machine Image (AMI) from an instance that is either running, stopping, or stopped, and polls for the `ImageState` to be `available`.
**Note**
The `aws:createImage` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
This action supports the following `CreateImage` parameters. For more information, see [CreateImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_CreateImage.html).
------
#### [ YAML ]
```
name: createMyImage
action: aws:createImage
maxAttempts: 3
onFailure: Abort
inputs:
InstanceId: i-1234567890abcdef0
ImageName: AMI Created on{{global:DATE_TIME}}
NoReboot: true
ImageDescription: My newly created AMI
```
------
#### [ JSON ]
```
{
"name": "createMyImage",
"action": "aws:createImage",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"InstanceId": "i-1234567890abcdef0",
"ImageName": "AMI Created on{{global:DATE_TIME}}",
"NoReboot": true,
"ImageDescription": "My newly created AMI"
}
}
```
------
InstanceId
The ID of the instance.
Type: String
Required: Yes
ImageName
The name for the image.
Type: String
Required: Yes
ImageDescription
A description of the image.
Type: String
Required: No
NoReboot
A Boolean literal.
By default, Amazon Elastic Compute Cloud (Amazon EC2) attempts to shut down and reboot the instance before creating the image. If the **No Reboot** option is set to `true`, Amazon EC2 doesn't shut down the instance before creating the image. When this option is used, file system integrity on the created image can't be guaranteed.
If you don't want the instance to run after you create an AMI from it, first use the [`aws:changeInstanceState` – Change or assert instance state](automation-action-changestate.md) action to stop the instance, and then use this `aws:createImage` action with the **NoReboot** option set to `true`.
Type: Boolean
Required: No
BlockDeviceMappings
The block devices for the instance.
Type: Map
Required: NoOutput
ImageId
The ID of the newly created image.
Type: String
ImageState
The current state of the image. If the state is available, the image is successfully registered and can be used to launch an instance.
Type: String
# `aws:createStack` – Create an CloudFormation stack
Creates an AWS CloudFormation stack from a template.
**Note**
The `aws:createStack` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
For supplemental information about creating CloudFormation stacks, see [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html) in the *AWS CloudFormation API Reference*.
**Input**
------
#### [ YAML ]
```
name: makeStack
action: aws:createStack
maxAttempts: 1
onFailure: Abort
inputs:
Capabilities:
- CAPABILITY_IAM
StackName: myStack
TemplateURL: http://s3.amazonaws.com/amzn-s3-demo-bucket/myStackTemplate
TimeoutInMinutes: 5
Parameters:
- ParameterKey: LambdaRoleArn
ParameterValue: "{{LambdaAssumeRole}}"
- ParameterKey: createdResource
ParameterValue: createdResource-{{automation:EXECUTION_ID}}
```
------
#### [ JSON ]
```
{
"name": "makeStack",
"action": "aws:createStack",
"maxAttempts": 1,
"onFailure": "Abort",
"inputs": {
"Capabilities": [
"CAPABILITY_IAM"
],
"StackName": "myStack",
"TemplateURL": "http://s3.amazonaws.com/amzn-s3-demo-bucket/myStackTemplate",
"TimeoutInMinutes": 5,
"Parameters": [
{
"ParameterKey": "LambdaRoleArn",
"ParameterValue": "{{LambdaAssumeRole}}"
},
{
"ParameterKey": "createdResource",
"ParameterValue": "createdResource-{{automation:EXECUTION_ID}}"
}
}
}
```
------
Capabilities
A list of values that you specify before CloudFormation can create certain stacks. Some stack templates include resources that can affect permissions in your AWS account. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter.
Valid values include `CAPABILITY_IAM`, `CAPABILITY_NAMED_IAM`, and `CAPABILITY_AUTO_EXPAND`.
**CAPABILITY\$1IAM and CAPABILITY\$1NAMED\$1IAM**
If you have IAM resources, you can specify either capability. If you have IAM resources with custom names, you must specify `CAPABILITY_NAMED_IAM`. If you don't specify this parameter, this action returns an `InsufficientCapabilities` error. The following resources require you to specify either `CAPABILITY_IAM` or `CAPABILITY_NAMED_IAM`.
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-accesskey.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-accesskey.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-group.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-group.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-instanceprofile.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-instanceprofile.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-policy.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-policy.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-iam-role.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-user.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-user.html)
+ [https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-addusertogroup.html](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-iam-addusertogroup.html)
If your stack template contains these resources, we recommend that you review all permissions associated with them and edit their permissions, if necessary.
For more information, see [Acknowledging IAM Resources in CloudFormation Templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html#capabilities).
**CAPABILITY\$1AUTO\$1EXPAND**
Some template contain macros. Macros perform custom processing on templates; this can include simple actions like find-and-replace operations, all the way to extensive transformations of entire templates. Because of this, users typically create a change set from the processed template, so that they can review the changes resulting from the macros before actually creating the stack. If your stack template contains one or more macros, and you choose to create a stack directly from the processed template, without first reviewing the resulting changes in a change set, you must acknowledge this capability.
For more information, see [Using AWS CloudFormation Macros to Perform Custom Processing on Templates](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-macros.html) in the *AWS CloudFormation User Guide*.
Type: array of Strings
Valid Values: `CAPABILITY_IAM | CAPABILITY_NAMED_IAM | CAPABILITY_AUTO_EXPAND`
Required: No
ClientRequestToken
A unique identifier for this CreateStack request. Specify this token if you set maxAttempts in this step to a value greater than 1. By specifying this token, CloudFormation knows that you aren't attempting to create a new stack with the same name.
Type: String
Required: No
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: [a-zA-Z0-9][-a-zA-Z0-9]\$1
DisableRollback
Set to `true` to turn off rollback of the stack if stack creation failed.
Conditional: You can specify either the `DisableRollback` parameter or the `OnFailure` parameter, but not both.
Default: `false`
Type: Boolean
Required: No
NotificationARNs
The Amazon Simple Notification Service (Amazon SNS) topic ARNs for publishing stack-related events. You can find SNS topic ARNs using the Amazon SNS console, [https://console.aws.amazon.com/sns/v3/home](https://console.aws.amazon.com/sns/v3/home).
Type: array of Strings
Array Members: Maximum number of 5 items.
Required: No
OnFailure
Determines the action to take if stack creation failed. You must specify `DO_NOTHING`, `ROLLBACK`, or `DELETE`.
Conditional: You can specify either the `OnFailure` parameter or the `DisableRollback` parameter, but not both.
Default: `ROLLBACK`
Type: String
Valid Values:` DO_NOTHING | ROLLBACK | DELETE`
Required: No
Parameters
A list of `Parameter` structures that specify input parameters for the stack. For more information, see the [Parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Parameter.html) data type.
Type: array of [Parameter](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Parameter.html) objects
Required: No
ResourceTypes
The template resource types that you have permissions to work with for this create stack action. For example: `AWS::EC2::Instance`, `AWS::EC2::*`, or `Custom::MyCustomInstance`. Use the following syntax to describe template resource types.
+ For all AWS resources:
```
AWS::*
```
+ For all custom resources:
```
Custom::*
```
+ For a specific custom resource:
```
Custom::logical_ID
```
+ For all resources of a particular AWS service:
```
AWS::service_name::*
```
+ For a specific AWS resource:
```
AWS::service_name::resource_logical_ID
```
If the list of resource types doesn't include a resource that you're creating, the stack creation fails. By default, CloudFormation grants permissions to all resource types. IAM uses this parameter for CloudFormation-specific condition keys in IAM policies. For more information, see [Controlling Access with AWS Identity and Access Management](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-iam-template.html).
Type: array of Strings
Length Constraints: Minimum length of 1. Maximum length of 256.
Required: No
RoleARN
The Amazon Resource Name (ARN) of an IAM role that CloudFormation assumes to create the stack. CloudFormation uses the role's credentials to make calls on your behalf. CloudFormation always uses this role for all future operations on the stack. As long as users have permission to operate on the stack, CloudFormation uses this role even if the users don't have permission to pass it. Ensure that the role grants the least amount of privileges.
If you don't specify a value, CloudFormation uses the role that was previously associated with the stack. If no role is available, CloudFormation uses a temporary session that is generated from your user credentials.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Required: No
StackName
The name that is associated with the stack. The name must be unique in the Region in which you're creating the stack.
A stack name can contain only alphanumeric characters (case sensitive) and hyphens. It must start with an alphabetic character and can't be longer than 128 characters.
Type: String
Required: Yes
StackPolicyBody
Structure containing the stack policy body. For more information, see [Prevent Updates to Stack Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/protect-stack-resources.html).
Conditional: You can specify either the `StackPolicyBody` parameter or the `StackPolicyURL` parameter, but not both.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 16384.
Required: No
StackPolicyURL
Location of a file containing the stack policy. The URL must point to a policy located in an S3 bucket in the same region as the stack. The maximum file size allowed for the stack policy is 16 KB.
Conditional: You can specify either the `StackPolicyBody` parameter or the `StackPolicyURL` parameter, but not both.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1350.
Required: No
Tags
Key-value pairs to associate with this stack. CloudFormation also propagates these tags to the resources created in the stack. You can specify a maximum number of 10 tags.
Type: array of [Tag](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_Tag.html) objects
Required: No
TemplateBody
Structure containing the template body with a minimum length of 1 byte and a maximum length of 51,200 bytes. For more information, see [Template Anatomy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html).
Conditional: You can specify either the `TemplateBody` parameter or the `TemplateURL` parameter, but not both.
Type: String
Length Constraints: Minimum length of 1.
Required: No
TemplateURL
Location of a file containing the template body. The URL must point to a template that is located in an S3 bucket. The maximum size allowed for the template is 460,800 bytes. For more information, see [Template Anatomy](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html).
Conditional: You can specify either the `TemplateBody` parameter or the `TemplateURL` parameter, but not both.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 1024.
Required: No
TimeoutInMinutes
The amount of time that can pass before the stack status becomes `CREATE_FAILED`. If `DisableRollback` isn't set or is set to `false`, the stack will be rolled back.
Type: Integer
Valid Range: Minimum value of 1.
Required: No
## Outputs
StackId
Unique identifier of the stack.
Type: String
StackStatus
Current status of the stack.
Type: String
Valid Values: `CREATE_IN_PROGRESS | CREATE_FAILED | CREATE_COMPLETE | ROLLBACK_IN_PROGRESS | ROLLBACK_FAILED | ROLLBACK_COMPLETE | DELETE_IN_PROGRESS | DELETE_FAILED | DELETE_COMPLETE | UPDATE_IN_PROGRESS | UPDATE_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_COMPLETE | UPDATE_ROLLBACK_IN_PROGRESS | UPDATE_ROLLBACK_FAILED | UPDATE_ROLLBACK_COMPLETE_CLEANUP_IN_PROGRESS | UPDATE_ROLLBACK_COMPLETE | REVIEW_IN_PROGRESS`
Required: Yes
StackStatusReason
Success or failure message associated with the stack status.
Type: String
Required: No
For more information, see [CreateStack](https://docs.aws.amazon.com/AWSCloudFormation/latest/APIReference/API_CreateStack.html).
## Security considerations
Before you can use the `aws:createStack` action, you must assign the following policy to the IAM Automation assume role. For more information about the assume role, see [Task 1: Create a service role for Automation](automation-setup-iam.md#create-service-role).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"sqs:*",
"cloudformation:CreateStack",
"cloudformation:DescribeStacks"
],
"Resource":"*"
}
]
}
```
------
# `aws:createTags` – Create tags for AWS resources
Creates new tags for Amazon Elastic Compute Cloud (Amazon EC2) instances or AWS Systems Manager managed instances.
**Note**
The `aws:createTags` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
This action supports most Amazon EC2 `CreateTags` and Systems Manager `AddTagsToResource` parameters. For more information, see [CreateTags](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_createtags.html) and [AddTagsToResource](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/api_addtagstoresource.html).
The following example shows how to tag an Amazon Machine Image (AMI) and an instance as production resources for a particular department.
------
#### [ YAML ]
```
name: createTags
action: aws:createTags
maxAttempts: 3
onFailure: Abort
inputs:
ResourceType: EC2
ResourceIds:
- ami-9a3768fa
- i-02951acd5111a8169
Tags:
- Key: production
Value: ''
- Key: department
Value: devops
```
------
#### [ JSON ]
```
{
"name": "createTags",
"action": "aws:createTags",
"maxAttempts": 3,
"onFailure": "Abort",
"inputs": {
"ResourceType": "EC2",
"ResourceIds": [
"ami-9a3768fa",
"i-02951acd5111a8169"
],
"Tags": [
{
"Key": "production",
"Value": ""
},
{
"Key": "department",
"Value": "devops"
}
]
}
}
```
------
ResourceIds
The IDs of the resource(s) to be tagged. If resource type isn't “EC2”, this field can contain only a single item.
Type: String List
Required: Yes
Tags
The tags to associate with the resource(s).
Type: List of Maps
Required: Yes
ResourceType
The type of resource(s) to be tagged. If not supplied, the default value of “EC2” is used.
Type: String
Required: No
Valid Values: `EC2` \$1 `ManagedInstance` \$1 `MaintenanceWindow` \$1 `Parameter`
**Output**
None
# `aws:deleteImage` – Delete an Amazon Machine Image
Deletes the specified Amazon Machine Image (AMI) and all related snapshots.
**Note**
The `aws:deleteImage` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
This action supports only one parameter. For more information, see the documentation for [DeregisterImage](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeregisterImage.html) and [DeleteSnapshot](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DeleteSnapshot.html).
------
#### [ YAML ]
```
name: deleteMyImage
action: aws:deleteImage
maxAttempts: 3
timeoutSeconds: 180
onFailure: Abort
inputs:
ImageId: ami-12345678
```
------
#### [ JSON ]
```
{
"name": "deleteMyImage",
"action": "aws:deleteImage",
"maxAttempts": 3,
"timeoutSeconds": 180,
"onFailure": "Abort",
"inputs": {
"ImageId": "ami-12345678"
}
}
```
------
ImageId
The ID of the image to be deleted.
Type: String
Required: Yes
**Output**
None
# `aws:deleteStack` – Delete an CloudFormation stack
Deletes an AWS CloudFormation stack.
**Note**
The `aws:deleteStack` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
------
#### [ YAML ]
```
name: deleteStack
action: aws:deleteStack
maxAttempts: 1
onFailure: Abort
inputs:
StackName: "{{stackName}}"
```
------
#### [ JSON ]
```
{
"name":"deleteStack",
"action":"aws:deleteStack",
"maxAttempts":1,
"onFailure":"Abort",
"inputs":{
"StackName":"{{stackName}}"
}
}
```
------
ClientRequestToken
A unique identifier for this `DeleteStack` request. Specify this token if you plan to retry requests so that CloudFormation knows that you aren't attempting to delete a stack with the same name. You can retry `DeleteStack` requests to verify that CloudFormation received them.
Type: String
Length Constraints: Minimum length of 1. Maximum length of 128.
Pattern: [a-zA-Z][-a-zA-Z0-9]\$1
Required: No
RetainResources.member.N
This input applies only to stacks that are in a `DELETE_FAILED` state. A list of logical resource IDs for the resources you want to retain. During deletion, CloudFormation deletes the stack, but doesn't delete the retained resources.
Retaining resources is useful when you can't delete a resource, such as a non-empty S3 bucket, but you want to delete the stack.
Type: array of strings
Required: No
RoleARN
The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that CloudFormation assumes to create the stack. CloudFormation uses the role's credentials to make calls on your behalf. CloudFormation always uses this role for all future operations on the stack. As long as users have permission to operate on the stack, CloudFormation uses this role even if the users don't have permission to pass it. Ensure that the role grants the least amount of privileges.
If you don't specify a value, CloudFormation uses the role that was previously associated with the stack. If no role is available, CloudFormation uses a temporary session that is generated from your user credentials.
Type: String
Length Constraints: Minimum length of 20. Maximum length of 2048.
Required: No
StackName
The name or the unique stack ID that is associated with the stack.
Type: String
Required: Yes
## Security considerations
Before you can use the `aws:deleteStack` action, you must assign the following policy to the IAM Automation assume role. For more information about the assume role, see [Task 1: Create a service role for Automation](automation-setup-iam.md#create-service-role).
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"sqs:*",
"cloudformation:DeleteStack",
"cloudformation:DescribeStacks"
],
"Resource":"*"
}
]
}
```
------
# `aws:executeAutomation` – Run another automation
Runs a secondary automation by calling a secondary runbook. With this action, you can create runbooks for your most common operations, and reference those runbooks during an automation. This action can simplify your runbooks by removing the need to duplicate steps across similar runbooks.
The secondary automation runs in the context of the user who initiated the primary automation. This means that the secondary automation uses the same AWS Identity and Access Management (IAM) role or user as the user who started the first automation.
**Important**
If you specify parameters in a secondary automation that use an assume role (a role that uses the iam:passRole policy), then the user or role that initiated the primary automation must have permission to pass the assume role specified in the secondary automation. For more information about setting up an assume role for Automation, see [Create the service roles for Automation using the console](automation-setup-iam.md).
**Input**
------
#### [ YAML ]
```
name: Secondary_Automation
action: aws:executeAutomation
maxAttempts: 3
timeoutSeconds: 3600
onFailure: Abort
inputs:
DocumentName: secondaryAutomation
RuntimeParameters:
instanceIds:
- i-1234567890abcdef0
```
------
#### [ JSON ]
```
{
"name":"Secondary_Automation",
"action":"aws:executeAutomation",
"maxAttempts":3,
"timeoutSeconds":3600,
"onFailure":"Abort",
"inputs":{
"DocumentName":"secondaryAutomation",
"RuntimeParameters":{
"instanceIds":[
"i-1234567890abcdef0"
]
}
}
}
```
------
DocumentName
The name of the secondary runbook to run during the step. For runbooks in the same AWS account, specify the runbook name. For runbooks shared from a different AWS account, specify the Amazon Resource Name (ARN) of the runbook. For information about using shared runbooks, see [Using shared SSM documents](documents-ssm-sharing.md#using-shared-documents).
Type: String
Required: Yes
DocumentVersion
The version of the secondary runbook to run. If not specified, Automation runs the default runbook version.
Type: String
Required: No
MaxConcurrency
The maximum number of targets allowed to run this task in parallel. You can specify a number, such as 10, or a percentage, such as 10%.
Type: String
Required: No
MaxErrors
The number of errors that are allowed before the system stops running the automation on additional targets. You can specify either an absolute number of errors, for example 10, or a percentage of the target set, for example 10%. If you specify 3, for example, the system stops running the automation when the fourth error is received. If you specify 0, then the system stops running the automation on additional targets after the first error result is returned. If you run an automation on 50 resources and set `MaxErrors` to 10%, then the system stops running the automation on additional targets when the sixth error is received.
Automations that are already running when the `MaxErrors` threshold is reached are allowed to complete, but some of these automations may fail as well. If you need to ensure that there won't be more failed automations than the specified `MaxErrors`, set `MaxConcurrency` to 1 so the automations proceed one at a time.
Type: String
Required: No
RuntimeParameters
Required parameters for the secondary runbook. The mapping uses the following format: \$1"parameter1" : "value1", "parameter2" : "value2" \$1
Type: Map
Required: No
Tags
Optional metadata that you assign to a resource. You can specify a maximum of five tags for an automation.
Type: MapList
Required: No
TargetLocations
A location is a combination of AWS Regions and/or AWS accounts where you want to run the automation. A minimum number of 1 item must be specified and a maximum number of 100 items can be specified. When specifying a value for this parameter, outputs aren't returned to the parent automation. If needed, you must make subsequent calls to API operations to retrieve the output from child automations.
Type: MapList
Required: No
TargetMaps
A list of key-value mappings of document parameters to target resources. Both `Targets` and `TargetMaps` can't be specified together.
Type: MapList
Required: No
TargetParameterName
The name of the parameter used as the target resource for the rate-controlled automation. Required if you specify `Targets`.
Type: String
Required: No
Targets
A list of key-value mappings to target resources. Required if you specify `TargetParameterName`.
Type: MapList
Required: NoOutput
Output
The output generated by the secondary automation. You can reference the output by using the following format: *Secondary\$1Automation\$1Step\$1Name*.Output
Type: StringList
Here is an example:
```
- name: launchNewWindowsInstance
action: 'aws:executeAutomation'
onFailure: Abort
inputs:
DocumentName: launchWindowsInstance
nextStep: getNewInstanceRootVolume
- name: getNewInstanceRootVolume
action: 'aws:executeAwsApi'
onFailure: Abort
inputs:
Service: ec2
Api: DescribeVolumes
Filters:
- Name: attachment.device
Values:
- /dev/sda1
- Name: attachment.instance-id
Values:
- '{{launchNewWindowsInstance.Output}}'
outputs:
- Name: rootVolumeId
Selector: '$.Volumes[0].VolumeId'
Type: String
nextStep: snapshotRootVolume
- name: snapshotRootVolume
action: 'aws:executeAutomation'
onFailure: Abort
inputs:
DocumentName: AWS-CreateSnapshot
RuntimeParameters:
VolumeId:
- '{{getNewInstanceRootVolume.rootVolumeId}}'
Description:
- 'Initial root snapshot for {{launchNewWindowsInstance.Output}}'
```
ExecutionId
The ID of the secondary automation.
Type: String
Status
The status of the secondary automation.
Type: String
# `aws:executeAwsApi` – Call and run AWS API operations
Calls and runs AWS API operations. Most API operations are supported, although not all API operations have been tested. Streaming API operations, such as the [GetObject](https://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectGET.html) operation, aren't supported. If you're not sure if an API operation you want to use is a streaming operation, review the [Boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html) documentation for the service to determine if an API requires streaming inputs or outputs. We regularly update the Boto3 version used by this action. However, following the release of a new Boto3 version it can take up to a few weeks for changes to be reflected in this action. Each `aws:executeAwsApi` action can run up to a maximum duration of 25 seconds. For more examples of how to use this action, see [Additional runbook examples](automation-document-examples.md).
**Note**
The `aws:executeAwsApi` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Inputs**
Inputs are defined by the API operation that you choose.
------
#### [ YAML ]
```
action: aws:executeAwsApi
inputs:
Service: The official namespace of the service
Api: The API operation or method name
API operation inputs or parameters: A value
outputs: # These are user-specified outputs
- Name: The name for a user-specified output key
Selector: A response object specified by using jsonpath format
Type: The data type
```
------
#### [ JSON ]
```
{
"action":"aws:executeAwsApi",
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation or method name",
"API operation inputs or parameters":"A value"
},
"outputs":[ These are user-specified outputs
{
"Name":"The name for a user-specified output key",
"Selector":"A response object specified by using JSONPath format",
"Type":"The data type"
}
]
}
```
------
Service
The AWS service namespace that contains the API operation that you want to run. You can view a list of supported AWS service namespaces in [Available services](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/index.html) of the AWS SDK for Python (Boto3). The namespace can be found in the **Client** section. For example, the namespace for Systems Manager is `ssm`. The namespace for Amazon Elastic Compute Cloud (Amazon EC2) is `ec2`.
Type: String
Required: Yes
Api
The name of the API operation that you want to run. 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).
Type: String
Required: Yes
API operation inputs
One or more API operation inputs. You can view the available inputs (also called parameters) 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 methods for Amazon RDS are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Choose the [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) method and scroll down to see the available parameters, such as **DBInstanceIdentifier**, **Name**, and **Values**.
```
inputs:
Service: The official namespace of the service
Api: The API operation name
API input 1: A value
API Input 2: A value
API Input 3: A value
```
```
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}
```
Type: Determined by chosen API operation
Required: Yes
**Outputs**
Outputs are specified by the user based on the response from the chosen API operation.
Name
A name for the output.
Type: String
Required: Yes
Selector
The JSONPath to a specific attribute in the response object. You can view the response objects 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 methods for Amazon RDS are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Choose the [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) method and scroll down to the **Response Structure** section. **DBInstances** is listed as a response object.
Type: Integer, Boolean, String, StringList, StringMap, or MapList
Required: Yes
Type
The data type for the response element.
Type: Varies
Required: Yes
# `aws:executeScript` – Run a script
Runs the Python or PowerShell script provided using the specified runtime and handler. Each `aws:executeScript` action can run up to a maximum duration of 600 seconds (10 minutes). You can limit the timeout by specifying the `timeoutSeconds` parameter for an `aws:executeScript` step.
Use return statements in your function to add outputs to your output payload. For examples of defining outputs for your `aws:executeScript` action, see [Example 2: Scripted runbook](automation-authoring-runbooks-scripted-example.md). You can also send the output from `aws:executeScript` actions in your runbooks to the Amazon CloudWatch Logs log group you specify. For more information, see [Logging Automation action output with CloudWatch Logs](automation-action-logging.md).
If you want to send output from `aws:executeScript` actions to CloudWatch Logs, or if the scripts you specify for `aws:executeScript` actions call AWS API operations, an AWS Identity and Access Management (IAM) service role (or assume role) is always required to run the runbook.
**Note**
The `aws:executeScript` action does not support automatic throttling retry. If your script makes AWS API calls that might be throttled, you must implement your own retry logic in your script code.
The `aws:executeScript` action contains the following preinstalled PowerShell Core modules:
+ Microsoft.PowerShell.Host
+ Microsoft.PowerShell.Management
+ Microsoft.PowerShell.Security
+ Microsoft.PowerShell.Utility
+ PackageManagement
+ PowerShellGet
To use PowerShell Core modules that aren't preinstalled, your script must install the module with the `-Force` flag, as shown in the following command. The `AWSPowerShell.NetCore` module isn't supported. Replace *ModuleName* with the module you want to install.
```
Install-Module ModuleName -Force
```
To use PowerShell Core cmdlets in your script, we recommend using the `AWS.Tools` modules, as shown in the following commands. Replace each *example resource placeholder* with your own information.
+ Amazon S3 cmdlets.
```
Install-Module AWS.Tools.S3 -Force
Get-S3Bucket -BucketName amzn-s3-demo-bucket
```
+ Amazon EC2 cmdlets.
```
Install-Module AWS.Tools.EC2 -Force
Get-EC2InstanceStatus -InstanceId instance-id
```
+ Common, or service independent AWS Tools for Windows PowerShell cmdlets.
```
Install-Module AWS.Tools.Common -Force
Get-AWSRegion
```
If your script initializes new objects in addition to using PowerShell Core cmdlets, you must also import the module as shown in the following command.
```
Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2
$tag = New-Object Amazon.EC2.Model.Tag
$tag.Key = "Tag"
$tag.Value = "TagValue"
New-EC2Tag -Resource i-02573cafcfEXAMPLE -Tag $tag
```
For examples of installing and importing `AWS.Tools` modules, and using PowerShell Core cmdlets in runbooks, see [Visual design experience for Automation runbooks](automation-visual-designer.md).
**Input**
Provide the information required to run your script. Replace each *example resource placeholder* with your own information.
**Note**
The attachment for a Python script can be a .py file or a .zip file that contains the script. PowerShell scripts must be stored in .zip files.
------
#### [ YAML ]
```
action: "aws:executeScript"
inputs:
Runtime: runtime
Handler: "functionName"
InputPayload:
scriptInput: '{{parameterValue}}'
Script: |-
def functionName(events, context):
...
Attachment: "scriptAttachment.zip"
```
------
#### [ JSON ]
```
{
"action": "aws:executeScript",
"inputs": {
"Runtime": "runtime",
"Handler": "functionName",
"InputPayload": {
"scriptInput": "{{parameterValue}}"
},
"Attachment": "scriptAttachment.zip"
}
}
```
------
Runtime
The runtime language to be used for running the provided script. `aws:executeScript` supports the runtimes in the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/automation-action-executeScript.html)
Type: String
Required: Yes
For python runtimes, the environment provides 512MB of memory and 512MB of disk space. For PowerShell runtimes, the environment provides 1024MB of memory and 512MB of disk space.
Handler
The name of your function. You must ensure the function defined in the handler has two parameters, `events` and `context`. The PowerShell runtime does not support this parameter.
Type: String
Required: Yes (Python) \$1 Not supported (PowerShell)
InputPayload
A JSON or YAML object that will be passed to the first parameter of the handler. This can be used to pass input data to the script.
Type: String
Required: No
```
description: Tag an instance
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.'
InstanceId:
type: String
description: (Required) The ID of the EC2 instance you want to tag.
mainSteps:
- name: tagInstance
action: 'aws:executeScript'
inputs:
Runtime: "python3.11"
Handler: tagInstance
InputPayload:
instanceId: '{{InstanceId}}'
Script: |-
def tagInstance(events,context):
import boto3
#Initialize client
ec2 = boto3.client('ec2')
instanceId = events['instanceId']
tag = {
"Key": "Env",
"Value": "ExamplePython"
}
print(f"Adding tag {tag} to instance id {instanceId}")
ec2.create_tags(
Resources=[instanceId],
Tags=[tag]
)
return tag
outputs:
- Type: String
Name: TagKey
Selector: $.Payload.Key
outputs:
- tagInstance.TagKey
```
```
description: Tag an instance
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.
InstanceId:
type: String
description: (Required) The ID of the EC2 instance you want to tag.
mainSteps:
- name: tagInstance
action: aws:executeScript
isEnd: true
inputs:
Runtime: PowerShell 7.4
InputPayload:
instanceId: '{{InstanceId}}'
Script: |-
Install-Module AWS.Tools.EC2 -Force
Import-Module AWS.Tools.EC2
$input = $env:InputPayload | ConvertFrom-Json
$tag = New-Object Amazon.EC2.Model.Tag
$tag.Key = "Env"
$tag.Value = "ExamplePowerShell"
Write-Information "Adding tag key: $($tag.Key) and value: $($tag.Value) to instance id $($input.instanceId)"
New-EC2Tag -Resource $input.instanceId -Tag $tag
return $tag
outputs:
- Type: String
Name: TagKey
Selector: $.Payload.Key
outputs:
- tagInstance.TagKey
```
Script
An embedded script that you want to run during the automation.
Type: String
Required: No (Python) \$1 Yes (PowerShell)
Attachment
The name of a standalone script file or .zip file that can be invoked by the action. Specify the same value as the `Name` of the document attachment file you specify in the `Attachments` request parameter. For more information, see [Attachments](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CreateDocument.html#systemsmanager-CreateDocument-request-Attachments) in the *AWS Systems Manager API Reference*. If you're providing a script using an attachment, you must also define a `files` section in the top-level elements of your runbook. For more information, see [Schema version 0.3](documents-schemas-features.md#automation-doc-syntax-examples).
To invoke a file for Python, use the `filename.method_name` format in `Handler`.
The attachment for a Python script can be a .py file or a .zip file that contains the script. PowerShell scripts must be stored in .zip files.
When including Python libraries in your attachment, we recommend adding an empty `__init__.py` file in each module directory. This allows you to import the modules from the library in your attachment within your script content. For example: `from library import module`
Type: String
Required: NoOutput
Payload
The JSON representation of the object returned by your function. Up to 100KB is returned. If you output a list, a maximum of 100 items is returned.
## Using attachments with aws:executeScript
Attachments provide a powerful way to package and reuse complex scripts, multiple modules, and external dependencies with your `aws:executeScript` actions. Use attachments when you need to:
+ Package multiple Python modules or PowerShell scripts together.
+ Reuse the same script logic across multiple runbooks.
+ Include external libraries or dependencies with your scripts.
+ Keep your runbook definition clean by separating complex script logic.
+ Share script packages across teams or automation workflows.
### Attachment structure and packaging
You can attach either single files or zip packages containing multiple files. The structure depends on your use case:
**Single file attachments**
For simple scripts, you can attach a single `.py` file (Python) or a `.zip` file containing a single PowerShell script.
**Multi-module packages**
For complex automation that requires multiple modules, create a zip package with the following recommended structure:
```
my-automation-package.zip
├── main.py # Entry point script
├── utils/
│ ├── __init__.py # Required for Python module imports
│ ├── helper_functions.py # Utility functions
│ └── aws_operations.py # AWS-specific operations
├── config/
│ ├── __init__.py
│ └── settings.py # Configuration settings
└── requirements.txt # Optional: document dependencies
```
**Important**
For Python packages, you must include an empty `__init__.py` file in each directory that contains Python modules. This allows you to import modules using standard Python import syntax like `from utils import helper_functions`.
**PowerShell package structure**
PowerShell attachments must be packaged in zip files with the following structure:
```
my-powershell-package.zip
├── Main.ps1 # Entry point script
├── Modules/
│ ├── HelperFunctions.ps1 # Utility functions
│ └── AWSOperations.ps1 # AWS-specific operations
└── Config/
└── Settings.ps1 # Configuration settings
```
### Creating runbooks with attachments
Follow these steps to create runbooks that use attachments:
1. **Upload your attachment to Amazon S3**
Upload your script file or zip package to an S3 bucket that your automation role can access. Note the S3 URI for use in the next step.
```
aws s3 cp my-automation-package.zip s3://my-automation-bucket/scripts/
```
1. **Calculate the attachment checksum**
Calculate the SHA-256 checksum of your attachment file for security verification:
```
# Linux/macOS
shasum -a 256 my-automation-package.zip
# Windows PowerShell
Get-FileHash -Algorithm SHA256 my-automation-package.zip
```
1. **Define the files section in your runbook**
Add a `files` section at the top level of your runbook to reference your attachment:
```
files:
my-automation-package.zip:
checksums:
sha256: "your-calculated-checksum-here"
```
1. **Reference the attachment in your executeScript step**
Use the `Attachment` parameter to reference your uploaded file:
```
- name: runMyScript
action: aws:executeScript
inputs:
Runtime: python3.11
Handler: main.process_data
Attachment: my-automation-package.zip
InputPayload:
inputData: "{{InputParameter}}"
```
## aws:executeScript attachment examples
The following examples demonstrate different ways to use attachments with the `aws:executeScript` action.
### Example 1: Single file attachment
This example shows how to use a single Python file as an attachment to process EC2 instance data.
**Attachment file: process\$1instance.py**
Create a Python file with the following content:
```
import boto3
import json
def process_instance_data(events, context):
"""Process EC2 instance data and return formatted results."""
try:
instance_id = events.get('instanceId')
if not instance_id:
raise ValueError("instanceId is required")
ec2 = boto3.client('ec2')
# Get instance details
response = ec2.describe_instances(InstanceIds=[instance_id])
instance = response['Reservations'][0]['Instances'][0]
# Format the response
result = {
'instanceId': instance_id,
'instanceType': instance['InstanceType'],
'state': instance['State']['Name'],
'availabilityZone': instance['Placement']['AvailabilityZone'],
'tags': {tag['Key']: tag['Value'] for tag in instance.get('Tags', [])}
}
print(f"Successfully processed instance {instance_id}")
return result
except Exception as e:
print(f"Error processing instance: {str(e)}")
raise
```
**Complete runbook**
Here's the complete runbook that uses the single file attachment:
```
description: Process EC2 instance data using single file attachment
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
description: (Required) IAM role for automation execution
InstanceId:
type: String
description: (Required) EC2 instance ID to process
files:
process_instance.py:
checksums:
sha256: "abc123def456..."
mainSteps:
- name: processInstance
action: aws:executeScript
inputs:
Runtime: python3.11
Handler: process_instance.process_instance_data
Attachment: process_instance.py
InputPayload:
instanceId: '{{InstanceId}}'
outputs:
- Type: StringMap
Name: InstanceData
Selector: $.Payload
outputs:
- processInstance.InstanceData
```
### Example 2: Multi-module package
This example demonstrates using a zip package containing multiple Python modules for complex S3 bucket operations.
**Package structure**
Create a zip package with the following structure:
```
s3-operations.zip
├── main.py
├── utils/
│ ├── __init__.py
│ ├── s3_helper.py
│ └── validation.py
└── config/
├── __init__.py
└── settings.py
```
**main.py (entry point)**
The main script that orchestrates the operations:
```
from utils.s3_helper import S3Operations
from utils.validation import validate_bucket_name
from config.settings import get_default_settings
def cleanup_s3_bucket(events, context):
"""Clean up S3 bucket based on specified criteria."""
try:
bucket_name = events.get('bucketName')
max_age_days = events.get('maxAgeDays', 30)
# Validate inputs
if not validate_bucket_name(bucket_name):
raise ValueError(f"Invalid bucket name: {bucket_name}")
# Initialize S3 operations
s3_ops = S3Operations()
settings = get_default_settings()
# Perform cleanup
deleted_objects = s3_ops.delete_old_objects(
bucket_name,
max_age_days,
settings['dry_run']
)
result = {
'bucketName': bucket_name,
'deletedCount': len(deleted_objects),
'deletedObjects': deleted_objects[:10], # Return first 10 for brevity
'dryRun': settings['dry_run']
}
print(f"Cleanup completed for bucket {bucket_name}")
return result
except Exception as e:
print(f"Error during S3 cleanup: {str(e)}")
raise
```
## Troubleshooting aws:executeScript attachments
Use the following guidance to resolve common issues with `aws:executeScript` attachments:
**Module import errors**
If you receive import errors when using multi-module packages:
+ Ensure you have included an empty `__init__.py` file in each directory containing Python modules.
+ Verify that your import statements match the actual file and directory structure in your zip package.
+ Use relative imports (e.g., `from .utils import helper`) or absolute imports (e.g., `from utils import helper`) consistently.
**Attachment not found errors**
If your automation fails to find the attachment:
+ Verify that the `Attachment` parameter value exactly matches the key in your `files` section.
+ Check that your S3 bucket path and file name are correct in the `files` section.
+ Ensure your automation role has `s3:GetObject` permission for the attachment S3 location.
+ Verify that the checksum in your runbook matches the actual file checksum.
**Handler function errors**
If you receive handler-related errors:
+ For Python: Use the format `filename.function_name` in the `Handler` parameter (e.g., `main.process_data`).
+ Ensure your handler function accepts exactly two parameters: `events` and `context`.
+ For PowerShell: Do not specify a `Handler` parameter; the script runs directly.
**Script execution failures**
If your script fails during execution:
+ Check the automation execution history for detailed error messages and stack traces.
+ Use `print()` statements (Python) or `Write-Information` (PowerShell) to add debugging output.
+ Verify that all required AWS permissions are granted to your automation role.
+ Test your script logic locally before packaging it as an attachment.
**Exit codes and error handling**
To properly handle errors and return exit codes:
+ In Python: Use `raise Exception("error message")` to indicate script failure.
+ In PowerShell: Use `throw "error message"` or `Write-Error` to indicate failure.
+ Return structured data from your functions to provide detailed success/failure information.
+ Use try-catch blocks to handle exceptions gracefully and provide meaningful error messages.
# `aws:executeStateMachine` – Run an AWS Step Functions state machine
Runs an AWS Step Functions state machine.
**Note**
The `aws:executeStateMachine` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
This action supports most parameters for the Step Functions [StartExecution](https://docs.aws.amazon.com/step-functions/latest/apireference/API_StartExecution.html) API operation.
**Required AWS Identity and Access Management (IAM) permissions**
+ `states:DescribeExecution`
+ `states:StartExecution`
+ `states:StopExecution`
------
#### [ YAML ]
```
name: executeTheStateMachine
action: aws:executeStateMachine
inputs:
stateMachineArn: StateMachine_ARN
input: '{"parameters":"values"}'
name: name
```
------
#### [ JSON ]
```
{
"name": "executeTheStateMachine",
"action": "aws:executeStateMachine",
"inputs": {
"stateMachineArn": "StateMachine_ARN",
"input": "{\"parameters\":\"values\"}",
"name": "name"
}
}
```
------
stateMachineArn
The Amazon Resource Name (ARN) of the Step Functions state machine.
Type: String
Required: Yes
name
The name of the execution.
Type: String
Required: No
input
A string that contains the JSON input data for the execution.
Type: String
Required: No
**Outputs**
The following outputs are predefined for this action.
executionArn
The ARN of the execution.
Type: String
input
The string that contains the JSON input data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding..
Type: String
name
The name of the execution.
Type: String
output
The JSON output data of the execution. Length constraints apply to the payload size, and are expressed as bytes in UTF-8 encoding.
Type: String
startDate
The date the execution is started.
Type: String
stateMachineArn
The ARN of the executed stated machine.
Type: String
status
The current status of the execution.
Type: String
stopDate
If the execution has already ended, the date the execution stopped.
Type: String
# `aws:invokeWebhook` – Invoke an Automation webhook integration
Invokes the specified Automation webhook integration. For information about creating Automation integrations, see [Creating webhook integrations for Automation](creating-webhook-integrations.md).
**Note**
The `aws:invokeWebhook` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Note**
To use the `aws:invokeWebhook` action, your user or service role must allow the following actions:
ssm:GetParameter
kms:Decrypt
Permission for the AWS Key Management Service (AWS KMS) `Decrypt` operation is only required if you use a customer managed key to encrypt the parameter for your integration.
**Input**
Provide the information for the Automation integration you want to invoke.
------
#### [ YAML ]
```
action: "aws:invokeWebhook"
inputs:
IntegrationName: "exampleIntegration"
Body: "Request body"
```
------
#### [ JSON ]
```
{
"action": "aws:invokeWebhook",
"inputs": {
"IntegrationName": "exampleIntegration",
"Body": "Request body"
}
}
```
------
IntegrationName
The name of the Automation integration. For example, `exampleIntegration`. The integration you specify must already exist.
Type: String
Required: Yes
Body
The payload you want to send when your webhook integration is invoked.
Type: String
Required: NoOutput
Response
The text received from the webhook provider response.
ResponseCode
The HTTP status code received from the webhook provider response.
# `aws:invokeLambdaFunction` – Invoke an AWS Lambda function
Invokes the specified AWS Lambda function.
**Note**
Each `aws:invokeLambdaFunction` action can run up to a maximum duration of 300 seconds (5 minutes). You can limit the timeout by specifying the `timeoutSeconds` parameter for an `aws:invokeLambdaFunction` step.
**Note**
The `aws:invokeLambdaFunction` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
This action supports most invoked parameters for the Lambda service. For more information, see [Invoke](https://docs.aws.amazon.com/lambda/latest/dg/API_Invoke.html).
------
#### [ YAML ]
```
name: invokeMyLambdaFunction
action: aws:invokeLambdaFunction
maxAttempts: 3
timeoutSeconds: 120
onFailure: Abort
inputs:
FunctionName: MyLambdaFunction
```
------
#### [ JSON ]
```
{
"name": "invokeMyLambdaFunction",
"action": "aws:invokeLambdaFunction",
"maxAttempts": 3,
"timeoutSeconds": 120,
"onFailure": "Abort",
"inputs": {
"FunctionName": "MyLambdaFunction"
}
}
```
------
FunctionName
The name of the Lambda function. This function must exist.
Type: String
Required: Yes
Qualifier
The function version or alias name.
Type: String
Required: No
InvocationType
The invocation type. The default value is `RequestResponse`.
Type: String
Valid values: `Event` \$1 `RequestResponse` \$1 `DryRun`
Required: No
LogType
If the default value is `Tail`, the invocation type must be `RequestResponse`. Lambda returns the last 4 KB of log data produced by your Lambda function, base64-encoded.
Type: String
Valid values: `None` \$1 `Tail`
Required: No
ClientContext
The client-specific information.
Required: No
InputPayload
A YAML or JSON object that is passed to the first parameter of the handler. You can use this input to pass data to the function. This input provides more flexibility and support than the legacy `Payload` input. If you define both `InputPayload` and `Payload` for the action, `InputPayload` takes precedence and the `Payload` value is not used.
Type: StringMap
Required: No
Payload
A JSON string that's passed to the first parameter of the handler. This can be used to pass input data to the function. We recommend using `InputPayload` input for added functionality.
Type: String
Required: NoOutput
StatusCode
The HTTP status code.
FunctionError
If present, it indicates that an error occurred while executing the function. Error details are included in the response payload.
LogResult
The base64-encoded logs for the Lambda function invocation. Logs are present only if the invocation type is `RequestResponse`, and the logs were requested.
Payload
The JSON representation of the object returned by the Lambda function. Payload is present only if the invocation type is `RequestResponse`.
The following is a portion from the `AWS-PatchInstanceWithRollback` runbook demonstrating how to reference outputs from the `aws:invokeLambdaFunction` action.
------
#### [ YAML ]
```
- name: IdentifyRootVolume
action: aws:invokeLambdaFunction
inputs:
FunctionName: "IdentifyRootVolumeLambda-{{automation:EXECUTION_ID}}"
Payload: '{"InstanceId": "{{InstanceId}}"}'
- name: PrePatchSnapshot
action: aws:executeAutomation
inputs:
DocumentName: "AWS-CreateSnapshot"
RuntimeParameters:
VolumeId: "{{IdentifyRootVolume.Payload}}"
Description: "ApplyPatchBaseline restoration case contingency"
```
------
#### [ JSON ]
```
{
"name": "IdentifyRootVolume",
"action": "aws:invokeLambdaFunction",
"inputs": {
"FunctionName": "IdentifyRootVolumeLambda-{{automation:EXECUTION_ID}}",
"Payload": "{\"InstanceId\": \"{{InstanceId}}\"}"
}
},
{
"name": "PrePatchSnapshot",
"action": "aws:executeAutomation",
"inputs": {
"DocumentName": "AWS-CreateSnapshot",
"RuntimeParameters": {
"VolumeId": "{{IdentifyRootVolume.Payload}}",
"Description": "ApplyPatchBaseline restoration case contingency"
}
}
}
```
------
# `aws:loop` – Iterate over steps in an automation
This action iterates over a subset of steps in an automation runbook. You can choose a `do while` or `for each` style loop. To construct a `do while` loop, use the `LoopCondition` input parameter. To construct a `for each` loop, use the `Iterators` and `IteratorDataType` input parameters. When using an `aws:loop` action, only specify either the `Iterators` or `LoopCondition` input parameter. The maximum number of iterations is 100.
The `onCancel` property can only be used for steps defined within a loop. The `onCancel` property isn't supported for the `aws:loop` action. The `onFailure` property can be used for an `aws:loop` action, however it will only be used if an unexpected error occurs causing the step to fail. If you define `onFailure` properties for the steps within a loop, the `aws:loop` action inherits those properties and reacts accordingly when a failure occurs.
**Examples**
The following are examples of how to construct the different types of loop actions.
------
#### [ do while ]
```
name: RepeatMyLambdaFunctionUntilOutputIsReturned
action: aws:loop
inputs:
Steps:
- name: invokeMyLambda
action: aws:invokeLambdaFunction
inputs:
FunctionName: LambdaFunctionName
outputs:
- Name: ShouldRetry
Selector: $.Retry
Type: Boolean
LoopCondition:
Variable: "{{ invokeMyLambda.ShouldRetry }}"
BooleanEquals: true
MaxIterations: 3
```
------
#### [ for each ]
```
name: stopAllInstancesWithWaitTime
action: aws:loop
inputs:
Iterators: "{{ DescribeInstancesStep.InstanceIds }}"
IteratorDataType: "String"
Steps:
- name: stopOneInstance
action: aws:changeInstanceState
inputs:
InstanceIds:
- "{{stopAllInstancesWithWaitTime.CurrentIteratorValue}}"
CheckStateOnly: false
DesiredState: stopped
- name: wait10Seconds
action: aws:sleep
inputs:
Duration: PT10S
```
------
**Input**
The input is as follows.
Iterators
The list of items for the steps to iterate over. The maximum number of iterators is 100.
Type: StringList
Required: No
IteratorDataType
An optional parameter to specify the data type of the `Iterators`. A value for this parameter can be provided along with the `Iterators` input parameter. If you don’t specify a value for this parameter and `Iterators`, then you must specify a value for the `LoopCondition` parameter.
Type: String
Valid values: Boolean \$1 Integer \$1 String \$1 StringMap
Default: String
Required: No
LoopCondition
Consists of a `Variable` and an operator condition to evaluate. If you don’t specify a value for this parameter, then you must specify values for the `Iterators` and `IteratorDataType` parameters. You can use complex operator evaluations by using a combination of `And`, `Not`, and `Or` operators. The condition is evaluated after the steps in the loop complete. If the condition is `true` and the `MaxIterations` value has not been reached, the steps in the loop run again. The operator conditions are as follows:
**String operations**
+ StringEquals
+ EqualsIgnoreCase
+ StartsWith
+ EndsWith
+ Contains
**Numeric operations**
+ NumericEquals
+ NumericGreater
+ NumericLesser
+ NumericGreaterOrEquals
+ NumericLesser
+ NumericLesserOrEquals
**Boolean operation**
+ BooleanEquals
Type: StringMap
Required: No
MaxIterations
The maximum number of times the steps in the loop run. Once the value specified for this input is reached, the loop stops running even if the `LoopCondition` is still `true` or if there are objects remaining in the `Iterators` parameter.
Type: Integer
Valid values: 1 - 100
Required: No
Steps
The list of steps to run in the loop. These function like a nested runbook. Within these steps you can access the current iterator value for a `for each` loop using the syntax `{{loopStepName.CurrentIteratorValue}}`. You can also access an integer value of the current iteration for both loop types using the syntax `{{loopStepName.CurrentIteration}}`.
Type: List of steps
Required: YesOutput
CurrentIteration
The current loop iteration as an integer. Iteration values start at 1.
Type: Integer
CurrentIteratorValue
The value of the current iterator as a string. This output is only present in `for each` loops.
Type: String
# `aws:pause` – Pause an automation
This action pauses the automation. Once paused, the automation status is *Waiting*. To continue the automation, use the [SendAutomationSignal](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendAutomationSignal.html) API operation with the `Resume` signal type. We recommend using the `aws:sleep` or `aws:approve` action for more granular control of your workflows.
**Note**
The default timeout for this action is 7 days (604800 seconds) and the maximum value is 30 days (2592000 seconds). You can limit or extend the timeout by specifying the `timeoutSeconds` parameter for an `aws:pause` step.
**Input**
The input is as follows.
------
#### [ YAML ]
```
name: pauseThis
action: aws:pause
timeoutSeconds: 1209600
inputs: {}
```
------
#### [ JSON ]
```
{
"name": "pauseThis",
"action": "aws:pause",
"timeoutSeconds": "1209600",
"inputs": {}
}
```
------Output
None
# `aws:runCommand` – Run a command on a managed instance
Runs the specified commands.
**Note**
Automation only supports *output* of one AWS Systems Manager Run Command action. A runbook can include multiple Run Command actions, but output is supported for only one action at a time.
**Input**
This action supports most send command parameters. For more information, see [SendCommand](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_SendCommand.html).
------
#### [ YAML ]
```
- name: checkMembership
action: 'aws:runCommand'
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- '{{InstanceIds}}'
Parameters:
commands:
- (Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain
```
------
#### [ JSON ]
```
{
"name": "checkMembership",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{InstanceIds}}"
],
"Parameters": {
"commands": [
"(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
]
}
}
}
```
------
DocumentName
If the Command type document is owned by you or AWS, specify the name of the document. If you're using a document shared with you by a different AWS account, specify the Amazon Resource Name (ARN) of the document. For more information about using shared documents, see [Using shared SSM documents](documents-ssm-sharing.md#using-shared-documents).
Type: String
Required: Yes
InstanceIds
The instance IDs where you want the command to run. You can specify a maximum of 50 IDs.
You can also use the pseudo parameter `{{RESOURCE_ID}}` in place of instance IDs to run the command on all instances in the target group. For more information about pseudo parameters, see [Using pseudo parameters when registering maintenance window tasks](maintenance-window-tasks-pseudo-parameters.md).
Another alternative is to send commands to a fleet of instances by using the `Targets` parameter. The `Targets` parameter accepts Amazon Elastic Compute Cloud (Amazon EC2) tags. For more information about how to use the `Targets` parameter, see [Run commands at scale](send-commands-multiple.md).
Type: StringList
Required: No (If you don't specify InstanceIds or use the `{{RESOURCE_ID}}` pseudo parameter, then you must specify the `Targets` parameter.)
Targets
An array of search criteria that targets instances by using a Key,Value combination that you specify. `Targets` is required if you don't provide one or more instance IDs in the call. For more information about how to use the `Targets` parameter, see [Run commands at scale](send-commands-multiple.md).
Type: MapList (The schema of the map in the list must match the object.) For information, see [Target](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_Target.html) in the *AWS Systems Manager API Reference*.
Required: No (If you don't specify `Targets`, then you must specify InstanceIds or use the `{{RESOURCE_ID}}` pseudo parameter.)
Following is an example.
```
- name: checkMembership
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
Targets:
- Key: tag:Stage
Values:
- Gamma
- Beta
- Key: tag-key
Values:
- Suite
Parameters:
commands:
- (Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain
```
```
{
"name": "checkMembership",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"Targets": [
{
"Key": "tag:Stage",
"Values": [
"Gamma", "Beta"
]
},
{
"Key": "tag:Application",
"Values": [
"Suite"
]
}
],
"Parameters": {
"commands": [
"(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
]
}
}
}
```
Parameters
The required and optional parameters specified in the document.
Type: Map
Required: No
CloudWatchOutputConfig
Configuration options for sending command output to Amazon CloudWatch Logs. For more information about sending command output to CloudWatch Logs, see [Configuring Amazon CloudWatch Logs for Run Command](sysman-rc-setting-up-cwlogs.md).
Type: StringMap (The schema of the map must match the object. For more information, see [CloudWatchOutputConfig](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_CloudWatchOutputConfig.html) in the *AWS Systems Manager API Reference*).
Required: No
Following is an example.
```
- name: checkMembership
action: aws:runCommand
inputs:
DocumentName: AWS-RunPowerShellScript
InstanceIds:
- "{{InstanceIds}}"
Parameters:
commands:
- "(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
CloudWatchOutputConfig:
CloudWatchLogGroupName: CloudWatchGroupForSSMAutomationService
CloudWatchOutputEnabled: true
```
```
{
"name": "checkMembership",
"action": "aws:runCommand",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{InstanceIds}}"
],
"Parameters": {
"commands": [
"(Get-WmiObject -Class Win32_ComputerSystem).PartOfDomain"
]
},
"CloudWatchOutputConfig" : {
"CloudWatchLogGroupName": "CloudWatchGroupForSSMAutomationService",
"CloudWatchOutputEnabled": true
}
}
}
```
Comment
User-defined information about the command.
Type: String
Required: No
DocumentHash
The hash for the document.
Type: String
Required: No
DocumentHashType
The type of the hash.
Type: String
Valid values: `Sha256` \$1 `Sha1`
Required: No
NotificationConfig
The configurations for sending notifications.
Required: No
OutputS3BucketName
The name of the S3 bucket for command output responses. Your managed node must have permissions for the S3 bucket to successfully log output.
Type: String
Required: No
OutputS3KeyPrefix
The prefix.
Type: String
Required: No
ServiceRoleArn
The ARN of the AWS Identity and Access Management (IAM) role.
Type: String
Required: No
TimeoutSeconds
The amount of time in seconds to wait for a command to deliver to the AWS Systems Manager SSM Agent on an instance. If the command isn't received by the SSM Agent on the instance before the value specified is reached, then the status of the command changes to `Delivery Timed Out`.
Type: Integer
Required: No
Valid values: 30-2592000Output
CommandId
The ID of the command.
Status
The status of the command.
ResponseCode
The response code of the command. If the document you run has more than 1 step, a value isn't returned for this output.
Output
The output of the command. If you target a tag or multiple instances with your command, no output value is returned. You can use the `GetCommandInvocation` and `ListCommandInvocations` API operations to retrieve output for individual instances.
# `aws:runInstances` – Launch an Amazon EC2 instance
Launches a new Amazon Elastic Compute Cloud (Amazon EC2) instance.
**Note**
The `aws:runInstances` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
The action supports most API parameters. For more information, see the [RunInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_RunInstances.html) API documentation.
------
#### [ YAML ]
```
name: launchInstance
action: aws:runInstances
maxAttempts: 3
timeoutSeconds: 1200
onFailure: Abort
inputs:
ImageId: ami-12345678
InstanceType: t2.micro
MinInstanceCount: 1
MaxInstanceCount: 1
IamInstanceProfileName: myRunCmdRole
TagSpecifications:
- ResourceType: instance
Tags:
- Key: LaunchedBy
Value: SSMAutomation
- Key: Category
Value: HighAvailabilityFleetHost
```
------
#### [ JSON ]
```
{
"name":"launchInstance",
"action":"aws:runInstances",
"maxAttempts":3,
"timeoutSeconds":1200,
"onFailure":"Abort",
"inputs":{
"ImageId":"ami-12345678",
"InstanceType":"t2.micro",
"MinInstanceCount":1,
"MaxInstanceCount":1,
"IamInstanceProfileName":"myRunCmdRole",
"TagSpecifications":[
{
"ResourceType":"instance",
"Tags":[
{
"Key":"LaunchedBy",
"Value":"SSMAutomation"
},
{
"Key":"Category",
"Value":"HighAvailabilityFleetHost"
}
]
}
]
}
}
```
------
AdditionalInfo
Reserved.
Type: String
Required: No
BlockDeviceMappings
The block devices for the instance.
Type: MapList
Required: No
ClientToken
The identifier to ensure idempotency of the request.
Type: String
Required: No
DisableApiTermination
Turns on or turns off instance API termination.
Type: Boolean
Required: No
EbsOptimized
Turns on or turns off Amazon Elastic Block Store (Amazon EBS) optimization.
Type: Boolean
Required: No
IamInstanceProfileArn
The Amazon Resource Name (ARN) of the AWS Identity and Access Management (IAM) instance profile for the instance.
Type: String
Required: No
IamInstanceProfileName
The name of the IAM instance profile for the instance.
Type: String
Required: No
ImageId
The ID of the Amazon Machine Image (AMI).
Type: String
Required: Yes
InstanceInitiatedShutdownBehavior
Indicates whether the instance stops or terminates on system shutdown.
Type: String
Required: No
InstanceType
The instance type.
If an instance type value isn't provided, the m1.small instance type is used.
Type: String
Required: No
KernelId
The ID of the kernel.
Type: String
Required: No
KeyName
The name of the key pair.
Type: String
Required: No
MaxInstanceCount
The maximum number of instances to be launched.
Type: String
Required: No
MetadataOptions
The metadata options for the instance. For more information, see [InstanceMetadataOptionsRequest](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_InstanceMetadataOptionsRequest.html).
Type: StringMap
Required: No
MinInstanceCount
The minimum number of instances to be launched.
Type: String
Required: No
Monitoring
Turns on or turns off detailed monitoring.
Type: Boolean
Required: No
NetworkInterfaces
The network interfaces.
Type: MapList
Required: No
Placement
The placement for the instance.
Type: StringMap
Required: No
PrivateIpAddress
The primary IPv4 address.
Type: String
Required: No
RamdiskId
The ID of the RAM disk.
Type: String
Required: No
SecurityGroupIds
The IDs of the security groups for the instance.
Type: StringList
Required: No
SecurityGroups
The names of the security groups for the instance.
Type: StringList
Required: No
SubnetId
The subnet ID.
Type: String
Required: No
TagSpecifications
The tags to apply to the resources during launch. You can only tag instances and volumes at launch. The specified tags are applied to all instances or volumes that are created during launch. To tag an instance after it has been launched, use the [`aws:createTags` – Create tags for AWS resources](automation-action-createtag.md) action.
Type: MapList (For more information, see [TagSpecification](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_TagSpecification.html).)
Required: No
UserData
A script provided as a string literal value. If a literal value is entered, then it must be Base64-encoded.
Type: String
Required: NoOutput
InstanceIds
The IDs of the instances.
InstanceStates
The current state of the instance.
# `aws:sleep` – Delay an automation
Delays an automation for a specified amount of time. This action uses the International Organization for Standardization (ISO) 8601 date and time format. For more information about this date and time format, see [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html).
**Input**
You can delay an automation for a specified duration.
------
#### [ YAML ]
```
name: sleep
action: aws:sleep
inputs:
Duration: PT10M
```
------
#### [ JSON ]
```
{
"name":"sleep",
"action":"aws:sleep",
"inputs":{
"Duration":"PT10M"
}
}
```
------
You can also delay an automation until a specified date and time. If the specified date and time has passed, the action proceeds immediately.
------
#### [ YAML ]
```
name: sleep
action: aws:sleep
inputs:
Timestamp: '2020-01-01T01:00:00Z'
```
------
#### [ JSON ]
```
{
"name": "sleep",
"action": "aws:sleep",
"inputs": {
"Timestamp": "2020-01-01T01:00:00Z"
}
}
```
------
**Note**
Automation supports a maximum delay of 604799 seconds (7 days).
Duration
An ISO 8601 duration. You can't specify a negative duration.
Type: String
Required: No
Timestamp
An ISO 8601 timestamp. If you don't specify a value for this parameter, then you must specify a value for the `Duration` parameter.
Type: String
Required: NoOutput
None
# `aws:updateVariable` – Updates a value for a runbook variable
This action updates a value for a runbook variable. The data type of the value must match the data type of the variable you want to update. Data type conversions aren't supported. The `onCancel` property isn't supported for the `aws:updateVariable` action.
**Input**
The input is as follows.
------
#### [ YAML ]
```
name: updateStringList
action: aws:updateVariable
inputs:
Name: variable:variable name
Value:
- "1"
- "2"
```
------
#### [ JSON ]
```
{
"name": "updateStringList",
"action": "aws:updateVariable",
"inputs": {
"Name": "variable:variable name",
"Value": ["1","2"]
}
}
```
------
Name
The name of the variable whose value you want to update. You must use the format `variable:variable name`
Type: String
Required: Yes
Value
The new value to assign to the variable. The value must match the data type of the variable. Data type conversions aren't supported.
Type: Boolean \$1 Integer \$1 MapList \$1 String \$1 StringList \$1 StringMap
Required: Yes
Constraints:
+ MapList can contain a maximum number of 200 items.
+ Key lengths can be a minimum length of 1 and a maximum length of 50.
+ StringList can be a minimum number of 0 items and a maximum number of 50 items.
+ String lengths can be a minimum length of 1 and a maximum length of 512.Output
None
# `aws:waitForAwsResourceProperty` – Wait on an AWS resource property
The `aws:waitForAwsResourceProperty` action allows your automation to wait for a specific resource state or event state before continuing the automation. For more examples of how to use this action, see [Additional runbook examples](automation-document-examples.md).
**Note**
The default timeout value for this action is 3600 seconds (one hour). You can limit or extend the timeout by specifying the `timeoutSeconds` parameter for an `aws:waitForAwsResourceProperty` step. For more information and examples of how to use this action, see [Handling timeouts in runbooks](automation-handling-timeouts.md).
**Note**
The `aws:waitForAwsResourceProperty` action supports automatic throttling retry. For more information, see [Configuring automatic retry for throttled operations](automation-throttling-retry.md).
**Input**
Inputs are defined by the API operation that you choose.
------
#### [ YAML ]
```
action: aws:waitForAwsResourceProperty
inputs:
Service: The official namespace of the service
Api: The API operation or method name
API operation inputs or parameters: A value
PropertySelector: Response object
DesiredValues:
- Desired property value
```
------
#### [ JSON ]
```
{
"action": "aws:waitForAwsResourceProperty",
"inputs": {
"Service":"The official namespace of the service",
"Api":"The API operation or method name",
"API operation inputs or parameters":"A value",
"PropertySelector": "Response object",
"DesiredValues": [
"Desired property value"
]
}
}
```
------
Service
The AWS service namespace that contains the API operation that you want to run. For example, the namespace for AWS Systems Manager is `ssm`. The namespace for Amazon Elastic Compute Cloud (Amazon EC2) is `ec2`. You can view a list of supported AWS service namespaces in the [Available Services](https://docs.aws.amazon.com/cli/latest/reference/#available-services) section of the *AWS CLI Command Reference*.
Type: String
Required: Yes
Api
The name of the API operation that you want to run. 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).
Type: String
Required: Yes
API operation inputs
One or more API operation inputs. You can view the available inputs (also called parameters) 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 methods for Amazon RDS are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Choose the [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) method and scroll down to see the available parameters, such as **DBInstanceIdentifier**, **Name**, and **Values**.
```
inputs:
Service: The official namespace of the service
Api: The API operation name
API input 1: A value
API Input 2: A value
API Input 3: A value
```
```
"inputs":{
"Service":"The official namespace of the service",
"Api":"The API operation name",
"API input 1":"A value",
"API Input 2":"A value",
"API Input 3":"A value"
}
```
Type: Determined by chosen API operation
Required: Yes
PropertySelector
The JSONPath to a specific attribute in the response object. You can view the response objects 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 methods for Amazon RDS are listed on the following page: [Amazon RDS methods](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html). Choose the [describe\$1db\$1instances](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/rds.html#RDS.Client.describe_db_instances) method and scroll down to the **Response Structure** section. **DBInstances** is listed as a response object.
Type: String
Required: Yes
DesiredValues
The expected status or state on which to continue the automation.
Type: MapList, StringList
Required: Yes
# Automation system variables
AWS Systems Manager Automation runbooks use the following variables. For an example of how these variables are used, view the JSON source of the `AWS-UpdateWindowsAmi` runbook.
**To view the JSON source of the `AWS-UpdateWindowsAmi` 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. In the document list, use either the Search bar or the numbers to the right of the Search bar to choose the runbook `AWS-UpdateWindowsAmi`.
1. Choose the **Content** tab.
**System variables**
Automation runbooks support the following system variables.
****
| Variable | Details |
| --- | --- |
| `global:ACCOUNT_ID` | The AWS account ID of the user or role in which Automation runs. |
| `global:DATE` | The date (at run time) in the format yyyy-MM-dd. |
| `global:DATE_TIME` | The date and time (at run time) in the format yyyy-MM-dd\$1HH.mm.ss. |
| `global:AWS_PARTITION` | The partition that the resource is in. For standard AWS Regions, the partition is `aws`. For resources in other partitions, the partition is `aws-partitionname`. For example, the partition for resources in the AWS GovCloud (US-West) Region is `aws-us-gov`. |
| `global:REGION` | The Region that the runbook is run in. For example, us-east-2. |
**Automation variables**
Automation runbooks support the following automation variables.
****
| Variable | Details |
| --- | --- |
| `automation:EXECUTION_ID` | The unique identifier assigned to the current automation. For example, `1a2b3c-1a2b3c-1a2b3c-1a2b3c1a2b3c1a2b3c`. |
**Topics**
+ [Terminology](#automation-terms)
+ [Supported scenarios](#automation-variables-support)
+ [Unsupported scenarios](#automation-variables-unsupported)
## Terminology
The following terms describe how variables and parameters are resolved.
****
| Term | Definition | Example |
| --- | --- | --- |
| Constant ARN | A valid Amazon Resource Name (ARN) without variables. | `arn:aws:iam::123456789012:role/roleName` |
| Runbook parameter | A parameter defined at the runbook level (for example, `instanceId`). The parameter is used in a basic string replace. Its value is supplied at Start Execution time. | {
"description": "Create Image Demo",
"version": "0.3",
"assumeRole": "Your_Automation_Assume_Role_ARN",
"parameters":{
"instanceId": {
"type": "String",
"description": "Instance to create image from"
}
} |
| System variable | A general variable substituted into the runbook when any part of the runbook is evaluated. | "activities": [
{
"id": "copyImage",
"activityType": "AWS-CopyImage",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"ImageName": "{{imageName}}",
"SourceImageId": "{{sourceImageId}}",
"SourceRegion": "{{sourceRegion}}",
"Encrypted": true,
"ImageDescription": "Test CopyImage Description created on {{global:DATE}}"
}
}
]
|
| Automation variable | A variable relating to the automation substituted into the runbook when any part of the runbook is evaluated. | {
"name": "runFixedCmds",
"action": "aws:runCommand",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds": [
"{{LaunchInstance.InstanceIds}}"
],
"Parameters": {
"commands": [
"dir",
"date",
"“{{outputFormat}}” -f “left”,”right”,”{{global:DATE}}”,”{{automation:EXECUTION_ID}}”
]
}
}
} |
| Systems Manager Parameter | A variable defined within AWS Systems Manager Parameter Store. It can't be directly referenced in step input. Permissions might be required to access the parameter. |
description: Launch new Windows test instance
schemaVersion: '0.3'
assumeRole: '{{AutomationAssumeRole}}'
parameters:
AutomationAssumeRole:
type: String
default: ''
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.
LatestAmi:
type: String
default: >-
{{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}
description: The latest Windows Server 2016 AMI queried from the public parameter.
mainSteps:
- name: launchInstance
action: 'aws:runInstances'
maxAttempts: 3
timeoutSeconds: 1200
onFailure: Abort
inputs:
ImageId: '{{LatestAmi}}'
...
|
## Supported scenarios
****
| Scenario | Comments | Example |
| --- | --- | --- |
| Constant ARN `assumeRole` at creation. | An authorization check is performed to verify that the calling user is permitted to pass the given `assumeRole`. | {
"description": "Test all Automation resolvable parameters",
"schemaVersion": "0.3",
"assumeRole": "arn:aws:iam::123456789012:role/roleName",
"parameters": {
... |
| Runbook parameter supplied for `AssumeRole` when the automation is started. | Must be defined in the parameter list of the runbook. | {
"description": "Test all Automation resolvable parameters",
"schemaVersion": "0.3",
"assumeRole": "{{dynamicARN}}",
"parameters": {
... |
| Value supplied for runbook parameter at start. | Customer supplies the value to use for a parameter. Any inputs supplied at start time need to be defined in the parameter list of the runbook. | ...
"parameters": {
"amiId": {
"type": "String",
"default": "ami-12345678",
"description": "list of commands to run as part of first step"
},
...
Inputs to Start Automation Execution include : `{"amiId" : ["ami-12345678"] }` |
| Systems Manager Parameter referenced within runbook content. | The variable exists within the customer's account, or is a publicly accessibly parameter, and the `AssumeRole` for the runbook has access to the variable. A check is performed at create time to confirm the `AssumeRole` has access. The parameter can't be directly referenced in step input. |
...
parameters:
LatestAmi:
type: String
default: >-
{{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}
description: The latest Windows Server 2016 AMI queried from the public parameter.
mainSteps:
- name: launchInstance
action: 'aws:runInstances'
maxAttempts: 3
timeoutSeconds: 1200
onFailure: Abort
inputs:
ImageId: '{{LatestAmi}}'
...
|
| System variable referenced within step definition | A system variable is substituted into the runbook when the automation is started. The value injected into the runbook is relative to when the substitution occurs. That is, the value of a time variable injected at step 1 is different from the value injected at step 3 because of the time it takes to run the steps between. System variables don't need to be set in the parameter list of the runbook. | ...
"mainSteps": [
{
"name": "RunSomeCommands",
"action": "aws:runCommand",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"DocumentName": "AWS:RunPowerShell",
"InstanceIds": ["{{LaunchInstance.InstanceIds}}"],
"Parameters": {
"commands" : [
"echo {The time is now {{global:DATE_TIME}}}"
]
}
}
}, ...
|
| Automation variable referenced within step definition. | Automation variables don't need to be set in the parameter list of the runbook. The only supported Automation variable is **automation:EXECUTION\$1ID**. | ...
"mainSteps": [
{
"name": "invokeLambdaFunction",
"action": "aws:invokeLambdaFunction",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"FunctionName": "Hello-World-LambdaFunction",
"Payload" : "{ "executionId" : "{{automation:EXECUTION_ID}}" }"
}
}
...
|
| Refer to output from previous step within next step definition. | This is parameter redirection. The output of a previous step is referenced using the syntax `{{stepName.OutputName}}`. This syntax can't be used by the customer for runbook parameters. This is resolved when the referring step runs. The parameter isn't listed in the parameters of the runbook. | ...
"mainSteps": [
{
"name": "LaunchInstance",
"action": "aws:runInstances",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"ImageId": "{{amiId}}",
"MinInstanceCount": 1,
"MaxInstanceCount": 2
}
},
{
"name":"changeState",
"action": "aws:changeInstanceState",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"InstanceIds": ["{{LaunchInstance.InstanceIds}}"],
"DesiredState": "terminated"
}
}
...
|
## Unsupported scenarios
****
| Scenario | Comment | Example |
| --- | --- | --- |
| Systems Manager Parameter supplied for `assumeRole` at create | Not supported. | ...
{
"description": "Test all Automation resolvable parameters",
"schemaVersion": "0.3",
"assumeRole": "{{ssm:administratorRoleARN}}",
"parameters": {
...
|
| Systems Manager Parameter directly referenced in step input. | Returns `InvalidDocumentContent` exception at create time. |
...
mainSteps:
- name: launchInstance
action: 'aws:runInstances'
maxAttempts: 3
timeoutSeconds: 1200
onFailure: Abort
inputs:
ImageId: '{{ssm:/aws/service/ami-windows-latest/Windows_Server-2016-English-Full-Base}}'
...
|
| Variable step definition | The definition of a step in the runbook is constructed by variables. | ...
"mainSteps": [
{
"name": "LaunchInstance",
"action": "aws:runInstances",
"{{attemptModel}}": 1,
"onFailure": "Continue",
"inputs": {
"ImageId": "ami-12345678",
"MinInstanceCount": 1,
"MaxInstanceCount": 2
}
...
User supplies input : { "attemptModel" : "minAttempts" }
|
| Cross referencing runbook parameters | The user supplies an input parameter at start time, which is a reference to another parameter in the runbook. | ...
"parameters": {
"amiId": {
"type": "String",
"default": "ami-7f2e6015",
"description": "list of commands to run as part of first step"
},
"alternateAmiId": {
"type": "String",
"description": "The alternate AMI to try if this first fails".
"default" : "{{amiId}}"
},
...
|
| Multi-level expansion | The runbook defines a variable that evaluates to the name of a variable. This sits within the variable delimiters (that is *\$1\$1 \$1\$1*) and is expanded to the value of that variable/parameter. | ...
"parameters": {
"firstParameter": {
"type": "String",
"default": "param2",
"description": "The parameter to reference"
},
"secondParameter": {
"type": "String",
"default" : "echo {Hello world}",
"description": "What to run"
}
},
"mainSteps": [{
"name": "runFixedCmds",
"action": "aws:runCommand",
"maxAttempts": 1,
"onFailure": "Continue",
"inputs": {
"DocumentName": "AWS-RunPowerShellScript",
"InstanceIds" : "{{LaunchInstance.InstanceIds}}",
"Parameters": {
"commands": [ "{{ {{firstParameter}} }}"]
}
...
Note: The customer intention here would be to run a command of "echo {Hello world}"
|
| Referencing output from a runbook step that is a different variable type | The user references the output from a preceding runbook step within a subsequent step. The output is a variable type that doesn't meet the requirements of the action in the subsequent step. | ...
mainSteps:
- name: getImageId
action: aws:executeAwsApi
inputs:
Service: ec2
Api: DescribeImages
Filters:
- Name: "name"
Values:
- "{{ImageName}}"
outputs:
- Name: ImageIdList
Selector: "$.Images"
Type: "StringList"
- name: copyMyImages
action: aws:copyImage
maxAttempts: 3
onFailure: Abort
inputs:
SourceImageId: {{getImageId.ImageIdList}}
SourceRegion: ap-northeast-2
ImageName: Encrypted Copies of LAMP base AMI in ap-northeast-2
Encrypted: true
...
Note: You must provide the type required by the Automation action.
In this case, aws:copyImage requires a "String" type variable but the preceding step outputs a "StringList" type variable.
|