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

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

AWS Systems Manager の一機能である Run Command を使用して、targets パラメータで、数十、数百、または数千のマネージドノードにコマンドを送信することができます。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 リソースグループを名前に基づいてターゲットにする

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

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

DevelopmentTestPre-productionProductionEnvironmentValues という名前の 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 のうち DepartmentValues という 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 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 のリスト内にある 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] (コマンドを実行) ページの [Concurrecy] ((同時実行数) オプションを使用して、同時にコマンドを実行するマネージドノードの数を制御できます。マネージドノードの絶対数 (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-errors10% に設定した場合、6 番目のエラーが受信されると、システムから他のノードにコマンドが送信されなくなります。

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