---
cuppy_hub: aws
cuppy_path: patterns/alb-to-ecs-fargate.md
cuppy_section: docs
cuppy_doc: Q5EM-SS37
cuppy_doc_uuid: 79c34532-4a4c-4902-9b43-63db485ecf46
cuppy_permalink: https://cuppy.io/aws/d/Q5EM-SS37
cuppy_version: 4
cuppy_updated: 2026-10-23T16:16:52.575Z
cuppy_canonical: https://cuppy.io/aws/docs/patterns/alb-to-ecs-fargate
cuppy_mcp: https://cuppy.io/mcp
cuppy_body_sha256: 62d8e5e79eb8613cc32f1b53209f97043bf27f4913384693f90efc52cbe3548f
# cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks.
---


# ALB to ECS Fargate

**Fargate tasks have no instance ID, only their own network interface and IP, so the target group must be `TargetType: ip`.** ECS registers and deregisters task IPs for you when the *service* names the target group. The task's security group must admit the container port from the **ALB's security group**.

## What crosses the handoff

| Side | Provides / expects |
|---|---|
| **ALB** | A target group with `TargetType: ip`, protocol and port matching the container, and a health check path the container answers with a code in `Matcher`. Its security group must be able to send to the tasks. A new group allows all outbound traffic. |
| **ECS service** | `networkMode: awsvpc` (Fargate always). `loadBalancers: [{ targetGroupArn, containerName, containerPort }]`. Task subnets in AZs **enabled on the ALB**. A task security group admitting `containerPort` from the ALB's group. |

## Known-good

```
aws elbv2 create-target-group --name <app> --target-type ip --protocol HTTP --port 8080 \
  --vpc-id <vpc> --health-check-path /healthz --matcher HttpCode=200-399
aws ec2 authorize-security-group-ingress --group-id <task-sg> --protocol tcp --port 8080 --source-group <alb-sg>
aws ecs create-service --cluster <cluster> --service-name <app> --task-definition <family> \
  --desired-count 2 --launch-type FARGATE \
  --network-configuration 'awsvpcConfiguration={subnets=[<priv-a>,<priv-b>],securityGroups=[<task-sg>],assignPublicIp=DISABLED}' \
  --load-balancers targetGroupArn=<tg-arn>,containerName=app,containerPort=8080 \
  --health-check-grace-period-seconds 60
```

(`create-service` flags beyond `--network-configuration`: UNVERIFIED in the collected sources, cross-checked against the ECS SDK's `CreateService` input names `loadBalancers` and `healthCheckGracePeriodSeconds`.)

- The task needs a route to pull its image (`patterns/ecs-to-ecr.md`). The ALB doesn't change that.
- The container's keep-alive timeout must be longer than the ALB's idle timeout (60 s by default), or you get intermittent 502s.
- If the health check uses a different port from the traffic port, open that port from `alb-sg` too.
- If custom NACLs are used, allow the health-check and traffic ports inbound on the task subnets, and ephemeral ports 1024–65535 back to the ALB subnets.

## Known-bad

| Configuration | Symptom |
|---|---|
| Target group `TargetType: instance` | The service can't register Fargate tasks (UNVERIFIED exact error text) |
| Task security group admits only the VPC CIDR's port 80, but the container listens on 8080 | `Target.Timeout`, tasks replaced repeatedly |
| Task security group has no rule from `alb-sg` | `Target.Timeout`; 504 when every target fails and the ALB fails open |
| Health check path needs auth or redirects (301/302) | `Target.ResponseCodeMismatch` "Health checks failed with these codes: [302]" |
| App routes by host name | Health checks fail: their `Host` is the task's private IP |
| Task subnets in an AZ not enabled on the ALB | `Target.NotInUse` |
| No running tasks (crash loop, image pull failure) | 503: no registered targets (`reference/ecs/errors.md`) |
| Slow start, no grace period | The service kills tasks before they pass the 5 consecutive checks (defaults) needed to count as healthy |
| Container keep-alive shorter than the ALB idle timeout | Intermittent 502 |
| Long requests during deployments | 502 when the deregistration delay elapses mid-request. Raise the delay |

## Which side is wrong?

- `describe-target-health` shows **`Target.*` reasons** → the ECS/task side: security group, port, path, start-up time.
- **No targets at all** → the ECS service: tasks not running, or the `loadBalancers` mapping is wrong (container name and port must match the task definition).
- **Targets healthy, but clients get 502/504** → timeouts or the response: `guides/elb/fix-alb-5xx.md`.


---
<!-- cuppy -->
You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.
<!-- /cuppy -->