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.
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:
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:
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:
aws ssm send-command --document-name name --max-concurrency 10 --targets "Key=tag:Environment,Values=Development" [...]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:
aws ssm send-command --document-name name --max-errors 10 --targets "Key=tag:Database,Values=Development" [...]--document-name name --max-errors 10% --targets "Key=tag:Environment,Values=Development" [...]aws ssm send-command --document-name name --max-concurrency 1 --max-errors 1 --targets "Key=tag:Environment,Values=Production" [...]
