[EC2 Systems Manager] Maintenance Windowsの「Stop after(Max Errors)」とは何か？

こんにちわ。大阪のガノタです。
EC2 Systems ManagerのMaintenance Windowsについて、今回は 「Stop after(Max Errors)」 という設定について検証してみたのでご紹介します。

「Stop after」(Max Errors)の意味

一言で言うと「Stop after」は「許容されるエラー数の指定」です。新しいターゲットにタスクを送信する前に許容できるエラー数(最大数) のことです。

ちなみに「Stop after」の項目は、以前はマネジメントコンソール上では 「Max Errors」 という表示でした。AWS CLIでは「MaxErrors」として指定します。
「Max Errors」の方が直感的に分かりやすいので、以後「Stop after」は「Max Errors」として表記します。

「Max Errors(Stop after)」の意味

改めて「Max Errors」の意味についてです。ウォークスルーのページには下記の通り「Stop after」の説明文が記載されていました。

メンテナンスウィンドウコンソールのチュートリアル - Amazon EC2 Systems Manager _

さらに詳しい説明は、CLIのウォークスルーのページに記載されています。

この 「追加のターゲットへのコマンド送信を止める」 という点がポイントです。コマンドの送信(実行)単位は、ターゲット内のインスタンス数に関係なく、ターゲット単位 ということです。

尚、各設定項目の説明は下記のドキュメントが参考になるかと思います。

メンテナンスウィンドウ CLI のチュートリアル - Amazon EC2 Systems Manager

「Max Errors」の検証

具体的な動作を確認する為に検証してみました。検証した概要は次の通りです。

• タスクを2つ登録 (MyErrDocument, MyTestDocument)
  • 「MyErrDocument」
  • 実行しても必ず失敗するタスク
  • Priorityは「1」
  • 「MyTestDocument」
  • 実行したら成功するタスク
  • Priorityは「2」
• ターゲットを各タスクにそれぞれ2つ設定
  • 特定のタグで指定(対象は2台)
  • インスタンスを個別に2台指定

まず、下記のように2つのタスクを登録します。このうちPriorityが「1」のタスク(MyErrDocument)が最初に実行されます。それぞれのタスクの内容は「View」で確認できます。

この「MyErrDocument」は、わざとエラーになる内容にしています。

「MyErrDocument」と「MyTestDocument」のタスクは、同じターゲットを設定しました。
「ami-backup」というタグが「true」になっているインスタンスを対象としたターゲットと、インスタンスを個別に2つ指定したターゲットです。「Max Errors」は両方とも「1」にしています。

次の画像は、「MyErrDocument」のタスク内容です。

「MyTestDocument」のタスク内容は以下のようになります。(Priorityを2にしています)

尚、「Target」は事前に登録しておきます。

動作確認

メンテナンスウィンドウのcron時刻を修正して、すぐに実行して確認します。
実行結果をメンテナンスウィンドウの「History」タブで確認すると想定通り「Failed」になっています。詳細は「View datails」で確認できます。

詳細を確認すると、最初に実行された「MyErrDocument」のタスクが「Failed」になっています。下側の欄は各ターゲットのステータスです。

最初に実行したターゲットで失敗していて、次のターゲットでの実行が 「Pending」 で実行されていません。(尚、「View datails」からどのターゲットでコマンドが実行されたかを確認できます。)

次の「MyTestDocument」タスクはどちらのターゲットに対しても「Success」で成功しています。

「Max Errors」の動作イメージ

この検証結果を元にした動作イメージは、下記のような形になります。

この図について説明します。

• 最初の「Task-1」は上記の「MyErrDocument」を想定。
  • つまり、どちらのインスタンスでも失敗するものとする。
  • 「Target-1」の2つのインスタンスで失敗してエラーカウントは「2」になる。
  • エラーカウントが「2」になったので、次の「Target-2」には「Task-1」は実行されない(Pending)。
    • 「Max Errors」の設定値が「1」の為。
