developersIO
Amazon ECSデプロイメントサーキットブレーカーで閾値と失敗カウント方法を指定できるようになりました

Amazon ECSデプロイメントサーキットブレーカーで閾値と失敗カウント方法を指定できるようになりました

Amazon ECSのデプロイメントサーキットブレーカーに、閾値タイプと失敗カウントモデルを指定する新パラメータが追加されました。Fargateサービスでデフォルト値やCOUNT指定時の挙動を確認しました。
Amazon ECSAWS FargateAWS CloudFormationECS on FargateAWS
2026.07.02

はじめに

2026年7月1日、Amazon ECSのデプロイメントサーキットブレーカーに新しいカスタマイズパラメータが追加されました。

https://aws.amazon.com/jp/about-aws/whats-new/2026/07/amazon-ecs-circuit-breaker-settings/

従来のサーキットブレーカーは「有効/無効」と「ロールバックの有効/無効」の二択で、閾値や失敗カウント方法を変更できませんでした。今回のアップデートで、環境や要件に応じた細かい制御が可能になっています。

従来との比較

項目 従来 今回のアップデート
サーキットブレーカー有効/無効 ✅ ✅
ロールバック有効/無効 ✅ ✅
失敗カウントモデル consecutive 固定 consecutive / cumulative 選択可能
閾値タイプ BOUNDED_PERCENT(50) 固定 BOUNDED_PERCENT / UNBOUNDED_PERCENT / COUNT
閾値の値 変更不可 タイプに応じた値を指定可能

新パラメータ

今回追加されたパラメータは以下の2つです。

resetOnHealthyTask（失敗カウントモデル）

  • true（デフォルト）: consecutiveモデル。タスクがhealthyと判定されると失敗カウンタがリセットされます。
  • false: cumulativeモデル。失敗カウンタはリセットされず、デプロイ開始からの累積で閾値を判定します。

thresholdConfiguration（閾値設定）

  • type: 閾値のタイプを指定します。
    • BOUNDED_PERCENT（デフォルト）: desiredCountに対するパーセンテージ。下限3・上限200の範囲に補正されます。
    • UNBOUNDED_PERCENT: 上下限なしのパーセンテージ。
    • COUNT: 固定の失敗回数。
  • value: 閾値の値。デフォルトは50（BOUNDED_PERCENTの場合は50%を意味します）。

https://docs.aws.amazon.com/AmazonECS/latest/developerguide/deployment-circuit-breaker.html

検証環境

以下の環境で検証しました。

  • リージョン： ap-northeast-1
  • ECSクラスター: 新規作成
  • 起動タイプ： FARGATE
  • タスク定義： 即座にexit 1するコンテナ（意図的な失敗用）
  • desiredCount: 2

ダミーの失敗アプリとして、以下のDockerfileを使用しました。

FROM alpine:3.20
CMD ["sh", "-c", "echo 'Intentional failure for circuit breaker test' && exit 1"]

検証結果

3パターンの設定でサーキットブレーカーの発動を確認しました。

デフォルト設定での挙動

新パラメータを指定せず、deploymentCircuitBreaker={enable=true,rollback=true} のみでサービスを作成しました。

aws ecs create-service \
  --cluster cb-test-cluster \
  --service-name cb-test-default \
  --task-definition cb-test-fail:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxxxxxxxxxxxxxxx,subnet-yyyyyyyyyyyyyyyyy],securityGroups=[sg-xxxxxxxxxxxxxxxxx],assignPublicIp=ENABLED}" \
  --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true}"

describe-servicesの出力です。

{
    "deploymentCircuitBreaker": {
        "enable": true,
        "rollback": true,
        "resetOnHealthyTask": true,
        "thresholdConfiguration": {
            "type": "BOUNDED_PERCENT",
            "value": 50
        }
    }
}

約5分後、サーキットブレーカーが発動しました。

{
    "rolloutState": "FAILED",
    "failedTasks": 4,
    "desiredCount": 2,
    "rolloutStateReason": "ECS deployment circuit breaker: tasks failed to start."
}

desiredCount=2の場合、BOUNDED_PERCENT 50の閾値は、desiredCountの50%を基に計算され、ドキュメント上は下限3・上限200の範囲に補正されます。今回の検証では、この条件で下限の3が実効閾値として適用されることを確認しました。内部の失敗カウントが閾値に達した時点でサーキットブレーカーが発動しました。なお、describe-servicesで確認できるfailedTasksの値（ここでは4）は取得タイミングに依存し、閾値と一致しないことがあります。

COUNT + cumulative（素早いロールバック）

閾値を固定回数2、失敗カウントモデルをcumulativeに設定しました。

aws ecs create-service \
  --cluster cb-test-cluster \
  --service-name cb-test-count-cumulative \
  --task-definition cb-test-fail:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxxxxxxxxxxxxxxx,subnet-yyyyyyyyyyyyyyyyy],securityGroups=[sg-xxxxxxxxxxxxxxxxx],assignPublicIp=ENABLED}" \
  --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true,resetOnHealthyTask=false,thresholdConfiguration={type=COUNT,value=2}}"

約4分後、サーキットブレーカーが発動しました。

{
    "rolloutState": "FAILED",
    "failedTasks": 3,
    "desiredCount": 2,
    "rolloutStateReason": "ECS deployment circuit breaker: tasks failed to start."
}

COUNT=2の設定では、指定した値がそのまま閾値として使われます。失敗カウントが閾値に達した時点でサーキットブレーカーが発動しています（failedTasksの表示値は取得タイミングにより閾値と一致しないことがあります）。

COUNT + consecutive（デフォルトとの比較用）

