コマンドを大規模に実行する - AWS Systems Manager
複数のマネージドノードをターゲットにするレート制御の使用

コマンドを大規模に実行する

AWS Systems Manager のツールである Run Command を使用すると、targets を使用してマネージドノードのフリートでコマンドを実行できます。targets パラメータは、マネージドノードに指定したタグに基づいて Key,Value の組み合わせを受け取ります。コマンドを実行すると、システムは指定されたタグと一致するすべてのマネージドノードでコマンドの実行を試みます。マネージドインスタンスへのタグ付けの詳細については、「AWS リソースのタグ付けユーザーガイド」の「AWS リソースのタグ付け」を参照してください。マネージド 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 リソースグループを名前に基づいてターゲットにする

コマンドごとに最大 1 つのリソースグループ名を指定できます。リソースグループを作成する場合は、リソースタイプとして 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 リソースグループをターゲットにする

コマンドごとに最大 5 つのリソースグループタイプを指定できます。リソースグループを作成する場合は、リソースタイプとして 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 パラメータを使用してマネージドノードをターゲットにする方法を示します。各デバイスには mi-ID_number が割り当てられているので、このキーを使ってマネージド AWS IoT Greengrass コアデバイスをターゲットにすることができます。デバイス ID は AWS Systems Manager のツールである Fleet Manager で確認できます。

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

Development、Test、Pre-production、Production の Environment と Values という名前の Key を使用して、複数の異なる環境のマネージドノードに対してタグ付けされると、次の構文の targets パラメータを使用してこれらの環境の 1 つにあるすべてのマネージドノードにコマンドを送信できます。

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 条件を含めると、システムは全ての条件を満たマネージドノードをターゲットにします。次のコマンドは、Finance Department およびデータベース サーバーロールに対してタグが付いているすべてのマネージドノードをターゲットとします。

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 条件を使用してタグ付けされたマネージドノードをターゲットにします

複数の異なる環境のマネージドノードに対して Sales および Finance のうち Department と Values という Key を使用してタグ付けされた場合、次の 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 ^
    [...]

各キーには、最大 5 つのタグキーと 5 つの値を指定できます。

タグキー (タグの名前) またはタグ値にスペースが含まれる場合、次の例に示すようにタグキーまたは値を疑問符で囲みます。

例: 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 のリスト内にある 1 つの項目にスペースが含まれる場合

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% など) を指定できます。キューシステムにより、コマンドは 1 つのノードに送信され、システムがこの最初の呼び出しを確認するのを待ってから、さらに 2 つのノードにコマンドが送信されます。システムで 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% に設定した場合、6 番目のエラーが受信されると、システムから他のノードにコマンドが送信されなくなります。

max-errors に達したときに既にコマンドを実行中の呼び出しについては、完了はできますが、一部が失敗する場合があります。呼び出しの失敗数が max-errors を超えないようにするには、max-concurrency を 1 に設定して、一度に 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 ^
    [...]