Menu
Sign In to the Console
Amazon Elastic Compute Cloud
User Guide for Linux Instances

Actions Reference for Automation Documents

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:runInstance: Launches one or more instances for a given AMI ID.

  • aws:runCommand: Remote command execution. Executes an SSM Run Command document.

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

  • aws:changeInstanceState: Changes an instance state to stopped, terminated, or running.

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

  • aws:deleteImage: Deletes an AMI.

All actions use the syntax shown later in this section. The properties specified outside the inputs section remain the same across all actions. You can use different values for any property in any action.

Common Properties In All Actions

name

A string specifying a unique identifier. The value of this property is expected to be unique across all step names in the document.

Required: Yes

action

A string specifying the name of the action a particular step intends to execute.

Required: Yes

maxAttempts

An integer value for number of times the step should be retried in case of failures. If the value specified is greater than one, the step is not declared failed until all attempts have failed. One is assumed as the default value.

Required: No

timeoutSeconds

An integer value for the step to timeout the execution.

Required: No

onFailure

A string indicating if the workflow should Abort or Continue on failures. By default the value Abort is assumed.

Required: No

inputs

Map of properties specific to the action

Required: Yes

Important

The outputs of an action are not supposed to be specified in the document. They are available to the user for linking the steps or adding into the output section of the doc. E.g. if you want to make output of aws:runInstances step, i.e. the instanceId an input for the next action which is let’s say aws:runCommand, you have it available to you. See the example below to understand more.

Syntax

"mainSteps": [ 
	{
		"name": "launchInstance",
      		"action": "aws:runInstances",
      		"maxAttempts": 3,
      		"timeoutSeconds": 1200,
      		"onFailure": "Abort",
      		"inputs": {
        		"ImageId": "ami-123456",
        		"InstanceType": "t2.micro"
		}
	},
	{
      		"name": "updateInstance",
      		"action": "aws:runCommand",
      		"timeoutSeconds": 1200,
      		"onFailure": "Continue",
      		"inputs": {
        		"DocumentName": "AWS-RunShellScript",
        		"InstanceIds": [
          			"{{launchInstance.InstanceIds}}"
        		],
        		"Parameters": {
          			"commands": [
            				"ls -l"
          			]
        		}
      		}
	}
]

Action aws:runInstance

You can use this action to launch anew instance. The action supports most run-instance API arguments.

JSON Sample

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

Inputs

The action supports most run-instances API’s parameters. For specific permitted value, please refer to the run-instances api documentation. 

ImageId

A string literal containing the id of the image to launch the instance.

Required: Yes

AdditionalInfo

A string containing additional info to launch the instance.

Required: No

BlockDeviceMappings

A map list containing the mappings for the instance.

Required: No

ClientToken

A string literal.

Required: No

DisableApiTermination

A boolean value.

Required: No

EbsOptimized

A boolean value.

Required: No

IamInstanceProfileArn

A string literal containing the ARN of.

Required: No

IamInstanceProfileName

A string literal containing name of the IAM profile to associate with the instance.

Required: No

InstanceInitiatedShutdownBehavior

A string value.

Required: No

InstanceType

A string literal containing the instance type.

Required: No

KernelId

A string value containing kernel id.

Required: No

KeyName

A string literal containing the name of the security key.

Required: No

MaxInstanceCount

An integer value for defining the maximum number of instances to be launched.

Required: No

MinInstanceCount

An integer value for defining the minimum number of instances to be launched.

Required: No

Monitoring

A boolean value to indicate enabling cloud watch monitoring.

Required: No

NetworkInterfaces

A list of maps containing all the network interfaces.

Required: No

Placement

A map of string literals.

Required: No

PrivateIpAddress

A string value containing the IP address.

Required: No

RamdiskId

A string literal containing ram disk id.

Required: No

SecurityGroupIds

A list of string literals containing the Ids of the security groups.

Required: No

SecurityGroups

A list of string literals containing the names of the security groups.

Required: No

SubnetId

A string value containing the subnet id.

Required: No

UserData

An execution script provided as a string literal value.

Required: No

Outputs

InstanceIds

List of string literals containing instance ids.

Action aws:runCommand

You can use this action to run any commands using send-command API. This action supports most send-command API arguments. The example below shows using only one to many public run command documents.

JSON Sample

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

Inputs

All the inputs listed here are simply the enumeration of all send-command parameters across all public documents. For specific public command document specific value, please refer to the send-command api documentation. 

DocumentName

A string literal containing the name of the run command document.

Required: Yes

InstanceIds

A list of string literals containing the ids of the instances.

Required: Yes

Parameters

This is not a property. This is an additional section inside inputs section. It is a map of properties below.

Required: No

Comment

A string literal.

Required: No

DocumentHash

A string containing hash for the PowerShell module to be installed.

Required: No

