Overview

AWS Fargate periodically retires platform version revisions to apply security patches and infrastructure updates. When multiple retirements occur in close succession, teams sometimes find themselves manually restarting tasks — only to land on a revision that is itself about to be retired.

This article walks through how ECS handles task retirements automatically, and provides options for controlling the timing and behavior of these retirements based on your workload requirements.

What Is a Fargate Task Retirement?

AWS retires older Fargate platform version revisions (not the platform version itself — for example, version 1.4.0 remains, but the underlying revision changes). Once a newer revision is available, the older revision is retired so all workloads benefit from the latest updates. For more details, see Task retirement and maintenance for AWS Fargate.

How Task Placement Works During Retirement

• New tasks are always placed on the latest available revision
• Existing running tasks remain on their original revision until the revision is retired
• Replacement tasks launched during retirement are placed on the latest revision

How to Confirm a Task Was Retired

You can run describe-tasks and check the stoppedReason field. If it shows ECS is performing maintenance on the underlying infrastructure hosting the task, the task was stopped as part of a revision retirement.

Automatic Replacement for Service Tasks

If your tasks are running as part of an ECS service, no action is required on your part. The ECS scheduler automatically replaces retired tasks while maintaining your desired task count.

The replacement behavior is determined by your deployment configuration:

Parameter	Default	What happens during retirement
minimumHealthyPercent	100%	A new task is launched and confirmed running before the old task is stopped
maximumPercent	200%	ECS is allowed to temporarily exceed the desired count during replacement

With the default values (100%/200%), ECS launches a replacement task first, waits for it to reach a running state, and then stops the retiring task. This results in a seamless replacement with no reduction in capacity.

If maximumPercent is set to 100% and minimumHealthyPercent is set to 50%, ECS cannot launch a new task before stopping the old one (since it cannot exceed the desired count). It will stop half of your tasks before launching replacements — which means a brief period of reduced capacity.

Recommended configuration:

{
  "deploymentConfiguration": {
    "minimumHealthyPercent": 100,
    "maximumPercent": 200,
    "deploymentCircuitBreaker": {
      "enable": true,
      "rollback": true
    }
  }
}

Note: Automatic replacement may not succeed if there are issues with IAM roles, subnet capacity, security groups, or the task definition. In these cases, retired tasks are stopped without replacement. Additionally, standalone tasks (started via RunTask, EventBridge Scheduler, AWS Batch, or Step Functions) are not automatically replaced — only service-managed tasks are.

Scheduling Retirements During Off-Peak Hours (Event Windows)

When to use this: Your services are handling retirements correctly, but you want to avoid replacements happening during peak business hours — for example, restricting them to weekends or overnight windows.

Since December 2025, you can use Amazon EC2 event windows to define exactly when Fargate is allowed to retire your tasks. This is helpful for workloads where even a brief connection reset or cache cold-start during business hours is undesirable.

Key behavior:

• Fargate ensures that tasks run for at least 3 days before they are retired, unless stopped by user-initiated actions or critical health events
• Event windows take precedence over the fargateTaskRetirementWaitPeriod setting
• Each window must be open for at least 4 hours per week, with each time range at least 2 hours long
• This configuration applies to future retirements only — currently scheduled retirements are not affected
• Retirement within event windows is best effort. If you observe tasks being retired outside your window, consider expanding the duration (8 hours or more) or increasing frequency (at least once every 3 days)
• Critical infrastructure health events may bypass event windows

Scoping options:

Level	Tag	When to use
All Fargate tasks	aws:ecs:fargateTask=true	Apply an account-wide default window
Specific cluster	aws:ecs:clusterArn=<ARN>	Different windows per environment
Specific service	aws:ecs:serviceArn=<ARN>	Protect individual critical services

Precedence order: Service-level → Cluster-level → Account-level → fargateTaskRetirementWaitPeriod fallback

How to Set Up Scheduled Retirements

Note: The fargateEventWindows account setting is configured using the put-account-setting-default API, and target association uses the associate-instance-event-window API. The EC2 event window itself can also be created through the EC2 Console under Events → Manage event windows.

The ECS Console displays the current state under Account settings → Fargate task retirement:

Step 1: Enable Fargate event windows (one-time, per account per region)

Run this as root or an administrative user:

aws ecs put-account-setting-default \
  --name fargateEventWindows \
  --value enabled

You can verify with:

aws ecs list-account-settings --effective-settings --name fargateEventWindows

Step 2: Create an EC2 event window

Using a time range (for example, Saturdays 2–8 AM UTC):

aws ec2 create-instance-event-window \
  --time-range StartWeekDay=saturday,StartHour=2,EndWeekDay=saturday,EndHour=8 \
  --tag-specifications 'ResourceType=instance-event-window,Tags=[{Key=Purpose,Value=fargate-maintenance}]' \
  --name fargate-weekend-maintenance

Using a cron expression (for example, nightly 12–4 AM UTC):

