Topic lessonTopic: Containers, ECS and Fargate
ECS rolling deployments: task-count limits and rollback conditions
Convert deployment percentages into task counts. A numerical slot does not guarantee that a new task can start and become healthy. Use fixed examples with desired counts of three and four to understand rounding, health checks and the limits of rollback.
Calculate minimum healthy and maximum task counts, investigate stalled updates, and distinguish version rollback from business recovery.
Read ECS task/service fundamentals and container/ALB health checks first. The examples use a REPLICA service with ROLLING, earlySuccessCriteria disabled, all old tasks initially healthy, and no initially pending or stopping tasks. This is neither a live-AWS procedure nor a complete placement simulator.
Think in task counts during an update
MinimumHealthyPercent sets a lower healthy-task bound; maximumPercent sets an upper deployment-task bound. Multiply by desiredCount, round the minimum up and the maximum down. Different percentages can therefore produce the same whole-task count.
| Bound | Calculation | Meaning |
|---|---|---|
| Minimum healthy | ceil(desiredCount × minimumHealthyPercent / 100) | Round up; helps assess room to stop healthy old tasks. |
| Maximum tasks | floor(desiredCount × maximumPercent / 100) | Round down; helps assess room to add tasks. |
Desired count three: percentages without a whole-task slot
Desired count 3, minimumHealthyPercent 75 and maximumPercent 125. The minimum is ceil(2.25)=3; the maximum is floor(3.75)=3. Starting with three healthy old tasks leaves no room either to stop one healthy task while preserving the minimum or to add one while preserving the maximum.
- Minimum healthy 3 → Three old tasks, all healthyNo healthy stop slot
- Three old tasks, all healthy → Maximum tasks 3No add slot
- Minimum healthy 3
- ceil(3 × 75 / 100)
- Three old tasks, all healthy
- Fixed initial condition
- Maximum tasks 3
- floor(3 × 125 / 100)
Desired count four: a slot is not readiness
| Item | Value | What this does not establish |
|---|---|---|
| Minimum healthy | ceil(4 × 50 / 100)=2 | Two tasks need not meet workload or latency requirements. |
| Maximum tasks | floor(4 × 200 / 100)=8 | Eight tasks need not actually be placeable or startable. |
| Initial add room | 8 − 4 = 4 | Resources, IPs, quotas, startup and checks remain unverified. |
| Numerical room to stop healthy old tasks | 4 − 2 = 2 | This does not predict that two will stop simultaneously. |
Check when newly started tasks count toward the healthy bound. Essential-container checks and load-balancer checks, when configured, affect that decision. A RUNNING count alone does not establish that reducing old tasks is safe.
EarlySuccessCriteria is disabled in these examples. When configured, read its completion criterion separately from subsequent source-task cleanup. Do not generalize a COMPLETED label into proof that every task already runs the new revision.
Separate failure detection from rollback eligibility
| Aspect | Check | Avoid assuming |
|---|---|---|
| Deployment scope | ROLLING and enable configuration. | This is not the same mechanism for every strategy. |
| Failure counting | thresholdConfiguration, resetOnHealthyTask and related settings. | One failure count does not apply to every configuration. |
| Automatic rollback | Whether rollback is enabled. | Enabled detection is not evidence of completed recovery. |
| Rollback target | The most recent eligible COMPLETED deployment. | A newly created service need not have a completed target. |
| Recovery evidence | Revision, tasks, checks, user operations and side effects. | Reverting application code does not revert all data. |
Without an eligible COMPLETED target, do not expect automatic circuit-breaker rollback. The guide describes new task launching stopping and the deployment stalling in this case. An initial release therefore also needs a recovery plan.
Investigate a stalled update with matching revisions and times
- Identify service, strategy, desired count, source/target revisions and observation time.
- Convert percentages to whole-task bounds; compare actual RUNNING/PENDING/STOPPING and healthy counts.
- Use service events to distinguish add/stop constraints, placement, IP, quotas and startup failures.
- Compare new-task container and ALB checks; do not infer health from RUNNING alone.
- Check failure detection, rollback settings and an eligible COMPLETED target.
- After rollback or retry, verify actual revision, user operations, data and external effects.
Separate unhealthy-task replacement from an update to the target revision. Current guidance describes replacement using the service revision to which the unhealthy task belongs. Replacing an unhealthy source-revision task does not by itself establish completion of the target deployment.
Check the arithmetic and the evidence
Choose an option to see the result and explanation.
Check, then explain in your own words
- Explain why the three-task example has no whole-task room after rounding.
- Separate computable bounds from conditions needing real evidence in the four-task example.
- Explain rollback eligibility and limits including data and external effects.
Check your understanding: Do valid deployment bounds and enabled rollback guarantee uninterrupted recovery?
No. Bounds, placement/health, rollback target and business outcomes need separate evidence.
Whole-task room is only part of the conditions. Verify target eligibility, real capacity and checks, plus data compatibility and reversible effects.
Sources and conditions checked
The official references used in this lesson are collected here with their scope, conditions and corresponding sections. Independent expert review and live AWS comparison have not been performed.
Scope and conditionsMinimum ceiling, maximum floor, whole-task room and same-service-revision unhealthy replacements. Bounds are not proof of real placement. Documentation review, not live AWS verification.
Used in this lessonThink in task counts during an update Desired count three: percentages without a whole-task slot Investigate a stalled update with matching revisions and times Check the arithmetic and the evidence
Scope and conditionsDistinguish grace, ceil/floor bounds and early-success configuration. Guide maximumPercent includes STOPPING; API state wording differs. Documentation review, not live AWS verification.
Used in this lessonThink in task counts during an update Desired count four: a slot is not readiness Investigate a stalled update with matching revisions and times Check the arithmetic and the evidence
- ECS DeploymentConfiguration APIChecked:
Scope and conditionsBounds agree with the guide; retain the API RUNNING/PENDING wording difference. Do not infer that a stopping task always frees a slot immediately. Documentation review, not live AWS verification.
Used in this lessonThink in task counts during an update Check the arithmetic and the evidence
Scope and conditionsTask-definition health checks versus lifecycle, LB and application observations. Documentation review, not live AWS verification.
Used in this lessonDesired count four: a slot is not readiness
- ECS deployment circuit breakerChecked:
Scope and conditionsRolling failure detection and prior COMPLETED target conditions; configurable failure modes mean the bounded default is not universal. Documentation review, not live AWS verification.
Used in this lessonSeparate failure detection from rollback eligibility Investigate a stalled update with matching revisions and times Check the arithmetic and the evidence
- ECS DeploymentCircuitBreaker APIChecked:
Scope and conditionsReview enable, rollback, resetOnHealthyTask and thresholdConfiguration; configuration differs from observed recovery. Documentation review, not live AWS verification.
Used in this lessonSeparate failure detection from rollback eligibility Check the arithmetic and the evidence
Scope and conditionsService events as a diagnostic starting point; bounded history and API/console differences. Documentation review, not live AWS verification.
Used in this lessonInvestigate a stalled update with matching revisions and times