Systems Manager Automation Actions

Systems Manager Automation executes steps defined in Automation documents. 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 Automation document. Automation supports the following actions.

aws:changeInstanceState: Changes the state of an instance.
aws:copyImage: Copies an AMI from any region into the current region. This action can also encrypt the new AMI.
aws:createImage: Creates an AMI from a running instance.
aws:createStack: Creates a new AWS CloudFormation stack from a template.
aws:createTags: Creates new tags for Amazon EC2 instances or Systems Manager managed instances.
aws:deleteImage: Deletes an AMI.
aws:deleteStack: Deletes an AWS CloudFormation stack.
aws:invokeLambdaFunction: Enables you to run external worker functions in your automation workflow.
aws:runCommand: Executes a remote command.
aws:runInstances: Launches one or more instances.
aws:sleep: Delays Automation execution for a specified amount of time.

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 Automation documents, 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 Automation document.

Common Properties In All Actions

The following properties are common to all actions:

Copy
"mainSteps": [
    {
        "name": "name",
        "action": "action",
        "maxAttempts": value,
        "timeoutSeconds": value,
        "onFailure": "Abort",
        "inputs": {
            ...
        }
    },
    {
        "name": "name",
        "action": "action",
        "maxAttempts": value,
        "timeoutSeconds": value,
        "onFailure": "Abort",
        "inputs": {
            ...
        }
    }
]

name

An identifier that must be unique across all step names in the document.

Type: String

Required: Yes

action

The name of the action the step is to execute.

Type: String

Required: Yes

maxAttempts

The number of times the step should be retried in case of failure. If the value is greater than 1, the step is not considered to have failed until all retry attempts have failed. The default value is 1.

Type: Integer

Required: No

timeoutSeconds

The execution timeout value for the step. If the timeout is reached and the value of maxAttempts is greater than 1, then the step is not considered to have timed out until all retries have been attempted. There is no default value for this field.

Type: Integer

Required: No

onFailure

Indicates whether the workflow should continue on failure. The default is to abort on failure.

Type: String

Valid values: Abort | Continue

Required: No

inputs

The properties specific to the action.

Type: Map

Required: Yes

aws:changeInstanceState

Changes or asserts the state of the instance.

