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

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

您可以透過 targets 參數使用 Run Command (AWS Systems Manager 的功能) 傳送命令至數十、數百或數千個受管節點。targets 參數接受以您為受管節點指定的標記為基礎的 Key,Value 組。當您執行命令時,系統會尋找並嘗試在符合指定標記的所有受管節點上執行命令。如需標記受管執行個體的詳細資訊,請參閱《AWS Resource Groups 使用者指南》中的標籤編輯器。如需標記受管 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: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 為目標

下列範例示範如何將 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 ^ [...]

如果您使用名為 EnvironmentKey 以及 DevelopmentTestPre-productionValues 以及 Production,為不同環境的受管節點加上標記,則您可以使用 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 ^ [...]