Menu
Amazon EC2 Systems Manager
User Guide

Systems Manager Automation Actions

Systems Manager Automation performs tasks defined in Automation documents. To define a task, you specify one or more of the following actions in any order in the mainSteps section of your Automation document.

  • aws:runInstances: Launches one or more instances.

  • aws:runCommand: Executes a remote command.

  • aws:invokeLambdaFunction: Enables you to run external worker functions in your automation workflow.

  • aws:changeInstanceState: Changes the state of an instance.

  • aws:createImage: Creates an AMI from a running instance.

  • aws:createTag: Creates new tags for Amazon EC2 instances or Systems Manager managed instances.

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

  • aws:deleteImage: Deletes an AMI.

The output of an action is not supposed to be specified in the document. Output is available for you to link steps or add to the output section of the document. For example, you can make the output of aws:runInstances available for a subsequent aws:runCommand action.

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.

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:runInstances Action

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.

Required: No

Output

InstanceIds

The IDs of the instances.

aws:runCommand Action

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

Output

CommandId

The ID of the command.

Output

The truncated output of the command.

ResponseCode

The command status code.

Status

The status of the command.

aws:invokeLambdaFunction Action

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:changeInstanceState Action

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:createImage Action

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

The state of the newly created image.

aws:createTags Action

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:copyImage Action

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:deleteImage Action

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