This action can be used in assert mode (do not execute the API to change the state but verify 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, 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 AMI.

Input

Copy
{
    "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: String

Required: Yes

CheckStateOnly

If false, sets the instance state to the desired state. If true, asserts the desired state using polling.

Type: Boolean

Required: No

DesiredState

The desired state.

Type: String

Valid values: running | stopped | terminated

Required: Yes

Force

If set, forces the instances to stop. The instances do not 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 is not recommended for Windows instances.

Type: Boolean

Required: No

AdditionalInfo

Reserved.

Type: String

Required: No

Output

None

aws:copyImage

Copies an AMI from any region into the current region. This action can also encrypt the new AMI.

Input

This action supports most CopyImage parameters. For more information, see CopyImage.

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.

Copy
{   
    "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 currently 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 Key Management Service CMK to use when encrypting the snapshots of an image during a copy operation. For more information, see CopyImage.

Type: String

Required: No

ClientToken

A unique, case-sensitive identifier that you provide to ensure request idempotency. For more information, see CopyImage.

Type: String

Required: No

Output

ImageId

The ID of the copied image.

ImageState

The state of the copied image.

Valid values: available | pending | failed

aws:createImage

Creates a new AMI from a stopped instance.

Important

This action does not stop the instance implicitly. You must use the aws:changeInstanceState action to stop the instance. If this action is used on a running instance, the resultant AMI might be defective.

Input

This action supports most CreateImage parameters. For more information, see CreateImage.

Copy
{
    "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 of the image.

Type: String

Required: Yes

ImageDescription

A description of the image.

Type: String

Required: No

NoReboot

A boolean literal.

Type: Boolean

Required: No

BlockDeviceMappings

The block devices for the instance.

Type: Map

Required: No

Output

ImageId

The ID of the newly created image.

ImageState

An execution script provided as a string literal value. If a literal value is entered, then it must be Base64-encoded.

Required: No

aws:createStack

Creates a new AWS CloudFormation stack from a template.

Input

Copy
{
      "name": "makeStack",
      "action": "aws:createStack",
      "maxAttempts": 1,
      "onFailure": "Abort",
      "inputs": {
        "Capabilities": [
          "CAPABILITY_IAM"
        ],
        "StackName": "myStack",
        "TemplateURL": "http://s3.amazonaws.com/mybucket/myStackTemplate",
        "TimeoutInMinutes": 5
      }
    }

Capabilities

A list of values that you specify before AWS CloudFormation can create certain stacks. Some stack templates include resources that can affect permissions in your AWS account. For example, creating new AWS Identity and Access Management (IAM) users can affect permissions in your account. For those stacks, you must explicitly acknowledge their capabilities by specifying this parameter.

The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM. The following resources require you to specify this parameter.

If your stack template contains these resources, we recommend that you review all permissions associated with them and edit their permissions, if necessary.

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.

For more information, see Acknowledging IAM Resources in AWS CloudFormation Templates.

Type: array of Strings

Valid Values: CAPABILITY_IAM | CAPABILITY_NAMED_IAM

Required: No

DisableRollback

Set to true to disable 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 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/v2/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 data type.

Type: array of Parameter 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, AWS CloudFormation grants permissions to all resource types. IAM uses this parameter for AWS CloudFormation-specific condition keys in IAM policies. For more information, see Controlling Access with AWS Identity and Access Management.

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 AWS CloudFormation assumes to create the stack. AWS CloudFormation uses the role's credentials to make calls on your behalf. AWS CloudFormation always uses this role for all future operations on the stack. As long as users have permission to operate on the stack, AWS 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, AWS CloudFormation uses the role that was previously associated with the stack. If no role is available, AWS 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 are creating the stack.

Note

A stack name can contain only alphanumeric characters (case sensitive) and hyphens. It must start with an alphabetic character and cannot 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.

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 Amazon 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. AWS 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 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.

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 Amazon S3 bucket. The maximum size allowed for the template is 460,800 bytes. For more information, see Template Anatomy.

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 is not 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

Required: Yes

StackStatusReason

Success or failure message associated with the stack status.

Type: String

Required: No

For more information, see CreateStack.

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 2: Create an IAM Role for Automation.

Copy
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "sqs:*",
            "cloudformation:CreateStack",
            "cloudformation:DescribeStacks"
         ],
         "Resource":"*"
      }
   ]
}

aws:createTags

Create new tags for Amazon EC2 instances or Systems Manager managed instances.

Input

This action supports most EC2 CreateTags and SSM AddTagsToResource parameters. For more information, see CreateTags and AddTagsToResource.

The following example shows how to tag an AMI and an instance as being production resources for a particular department.

