大规模运行命令 - AWS Systems Manager
将多个托管式节点设为目标使用速率控制

大规模运行命令

您可以使用（Run CommandAWS Systems Manager 的一项功能）通过使用 targets 在托管节点实例集上运行命令。targets 参数根据您为托管式节点指定的标签接受 Key,Value 组合。当您运行该命令时，系统会找到并尝试在匹配指定标签的所有托管式节点上运行命令。有关标记托管式实例的更多信息，请参阅《Tagging AWS Resources User Guide》中的 Tagging your AWS resources。有关标记托管式 IoT 设备的信息，请参阅 AWS IoT Greengrass Version 2 开发人员指南中的标记 AWS IoT Greengrass Version 2 资源。

您也可以使用 targets 参数将特定托管式节点 ID 的列表设为目标，如下一部分中所述。

为控制数百个或数千个托管式节点的命令运行，Run Command 还包含一些参数，用于限制同时处理一个请求的节点数量以及取消命令前其可引发的错误数量。

将多个托管式节点设为目标

您可以通过指定标签、AWS 资源组名称或托管式节点 ID 来运行命令并将托管式节点设为目标。

以下示例显示使用 AWS Command Line Interface (AWS CLI ) 中的 Run Command 时的命令格式。将每个示例资源占位符替换为您自己的信息。本部分的示例命令使用 [...] 进行截断。

示例 1：将标签设为目标

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:tag-name,Values=tag-value \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:tag-name,Values=tag-value ^
    [...]

示例 2：通过名称将 AWS 资源组设为目标

您最多可以为每个命令指定一个资源组名称。当您创建资源组时，我们建议您包含 AWS::SSM:ManagedInstance 和 AWS::EC2::Instance 作为分组条件中的资源类型。

注意

为发送将资源组设为目标的命令，您必须已获得列出或查看属于该组的资源的 AWS Identity and Access Management (IAM) 权限。有关更多信息，请参阅 AWS Resource Groups 用户指南中的设置权限。

Linux & macOS
aws ssm send-command \    
    --document-name document-name \
    --targets Key=resource-groups:Name,Values=resource-group-name \
    [...]
Windows
aws ssm send-command ^    
    --document-name document-name ^
    --targets Key=resource-groups:Name,Values=resource-group-name ^
    [...]

示例 3：通过资源类型将 AWS 资源组设为目标

您最多可以为每个命令指定五个资源组类型。当您创建资源组时，我们建议您包含 AWS::SSM:ManagedInstance 和 AWS::EC2::Instance 作为分组条件中的资源类型。

注意

为了发送将资源组设为目标的命令，您必须已被授予列出或查看属于该组的资源的 IAM 权限。有关更多信息，请参阅 AWS Resource Groups 用户指南中的设置权限。

Linux & macOS
aws ssm send-command \    
    --document-name document-name \
    --targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 \
    [...]
Windows
aws ssm send-command ^    
    --document-name document-name ^
    --targets Key=resource-groups:ResourceTypeFilters,Values=resource-type-1,resource-type-2 ^
    [...]

示例 4：将实例 ID 设为目标

以下示例演示如何使用 instanceids 密钥和 targets 参数将托管式节点设为目标。您可以使用此密钥来将托管式 AWS IoT Greengrass 核心设备设为目标，因为每台设备分配到了 mi-ID_NUMBER。您可以在 Fleet Manager（AWS Systems Manager 的一项功能）中查看设备 ID。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=instanceids,Values=instance-ID-1,instance-ID-2,instance-ID-3 ^
    [...]

如果您使用名为 Environment 的 Key，以及 Development、Test、Pre-production 和 Production 的 Values 标记不同环境的托管式节点，则可以使用采用以下语法的 targets 参数，向其中一个环境的所有托管式节点发送命令。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:Environment,Values=Development \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:Environment,Values=Development ^
    [...]

通过添加到 Values 列表，您可以将其他环境中的其他托管式节点设为目标。使用逗号分隔项目。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:Environment,Values=Development,Test,Pre-production \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:Environment,Values=Development,Test,Pre-production ^
    [...]

变体：使用多个 Key 条件细化您的目标。

通过包括多个 Key 条件，您可以细化您的命令的目标数。如果包括多个 Key 条件，系统会将符合所有条件的托管式节点设为目标。以下命令会将标记为财务部门和标记为数据库服务器角色的所有托管式节点设为目标。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:Department,Values=Finance Key=tag:ServerRole,Values=Database ^
    [...]

