ターゲットとレート制御を使用してフリートにコマンドを送信する - AWS Systems Manager

ターゲットとレート制御を使用してフリートにコマンドを送信する

targets パラメータ (コンソールの [Run a command] ページの [Specify instance tags] オプション) を使用すると、数十、数百、数千のインスタンスにコマンドを送信できます。targets パラメータは、インスタンスに指定した Amazon EC2 タグに基づいて Key,Value の組み合わせを受け取ります。コマンドを実行すると、システムは指定されたタグと一致するすべてのインスタンスでコマンドの実行を試みます。Amazon EC2 タグの詳細については、Amazon EC2 ユーザーガイドの「Amazon EC2 リソースにタグを付ける」を参照してください (内容は Windows Server および Linux インスタンスに適用されます)。AWS リソースグループに属するインスタンスにコマンドを送信することもできます。リソースグループの詳細については、『AWS Resource Groups ユーザーガイド』の「 リソースグループとは」を参照してください。

注記

以下のセクションで説明しているように、targets パラメータを使用して、特定のインスタンス ID のリストを対象にできます。

数百または数千のインスタンスにまたがってコマンドを制御するために、Run Command には、同時に 1 つのリクエストを処理できるインスタンス数とコマンドが終了されるまでにスローできるエラー数を制限するためのパラメータも用意されています。

複数のインスタンスを対象にする

コマンドとターゲットインスタンスを実行するには、マネージドインスタンス、AWS リソースグループ名、またはインスタンス ID に適用されるタグを指定します。

注記

このセクションのサンプルコマンドは、[...] で省略されています。

AWS CLI send-command コマンドで使用できるように、targets パラメータは、次の例に示す構文をサポートします。

例 1: タグをターゲットにする

Linux
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:ManagedInstanceAWS::EC2::Instance をグループ化の条件に含めることをお勧めします。

注記

リソースグループをターゲットとするコマンドを送信するには、そのグループに属するリソースをリストまたは表示する IAM アクセス許可が付与されている必要があります。詳細については、AWS Resource Groups ユーザーガイド の「アクセス許可の設定」を参照してください。

Linux
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: インスタンス ID をターゲットにする

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

複数の異なる環境のインスタンスに対して Key として Environment を使用し、Values として DevelopmentTestPre-productionProduction を使用してタグを付けると、個別の環境のすべてのインスタンスに対して次の構文の targets パラメータを使用してコマンドを送信できます。

Linux
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
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
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
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 条件を使用してタグ付けされたインスタンスを対象にする

複数の異なる環境のインスタンスに対して Key として Department を使用し、Values として Sales および Finance を使用してタグを付けた場合、次の targets パラメータを使用した構文で個別の環境のすべてのインスタンスに対してコマンドを送信できます。

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

Linux
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% など) を指定できます。キューシステムにより、コマンドは 1 つのインスタンスに送信され、この最初の呼び出しが完了するのを待ってから、さらに 2 つのインスタンスにコマンドが送信されます。max-concurrency の値に達するまで、コマンドの送信先のインスタンス数は指数関数的に増えていきます。max-concurrency のデフォルト値は 50 です。次の例は、max-concurrency パラメータの値を指定する方法を示しています。

Linux
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] ページの [エラーのしきい値] フィールド)。このパラメータが指定するエラー数に達すると、システムからは他のインスタンスにコマンドが送信されなくなります。エラーの絶対数 (10 など) またはターゲットセットのパーセント数 (10% など) を指定できます。たとえば、3 を指定した場合、4 番目のエラーが受信されると、システムからコマンドが送信されなくなります。0 を指定した場合、最初のエラー結果が返されると、システムから他のインスタンスにコマンドが送信されなくなります。コマンドの送信先のインスタンス数が 50 で max-errors10% に設定した場合、6 番目のエラーが受信されると、システムから他のインスタンスにコマンドが送信されなくなります。

max-errors に達したときに既にコマンドを実行中の呼び出しについては、完了はできますが、一部が失敗する場合があります。呼び出しの失敗数が max-errors を超えないようにするには、max-concurrency1 に設定して、一度に 1 つの呼び出しが処理されるようにします。max-errors のデフォルト値は 0 です。次の例は、max-errors パラメータの値を指定する方法を示しています。

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