Copy
{
        "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 is not “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 | ManagedInstance | MaintenanceWindow | Parameter

Output

None

aws:deleteImage

Deletes the specified image and all related snapshots.

Input

This action supports only one parameter. For more information, see the documentation for DeregisterImage and DeleteSnapshot.

Copy
{
    "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

Deletes an AWS CloudFormation stack.

Input

Copy
{
   "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 AWS CloudFormation knows that you're not attempting to delete a stack with the same name. You can retry DeleteStack requests to verify that AWS CloudFormation received them.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

Pattern: [a-zA-Z][-a-zA-Z0-9]*

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, AWS CloudFormation deletes the stack, but does not delete the retained resources.

Retaining resources is useful when you can't delete a resource, such as a non-empty Amazon S3 bucket, but you want to delete the stack.

Type: array of strings

Required: No

RoleARN

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 2: Create an IAM Role for Automation.

Copy
{
   "Version":"2012-10-17",
   "Statement":[
      {
         "Effect":"Allow",
         "Action":[
            "sqs:*",
            "cloudformation:DeleteStack",
            "cloudformation:DescribeStacks"
         ],
         "Resource":"*"
      }
   ]
}

aws:invokeLambdaFunction

Invokes the specified Lambda function.

Input

This action supports most invoke parameters for the Lambda service. For more information, see Invoke.

Copy
{
    "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 is RequestResponse.

Type: String

Valid values: Event | RequestResponse | DryRun

Required: No

LogType

If Tail, the invocation type must be RequestResponse. AWS Lambda returns the last 4 KB of log data produced by your Lambda function, base64-encoded.

Type: String

Valid values: None | Tail

Required: No

ClientContext

The client-specific information.

Required: No

Payload

The JSON input for your Lambda function.

Required: No

Output

StatusCode: The function execution status code.
FunctionError: Indicates whether an error occurred while executing the Lambda function. If an error occurred, this field will show either Handled or Unhandled. Handled errors are reported by the function. Unhandled errors are detected and reported by AWS Lambda.
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.

aws:runCommand

Runs the specified commands.

Input

This action supports most send command parameters. For more information, see SendCommand.

Copy
{
    "name": "installPowerShellModule",
    "action": "aws:runCommand",
    "inputs": {
        "DocumentName": "AWS-InstallPowerShellModule",
        "InstanceIds": ["i-1234567890abcdef0"],
        "Parameters": {
            "source": "https://my-s3-url.com/MyModule.zip ",
            "sourceHash": "ASDFWER12321WRW"
        }
    }
}

DocumentName

The name of the run command document.

Type: String

Required: Yes

InstanceIds

The IDs of the instances.

Type: String

Required: Yes

Parameters

The required and optional parameters specified in the document.

Type: Map

Required: No

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 | Sha1

Required: No

NotificationConfig

The configurations for sending notifications.

Required: No

OutputS3BucketName

The name of the S3 bucket for command execution responses.

Type: String

Required: No

OutputS3KeyPrefix

The prefix.

Type: String

Required: No

ServiceRoleArn

The ARN of the IAM role.

Type: String

Required: No

TimeoutSeconds

The run-command timeout value, in seconds.

Type: Integer

Required: No

aws:runInstances

Launches a new instance.

Input

The action supports most API parameters. For more information, see the RunInstances API documentation.

Copy
{
    "name": "launchInstance",
    "action": "aws:runInstances",
    "maxAttempts": 3,
    "timeoutSeconds": 1200,
    "onFailure": "Abort",
    "inputs": {
        "ImageId": "ami-12345678",
        "InstanceType": "t2.micro",
        "MinInstanceCount": 1,
        "MaxInstanceCount": 1,
        "IamInstanceProfileName": "myRunCmdRole"
    }
}

ImageId

The ID of the Amazon Machine Image (AMI).

Required: Yes

InstanceType

The instance type.

Required: No

MinInstanceCount

The minimum number of instances to be launched.

Required: No

MaxInstanceCount

The maximum number of instances to be launched.

Required: No

AdditionalInfo

Reserved.

Required: No

BlockDeviceMappings

The block devices for the instance.

Required: No

ClientToken

The identifier to ensure idempotency of the request.

Required: No

DisableApiTermination

Enables or disables instance API termination

Required: No

EbsOptimized

Enables or disabled EBS optimization.

Required: No

IamInstanceProfileArn

The ARN of the IAM instance profile for the instance.

Required: No

IamInstanceProfileName

The name of the IAM instance profile for the instance.

Required: No

InstanceInitiatedShutdownBehavior

Indicates whether the instance stops or terminates on system shutdown.

Required: No

KernelId

The ID of the kernel.

Required: No

KeyName

The name of the key pair.

Required: No

Monitoring

Enables or disables detailed monitoring.

Required: No

NetworkInterfaces

The network interfaces.

Required: No

Placement

The placement for the instance.

Required: No

PrivateIpAddress

The primary IPv4 address.

Required: No

RamdiskId

The ID of the RAM disk.

Required: No

SecurityGroupIds

The IDs of the security groups for the instance.

Required: No

SecurityGroups

The names of the security groups for the instance.

Required: No

SubnetId

The subnet ID.

Required: No

UserData

An execution script provided as a string literal value. If a literal value is entered, then it must be Base64-encoded.

Required: No

Output

InstanceIds: The IDs of the instances.

aws:sleep

Delays Automation execution 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.

Input

You can delay execution for a specified duration.

Copy
{
   "name":"sleep",
   "action":"aws:sleep",
   "inputs":{
      "Duration":"PT10M"
   }
}

You can also delay execution until a specified date and time. If the specified date and time has passed, the action proceeds immediately.

Copy
{
    "name": "sleep",
    "action": "aws:sleep",
    "inputs": {
        "Timestamp": "2020-01-01T01:00:00Z"
    }
}

Note

Automation currently supports a maximum delay of 604800 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: No

Output

None

Document Conventions

« Previous Next »