Menu
Amazon EC2 Systems Manager
User Guide

Sending a Command to Multiple Instances

You can send commands to tens, hundreds, or thousands of instances by using the targets parameter, which is currently supported when executing commands from the AWS CLI. The targets parameter accepts a Key,Value combination based on Amazon EC2 tags that you specified for your instances. When you execute the command, the system locates and attempts to run the command on all instances that match the specified criteria. For more information about Amazon EC2 tags, see Tagging Your Amazon EC2 Resources in the Amazon EC2 User Guide.

To control command execution across hundreds or thousands of instances, Run Command also includes parameters for restricting how many instances can simultaneously process a request and how many errors can be thrown by a command before the command is terminated.

Targeting Multiple Instances

The targets parameter uses the following syntax:

Copy
aws ssm send-command --document-name name --targets "Key=tag:tag name,Values=tag value" [...]

Note

Example commands in this section are truncated using [...].

For example, if you tagged instances for different environments using a Key named Environment and Values of Development, Test, Pre-production and Production, then you could send a command to all of the instances in one of these environments by using the targets parameter with the following syntax:

Copy
aws ssm send-command --document-name name --targets "Key=tag:Environment,Values=Development" [...]

Using Concurrency Controls

You can control how many servers execute the command at the same time by using the max-concurrency parameter. You can specify either an absolute number of instances, for example 10, or a percentage of the target set, for example 10%. The queueing system delivers the command to a single instance and waits until the initial invocation completes before sending the command to two more instances. The system exponentially sends commands to more instances until the value of max-concurrency is met. The default for value max-concurrency is 50. The following examples show you how to specify values for the max-concurrency parameter:

Copy
aws ssm send-command --document-name name --max-concurrency 10 --targets "Key=tag:Environment,Values=Development" [...]
Copy
aws ssm send-command --document-name name --max-concurrency 10% --targets Key=tag:Department,Values=Finance,Marketing" "Key=tag:ServerRole,Values=WebServer,Database" [...]

Using Error Controls

You can also control the execution of a command to hundreds or thousands of instances by setting an error limit using the max-errors parameters. The parameter specifies how many errors are allowed before the system stops sending the command to additional instances. 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 0, then the system stops sending the command to additional instances after the first error result is returned. If you send a command to 50 instances and set max-errors to 10%, then the system stops sending the command to additional instances after the fifth error.

Invocations that are already running a command when max-errors is reached are allowed to complete, but some of these invocations may fail as well. If you need to ensure that there won’t be more than max-errors failed invocations, set max-concurrency to 1 so the invocations proceed one at a time. The default for max-concurrency is 50. The following examples show you how to specify values for the max-errors parameter:

Copy
aws ssm send-command --document-name name --max-errors 10 --targets "Key=tag:Database,Values=Development" [...]
Copy
--document-name name --max-errors 10% --targets "Key=tag:Environment,Values=Development" [...]
Copy
aws ssm send-command --document-name name --max-concurrency 1 --max-errors 1 --targets "Key=tag:Environment,Values=Production" [...]