同じ閾値COUNT=2で、失敗カウントモデルをconsecutive（デフォルト）に設定しました。

aws ecs create-service \
  --cluster cb-test-cluster \
  --service-name cb-test-count-consecutive \
  --task-definition cb-test-fail:1 \
  --desired-count 2 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[subnet-xxxxxxxxxxxxxxxxx,subnet-yyyyyyyyyyyyyyyyy],securityGroups=[sg-xxxxxxxxxxxxxxxxx],assignPublicIp=ENABLED}" \
  --deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true,resetOnHealthyTask=true,thresholdConfiguration={type=COUNT,value=2}}"

約3〜4分後、サーキットブレーカーが発動しました。

{
    "rolloutState": "FAILED",
    "failedTasks": 2,
    "desiredCount": 2,
    "rolloutStateReason": "ECS deployment circuit breaker: tasks failed to start."
}

検証結果まとめ

今回は全タスクが即座に失敗するケースのため、healthyと判定されるタスクがなく、カウンタのリセット契機が発生しません。そのためconsecutiveとcumulativeで挙動差が生じず、明確な違いは現れていません。本来の差が顕著になるのは「一部のタスクが成功し、一部が失敗する」混在ケースです。

  • consecutive（resetOnHealthyTask=true）: タスクがhealthyと判定されるとカウンタがリセットされるため、成功と失敗が混在するケースでは閾値に達しにくくなります。
  • cumulative（resetOnHealthyTask=false）: カウンタがリセットされないため、散発的な失敗でも累積で閾値に達すればロールバックが発動します。
設定 実効閾値 FAILED時のfailedTasks 所要時間
デフォルト（BOUNDED_PERCENT 50, consecutive） 3（下限適用） 4 約5分
COUNT=2, cumulative 2 3 約4分
COUNT=2, consecutive 2 2 約3〜4分

failedTasksの値は、サーキットブレーカーの内部評価タイミングとdescribe-servicesの取得タイミングに依存するため、必ずしも実効閾値と一致しません。

CloudFormation での設定

CloudFormationでも新パラメータを指定できます。AWS::ECS::ServiceのDeploymentConfiguration.DeploymentCircuitBreaker配下に追加します。

Resources:
  ECSService:
    Type: AWS::ECS::Service
    Properties:
      ServiceName: my-service
      Cluster: my-cluster
      TaskDefinition: !Ref TaskDefinition
      DesiredCount: 2
      LaunchType: FARGATE
      NetworkConfiguration:
        AwsvpcConfiguration:
          AssignPublicIp: ENABLED
          Subnets:
            - !Ref SubnetA
            - !Ref SubnetB
          SecurityGroups:
            - !Ref SecurityGroup
      DeploymentConfiguration:
        DeploymentCircuitBreaker:
          Enable: true
          Rollback: true
          ResetOnHealthyTask: false
          ThresholdConfiguration:
            Type: COUNT
            Value: 2

実際にこのテンプレートでスタックを作成したところ、ECSサービスの作成処理が開始された後、デプロイメントサーキットブレーカーが発動しました。結果としてCloudFormationスタックはROLLBACKしています（失敗タスク定義を使っているため期待どおりの挙動です）。

{
    "deploymentCircuitBreaker": {
        "enable": true,
        "rollback": true,
        "resetOnHealthyTask": false,
        "thresholdConfiguration": {
            "type": "COUNT",
            "value": 2
        }
    }
}

スタックイベントの抜粋です。サービス作成から約2分でサーキットブレーカーが発動しており、CLI検証時と同様にカスタム設定が反映されていることが確認できました。

Timestamp (UTC) リソース ステータス
01:11:59 ECSService CREATE_IN_PROGRESS (Resource creation Initiated)
01:14:00 ECSService CREATE_FAILED (ECS Deployment Circuit Breaker was triggered)
01:14:56 cb-test-circuit-breaker ROLLBACK_COMPLETE

命名規則の対応は以下のとおりです。

CLI パラメータ CloudFormation プロパティ
resetOnHealthyTask ResetOnHealthyTask
thresholdConfiguration.type ThresholdConfiguration.Type
thresholdConfiguration.value ThresholdConfiguration.Value

まとめ

ECSデプロイメントサーキットブレーカーに、閾値タイプと失敗カウントモデルの選択肢が追加されました。COUNTによる固定回数の閾値指定や、cumulativeモデルによる累積失敗数での判定が可能になり、デプロイメント失敗の検知条件をより細かく調整できます。

今回の検証では、デフォルト設定が従来相当のBOUNDED_PERCENT 50 / consecutiveで動作すること、COUNT=2では固定回数の閾値として扱われることを確認しました。全タスクが即座に失敗するケースではhealthyと判定されるタスクがないため、consecutiveとcumulativeの差は明確には現れていません。

新パラメータを明示的に指定しない場合、既存サービスの判定挙動は従来相当です。一方で、失敗を早期に検知したい場合や、一時的な起動失敗をある程度許容したい場合に、閾値と失敗カウントモデルを用途に応じて調整できるようになりました。

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事

AWS CDKでS3バケットに資材がPUTされたことをトリガーにECSの1つのコンテナを入れ替えるだけのシンプルなCI/CDパイプラインを作ってみた
のんピ
2026.05.15
[レポート] Build safe and resilient deployment pipelines for Amazon ECS #CNS353 #AWSreInvent
miyan
2025.12.04
Amazon ECSでサービスデプロイメントの一時停止と再開の制御機能がサポートされました
のんピ
2026.05.20
ECSサービスのデプロイ戦略をブルー/グリーンに変更する
serina
2026.03.02