# Protect your Amazon ECS tasks from being terminated by scale-in events
You can use Amazon ECS task scale-in protection to protect your tasks from being terminated by scale-in events from either service auto scaling or deployments.
Certain applications require a mechanism to safeguard mission-critical tasks from termination by scale-in events during times of low utilization or during service deployments. For example:
+ You have a queue-processing asynchronous application such as a video transcoding job where some tasks need to run for hours even when cumulative service utilization is low.
+ You have a gaming application that runs game servers as Amazon ECS tasks that need to continue running even if all users have logged-out to reduce start-up latency of a server reboot.
+ When you deploy a new code version, you need tasks to continue running because it would be expensive to reprocess.
To protect tasks that belong to your service from terminating in a scale-in event, set the `ProtectionEnabled` attribute to `true`. When you set `ProtectionEnabled` to true, tasks are protected for 2 hours by default. You can then customize the protection period by using the `ExpiresInMinutes` attribute. You can protect your tasks for a minimum of 1 minute and up to a maximum of 2880 minutes (48 hours). If you're using the AWS CLI, you can specify the `--protection-enabled` option.
After a task finishes its requisite work, you can set the `ProtectionEnabled` attribute to `false`, allowing the task to be terminated by subsequent scale-in events. If you're using the AWS CLI, you can specify the `--no-protection-enabled` option.
## Task scale-in protection mechanisms
You can set and get task scale-in protection using either the Amazon ECS container agent endpoint or the Amazon ECS API.
+ **Amazon ECS container agent endpoint**
We recommend using the Amazon ECS container agent endpoint for tasks that can self-determine the need to be protected. Use this approach for queue-based or job-processing workloads.
When a container starts processing work, for example by consuming an SQS message, you can set the `ProtectionEnabled` attribute through the task scale-in protection endpoint path `$ECS_AGENT_URI/task-protection/v1/state` from within the container. Amazon ECS will not terminate this task during scale-in events. After your task finishes its work, you can clear the `ProtectionEnabled` attribute using the same endpoint, making the task eligible for termination during subsequent scale-in events.
For more information about the Amazon ECS container agent endpoint, see [Amazon ECS task scale-in protection endpoint](task-scale-in-protection-endpoint.md).
+ **Amazon ECS API**
You can use the Amazon ECS API to set and retrieve task scale-in protection if your application has a component that tracks the status of active tasks. Use `UpdateTaskProtection` to mark one or more tasks as protected. Use `GetTaskProtection` to retrieve the protection status.
An example of this approach would be if your application is hosting game server sessions as Amazon ECS tasks. When a user logs in to a session on the server (task), you can mark the task as protected. After the user logs out, you can either clear the protection specifically for this task or periodically clear protection for similar tasks that no longer have active sessions, depending on your requirement to keep idle servers.
For more information, see [UpdateTaskProtection](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateTaskProtection.html) and [GetTaskProtection](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_GetTaskProtection.html) in the *Amazon Elastic Container Service API Reference*.
You can combine both approaches. For example, use the Amazon ECS agent endpoint to set task protection from within a container and use the Amazon ECS API to remove task protection from your external controller service.
## Considerations
Consider the following points before using task scale-in protection:
+ Task scale-in protection is only supported with tasks deployed from a service.
+ Task scale-in protection is supported with tasks deployed from a service running on Amazon ECS Managed Instances.
+ We recommend using the Amazon ECS container agent endpoint because the Amazon ECS agent has built-in retry mechanisms and a simpler interface.
+ You can reset the task scale-in protection expiration period by calling `UpdateTaskProtection` for a task that already has protection turned on.
+ Determine how long a task would need to complete its requisite work and set the `expiresInMinutes` property accordingly. If you set the protection expiration longer than necessary, then you will incur costs and face delays in the deployment of new tasks.
+ Task scale-in protection is supported on Amazon ECS container agent `1.65.0` or later. You can add support for this feature on Amazon EC2 instances using older versions of the Amazon ECS container agent by updating the agent to the latest version. For more information, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
+ Deployment considerations:
+ If the service uses a rolling update, new tasks will be created but tasks running older version will not be terminated until `protectionEnabled` is cleared or expires. You can adjust the `maximumPercentage` parameter in deployment configuration to a value that allows new tasks to be created when old tasks are protected.
+ If a blue/green update is applied, the blue deployment with protected tasks will not be removed if tasks have `protectionEnabled`. Traffic will be diverted to the new tasks that come up and older tasks will only be removed when `protectionEnabled` is cleared or expires. Depending on the timeout of the CodeDeploy or CloudFormation updates, the deployment may timeout and the older Blue tasks may still be present.
+ If you use CloudFormation, the update-stack has a 3 hour timeout. Therefore, if you set your task protection for longer than 3 hours, then your CloudFormation deployment may result in failure and rollback.
During the time your old tasks are protected, the CloudFormation stack shows `UPDATE_IN_PROGRESS`. If task scale-in protection is removed or expires within the 3 hour window, your deployment will succeed and move to the `UPDATE_COMPLETE` status. If the deployment is stuck in `UPDATE_IN_PROGRESS` for more than 3 hours, it will fail and show `UPDATE_FAILED` state, and will then be rolled back to old task set.
+ Amazon ECS sends service events when protected tasks keep a deployment (rolling or blue/green) from reaching the steady state, so that you can take remedial actions. While trying to update the protection status of a task, if you receive a `DEPLOYMENT_BLOCKED` error message, it means the service has more protected tasks than the desired count of tasks for the service. To resolve this error, do one the following:
+ Wait for the current task protection to expire. Then set task protection.
+ Determine which tasks can be stopped. Then use `UpdateTaskProtection`with the `protectionEnabled` option set to `false` for these tasks.
+ Increase the desired task count of the service to more than the number of protected tasks.
## IAM permissions required for task scale-in protection
The task must have the Amazon ECS task role with the following permissions:
+ `ecs:GetTaskProtection`: Allows the Amazon ECS container agent to call `GetTaskProtection`.
+ `ecs:UpdateTaskProtection`: Allows the Amazon ECS container agent to call `UpdateTaskProtection`.
# Amazon ECS task scale-in protection endpoint
The Amazon ECS container agent automatically injects the `ECS_AGENT_URI` environment variable into the containers of Amazon ECS tasks to provide a method to interact with the container agent API endpoint.
We recommend using the Amazon ECS container agent endpoint for tasks that can self-determine the need to be protected.
When a container starts processing work, you can set the `protectionEnabled` attribute using the task scale-in protection endpoint path `$ECS_AGENT_URI/task-protection/v1/state` from within the container.
Use a PUT request to this URI from within a container to set task scale-in protection. A GET request to this URI returns the current protection status of a task.
## Task scale-in protection request parameters
You can set task scale-in protection using the `${ECS_AGENT_URI}/task-protection/v1/state` endpoint with the following request parameters.
`ProtectionEnabled`
Specify `true` to mark a task for protection. Specify `false` to remove protection and make the task eligible for termination.
Type: Boolean
Required: Yes
`ExpiresInMinutes`
The number of minutes the task is protected. You can specify a minimum of 1 minute to up to 2,880 minutes (48 hours). During this time period, your task will not be terminated by scale-in events from service Auto Scaling or deployments. After this time period lapses, the `protectionEnabled` parameter is set to `false`.
If you don’t specify the time, then the task is automatically protected for 120 minutes (2 hours).
Type: Integer
Required: No
The following examples show how to set task protection with different durations.
**Example of how to protect a task with the default time period**
This example shows how to protect a task with the default time period of 2 hours.
```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true}'
```
**Example of how to protect a task for 60 minutes**
This example shows how to protect a task for 60 minutes using the `expiresInMinutes` parameter.
```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":60}'
```
**Example of how to protect a task for 24 hours**
This example shows how to protect a task for 24 hours using the `expiresInMinutes` parameter.
```
curl --request PUT --header 'Content-Type: application/json' ${ECS_AGENT_URI}/task-protection/v1/state --data '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}'
```
**Examples for Windows containers**
For Windows containers, you can use PowerShell's `Invoke-RestMethod` cmdlet instead of curl. The following examples show the PowerShell equivalents of the previous curl commands.
**Example of how to protect a Windows container task with the default time period**
This example shows how to protect a task with the default time period of 2 hours using PowerShell.
```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true}' -ContentType 'application/json'
```
**Example of how to protect a Windows container task for 60 minutes**
This example shows how to protect a task for 60 minutes using the `expiresInMinutes` parameter with PowerShell.
```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true,"ExpiresInMinutes":60}' -ContentType 'application/json'
```
**Example of how to protect a Windows container task for 24 hours**
This example shows how to protect a task for 24 hours using the `expiresInMinutes` parameter with PowerShell.
```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Put -Body '{"ProtectionEnabled":true,"ExpiresInMinutes":1440}' -ContentType 'application/json'
```
The PUT request returns the following response.
```
{
"protection": {
"ExpirationDate": "2023-12-20T21:57:44.837Z",
"ProtectionEnabled": true,
"TaskArn": "arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
}
}
```
## Task scale-in protection response parameters
The following information is returned from the task scale-in protection endpoint `${ECS_AGENT_URI}/task-protection/v1/state` in the JSON response.
`ExpirationDate`
The epoch time when protection for the task will expire. If the task is not protected, this value is null.
`ProtectionEnabled`
The protection status of the task. If scale-in protection is enabled for a task, the value is `true`. Otherwise, it is `false`.
`TaskArn`
The full Amazon Resource Name (ARN) of the task that the container belongs to.
The following example shows the details returned for a protected task.
```
curl --request GET ${ECS_AGENT_URI}/task-protection/v1/state
```
For Windows containers, use the following PowerShell command to get the protection status:
```
Invoke-RestMethod -Uri $env:ECS_AGENT_URI/task-protection/v1/state -Method Get
```
```
{
"protection":{
"ExpirationDate":"2023-12-20T21:57:44Z",
"ProtectionEnabled":true,
"TaskArn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0"
}
}
```
The following information is returned when a failure occurs.
`Arn`
The full Amazon Resource Name (ARN) of the task.
`Detail`
The details related to the failure.
`Reason`
The reason for the failure.
The following example shows the details returned for a task that is not protected.
```
{
"failure":{
"Arn":"arn:aws:ecs:us-west-2:111122223333:task/1234567890abcdef0",
"Detail":null,
"Reason":"TASK_NOT_VALID"
}
}
```
The following information is returned when an exception occurs.
`requestID`
The AWS request ID for the Amazon ECS API call that results in an exception.
`Arn`
The full Amazon Resource Name (ARN) of the task or service.
`Code`
The error code.
`Message`
The error message.
If a `RequestError` or `RequestTimeout` error appears, it is likely that it's a networking issue. Try using VPC endpoints for Amazon ECS.
The following example shows the details returned when an error occurs.
```
{
"requestID":"12345-abc-6789-0123-abc",
"error":{
"Arn":"arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
"Code":"AccessDeniedException",
"Message":"User: arn:aws:sts::444455556666:assumed-role/my-ecs-task-role/1234567890abcdef0 is not authorized to perform: ecs:GetTaskProtection on resource: arn:aws:ecs:us-west-2:555555555555:task/test/1234567890abcdef0 because no identity-based policy allows the ecs:GetTaskProtection action"
}
}
```
The following error appears if the Amazon ECS agent is unable to get a response from the Amazon ECS endpoint for reasons such as network issues or the Amazon ECS control plane is down.
```
{
"error": {
"Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
"Code": "RequestCanceled",
"Message": "Timed out calling Amazon ECS Task Protection API"
}
}
```
The following error appears when the Amazon ECS agent gets a throttling exception from Amazon ECS.
```
{
"requestID": "12345-abc-6789-0123-abc",
"error": {
"Arn": "arn:aws:ecs:us-west-2:555555555555:task/my-cluster-name/1234567890abcdef0",
"Code": "ThrottlingException",
"Message": "Rate exceeded"
}
}
```