Target group deregistration delay (connection draining)
Deregistration delay (deregistration_delay.timeout_seconds) is how long an ALB or NLB keeps a deregistering target in the draining state so in-flight requests can finish: 300 seconds by default, 0 to 3,600 allowed. New requests stop going to the target immediately. For typical HTTP APIs with sub-second requests, 15 to 60 seconds makes ECS deployments and scale-in much faster; keep it longer than your slowest request, and make sure the task or instance doesn't exit before the delay ends.
What happens during deregistration
- The target is deregistered: by ECS stopping a task, Auto Scaling terminating an instance, or you calling
deregister-targets. - The load balancer stops routing new requests to it straight away; the target shows
draining. - Existing connections and in-flight requests carry on until they finish or the delay expires.
- When the delay ends the target becomes
unusedand the ALB closes anything still open. If a target with no active connections finishes early, deregistration completes at once, although the console may keep showingdraininguntil the timeout.
If the target itself shuts down before draining finishes, clients with open requests get 5xx errors. That is the usual source of 502s during deploys.
Recommended values
| Workload | Deregistration delay | Why |
|---|---|---|
| HTTP APIs with fast requests (under 1 to 2 s) | 15 to 30 s | Long enough for in-flight requests, short deploys |
| Web apps with some slow requests or uploads | 60 to 120 s | Cover the slowest normal request |
| WebSockets or long-polling | Match how long you can let clients stay before forcing reconnection | Connections stay until the delay ends |
| Batch-style or long downloads through the ALB | Up to 3,600 s | Only if requests truly last that long |
| NLB with long-lived TCP | As needed; consider deregistration_delay.connection_termination.enabled | Closes connections at the end of the delay |
Lambda targets don't use this attribute.
Line it up with how the target stops
For ECS, the sequence on a deploy is: deregister from the target group, wait for draining, then send SIGTERM to the container, wait stopTimeout (30 seconds by default on Fargate), then SIGKILL. So:
- The app should keep serving during draining and handle SIGTERM by finishing in-flight work, then exiting. Exit code 143 is a SIGTERM exit; see exit code 143.
- For EC2 Auto Scaling, use a termination lifecycle hook if instances need more time than the delay.
- A very long delay multiplied by many tasks and a low maximum percent makes deployments crawl.
Change it
CLI:
aws elbv2 modify-target-group-attributes \
--target-group-arn arn:aws:elasticloadbalancing:eu-west-2:123456789012:targetgroup/api/73e2d6bc24d8a067 \
--attributes Key=deregistration_delay.timeout_seconds,Value=30
aws elbv2 describe-target-group-attributes \
--target-group-arn arn:aws:elasticloadbalancing:eu-west-2:123456789012:targetgroup/api/73e2d6bc24d8a067 \
--query "Attributes[?starts_with(Key,'deregistration_delay')]"Console: EC2, Target Groups, select the group, Attributes, Edit, Deregistration delay.
CloudFormation: on AWS::ElasticLoadBalancingV2::TargetGroup, under TargetGroupAttributes:
TargetGroupAttributes:
- Key: deregistration_delay.timeout_seconds
Value: "30"Terraform: deregistration_delay on aws_lb_target_group (default 300).
Symptoms of a wrong value
- Deploys and scale-in take ages, with tasks in DEACTIVATING or "draining" for five minutes: the default 300 seconds is far longer than your requests.
- 502s or connection resets during deploys: the app exits before draining ends, or the delay is shorter than real request times.
- Long-lived connections cut at a fixed time after deploy: that is the delay ending; extend it or make clients reconnect gracefully.
Questions
What is the default deregistration delay?
300 seconds. The valid range is 0 to 3,600 seconds.
Does deregistration delay affect ECS deployments?
Yes. ECS waits for draining to finish before stopping old tasks, so the delay adds directly to deployment and scale-in time.
What does draining mean in a target group?
The target has been deregistered: it receives no new requests, but existing ones can complete until the deregistration delay expires.
A slow deploy at night is often just a five-minute default drain multiplied by every task. CloudConsole, a phone app for AWS, is being built to show ECS deployment progress and alarms on your phone.
About the app → · Download on the App Store