コマンドのステータスについて - AWS Systems Manager

コマンドのステータスについて

Run Command の一機能である AWS Systems Manager は、コマンドの各処理状態とコマンドを処理した各マネージノードの詳細なステータス情報をレポートします。次の方法を使用して、コマンドのステータスをモニタリングできます。

  • Amazon Elastic Compute Cloud (Amazon EC2) コンソールの [Run Command] ページで、[更新] アイコンを選択します。

  • 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) ドキュメントに定義されているコード実行ブロックです。プラグインの詳細については、「Systems Manager コマンドドキュメントプラグインリファレンス」を参照してください。

複数のマネージノードに、コマンドを同時に送信するとき、各ノードを対象とするコマンドの各コピーは、コマンド呼び出しです。例えば、AWS-RunShellScript ドキュメントを使用して 20 個の Linux インスタンスに ifconfig コマンドを送信すると、そのコマンドには 20 個の呼び出しがあります。各コマンド呼び出しで、個別にステータスが報告されます。コマンド呼び出しに含まれているプラグインも、個々にステータスを報告します。

最後に、Run Command コマンドには、すべてのプラグインと呼び出しの集約されたコマンドステータスがあります。集約されたコマンドステータスは、以下の表に示すように、プラグインまたは呼び出しによってレポートされるステータスとは異なる場合があります。

注記

max-concurrency パラメータまたは max-errors パラメータを使用して多数のマネージノードに対してコマンドを実行する場合は、以下の表に示すように、これらのパラメータによって強制される制限がコマンドのステータスに反映されます。これらのパラメータの詳細については、ターゲットとレート制御を使用してフリートにコマンドを送信するを参照してください。

コマンドのプラグインと呼び出しの詳細なステータス
ステータス 詳細
保留中 コマンドがまだマネージドノードに送信されていないか、SSM Agent によって受信されていません。Timeout (seconds) パラメータと Execution timeout パラメータの合計に等しい時間が経過する前にエージェントがコマンドを受信しなかった場合、ステータスは Delivery Timed Out に変わります。
進行中 Systems Manager がマネージドノードにコマンドを送信しようとしている、またはコマンドが SSM Agent によって受信され、インスタンスでその実行が開始されました。すべてのコマンドプラグインの結果に応じて、ステータスは SuccessFailedDelivery Timed OutExecution Timed Out のいずれかに変わります。例外: エージェントが実行中でないか、ノードで使用できない場合、コマンドステータスはエージェントが再び使用可能になるまで、または実行タイムアウト制限に達するまで In Progress のままになります。その後、ステータスは終了状態に変わります。
Delayed システムからマネージドノードにコマンドを送信しようとしましたが成功しませんでした。システムは再試行します。
成功 コマンドは、マネージドノードの SSM Agent で受け取られ、終了コードのゼロが返されました。このステータスは、コマンドがノード上で処理されたという意味ではありません。これは終了状態です。
注記

エラーをトラブルシューティングする方法、またはコマンド実行に関する詳細情報を取得するには、適切な終了コード (コマンドのエラーの場合はゼロ以外の終了コード) を返すことでエラーまたは例外を処理するコマンドを送信します。

Delivery Timed Out コマンドは、配信タイムアウトが期限切れになるまでにマネージドノードに配信されませんでした。配信タイムアウトは、親コマンドの max-errors の制限数にはカウントされませんが、親コマンドのステータスが SuccessIncomplete、またはDelivery Timed Out のいずれになるかに影響します。これは終了状態です。
Execution Timed Out コマンドの実行は、マネージドノードで開始されましたが、実行タイムアウトが期限切れになるまでに完了しませんでした。実行タイムアウトは、親コマンドの max-errors の制限数にカウントされます。これは終了状態です。タイムアウトに達すると、Systems Manager はコマンドの実行を停止します。
[Failed] (失敗)

マネージドノードでコマンドは失敗しました。プラグインの場合、これは結果コードがゼロではないことを示します。コマンドの呼び出しの場合、これは 1 つ以上のプラグインの結果コードがゼロではないことを示します。呼び出しの失敗は、親コマンドの max-errors の制限数にカウントされます。これは終了状態です。

Canceled コマンドが完了する前にキャンセルされました。これは終了状態です。
Undeliverable コマンドをマネージドノードに配信できません。ノードは存在していないか、応答していない可能性があります。配信不能な呼び出しは親コマンドの max-errors の制限数にはカウントされませんが、親コマンドのステータスが Success または Incomplete のいずれになるかには影響します。例えば、コマンドのすべての呼び出しのステータスが Undeliverable である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Undeliverable で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。
Terminated 親コマンドが max-errors の制限数を超え、後続のコマンド呼び出しはシステムによって取り消されました。これは終了状態です。
無効なプラットフォーム コマンドは、選択したドキュメントで指定された必須プラットフォームと一致しないマネージノードに送信されました。Invalid Platform は、親コマンドの max-errors 制限にはカウントされませんが、親コマンドのステータスが [Success] (成功) または [Failed] (失敗) であるかどうかに影響します。例えば、コマンドのすべての呼び出しのステータスが Invalid Platform である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Invalid Platform で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。
アクセスが拒否されました コマンドを実行している AWS Identity and Access Management (IAM) ユーザーまたはロールが対象のマネージドノードにアクセスできません。Access Denied は親コマンドの max-errors 制限数にはカウントされませんが、親コマンドのステータスが Success または Failed のいずれになるかには影響します。例えば、コマンドのすべての呼び出しのステータスが Access Denied である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Access Denied で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。
コマンドの詳細なステータス
ステータス 詳細
保留中 マネージドノードでコマンドはエージェントによってまだ受け取られていません。
進行中 コマンドは、1 つ以上のマネージドノードに送信されましたが、どのノードも終了状態に達していません。
Delayed システムから ノードにコマンドを送信しようとしましたが成功しませんでした。システムは再試行します。
成功 コマンドは、SSM Agent の指定したすべてのインスタンスまたは対象となるマネージドノードで受け取られ、終了コードのゼロが返されました。すべてのコマンドの呼び出しが終了状態に達しましたが、max-errors の値には達しませんでした。このステータスは、指定されたまたは対象となるすべてのマネージドノードで、コマンドが正常に処理されたという意味ではありません。これは終了状態です。
注記