aws ec2 create-instance-event-window \
  --cron-expression "* 0-4 * * *" \
  --tag-specifications 'ResourceType=instance-event-window,Tags=[{Key=Purpose,Value=fargate-maintenance}]' \
  --name fargate-nightly-maintenance

Using the console: Navigate to EC2 Console → Events → Actions → Manage event windows → Create instance event window.

Note the InstanceEventWindowId from the response (for example, iew-0abcdef1234500000).

Step 3: Associate the window with your ECS targets

For all Fargate tasks in the account:

aws ec2 associate-instance-event-window \
  --instance-event-window-id iew-0abcdef1234567890 \
  --association-target "InstanceTags=[{Key=aws:ecs:fargateTask,Value=true}]"

For a specific cluster:

aws ec2 associate-instance-event-window \
  --instance-event-window-id iew-0abcdef1234567890 \
  --association-target "InstanceTags=[{Key=aws:ecs:clusterArn,Value=arn:aws:ecs:us-east-1:123456789012:cluster/production}]"

For a specific service:

aws ec2 associate-instance-event-window \
  --instance-event-window-id iew-0abcdef1234567890 \
  --association-target "InstanceTags=[{Key=aws:ecs:serviceArn,Value=arn:aws:ecs:us-east-1:123456789012:service/production/payment-api}]"

Confirming the Result

After enabling via CLI, the ECS Console will reflect the updated state:

Considerations:

Consideration	Detail
Minimum total window duration	4 hours per week
Minimum per time range	2 hours
Retirement timing	Best effort
Minimum task runtime before retirement	At least 3 days (unless user-initiated stop or critical health event)
Recommendation for large clusters	8+ hour windows or at least once every 3 days
Maximum event windows per region	200
Maximum targets per window	100 instance IDs, 50 host IDs, or 50 instance tags

Extending the Retirement Wait Period

When to use this: You want more lead time between receiving the retirement notification and actual retirement, but you do not need precise scheduling.

The fargateTaskRetirementWaitPeriod setting controls how many days AWS waits after notifying you before starting to retire tasks:

Value	Behavior
0	Tasks are retired immediately after notification
7	7 calendar day wait (default)
14	14 calendar day wait

This is an account-level setting and does not provide per-service granularity. When event windows are configured, they take precedence over this setting.

aws ecs put-account-setting-default --name fargateTaskRetirementWaitPeriod --value 14

Replacing Tasks Proactively on Your Own Schedule

When to use this: You prefer to control exactly when your tasks move to the latest revision, rather than waiting for AWS to initiate the retirement.

For services using the rolling update deployment type:

aws ecs update-service \
  --service my-service \
  --cluster my-cluster \
  --force-new-deployment

For services using blue/green deployment with AWS CodeDeploy, create a new deployment using the same task definition revision.

Running this command launches new tasks on the latest platform version revision, effectively refreshing your service before AWS needs to retire the tasks. You can automate this on a recurring schedule using EventBridge Scheduler with a Lambda function.

Receiving Retirement Notifications

You can set up Amazon EventBridge to receive notifications when retirements are scheduled, allowing your team to stay informed or trigger automated responses:

{
  "source": ["aws.health"],
  "detail-type": ["AWS Health Event"],
  "detail": {
    "eventTypeCode": ["AWS_ECS_TASK_PATCHING_RETIREMENT"],
    "eventTypeCategory": ["scheduledChange"]
  }
}

Notifications include the task retirement date, affected service and cluster identifiers, and recommended next steps. They are sent per-region, separately for service tasks and standalone tasks.

For a walkthrough of forwarding these notifications to Slack, see Improving Operational Visibility with AWS Fargate Task Retirement Notifications.

Preventing Dropped Connections During Replacement

When to use this: Tasks are being replaced successfully, but you are observing dropped requests or brief errors during the transition.

When ECS replaces a task, the container receives a SIGTERM signal followed by SIGKILL after the stopTimeout period expires. If your application does not handle SIGTERM gracefully, in-flight requests may be dropped.

What your application should do:

• Catch SIGTERM — stop accepting new connections
• Drain in-flight work — complete active requests, close database connections
• Exit cleanly — return exit code 0 once draining is complete

Parameters to review:

Parameter	Default	Recommendation
stopTimeout	30s	Set to match your application's drain time (maximum 120s)
ELB deregistration delay	300s	Set to match the longest expected request lifetime
Health check grace period	0s	Set to your application's startup time plus a buffer

Common issues:

Issue	Impact
Application does not handle SIGTERM	Container is forcefully terminated, in-flight requests are dropped
stopTimeout too short	Application is mid-drain when SIGKILL is sent
Deregistration delay too short	Load balancer continues routing to a draining task
Health check grace period too short	New tasks may fail health checks before startup completes

Tip: Use the exec form in your Dockerfile (ENTRYPOINT ["java", "-jar", "app.jar"]) to ensure SIGTERM is delivered directly to your application process rather than to a shell wrapper. For more on this topic, see Graceful Shutdowns with ECS.