コマンドのステータスについて
Run Command の一機能である AWS Systems Manager は、コマンドの各処理状態とコマンドを処理した各マネージノードの詳細なステータス情報をレポートします。次の方法を使用して、コマンドのステータスをモニタリングできます。
-
Run Command コンソールインターフェイスの [Commands] (コマンド) タブで、[Refresh] (更新) アイコンを選択します。
-
AWS Command Line Interface (AWS CLI) を使用して list-commands または list-command-invocations を呼び出します。あるいは、AWS Tools for Windows PowerShell を使用して Get-SSMCommand または Get-SSMCommandInvocation を呼び出します。
-
状態またはステータスの変更に応答するように Amazon EventBridge を設定します。
-
すべての状況の変化、または
Failed
やTimedOut
など特定のステータスに関する通知を送信するよう、Amazon Simple Notification Service (Amazon SNS) を設定します。
Run Command のステータス
Run Command は、プラグイン、呼び出し、コマンドのステータス全体という 3 つのエリアでステータスの詳細をレポートします。プラグインは、コマンドの (SSM) ドキュメントに定義されているコード実行ブロックです。プラグインの詳細については、「コマンドドキュメントプラグインリファレンス」を参照してください。
複数のマネージノードに、コマンドを同時に送信するとき、各ノードを対象とするコマンドの各コピーは、コマンド呼び出しです。例えば、AWS-RunShellScript
ドキュメントを使用して 20 個の Linux インスタンスに ifconfig
コマンドを送信すると、そのコマンドには 20 個の呼び出しがあります。各コマンド呼び出しで、個別にステータスが報告されます。コマンド呼び出しに含まれているプラグインも、個々にステータスを報告します。
最後に、Run Command コマンドには、すべてのプラグインと呼び出しの集約されたコマンドステータスがあります。集約されたコマンドステータスは、以下の表に示すように、プラグインまたは呼び出しによってレポートされるステータスとは異なる場合があります。
注記
max-concurrency
パラメータまたは max-errors
パラメータを使用して多数のマネージノードに対してコマンドを実行する場合は、以下の表に示すように、これらのパラメータによって強制される制限がコマンドのステータスに反映されます。これらのパラメータの詳細については、コマンドを大規模に実行するを参照してください。
ステータス | 詳細 |
---|---|
保留中 | コマンドがまだマネージドノードに送信されていないか、SSM Agent によって受信されていません。Timeout (seconds) パラメータと Execution timeout パラメータの合計に等しい時間が経過する前にエージェントがコマンドを受信しなかった場合、ステータスは Delivery Timed Out に変わります。 |
InProgress | Systems Manager がマネージドノードにコマンドを送信しようとしている、またはコマンドが SSM Agent によって受信され、インスタンスでその実行が開始されました。すべてのコマンドプラグインの結果に応じて、ステータスは Success 、Failed 、 Delivery
Timed Out 、Execution Timed Out のいずれかに変わります。例外: エージェントが実行中でないか、ノードで使用できない場合、コマンドステータスはエージェントが再び使用可能になるまで、または実行タイムアウト制限に達するまで In
Progress のままになります。その後、ステータスは終了状態に変わります。 |
Delayed | システムからマネージドノードにコマンドを送信しようとしましたが成功しませんでした。システムは再試行します。 |
成功 | このステータスはさまざまな条件下で返されます。このステータスは、コマンドがノード上で処理されたという意味ではありません。例えば、コマンドはマネージドノードで SSM Agent によって受信され、PowerShell の ExecutionPolicy によってコマンドの実行が阻止された結果として終了コード 0 が返されることがあります。これは終了状態です。コマンドが Success ステータスを返す条件は次のとおりです。
注記リソースグループをターゲットにする場合も同じ条件が適用されます。エラーをトラブルシューティングする方法、またはコマンド実行に関する詳細情報を取得するには、適切な終了コード (コマンドのエラーの場合はゼロ以外の終了コード) を返すことでエラーまたは例外を処理するコマンドを送信します。 |
DeliveryTimedOut | 合計タイムアウトが期限切れになるまでに、コマンドがマネージドノードに配信されませんでした。合計タイムアウトは、親コマンドの max-errors の制限数には影響しませんが、親コマンドのステータスが Success 、Incomplete 、Delivery Timed Out のいずれになるかに影響します。これは終了状態です。 |
ExecutionTimedOut | コマンドのオートメーションは、マネージドノードで開始されましたが、実行タイムアウトが期限切れになるまでに完了しませんでした。実行タイムアウトは障害としてカウントされます。この場合、ゼロ以外の応答が送信され、Systems Manager はコマンドオートメーションの実行の試行を終了し、障害ステータスを報告します。 |
[失敗] | マネージドノードでコマンドは失敗しました。プラグインの場合、これは結果コードがゼロではないことを示します。コマンドの呼び出しの場合、これは 1 つ以上のプラグインの結果コードがゼロではないことを示します。呼び出しの失敗は、親コマンドの max-errors の制限数にカウントされます。これは終了状態です。 |
キャンセル | コマンドが完了する前にキャンセルされました。これは終了状態です。 |
Undeliverable | コマンドをマネージドノードに配信できません。ノードは存在していないか、応答していない可能性があります。配信不能な呼び出しは親コマンドの max-errors の制限数にはカウントされませんが、親コマンドのステータスが Success または Incomplete のいずれになるかには影響します。例えば、コマンドのすべての呼び出しのステータスが Undeliverable である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Undeliverable で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。 |
Terminated | 親コマンドが max-errors の制限数を超え、後続のコマンド呼び出しはシステムによって取り消されました。これは終了状態です。 |
InvalidPlatform | コマンドは、選択したドキュメントで指定された必須プラットフォームと一致しないマネージノードに送信されました。Invalid
Platform は、親コマンドの max-errors 制限にはカウントされませんが、親コマンドのステータスが [Success] (成功) または [Failed] (失敗) であるかどうかに影響します。例えば、コマンドのすべての呼び出しのステータスが Invalid Platform である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Invalid Platform で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。 |
AccessDenied | コマンドを実行している AWS Identity and Access Management (IAM) ユーザーまたはロールが対象のマネージドノードにアクセスできません。Access Denied は親コマンドの max-errors 制限数にはカウントされませんが、親コマンドのステータスが Success または Failed のいずれになるかには影響します。例えば、コマンドのすべての呼び出しのステータスが Access Denied である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Access Denied で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。 |
ステータス | 詳細 |
---|---|
保留中 | マネージドノードでコマンドはエージェントによってまだ受け取られていません。 |
InProgress | コマンドは、1 つ以上のマネージドノードに送信されましたが、どのノードも終了状態に達していません。 |
Delayed | システムから ノードにコマンドを送信しようとしましたが成功しませんでした。システムは再試行します。 |
成功 | コマンドは、SSM Agent の指定したすべてのインスタンスまたは対象となるマネージドノードで受け取られ、終了コードのゼロが返されました。すべてのコマンドの呼び出しが終了状態に達しましたが、max-errors の値には達しませんでした。このステータスは、指定されたまたは対象となるすべてのマネージドノードで、コマンドが正常に処理されたという意味ではありません。これは終了状態です。注記エラーをトラブルシューティングする方法、またはコマンド実行に関する詳細情報を取得するには、適切な終了コード (コマンドのエラーの場合はゼロ以外の終了コード) を返すことでエラーまたは例外を処理するコマンドを送信します。 |
DeliveryTimedOut | 合計タイムアウトが期限切れになるまでに、コマンドがマネージドノードに配信されませんでした。max-errors の値を超えるコマンドの呼び出しが Delivery Timed
Out のステータスを示しています。これは終了状態です。 |
[失敗] |
マネージドノードでコマンドは失敗しました。 |
Incomplete | コマンドは、すべてのマネージドノードで試行されましたが、1 つ以上の起動が Success の値を持っていません。ただし、スタータスが Failed になるほどの呼び出しの失敗はありません。これは終了状態です。 |
キャンセル | コマンドが完了する前にキャンセルされました。これは終了状態です。 |
RateExceeded | コマンドの対象となるマネージドノードの数が、保留中の呼び出しに対するアカウント クォータを超えています。システムは、どのノードでもコマンドを実行する前にキャンセルしています。これは終了状態です。 |
AccessDenied | コマンドを開始するユーザーまたはロールは、対象のリソースグループにアクセスすることができません。AccessDenied は親コマンドの max-errors 制限にはカウントされませんが、親コマンドのステータスが Success または Failed になるかどうかに影響します。(例えば、コマンドのすべての呼び出しのステータスが AccessDenied の場合、返されるコマンドのステータスは Failed です。 ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つがステータス AccessDenied を返し、そのうち 1 はステータス Success を返す場合、親コマンドのステータスは Success になります。) これは終了状態です。 |
タグにインスタンスがない | コマンドの対象となるタグのキーペア 値またはリソースグループは、どのマネージドノードとも一致しません。これは終了状態です。 |
コマンドタイムアウト値について
Systems Manager は、コマンドの実行時に以下のタイムアウト値を強制します。
合計タイムアウト
Systems Manager コンソールの [Timeout (seconds)] (タイムアウト (秒)) フィールドでタイムアウト値を指定します。コマンドの送信後、Run Command はコマンドの有効期限が切れているかどうかをチェックします。コマンドの有効期限制限 (合計タイムアウト) に達すると、ステータスが InProgress
、Pending
または Delayed
になっているすべての呼び出しのステータスが DeliveryTimedOut
に変わります。
より技術的なレベルで説明すると、合計タイムアウト ([Timeout (seconds)] (タイムアウト (秒))) は、次に示すような 2 つのタイムアウト値の組み合わせです。
Total timeout = "Timeout(seconds)" from the console + "timeoutSeconds": "{{
executionTimeout }}" from your SSM document
例えば、Systems Manager コンソールの Timeout (秒) のデフォルト値は 600 秒です。AWS-RunShellScript
SSM ドキュメントを使用してコマンドを実行する場合、"timeoutSeconds": "{{ executionTimeout }}" のデフォルト値は、次のドキュメントのサンプルに示すように 3600 秒です。
"executionTimeout": { "type": "String", "default": "3600", "runtimeConfig": { "aws:runShellScript": { "properties": [ { "timeoutSeconds": "{{ executionTimeout }}"
これは、システムがコマンドステータスを DeliveryTimedOut
に設定する前に、コマンドが 4,200 秒 (70 分) 実行されることを意味します。
実行タイムアウト
Systems Manager コンソールで、[Execution Timeout (実行タイムアウト)] フィールド (使用可能な場合) に実行タイムアウト値を指定します。すべての SSM ドキュメントで、実行タイムアウトを指定する必要があるわけではありません。[実行タイムアウト] フィールドは、対応する入力パラメータが SSM ドキュメントで定義されている場合にのみ表示されます。指定した場合、コマンドはこの期間内に完了する必要があります。
注記
Run Command は、SSM Agent ドキュメントの終了応答に依存して、コマンドがエージェントに配信されたかどうかを判断します。SSM Agent は、呼び出しまたはコマンドが ExecutionTimedOut
としてマークされるための ExecutionTimedOut
シグナルを送信する必要があります。
デフォルトの実行タイムアウト
SSM ドキュメントで実行タイムアウト値を明示的に指定する必要がない場合、Systems Manager がハードコーディングされたデフォルトの実行タイムアウトを強制します。
Systems Manager がタイムアウトをレポートする方法
Systems Manager がターゲットの SSM Agent から execution timeout
応答を受信すると、Systems Manager はコマンド呼び出しを executionTimeout
としてマークします。
Run Command が SSM Agent からドキュメント終了応答を受信しない場合、コマンド呼び出しは deliveryTimeout
としてマークされます。
ターゲットのタイムアウトステータスを判断するため、SSM Agent は executionTimeout
の計算対象の SSM ドキュメントのすべてのパラメータとコンテンツを結合します。SSM Agent がコマンドがタイムアウトしたと判断すると、サービスに executionTimeout
を送信します。
Timeout (seconds) のデフォルトは 3600 秒です。Execution Timeout のデフォルトも 3600 秒です。したがって、コマンドのデフォルトタイムアウトの合計は 7200 秒です。
注記
SSM Agent による executionTimeout
の処理方法は、 ドキュメントの種類とドキュメントのバージョンによって異なります。