变体：使用多个 Key 和 Value 条件

对上一个示例进行扩展，您可以通过在 Values 条件中包括其他项目来将多个部门和多个服务器角色设为目标。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^
    [...]

变体：使用多个 Values 条件将已标记托管式节点设为目标

如果您使用名为 Department 的 Key，以及 Sales 和 Finance 的 Values 标记不同环境的托管式节点，则可以使用采用以下语法的 targets 参数，向这些环境的所有节点发送命令。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:Department,Values=Sales,Finance \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:Department,Values=Sales,Finance ^
    [...]

您最多可以为每个键指定五个键和五个值。

如果某个标签密钥（标签名称）或某个标签值包含空格，则需要将该标签密钥或该值用引号引起来，如以下示例所示。

示例： Value 标签中的空格

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:OS,Values="Windows Server 2016" \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:OS,Values="Windows Server 2016" ^
    [...]

示例： tag 键和 Value 中的空格

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key="tag:Operating System",Values="Windows Server 2016" \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key="tag:Operating System",Values="Windows Server 2016" ^
    [...]

示例：Values 的列表中一个项目中的空格

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --targets Key=tag:Department,Values="Sales","Finance","Systems Mgmt" ^
    [...]

使用速率控制

您可以使用并发控件和错误控件，控制将命令发送到组中托管式节点的速率。

使用并发控件

您可以使用 max-concurrency 参数 [Run a command（运行命令）页面中的 Concurrency（并发）选项] 来控制同时运行命令的托管式节点数量。您可以指定绝对数量的托管式节点（例如 10），也可以指定目标集百分比（例如 10%）。队列系统将命令传递给单个节点，并等待系统确认了初始调用，再将命令发送到两个或更多节点。系统以指数增长方式将命令发送到更多节点，直到系统达到 max-concurrency 值。max-concurrency 值默认为 50。下列示例介绍如何为 max-concurrency 参数指定值。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --max-concurrency 10 \
    --targets Key=tag:Environment,Values=Development \
    [...]
aws ssm send-command \
    --document-name document-name \
    --max-concurrency 10% \
    --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --max-concurrency 10 ^
    --targets Key=tag:Environment,Values=Development ^
    [...]
aws ssm send-command ^
    --document-name document-name ^
    --max-concurrency 10% ^
    --targets Key=tag:Department,Values=Finance,Marketing Key=tag:ServerRole,Values=WebServer,Database ^
    [...]

使用错误控件

您也可以使用 max-errors 参数 [Run a command（运行命令）页面中的 Error threshold（错误阈值）字段] 设置错误限制，将命令的执行控制在几百个或几千个托管式节点范围内。该参数指定系统停止向其他托管式节点发送命令之前所允许的错误数。您可以指定绝对数量的错误（例如 10），也可以指定目标集百分比（例如 10%）。例如，如果您指定 3，系统将在收到第四个错误时停止发送命令。如果您指定 0，则系统会在返回第一个错误结果后停止向其他托管式节点发送命令。如果您向 50 个托管式节点发送命令并将 max-errors 设置为 10%，则系统会在收到第六个错误时停止向其他节点发送命令。

当达到 max-errors 时，允许完成已经运行命令的调用，但是其中一些调用也可能失败。如果您需要确保失败的调用数不超过 max-errors，请将 max-concurrency 设置为 1，以便一次进行一个调用。max-errors 默认为 0。下列示例介绍如何为 max-errors 参数指定值。

Linux & macOS
aws ssm send-command \
    --document-name document-name \
    --max-errors 10 \
    --targets Key=tag:Database,Values=Development \
    [...]
aws ssm send-command \
    --document-name document-name \
    --max-errors 10% \
    --targets Key=tag:Environment,Values=Development \
    [...]
aws ssm send-command \
    --document-name document-name \
    --max-concurrency 1 \
    --max-errors 1 \
    --targets Key=tag:Environment,Values=Production \
    [...]
Windows
aws ssm send-command ^
    --document-name document-name ^
    --max-errors 10 ^
    --targets Key=tag:Database,Values=Development ^
    [...]
aws ssm send-command ^
    --document-name document-name ^
    --max-errors 10% ^
    --targets Key=tag:Environment,Values=Development ^
    [...]
aws ssm send-command ^
    --document-name document-name ^
    --max-concurrency 1 ^
    --max-errors 1 ^
    --targets Key=tag:Environment,Values=Production ^
    [...]