AWS Fargate task maintenance

When AWS determines that a security or infrastructure update is needed for an Amazon ECS task hosted on AWS Fargate, the tasks need to be stopped and new tasks launched to replace them.

For tasks that are part of an Amazon ECS service, if there's an issue with the underlying host, AWS stops the task. Moreover, the service scheduler also launches a new task in an attempt to maintain the desired count for the service. When this occurs, no task retirement notice is sent. However, if there's a security issue with the underlying host or platform version that the task is using, a task retirement notice is sent to your AWS Health Dashboard. The notice is also sent to the email address that's associated with the account. The task retirement notice provides details about the issue, the task retirement date, and what the next steps are. For more information, see Understanding the task retirement notice.

For standalone tasks, when there's an issue with the underlying host or a security issue with the platform version that the task is using, AWS sends a task retirement notice to your AWS Health Dashboard. The notice also is sent to the email address associated with the account. The task retirement notice provides details about the issue, the task retirement date, and what the next steps are. For more information, see Understanding the task retirement notice.

When a task is stopped in any of the scenarios mentioned here, you can describe the stopped task to retrieve the stoppedReason value. The stoppedReason containing a ECS is performing maintenance on the underlying infrastructure hosting the task message indicates that the task was stopped due to a task maintenance issue.

Important

To prepare for the task retirement process, we recommend that you test your application behavior by simulating this scenario. You can do this by stopping an individual task in your service to test for resiliency.

The following table describes these scenarios.

Task type	Issue	Action
Standalone task	Host issue	A task retirement notice is sent using your AWS Health Dashboard and email. If no action is taken by the task retirement date, AWS stops the task.
	Security vulnerability	A task retirement notice is sent using your AWS Health Dashboard and email. If no action is taken by the task retirement date, AWS stops the task.
Service task	Host issue	The task is stopped by AWS and the service scheduler launches a new task in an attempt to maintain the desire count for the service. No notification is sent.
	Security vulnerability	A task retirement notice is sent using your AWS Health Dashboard and email. If no action is taken by the task retirement date, AWS stops the task and the service scheduler launches a new task in an attempt to maintain the service's desired count.

Understanding the task retirement notice

When a task retirement notice is sent, you're notified by email of the pending retirement. An email is sent before the event with the task ID and retirement date. This email is sent to the address that's associated with your account. This is the same email address that you use to log in to the AWS Management Console. If you use an email account that you don't check regularly, you can use the AWS Health Dashboard to determine if any of your tasks are scheduled for retirement. You can update the contact information for your account on the Account Settings page.

When a task reaches its scheduled retirement date, it's stopped or terminated by AWS. This is if it hasn't already been stopped. For service tasks, when the task is stopped, the service scheduler launches a new one to replace it to ensure the service maintains its desired count. For standalone tasks, they're stopped and you're responsible for launching a replacement.

Working with tasks scheduled for retirement

Note

This procedure only applies to service tasks. For standalone tasks, simply stop and run new standalone tasks.

For service tasks, when the task is stopped, the service scheduler starts a new one to replace it after it reaches its scheduled retirement date. The service scheduler maintains the services desired count. To update your service tasks before the retirement date, you can use the following steps. For more information, see Updating a service.

To update a running service (AWS Management Console)

1. Open the Amazon ECS console at https://console.aws.amazon.com/ecs/.

2. On the navigation bar, select the Region that your cluster is in.

3. In the navigation pane, choose Clusters.

4. On the Clusters page, select the name of the cluster where your service resides.

5. On the Cluster: name page, choose Services.

6. Check the box to the left of the service to update and choose Update.

7. On the Configure service page, your service information is pre-populated. Select Force new deployment and choose Next step.

   Note

   When you force a new deployment, the scheduler launches new tasks using the patched platform version. Your tasks don't require you select a different platform version in order to update. For more information, see AWS Fargate platform versions.

8. On the Configure network and Set Auto Scaling (optional) pages, choose Next step.

9. Choose Update Service to finish and update your service.

To update a running service (AWS CLI)

1. Obtain the Amazon Resource Name (ARN) for the service.

   aws ecs list-services --cluster cluster_name --region region

   The output is as follows.

   {
       "serviceArns": [
           "arn:aws:ecs:region:aws_account_id:service/MyService"
       ]
   }

2. Update your service that deploys new tasks.

   You might need to set the force-new-deployment option depending on your deployment type and changed service options. For information about when to set the force-new-deployment option, see update-services in the AWS CLI Command Reference.

   aws ecs update-service --service serviceArn --cluster cluster_name --region region

If you're using standalone tasks, then you can start a new task to replace it. For more information, see Run a standalone task.