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

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

Systems Manager Run Command は、処理中にコマンドで発生するさまざまな状態と、コマンドを処理した各インスタンスに関する詳細なステータス情報を報告します。次の方法を使用して、コマンドのステータスを監視できます。

  • Amazon EC2 コンソールの [Run Command (コマンドの実行)] ページの [Refresh (更新)] アイコンをクリックします。

  • AWS CLI を使用して list-commands または list-command-invocations を呼び出します。あるいは、AWS Tools for Windows PowerShell を使用して Get-SSMCommand または Get-SSMCommandInvocation を呼び出します。

  • 状態またはステータスの変更に応答するように EventBridge を設定します。

  • すべての状況の変化または Failed や TimedOut など、特定のステータスの通知を送信するよう Amazon SNS を設定します。

Run Command ステータス

Run Command は、プラグイン、呼び出し、コマンドのステータス全体という 3 つのエリアでステータスの詳細をレポートします。プラグインは、コマンドの Systems Manager (SSM) ドキュメントに定義されているコード実行ブロックです。プラグインの詳細については、「Systems Manager コマンドドキュメントプラグインリファレンス」を参照してください。

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

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

注記

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

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

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

Delivery Timed Out コマンドは、配信タイムアウトが期限切れになるまでにインスタンスに配信されませんでした。配信タイムアウトは、親コマンドの max-errors の制限数にはカウントされませんが、親コマンドのステータスが Success または Incomplete のいずれになるかに影響します。これは終了状態です。
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 になります。これは終了状態です。
アクセスが拒否されました コマンドを実行している IAM ユーザーまたは IAM ロールが対象のマネージドインスタンスにアクセスできません。Access Denied は親コマンドの max-errors の制限数にはカウントされませんが、親コマンドのステータスが Success または Failed のいずれになるかには影響します。たとえば、コマンドのすべての呼び出しのステータスが Access Denied である場合、返されるコマンドのステータスは Failed です。ただし、コマンドに 5 つの呼び出しがあり、そのうちの 4 つが返したステータスが Access Denied で 1 つが返したステータスが Success の場合、親コマンドのステータスは Success になります。これは終了状態です。
コマンドの詳細なステータス
ステータス 詳細
Pending インスタンスでコマンドはエージェントによってまだ受け取られていません。
進行中 コマンドは、1 つ以上のインスタンスに送信されましたが、どのインスタンスも終了状態に達していません。
Delayed システムからインスタンスにコマンドを送信しようとしましたが成功しませんでした。システムは再試行します。
成功 コマンドは、SSM エージェント の指定したすべてのインスタンスまたは対象となるインスタンスで受け取られ、終了コードのゼロが返されました。すべてのコマンドの呼び出しが終了状態に達しましたが、max-errors の値には達しませんでした。このステータスは、指定されたすべてのインスタンスまたは対象となるインスタンスで、コマンドが正常に処理されたという意味ではありません。これは終了状態です。
注記

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

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

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

Incomplete コマンドは、すべてのインスタンスで試行されましたが、Success の値になっていない呼び出しが 1 つ以上あります。ただし、スタータスが 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 エージェント ドキュメントの終了応答に依存して、コマンドがエージェントに配信されたかどうかを判断します。SSM エージェント は、呼び出しまたはコマンドが ExecutionTimedOut としてマークされるための ExecutionTimedOut シグナルを送信する必要があります。


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

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

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

合計タイムアウト

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

Systems Manager レポートのタイムアウトの仕組み

Systems Manager がターゲットのSSM エージェント から execution timeout 応答を受信した場合、Systems Manager はコマンド呼び出しを executionTimeout としてマークします。

Run Command が SSM エージェント からドキュメント終了応答を受信しない場合、コマンド呼び出しは deliveryTimeout としてマークされます。

ターゲットのタイムアウトステータスを判断するため、SSM エージェント は executionTimeout の計算対象の SSM ドキュメントのすべてのパラメータとコンテンツを結合します。SSM エージェント がコマンドがタイムアウトしたと判断すると、サービスに executionTimeout を送信します。

Timeout (seconds) のデフォルトは 3600 秒です。Execution Timeout のデフォルトも 3600 秒です。したがって、コマンドのデフォルトタイムアウトの合計は 7200 秒です。

注記

SSM エージェント による executionTimeout の処理方法は、SSM ドキュメントの種類とドキュメントのバージョンによって異なります。