エラーをトラブルシューティングする方法、またはコマンド実行に関する詳細情報を取得するには、適切な終了コード (コマンドのエラーの場合はゼロ以外の終了コード) を返すことでエラーまたは例外を処理するコマンドを送信します。

Delivery Timed Out コマンドは、配信タイムアウトが期限切れになるまでにマネージドノードに配信されませんでした。max-errors の値を超えるコマンドの呼び出しが Delivery Timed Out のステータスを示しています。これは終了状態です。
Execution Timed Out コマンドの実行は、マネージドノードで開始されましたが、実行タイムアウトが期限切れになるまでに完了しませんでした。max-errors の値を超えるコマンドの呼び出しが Execution Timed Out のステータスを示しています。これは終了状態です。
[Failed] (失敗)

マネージドノードでコマンドは失敗しました。max-errors の値を超えるコマンドの呼び出しが Failed のステータスを示しています。これは終了状態です。

Incomplete コマンドは、すべてのマネージドノードで試行されましたが、1 つ以上の起動が Success の値を持っていません。ただし、スタータスが Failed になるほどの呼び出しの失敗はありません。これは終了状態です。
Canceled コマンドが完了する前にキャンセルされました。これは終了状態です。
Rate Exceeded コマンドの対象となるマネージドノードの数が、保留中の呼び出しに対するアカウント クォータを超えています。システムは、どのノードでもコマンドを実行する前にキャンセルしています。これは終了状態です。
アクセスが拒否されました コマンドを開始する IAM ユーザーまたはロールは、対象のリソースグループにアクセスできません。AccessDenied は親コマンドの max-errors 制限にはカウントされませんが、親コマンドのステータスが Success または Failed であるかどうかに影響します。(例えば、コマンドのすべての呼び出しのステータスが AccessDenied の場合、返されるコマンドのステータスは Failed です。 ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つがステータス AccessDenied を返し、そのうち 1 はステータス Success を返す場合、親コマンドのステータスは Success になります。) これは終了状態です。
タグにインスタンスがない コマンドの対象となるタグのキーペア 値またはリソースグループは、どのマネージドノードとも一致しません。これは終了状態です。

コマンドタイムアウト値について

Systems Manager は、コマンドの実行時に以下のタイムアウト値を強制します。

配信タイムアウト

Systems Manager コンソールで、[タイムアウト (秒)] フィールドに配信タイムアウト値を指定します。コマンドの送信後、Run Command はコマンドの有効期限が切れているかどうかをチェックします。コマンドの有効期限制限 (合計タイムアウト) に達すると、ステータスが InProgressPending または Delayed になっているすべての呼び出しのステータスが DeliveryTimedOut に変わります。


                    Systems Manager コンソールの [タイムアウト (秒)] フィールド

技術的なレベルでは、配信タイムアウト (タイムアウト (秒)) は、次に示すように 2 つのタイムアウト値の組み合わせです。

Delivery 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 }}"

これは、システムが配信タイムアウトを返す前に、コマンドが 4,200 秒 (70 分) 実行されることを意味します。

実行タイムアウト

Systems Manager コンソールで、[Execution Timeout (実行タイムアウト)] フィールド (使用可能な場合) に実行タイムアウト値を指定します。すべての SSM ドキュメントで、実行タイムアウトを指定する必要があるわけではありません。指定した場合、コマンドはこの期間内に完了する必要があります。

注記

Run Command は、SSM Agent ドキュメントの終了応答に依存して、コマンドがエージェントに配信されたかどうかを判断します。SSM Agent は、呼び出しまたはコマンドが ExecutionTimedOut としてマークされるための ExecutionTimedOut シグナルを送信する必要があります。


                    Systems Manager コンソールの [実行タイムアウト] フィールド

デフォルトの実行タイムアウト

SSM ドキュメントで実行タイムアウト値を明示的に指定する必要がない場合、Systems Manager がハードコーディングされたデフォルトの実行タイムアウトを強制します。

合計タイムアウト

合計タイムアウトは、delivery timeout + execution timeout の値と等しくなります。execution timeout が SSM ドキュメントで必要でない場合、total timeoutdelivery timeout + default execution timeout の値と等しくなります。

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 の処理方法は、 ドキュメントの種類とドキュメントのバージョンによって異なります。