使用目標和速率控制將命令傳送至機群 - AWS Systems Manager

使用目標和速率控制將命令傳送至機群

您可以使用 targets 參數 (主控台 Run a command (執行命令) 頁面中 Specify instance tags (指定執行個體標籤) 選項),傳送命令至數十個、數百個或數千個執行個體。targets 參數接受基於 Amazon Elastic Compute Cloud (Amazon EC2) 標籤的 Key,Value 組合,而標籤由您為執行個體指定。當您執行命令時,系統會尋找並嘗試在符合指定標記的所有執行個體上執行命令。如需 Amazon EC2 標籤的詳細資訊,請參閱《Amazon EC2 使用者指南》中的標記您的 Amazon EC2 資源 (內容適用於 Windows Server 和 Linux 執行個體)。您也可以將命令傳送至屬於 AWS 資源群組的執行個體。如需 Resource Groups 的詳細資訊,請參閱《AWS Resource Groups 使用者指南》中的什麼是 Resource Groups?

您也可以使用 targets 參數設為目標的特定執行個體 ID,清單中所述的下一個部分。

若要在數百或者數千個執行個體間控制命令如何執行,Run Command (AWS Systems Manager 功能) 還包含可限制可以同時處理請求之執行個體數的參數,以及命令取消時命令能擲回的錯誤數。

以多個執行個體為目標

您可以透過指定在受管執行個體中套用的標籤、AWS 資源群組名稱或執行個體 ID,來執行命令和將執行個體視為目標。

若要使用 AWS Command Line Interface (AWS CLI ) send-command 命令,targets 參數支援下列範例中示範的語法。使用 [...] 將此區段中的範本命令截斷。

範例 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:ManagedInstanceAWS::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:ManagedInstanceAWS::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 為目標

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 ^ [...]

如果您使用名為 EnvironmentKey 以及 DevelopmentTestPre-productionProductionValues,為不同環境的執行個體加上標籤,則您可以使用 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 ^ [...]

變異:使用多個 KeyValue 條件

在之前的範例中展開,您可以透過在 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 條件以標記的執行個體為目標

如果您使用名為 DepartmentKey 以及 SalesFinanceValues,為不同環境的執行個體加上標記,則您可以使用 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 Nano" \ [...]
Windows
aws ssm send-command ^ --document-name document-name ^ --targets Key=tag:OS,Values="Windows Server 2016 Nano" ^ [...]

範例tag 索引鍵中的空格和 Value

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

範例 :在 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 (執行命令) 頁面中的 Concurrecy (並行) 選項) 控制同時執行之伺服器的數量。您可以指定絕對數量的執行個體 (例如 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,系統會在收到第 4 個錯誤時停止傳送命令。如果您指定 0,系統會在第一個錯誤結果傳回後停止將命令傳送至其他執行個體。如果您將命令傳送至 50 個執行個體,並將 max-errors 設為 10%,系統會在收到第六個錯誤時停止將命令傳送至其他執行個體。

達到 max-errors 時,系統會允許完成已在執行命令的呼叫,但一些呼叫也可能會失敗。如果您需要確保不會有超過 max-errors 個失敗的呼叫,請將 max-concurrency 設定為 1,以每次執行一個呼叫。錯誤上限預設值為 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 ^ [...]