コマンドを大規模に実行する
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 コアデバイスをターゲットにすることができます。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
^
[...]
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
^
[...]