DocumentHashType

A string containing type of the hash. Permitted values are Sha256 and Sha1.

Required: No

NotificationConfig

A map of string literals.

Required: No

OutputS3BucketName

A string literal.

Required: No

OutputS3KeyPrefix

A string literal.

Required: No

ServiceRoleArn

A string literal containing the ARN.

Required: No

TimeoutSeconds

An integer value to specify the run-command timeout seconds.

Required: No

Outputs

CommandId

String literal containing command id.

Output

String literal containing the truncated output of the command.

ResponseCode

String literals containing command status code.

Status

String literal indicating the status of the command.

Action aws:invokeLambdaFunction

You can use this action to invoke an existing Lambda function. Note that this action does not create the function if it does not exist.

JSON Sample

{
	"name": "invokeMyLambdaFunction",
      	"action": "aws:invokeLambdaFunction",
      	"maxAttempts": 3,
      	"timeoutSeconds": 120,
      	"onFailure": "Abort",
      	"inputs": {
        	"FunctionName": "MyLambdaFunction"
	}
}

Inputs

The action supports most invoke API’s parameters for Lambda service. For specific permitted value, please refer to the invoke api documentation. 

FunctionName

A string literal containing the id of the image to launch the instance.

Required: Yes

ClientContext

A string containing client context info.

Required: No

InvocationType

A string literal with permitted values RequestResponse or Event or DryRun.

Required: No

LogType

A string literal with permitted values None or Tail.

Required: No

Payload

A string literal.

Required: No

Qualifier

A string literal.

Required: No

Outputs

StatusCode

A string literals containing the function execution status code.

Action aws:changeInstanceState

You can use this action to either change or assert the state of the instance.

Important

This action can be used in assert mode i.e. not execute the start-instance/stop-instances/terminate-instances API to achieve the desired state, instead just validate that instance is desired state. The assert mode is activated by supplying parameter CheckStateOnly as true. This mode is very useful for customers executing Sysprep command in Windows AMIs. Sysprep is an asynchronous command. It runs in the background and can run for long time. So while its execution is incomplete if aws:changeInstanceState is executed without this flag CheckStateOnly set to true, when instance is stopped it will be in undesired state. The AMIs created from such instances may be defective.

JSON Sample

{
	"name":"stopMyInstance",
      	"action": "aws:changeInstanceState",
      	"maxAttempts": 3,
      	"timeoutSeconds": 3600,
      	"onFailure": "Abort",
      	"inputs": {
        	"InstanceIds": ["i-123456789"],
        	"CheckStateOnly": true,
        	"DesiredState": "stopped"
      	}
}

Inputs

DesiredState

A string literal with permitted values running or stopped or terminated.

Required: Yes

InstanceIds

A list of string literals containing the ids of the instances.

Required: Yes

AdditionalInfo

A string literal.

Required: No

CheckStateOnly

This is a boolean literal. If value is false, it’ll execute EC2 API like start-instance/stop-instances/terminate-instances to cause the desired state transition. If true, it only will assert desired state by polling for it.

Required: No

Force

A Boolean value. 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.

Required: No

Outputs

None.

Action aws:createImage

You can use this action to create a new image from a stopped instance.

Important

This action does not stop the instance implicitly. The user needs to use aws:changeInstanceState action to stop the instance. If this action is used on a running instance, the resultant AMI may be defective.

JSON Sample

{
	"name":"createMyImage",
	"action": "aws:createImage",
	"maxAttempts": 3,
	"onFailure": "Abort",
	"inputs": {
		"InstanceId": "i-123456789",
		"ImageName":  "AMI Created on{{global:DATE_TIME}}",
		"NoReboot": true,
		"ImageDescription": "My newly created AMI"
	}
}

Inputs

The action supports most create-image API’s parameters. For specific permitted value, please refer to the create-image api documentation. 

ImageName

A string literal containing the name of the image.

Required: Yes

InstanceId

A string literal containing the id of the instance.

Required: Yes

BlockDeviceMappings

A map list containing the mappings for the instance.

Required: No

ImageDescription

A string literal.

Required: No

NoReboot

A boolean literal.

Required: No

Outputs

ImageId

A string literals containing the id of the newly created image.

ImageState

A string literals containing the state of the newly created image.

Action aws:deleteImage

You can use this action to delete an existing image.

JSON Sample

{
	"name": "deleteMyImage",
      	"action": "aws:deleteImage",
      	"maxAttempts": 3,
      	"timeoutSeconds": 180,
      	"onFailure": "Abort",
      	"inputs": {
        	"ImageId": "ami-1234567890"
	}
}

Inputs

The action supports most of delete-image API’s parameters for Lambda service. For specific permitted value, please refer to the delete-image api documentation. 

ImageId

A string literal containing the id of the image to be deleted.

Required: Yes

Outputs

None.