• 「Task-2」は上記の「MyTestDocument」を想定。
  • 失敗しないのでエラーはカウントされず両方のターゲットで実行される。

エラーカウントの対象

上記よりエラーカウントの対象はインスタンスであることも分かります。

エラーカウントの対象が「失敗したターゲット数」であれば、上記の場合だとエラーカウントは「1」になります。エラーカウントが「2」ではないので、次のターゲットにはコマンドが送られるはずです。

その他のパターン

理解を深める為に、同様の設定を元にいくつかのパターンで動作検証をしてみました。実行するコマンドは上記と同様に「MyErrDocument」と「MyTestDocument」とします。

「Target-1」のインスタンスが1台の場合

この場合は、タスクの実行対象が1台なので「Task-1」のエラーカウントは「1」になります。「Max Errors」の値が「1」なので、次のターゲットにもタスクが実行されます。(Target-2でもコマンドは失敗します)
「Task-2」はエラーにならないので、どちらのターゲットにも実行されます。

「Target-1」のインスタンスが3台の場合

この場合は、タスクの実行対象が3台なので、エラーカウントは「3」になります。「Max Errors」の値が「1」なので、次のターゲットへは実行されません。(Pending)
「Task-2」はエラーにならないので、どちらのターゲットにも実行されます。

ターゲットが3つで「Max Errors」が「2」の場合

最後に、図のようなターゲット構成の場合で「Max Errors」が「2」 の場合についてです。

最初の「Target-1」はインスタンスが1台なので、2つ目のターゲット「Target-2」まで「Task-1」が実行されて、3つ目のターゲット「Target-3」にはタスクは実行されません。(Pending)

Historyを見ると、最初のタスクが2つ目のターゲットまで実行されて、3つ目のターゲットには実行されていないことが分かります。

次のタスク(Task-2)は全てのターゲットで実行されています。

割合での指定

先程の公式ドキュメントでは、「Execute on」と「Max Errors」に割合を指定できるという記載がありました。しかしマネジメントコンソールでは下記のようになっており、「Stop after」の項目にプルダウンがありません。これだけ見ると割合での指定ができそうに見えません。

しかし、プルダウンが無くても「％」を含めて記載すれば登録することが可能です。例えば「20%」の場合はそのまま「20%」と入力します。
また「Execute on」ではプルダウンから「数値」か「割合」を選択できますが、そのまま％表記で入力すると「割合」として設定することが可能 です。

設定後の表示は下記の様になります。

AWS CLIで確認すると以下の様になります。「MaxErrors」と「MaxConcurrency」の値が「％」表示になっていることが確認出来ます。

$ aws ssm describe-maintenance-window-tasks --window-id "mw-xxxxxxxxxxxxxxxx"

{
    "Tasks": [
        {
            "ServiceRoleArn": "arn:aws:iam::xxxxxxxxxxxx:role/MySsmMainteWindow",
            "MaxErrors": "20%",
            "TaskArn": "MyTestDocument",
            "MaxConcurrency": "10%",
            "WindowTaskId": "6cfxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "TaskParameters": {},
            "Priority": 1,
            "WindowId": "mw-xxxxxxxxxxxxxxxx",
            "Type": "RUN_COMMAND",
            "Targets": [
                {
                    "Values": [
                        "4f8xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "c6bxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                    ],
                    "Key": "WindowTargetIds"
                }
            ]
        }
    ]
}

設定項目の端に、インフォメーションボタンで項目の説明が記載されるようになると良いなと思いました。

最後に

このエントリを書いている時は、まだ英語のドキュメントしか無かったのですが、途中で日本語のドキュメントも公開されました。
昨年のre:Inventで発表された新しいサービスなので、これからドキュメントなども充実されてくるのかもしれませんね。

様々なサーバ運用がクラウドベースで管理できるようになり非常に便利なので、積極的に使っていきたいと思います。

以上です。