• 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).
# Run automated operations at scale
With AWS Systems Manager Automation, you can run automations on a fleet of AWS resources by using *targets*. Additionally, you can control the deployment of the automation across your fleet by specifying a concurrency value and an error threshold. The concurrency and error threshold features are collectively called *rate controls*. The concurrency value determines how many resources are allowed to run the automation simultaneously. Automation also provides an adaptive concurrency mode you can opt in to. Adaptive concurrency automatically scales your automation quota from 100 concurrently running automations up to 500. An error threshold determines how many automations are allowed to fail before Systems Manager stops sending the automation to other resources.
For more information about concurrency and error thresholds, see [Control automations at scale](running-automations-scale-controls.md). For more information about targets, see [Mapping targets for an automation](running-automations-map-targets.md).
The following procedures show you how to turn on adaptive concurrency, and how to run an automation with targets and rate controls by using the Systems Manager console and AWS Command Line Interface (AWS CLI).
## Running an automation with targets and rate controls (console)
The following procedure describes how to use the Systems Manager console to run an automation with targets and rate controls.
**To run an automation with targets and rate controls**
1. Open the AWS Systems Manager console at [https://console.aws.amazon.com/systems-manager/](https://console.aws.amazon.com/systems-manager/).
1. In the navigation pane, choose **Automation**, and then choose **Execute automation**.
1. In the **Automation document** list, choose a runbook. Choose one or more options in the **Document categories** pane to filter SSM documents according to their purpose. To view a runbook that you own, choose the **Owned by me** tab. To view a runbook that is shared with your account, choose the **Shared with me** tab. To view all runbooks, choose the **All documents** tab.
**Note**
You can view information about a runbook by choosing the runbook name.
1. In the **Document details** section, verify that **Document version** is set to the version that you want to run. The system includes the following version options:
+ **Default version at runtime** – Choose this option if the Automation runbook is updated periodically and a new default version is assigned.
+ **Latest version at runtime** – Choose this option if the Automation runbook is updated periodically, and you want to run the version that was most recently updated.
+ **1 (Default)** – Choose this option to run the first version of the document, which is the default.
1. Choose **Next**.
1. In the **Execution Mode** section, choose **Rate Control**. You must use this mode or **Multi-account and Region** if you want to use targets and rate controls.
1. In the **Targets** section, choose how you want to target the AWS resources where you want to run the Automation. These options are required.
1. Use the **Parameter** list to choose a parameter. The items in the **Parameter** list are determined by the parameters in the Automation runbook that you selected at the start of this procedure. By choosing a parameter you define the type of resource on which the Automation workflow runs.
1. Use the **Targets** list to choose how you want to target resources.
1. If you chose to target resources by using parameter values, then enter the parameter value for the parameter you chose in the **Input parameters** section.
1. If you chose to target resources by using AWS Resource Groups, then choose the name of the group from the **Resource Group** list.
1. If you chose to target resources by using tags, then enter the tag key and (optionally) the tag value in the fields provided. Choose **Add**.
1. If you want to run an Automation runbook on all instances in the current AWS account and AWS Region, then choose **All instances**.
1. In the **Input parameters** section, specify the required inputs. Optionally, you can choose an IAM service role from the **AutomationAssumeRole** list.
**Note**
You might not need to choose some of the options in the **Input parameters** section. This is because you targeted resources by using tags or a resource group. For example, if you chose the `AWS-RestartEC2Instance` runbook, then you don't need to specify or choose instance IDs in the **Input parameters** section. The Automation execution locates the instances to restart by using the tags or resource group you specified.
1. Use the options in the **Rate control** section to restrict the number of AWS resources that can run the Automation within each account-Region pair.
In the **Concurrency** section, choose an option:
+ Choose **targets** to enter an absolute number of targets that can run the Automation workflow simultaneously.
+ Choose **percentage** to enter a percentage of the target set that can run the Automation workflow simultaneously.
1. In the **Error threshold** section, choose an option:
+ Choose **errors** to enter an absolute number of errors allowed before Automation stops sending the workflow to other resources.
+ Choose **percentage** to enter a percentage of errors allowed before Automation stops sending the workflow to other resources.
1. (Optional) Choose a CloudWatch alarm to apply to your automation for monitoring. To attach a CloudWatch alarm to your automation, the IAM principal that starts the automation must have permission for the `iam:createServiceLinkedRole` action. For more information about CloudWatch alarms, see [Using Amazon CloudWatch alarms](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html). Note that if your alarm activates, the automation is stopped. If you use AWS CloudTrail, you will see the API call in your trail.
1. Choose **Execute**.
To view automations started by your rate control automation, in the navigation pane, choose Automation, and then select **Show child automations**.
After an automation execution completes, you can rerun the execution with the same or modified parameters. For more information, see [Rerunning automation executions](automation-rerun-executions.md).
## Running an automation with targets and rate controls (command line)
The following procedure describes how to use the AWS CLI (on Linux or Windows) or AWS Tools for PowerShell to run an automation with targets and rate controls.
**To run an automation with targets and rate controls**
1. Install and configure the AWS CLI or the AWS Tools for PowerShell, if you haven't already.
For information, see [Installing or updating the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and [Installing the AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell/latest/userguide/pstools-getting-set-up.html).
1. Run the following command to view a list of documents.
------
#### [ Linux & macOS ]
```
aws ssm list-documents
```
------
#### [ Windows ]
```
aws ssm list-documents
```
------
#### [ PowerShell ]
```
Get-SSMDocumentList
```
------
Note the name of the runbook that you want to use.
1. Run the following command to view details about the runbook. Replace the *runbook name* with the name of the runbook whose details you want to view. Also, note a parameter name (for example, `InstanceId`) that you want to use for the `--target-parameter-name` option. This parameter determines the type of resource on which the automation runs.
------
#### [ Linux & macOS ]
```
aws ssm describe-document \
--name runbook name
```
------
#### [ Windows ]
```
aws ssm describe-document ^
--name runbook name
```
------
#### [ PowerShell ]
```
Get-SSMDocumentDescription `
-Name runbook name
```
------
1. Create a command that uses the targets and rate control options you want to run. Replace each *example resource placeholder* with your own information.
*Targeting using tags*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets Key=tag:key name,Values=value \
--target-parameter-name parameter name \
--parameters "input parameter name=input parameter value,input parameter 2 name=input parameter 2 value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=tag:key name,Values=value ^
--target-parameter-name parameter name ^
--parameters "input parameter name=input parameter value,input parameter 2 name=input parameter 2 value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "tag:key name"
$Targets.Values = "value"
Start-SSMAutomationExecution `
DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "parameter name" `
-Parameter @{"input parameter name"="input parameter value";"input parameter 2 name"="input parameter 2 value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
*Targeting using parameter values*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets Key=ParameterValues,Values=value,value 2,value 3 \
--target-parameter-name parameter name \
--parameters "input parameter name=input parameter value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=ParameterValues,Values=value,value 2,value 3 ^
--target-parameter-name parameter name ^
--parameters "input parameter name=input parameter value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ParameterValues"
$Targets.Values = "value","value 2","value 3"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "parameter name" `
-Parameter @{"input parameter name"="input parameter value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
*Targeting using AWS Resource Groups*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets Key=ResourceGroup,Values=Resource group nname \
--target-parameter-name parameter name \
--parameters "input parameter name=input parameter value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=ResourceGroup,Values=Resource group name ^
--target-parameter-name parameter name ^
--parameters "input parameter name=input parameter value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "ResourceGroup"
$Targets.Values = "Resource group name"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "parameter name" `
-Parameter @{"input parameter name"="input parameter value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
*Targeting all Amazon EC2 instances in the current AWS account and AWS Region*
------
#### [ Linux & macOS ]
```
aws ssm start-automation-execution \
--document-name runbook name \
--targets "Key=AWS::EC2::Instance,Values=*" \
--target-parameter-name instanceId \
--parameters "input parameter name=input parameter value" \
--max-concurrency 10 \
--max-errors 25%
```
------
#### [ Windows ]
```
aws ssm start-automation-execution ^
--document-name runbook name ^
--targets Key=AWS::EC2::Instance,Values=* ^
--target-parameter-name instanceId ^
--parameters "input parameter name=input parameter value" ^
--max-concurrency 10 ^
--max-errors 25%
```
------
#### [ PowerShell ]
```
$Targets = New-Object Amazon.SimpleSystemsManagement.Model.Target
$Targets.Key = "AWS::EC2::Instance"
$Targets.Values = "*"
Start-SSMAutomationExecution `
-DocumentName "runbook name" `
-Targets $Targets `
-TargetParameterName "instanceId" `
-Parameter @{"input parameter name"="input parameter value"} `
-MaxConcurrency "10" `
-MaxError "25%"
```
------
The command returns an execution ID. Copy this ID to the clipboard. You can use this ID to view the status of the automation.
------
#### [ Linux & macOS ]
```
{
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}
```
------
#### [ Windows ]
```
{
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE"
}
```
------
#### [ PowerShell ]
```
a4a3c0e9-7efd-462a-8594-01234EXAMPLE
```
------
1. Run the following command to view the automation. Replace each *automation execution ID* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm describe-automation-executions \
--filter Key=ExecutionId,Values=automation execution ID
```
------
#### [ Windows ]
```
aws ssm describe-automation-executions ^
--filter Key=ExecutionId,Values=automation execution ID
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecutionList | `
Where {$_.AutomationExecutionId -eq "automation execution ID"}
```
------
1. To view details about the automation progress, run the following command. Replace each *automation execution ID* with your own information.
------
#### [ Linux & macOS ]
```
aws ssm get-automation-execution \
--automation-execution-id automation execution ID
```
------
#### [ Windows ]
```
aws ssm get-automation-execution ^
--automation-execution-id automation execution ID
```
------
#### [ PowerShell ]
```
Get-SSMAutomationExecution `
-AutomationExecutionId automation execution ID
```
------
The system returns information like the following.
------
#### [ Linux & macOS ]
```
{
"AutomationExecution": {
"StepExecutionsTruncated": false,
"AutomationExecutionStatus": "Success",
"MaxConcurrency": "1",
"Parameters": {},
"MaxErrors": "1",
"Outputs": {},
"DocumentName": "AWS-StopEC2Instance",
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
"ResolvedTargets": {
"ParameterValues": [
"i-02573cafcfEXAMPLE"
],
"Truncated": false
},
"ExecutionEndTime": 1564681619.915,
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
],
"DocumentVersion": "1",
"ExecutionStartTime": 1564681576.09,
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"StepExecutions": [
{
"Inputs": {
"InstanceId": "i-02573cafcfEXAMPLE"
},
"Outputs": {},
"StepName": "i-02573cafcfEXAMPLE",
"ExecutionEndTime": 1564681619.093,
"StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
"ExecutionStartTime": 1564681576.836,
"Action": "aws:executeAutomation",
"StepStatus": "Success"
}
],
"TargetParameterName": "InstanceId",
"Mode": "Auto"
}
}
```
------
#### [ Windows ]
```
{
"AutomationExecution": {
"StepExecutionsTruncated": false,
"AutomationExecutionStatus": "Success",
"MaxConcurrency": "1",
"Parameters": {},
"MaxErrors": "1",
"Outputs": {},
"DocumentName": "AWS-StopEC2Instance",
"AutomationExecutionId": "a4a3c0e9-7efd-462a-8594-01234EXAMPLE",
"ResolvedTargets": {
"ParameterValues": [
"i-02573cafcfEXAMPLE"
],
"Truncated": false
},
"ExecutionEndTime": 1564681619.915,
"Targets": [
{
"Values": [
"DEV"
],
"Key": "tag:ENV"
}
],
"DocumentVersion": "1",
"ExecutionStartTime": 1564681576.09,
"ExecutedBy": "arn:aws:sts::123456789012:assumed-role/Administrator/Admin",
"StepExecutions": [
{
"Inputs": {
"InstanceId": "i-02573cafcfEXAMPLE"
},
"Outputs": {},
"StepName": "i-02573cafcfEXAMPLE",
"ExecutionEndTime": 1564681619.093,
"StepExecutionId": "86c7b811-3896-4b78-b897-01234EXAMPLE",
"ExecutionStartTime": 1564681576.836,
"Action": "aws:executeAutomation",
"StepStatus": "Success"
}
],
"TargetParameterName": "InstanceId",
"Mode": "Auto"
}
}
```
------
#### [ PowerShell ]
```
AutomationExecutionId : a4a3c0e9-7efd-462a-8594-01234EXAMPLE
AutomationExecutionStatus : Success
CurrentAction :
CurrentStepName :
DocumentName : AWS-StopEC2Instance
DocumentVersion : 1
ExecutedBy : arn:aws:sts::123456789012:assumed-role/Administrator/Admin
ExecutionEndTime : 8/1/2019 5:46:59 PM
ExecutionStartTime : 8/1/2019 5:46:16 PM
FailureMessage :
MaxConcurrency : 1
MaxErrors : 1
Mode : Auto
Outputs : {}
Parameters : {}
ParentAutomationExecutionId :
ProgressCounters :
ResolvedTargets : Amazon.SimpleSystemsManagement.Model.ResolvedTargets
StepExecutions : {i-02573cafcfEXAMPLE}
StepExecutionsTruncated : False
Target :
TargetLocations : {}
TargetMaps : {}
TargetParameterName : InstanceId
Targets : {tag:Name}
```
------
**Note**
You can also monitor the status of the automation in the console. In the **Automation executions** list, choose the automation you just ran and then choose the **Execution steps** tab. This tab shows the status of the automation actions.
# Mapping targets for an automation
Use the `Targets` parameter to quickly define which resources are targeted by an automation. For example, if you want to run an automation that restarts your managed instances, then instead of manually selecting dozens of instance IDs in the console or typing them in a command, you can target instances by specifying Amazon Elastic Compute Cloud (Amazon EC2) tags with the `Targets` parameter.
When you run an automation that uses a target, AWS Systems Manager creates a child automation for each target. For example, if you target Amazon Elastic Block Store (Amazon EBS) volumes by specifying tags, and those tags resolve to 100 Amazon EBS volumes, then Systems Manager creates 100 child automations. The parent automation is complete when all child automations reach a final state.
**Note**
Any `input parameters` that you specify at runtime (either in the **Input parameters** section of the console or by using the `parameters` option from the command line) are automatically processed by all child automations.
You can target resources for an automation by using tags, Resource Groups,and parameter values. Additionally, you can use the `TargetMaps` option to target multiple parameter values from the command line or a file. The following section describes each of these targeting options in more detail.
## Targeting a tag
You can specify a single tag as the target of an automation. Many AWS resources support tags, including Amazon Elastic Compute Cloud (Amazon EC2) and Amazon Relational Database Service (Amazon RDS) instances, Amazon Elastic Block Store (Amazon EBS) volumes and snapshots, Resource Groups,and Amazon Simple Storage Service (Amazon S3) buckets, to name a few. You can quickly run automation on your AWS resources by targeting a tag. A tag is a key-value pair, such as Operating\$1System:Linux or Department:Finance. If you assign a specific name to a resource, then you can also use the word "Name" as a key, and the name of the resource as the value.
When you specify a tag as the target for an automation, you also specify a target parameter. The target parameter uses the `TargetParameterName` option. By choosing a target parameter, you define the type of resource on which the automation runs. The target parameter you specify with the tag must be a valid parameter defined in the runbook. For example, if you want to target dozens of EC2 instances by using tags, then choose the `InstanceId` target parameter. By choosing this parameter, you define *instances* as the resource type for the automation. When creating a custom runbook you must specify the **Target type** as `/AWS::EC2::Instance` to ensure only instances are used. Otherwise, all resources with the same tag will be targeted. When targeting instances with a tag, terminated instances might be included.
The following screenshot uses the `AWS-DetachEBSVolume` runbook. The logical target parameter is `VolumeId`.
![\[Using a tag as a target for a Systems Manager Automation\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/automation-rate-control-tags-1-new.png)
The `AWS-DetachEBSVolume` runbook also includes a special property called **Target type**, which is set to `/AWS::EC2::Volume`. This means that if the tag-key pair `Finance:TestEnv` returns different types of resources (for example, EC2 instances, Amazon EBS volumes, Amazon EBS snapshots) then only Amazon EBS volumes will be used.
**Important**
Target parameter names are case sensitive. If you run automations by using either the AWS Command Line Interface (AWS CLI) or AWS Tools for Windows PowerShell, then you must enter the target parameter name exactly as it's defined in the runbook. If you don't, the system returns an `InvalidAutomationExecutionParametersException` error. You can use the [DescribeDocument](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_DescribeDocument.html) API operation to see information about the available target parameters in a specific runbook. Following is an example AWS CLI command that provides information about the `AWS-DeleteSnapshot` document.
```
aws ssm describe-document \
--name AWS-DeleteSnapshot
```
Here are some example AWS CLI commands that target resources by using a tag.
**Example 1: Targeting a tag using a key-value pair to restart Amazon EC2 instances**
This example restarts all Amazon EC2 instances that are tagged with a key of *Department* and a value of *HumanResources*. The target parameter uses the *InstanceId* parameter from the runbook. The example uses an additional parameter to run the automation by using an Automation service role (also called an *assume role*).
```
aws ssm start-automation-execution \
--document-name AWS-RestartEC2Instance \
--targets Key=tag:Department,Values=HumanResources \
--target-parameter-name InstanceId \
--parameters "AutomationAssumeRole=arn:aws:iam::111122223333:role/AutomationServiceRole"
```
**Example 2: Targeting a tag using a key-value pair to delete Amazon EBS snapshots**
The following example uses the `AWS-DeleteSnapshot` runbook to delete all snapshots with a key of *Name* and a value of *January2018Backups*. The target parameter uses the *VolumeId* parameter.
```
aws ssm start-automation-execution \
--document-name AWS-DeleteSnapshot \
--targets Key=tag:Name,Values=January2018Backups \
--target-parameter-name VolumeId
```
## Targeting AWS Resource Groups
You can specify a single AWS resource group as the target of an automation. Systems Manager creates a child automation for every object in the target Resource Group.
For example, say that one of your Resource Groups is named PatchedAMIs. This Resource Group includes a list of 25 Windows Amazon Machine Images (AMIs) that are routinely patched. If you run an automation that uses the `AWS-CreateManagedWindowsInstance` runbook and target this Resource Group, then Systems Manager creates a child automation for each of the 25 AMIs. This means, that by targeting the PatchedAMIs Resource Group, the automation creates 25 instances from a list of patched AMIs. The parent automation is complete when all child automations complete processing or reach a final state.
The following AWS CLI command applies to the PatchAMIs Resource Group example. The command takes the *AmiId* parameter for the `--target-parameter-name` option. The command doesn't include an additional parameter defining which type of instance to create from each AMI. The `AWS-CreateManagedWindowsInstance` runbook defaults to the t2.medium instance type, so this command would create 25 t2.medium Amazon EC2 instances for Windows Server.
```
aws ssm start-automation-execution \
--document-name AWS-CreateManagedWindowsInstance \
--targets Key=ResourceGroup,Values=PatchedAMIs \
--target-parameter-name AmiId
```
The following console example uses a Resource Group called t2-micro-instances.
![\[Targeting an AWS resource group with a Systems Manager automation\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/automation-rate-control-resource-groups-new.png)
## Targeting parameter values
You can also target a parameter value. You enter `ParameterValues` as the key and then enter the specific resource value where you want the automation to run. If you specify multiple values, Systems Manager runs a child automation on each value specified.
For example, say that your runbook includes an **InstanceID** parameter. If you target the values of the **InstanceID** parameter when you run the Automation, then Systems Manager runs a child automation for each instance ID value specified. The parent automation is complete when the automation finishes running each specified instance, or if the automation fails. You can target a maximum of 50 parameter values.
The following example uses the `AWS-CreateImage` runbook. The target parameter name specified is *InstanceId*. The key uses *ParameterValues*. The values are two Amazon EC2 instance IDs. This command creates an automation for each instance, which produces an AMI from each instance.
```
aws ssm start-automation-execution
--document-name AWS-CreateImage \
--target-parameter-name InstanceId \
--targets Key=ParameterValues,Values=i-02573cafcfEXAMPLE,i-0471e04240EXAMPLE
```
**Note**
`AutomationAssumeRole` isn't a valid parameter. Don’t choose this item when running automation that target a parameter value.
### Targeting parameter value maps
The `TargetMaps` option expands your ability to target `ParameterValues`. You can enter an array of parameter values by using `TargetMaps` at the command line. You can specify a maximum of 50 parameter values at the command line. If you want to run commands that specify more than 50 parameter values, then you can enter the values in a JSON file. You can then call the file from the command line.
**Note**
The `TargetMaps` option isn't supported in the console.
Use the following format to specify multiple parameter values by using the `TargetMaps` option in a command. Replace each *example resource placeholder* with your own information.
```
aws ssm start-automation-execution \
--document-name runbook name \
--target-maps “parameter=value, parameter 2=value, parameter 3=value” “parameter 4=value, parameter 5=value, parameter 6=value”
```
If you want to enter more than 50 parameter values for the `TargetMaps` option, then specify the values in a file by using the following JSON format. Using a JSON file also improves readability when providing multiple parameter values.
```
[
{“parameter”: "value", “parameter 2”: "value", “parameter 3”: "value"},
{“parameter 4”: "value", “parameter 5”: "value", "parameter 6": "value"}
]
```
Save the file with a .json file extension. You can call the file by using the following command. Replace each *example resource placeholder* with your own information.
```
aws ssm start-automation-execution \
--document-name runbook name \
–-parameters input parameters \
--target-maps path to file/file name.json
```
You can also download the file from an Amazon Simple Storage Service (Amazon S3) bucket, as long as you have permission to read data from the bucket. Use the following command format. Replace each *example resource placeholder* with your own information.
```
aws ssm start-automation-execution \
--document-name runbook name \
--target-maps http://amzn-s3-demo-bucket.s3.amazonaws.com/file_name.json
```
Here is an example scenario to help you understand the `TargetMaps` option. In this scenario, a user wants to create Amazon EC2 instances of different types from different AMIs. To perform this task, the user creates a runbook named AMI\$1Testing. This runbook defines two input parameters: `instanceType` and `imageId`.
```
{
"description": "AMI Testing",
"schemaVersion": "0.3",
"assumeRole": "{{assumeRole}}",
"parameters": {
"assumeRole": {
"type": "String",
"description": "Role under which to run the automation",
"default": ""
},
"instanceType": {
"type": "String",
"description": "Type of EC2 Instance to launch for this test"
},
"imageId": {
"type": "String",
"description": "Source AMI id from which to run instance"
}
},
"mainSteps": [
{
"name": "runInstances",
"action": "aws:runInstances",
"maxAttempts": 1,
"onFailure": "Abort",
"inputs": {
"ImageId": "{{imageId}}",
"InstanceType": "{{instanceType}}",
"MinInstanceCount": 1,
"MaxInstanceCount": 1
}
}
],
"outputs": [
"runInstances.InstanceIds"
]
}
```
The user then specifies the following target parameter values in a file named `AMI_instance_types.json`.
```
[
{
"instanceType" : ["t2.micro"],
"imageId" : ["ami-b70554c8"]
},
{
"instanceType" : ["t2.small"],
"imageId" : ["ami-b70554c8"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
},
{
"instanceType" : ["t2.medium"],
"imageId" : ["ami-cfe4b2b0"]
}
]
```
The user can run the automation and create the five EC2 instances defined in `AMI_instance_types.json` by running the following command.
```
aws ssm start-automation-execution \
--document-name AMI_Testing \
--target-parameter-name imageId \
--target-maps file:///home/TestUser/workspace/runinstances/AMI_instance_types.json
```
## Targeting all Amazon EC2 instances
You can run an automation on all Amazon EC2 instances in the current AWS account and AWS Region by choosing **All instances** in the **Targets** list. For example, if you want to restart all Amazon EC2 instances your AWS account and the current AWS Region, you can choose the `AWS-RestartEC2Instance` runbook and then choose **All instances** from the **Targets** list.
![\[Targeting all Amazon EC2 instances for a runbook\]](http://docs.aws.amazon.com/systems-manager/latest/userguide/images/automation-rate-control-target-all-instances.png)
After you choose **All instances**, Systems Manager populates the **Instance** field with an asterisk (\$1) and makes the field unavailable for changes (the field is grayed out). Systems Manager also makes the **InstanceId** field in the **Input parameters** field unavailable for changes. Making these fields unavailable for changes is expected behavior if you choose to target all instances.
# Control automations at scale
You can control the deployment of an automation across a fleet of AWS resources by specifying a concurrency value and an error threshold. Concurrency and error threshold are collectively called *rate controls*.
**Concurrency**
Use Concurrency to specify how many resources are allowed to run an automation simultaneously. Concurrency helps to limit the impact or downtime on your resources when processing an automation. You can specify either an absolute number of resources, for example 20, or a percentage of the target set, for example 10%.
The queueing system delivers the automation to a single resource and waits until the initial invocation is complete before sending the automation to two more resources. The system exponentially sends the automation to more resources until the concurrency value is met.
**Error thresholds**
Use an error threshold to specify how many automations are allowed to fail before AWS Systems Manager stops sending the automation to other resources. 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 an absolute number of 3 errors, 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 send an automation to, for example, 50 instances and set the error threshold to 10%, then the system stops sending the command to additional instances when the fifth error is received. Invocations that are already running an automation when an error threshold is reached are allowed to be completed, but some of these automations might fail as well. If you need to ensure that there won’t be more errors than the number specified for the error threshold, then set the **Concurrency** value to 1 so that automations proceed one at a time.