Run commands at scale
You can use Run Command, a capability of AWS Systems Manager, to run commands on a fleet of
managed nodes by using the targets. The targets parameter
accepts a Key,Value combination based on tags that you specified for
your managed nodes. When you run the command, the system locates and attempts to run
the command on all managed nodes that match the specified tags. For more information
about tagging managed instances, see Tagging your AWS
resources in the Tagging AWS Resources User
Guide. For information about tagging your managed IoT devices, see Tag
your AWS IoT Greengrass Version 2 resources in the AWS IoT Greengrass Version 2 Developer Guide.
You can also use the targets parameter to target a list of specific
managed node IDs, as described in the next section.
To control how commands run across hundreds or thousands of managed nodes, Run Command also includes parameters for restricting how many nodes can simultaneously process a request and how many errors can be thrown by a command before the command is canceled.
Targeting multiple managed nodes
You can run a command and target managed nodes by specifying tags, AWS resource group names, or managed node IDs.
The following examples show the command format when using Run Command from the
AWS Command Line Interface (AWS CLI ). Replace each example resource
placeholder with your own information. Sample commands in this
section are truncated using [...].
Example 1: Targeting tags
Example 2: Targeting an AWS resource group by name
You can specify a maximum of one resource group name per command. When you
create a resource group, we recommend including
AWS::SSM:ManagedInstance and AWS::EC2::Instance as
resource types in your grouping criteria.
Note
In order to send commands that target a resource group, you must have been granted AWS Identity and Access Management (IAM) permissions to list or view the resources that belong to that group. For more information, see Set up permissions in the AWS Resource Groups User Guide.
Example 3: Targeting an AWS resource group by resource type
You can specify a maximum of five resource group types per command. When you
create a resource group, we recommend including
AWS::SSM:ManagedInstance and AWS::EC2::Instance as
resource types in your grouping criteria.
Note
In order to send commands that target a resource group, you must have been granted IAM permissions to list, or view, the resources that belong to that group. For more information, see Set up permissions in the AWS Resource Groups User Guide.
Example 4: Targeting instance IDs
The following examples show how to target managed nodes by using the
instanceids key with the targets parameter. You
can use this key to target managed AWS IoT Greengrass core devices because each device is
assigned an mi-ID_number. You can view device IDs in
Fleet Manager, a capability of AWS Systems Manager.
If you tagged managed nodes 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 managed nodes
in one of these environments by using the
targets parameter with the following syntax.
You could target additional managed nodes in other environments by adding to
the Values list. Separate items using commas.
Variation: Refining your targets using
multiple Key criteria
You can refine the number of targets for your command by including multiple
Key criteria. If you include more than one Key
criteria, the system targets managed nodes that meet all of
the criteria. The following command targets all managed nodes tagged for the
Finance Department and tagged for the database server
role.
Variation: Using multiple Key
and Value criteria
Expanding on the previous example, you can target multiple departments and
multiple server roles by including additional items in the Values
criteria.
Variation: Targeting tagged managed nodes
using multiple Values criteria
If you tagged managed nodes for different environments using a
Key named Department and Values of
Sales and Finance, then you could send a command
to all of the nodes in these environments by using the targets
parameter with the following syntax.
You can specify a maximum of five keys, and five values for each key.
If either a tag key (the tag name) or a tag value includes spaces, enclose the tag key or the value in quotation marks, as shown in the following examples.
Example: Spaces in Value
tag
Example: Spaces in tag key and
Value
Example: Spaces in one item in a list of
Values
Using rate controls
You can control the rate at which commands are sent to managed nodes in a group by using concurrency controls and error controls.
Using concurrency controls
You can control the number of managed nodes that run a command
simultaneously by using the max-concurrency parameter (the
Concurrency options in the Run a
command page). You can specify either an absolute number of
managed nodes, for example 10, or a percentage of the
target set, for example 10%. The queueing system
delivers the command to a single node and waits until the system
acknowledges the initial invocation before sending the command to two more
nodes. The system exponentially sends commands to more nodes until the
system meets the value of max-concurrency. The default for
value max-concurrency is 50. The following examples show you
how to specify values for the max-concurrency parameter.
Using error controls
You can also control the execution of a command to hundreds or thousands
of managed nodes by setting an error limit using the max-errors
parameters (the Error threshold field in the
Run a command page). The parameter specifies how
many errors are allowed before the system stops sending the command to
additional managed nodes. 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
3, for example, the system stops sending the
command when the fourth error is received. If you specify
0, then the system stops sending the command to
additional managed nodes after the first error result is returned. If you
send a command to 50 managed nodes and set max-errors to
10%, then the system stops sending the command to
additional nodes when the sixth error is received.
Invocations that are already running a command when
max-errors is reached are allowed to complete, but some of
these invocations might 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-errors is 0. The
following examples show you how to specify values for the
max-errors parameter.
