ECS on Fargate

In 1 minute

ECS (Elastic Container Service) runs containers. A task definition is the recipe: image, CPU, memory, env vars, secrets and logs. A task is one running copy of that recipe. A service keeps the wanted number of tasks running and replaces any that fail. All of them belong to a cluster, and with Fargate there are no servers for us to manage.

Picture it

flowchart TB
  CL["cluster minitickets-dev"] --> SVC["service minitickets-dev-api<br/>desiredCount 1"]
  TD["task definition<br/>minitickets-dev-api:revision"] --> SVC
  SVC --> T["task: one api container<br/>+ Service Connect proxy"]
  SVC -->|"registers task IP"| TG["api target group"]

The web side has the same shape: minitickets-dev-web.

How it works

1. The task definition says which image, how much CPU and memory, which env vars and secrets, and which roles. Every change makes a new numbered revision.
2. The service starts tasks from the newest revision and keeps desiredCount of them running. On a new revision it starts new tasks first, then stops the old ones.
3. Each task gets its own network card (awsvpc mode), a private IP, a security group and, here, a public IP.
4. Health decides who lives. A task that fails its health checks is stopped and replaced. If new tasks never get healthy, the circuit breaker rolls back to the last working revision.

In MiniTickets

	api	web
Size (Fargate, ARM64)	512 CPU, 1024 MB	512 CPU, 1024 MB
Port	4000	3000
Roles	execution role + task role	execution role only
Health	container check on /health, ALB check on /health	ALB check on /

Both services run one task on FARGATE_SPOT: spare AWS capacity, about 70% cheaper, which AWS may take back with a 2-minute warning. Each has a 60 s health check grace period and the circuit breaker with rollback (infra/src/compute/service.ts → createApiService).

Service Connect gives the two services private names in the namespace minitickets.internal: the web server calls http://api:4000 to render /events, and the api calls http://web:3000 to clear the web cache. A small proxy in each task listens on 14000 (api) and 13000 (web).

From → to	What happens	What allows it
API ECS service → Public subnetsonly when computeEnabled = true	api tasks get a private and a public IP in a public subnet	config networkConfiguration: subnets = public subnets, assignPublicIp: truecreateApiService
API ECS service → ECS Service Connectonly when entryEnabled = true	api offers the name api and may call web	service-connect serviceConnectConfiguration: namespace minitickets.internal, discoveryName api, clientAlias port 4000, proxy port 14000createApiService
API ECS service → API security grouponly when computeEnabled = true	every API task (and the migration task) uses the api security group	config networkConfiguration.securityGroups: [apiSgId]; run-migrations.sh uses the same groupcreateApiService
API target group → API ECS serviceonly when entryEnabled = true	the ALB forwards to a healthy api task on port 4000 and checks GET /health	sg-rule api-sg inbound rule minitickets-dev-api-in-4000: TCP 4000 from alb-sgcreateSecurityGroups registration the api service registers each task IP: loadBalancers container api, port 4000; health check grace 60 screateApiService
Web ECS service → API ECS serviceonly when entryEnabled = true	server-side rendering: the web server calls http://api:4000	service-connect API_INTERNAL_URL http://api:4000 → web's proxy → the api's proxy on 14000 → the api containercreateServiceConnect sg-rule api-sg inbound rule minitickets-dev-api-in-14000: TCP 14000 from web-sgcreateServiceConnect
API ECS service → Web ECS serviceonly when entryEnabled = true	revalidate: POST http://web:3000/api/revalidate after an event or seat count changes	service-connect WEB_INTERNAL_URL http://web:3000 → the web proxy on 13000 → the web containercreateServiceConnect sg-rule web-sg inbound rule minitickets-dev-web-in-13000: TCP 13000 from api-sgcreateServiceConnect secret the call carries REVALIDATE_SECRET; both tasks read it from minitickets/dev/revalidate-secretrevalidateEventsPages
API ECS service → RDS Postgresonly when computeEnabled = true	SQL over TLS on port 5432	sg-rule db-sg inbound rule minitickets-dev-db-in-5432: TCP 5432 from api-sgcreateSecurityGroups route local route 10.0.0.0/16: a public subnet reaches a private subnet without leaving the VPCcreateNetwork secret DB_USER and DB_PASSWORD from the RDS master secret (<arn>:username::, <arn>:password::)createApiTask
API ECS service → ElastiCache Valkeyonly when computeEnabled = true	the Redis protocol over TLS (rediss://) on port 6379	sg-rule redis-sg inbound rule minitickets-dev-redis-in-6379: TCP 6379 from api-sgcreateSecurityGroups route local route 10.0.0.0/16: a public subnet reaches a private subnet without leaving the VPCcreateNetwork secret REDIS_URL from minitickets/dev/redis-url, which holds the Valkey auth tokencreateSecrets
API ECS service → API task definitiononly when computeEnabled = true	the service starts tasks from the newest revision	config taskDefinition = minitickets-dev-api:<revision>; a new revision rolls the servicecreateApiService
API ECS service → ECS clusteronly when computeEnabled = true	the api service runs in cluster minitickets-dev on FARGATE_SPOT	config capacityProviderStrategies: FARGATE_SPOT weight 1 (attached to the cluster)createCluster
API ECS service → API apponly when computeEnabled = true	each api task runs the Fastify server on port 4000	config container api, HOST 0.0.0.0, PORT 4000createApiTask
API ECS service → ECR repositoriesonly when computeEnabled = true	ECS pulls the api image when a task starts	iam api execution role: AmazonECSTaskExecutionRolePolicy (ECR pull, CloudWatch Logs write)createIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork sg-rule api-sg outbound rule minitickets-dev-api-out-all: all traffic to 0.0.0.0/0createSecurityGroups
API ECS service → CloudWatch log groupsonly when computeEnabled = true	the awslogs driver sends every api line to /minitickets/dev/api	iam api execution role managed policy: logs:CreateLogStream, logs:PutLogEventscreateIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork
API ECS service → Booking-events SNS topiconly when computeEnabled = true	the outbox relay publishes each booking-confirmed event	iam api task role, policy send-jobs: sns:Publish on minitickets-dev-booking-events onlycreateIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork
API ECS service → Tickets tableonly when computeEnabled = true	reads one user's tickets for My tickets	iam api task role ReadTickets: dynamodb:Query on minitickets-dev-tickets (no Scan, no writes)createIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork
API ECS service → Ticket assets bucketonly when computeEnabled = true	signs GET and PUT URLs, and copies a checked upload to posters/	iam api task role: s3:GetObject on tickets/*, posters/*, poster-uploads/*; s3:PutObject on posters/* and poster-uploads/* only with x-amz-server-side-encryption AES256createIamRoles resource-policy bucket policy: Deny every s3:* request when aws:SecureTransport is falsecreateTicketStorage
CD deploy job → API ECS serviceonly when computeEnabled = true	phase B pulumi up rolls the services; aws ecs wait services-stable	iam deploy role StackServices grants ecs:* on Resource *; PassOurRolesToEcsTasksAndLambda grants iam:PassRole on minitickets-dev-* to ECS tasks; DenyOtherRegions blocks calls outside us-east-1createCicd
API ECS service → RDS master password secretonly when computeEnabled = true	ECS reads the database user and password when a task starts	iam api execution role, policy read-secrets: secretsmanager:GetSecretValue on this secret's ARNcreateIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork
API ECS service → Redis URL secretonly when computeEnabled = true	ECS reads REDIS_URL when a task starts	iam api execution role, policy read-secrets: secretsmanager:GetSecretValue on minitickets/dev/redis-urlcreateIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork
API ECS service → Revalidate secretonly when entryEnabled = true	ECS reads REVALIDATE_SECRET for the api when a task starts	iam api execution role, policy read-secrets: secretsmanager:GetSecretValue on minitickets/dev/revalidate-secretcreateIamRoles route public route table: 0.0.0.0/0 → minitickets-dev-igw. The task has a public IP; there is no NAT gateway and no VPC endpoint.createNetwork

See the api service on the map →

See it in AWS

Console

ECS → Clusters → minitickets-dev → Services → minitickets-dev-api → Deployments, Events, Tasks.

CLI

aws ecs describe-services --cluster minitickets-dev --services minitickets-dev-api

Code

infra/src/compute/task.ts → createApiTask

Break it

Symptom	Cause	Where to look
“circuit breaker triggered”, old version still runs	New tasks never got healthy	Service → Events
The api is down a minute, then back by itself	AWS took back the Spot capacity	Stopped task’s reason
SSR times out calling http://api:4000	No api-sg rule for TCP 14000 from web-sg	api-sg → Inbound rules

Say it in an interview

Say it like this (20-30 seconds)

A task definition is the versioned recipe for a container: image, CPU, memory, roles, secrets and logs. A service keeps a desired count of tasks from the latest revision running, registers them in the ALB target group and replaces unhealthy ones. MiniTickets runs one api and one web task on Fargate Spot in ARM64, with a circuit breaker that rolls back failed deploys. Service Connect gives them private names for server-to-server calls.

Follow-ups

What is the trade-off of Fargate Spot?

It is about 70% cheaper, but AWS can reclaim the capacity with two minutes’ warning. With one task, that means a short outage until the replacement is healthy. Production would run at least two tasks, partly on regular FARGATE.

Fargate or EC2 launch type?

Fargate: no servers to patch or scale, pay per task. EC2: cheaper at steady high load and more control, but we would manage the instances. For one small task each, Fargate wins.

Why do the web and api not call each other through the ALB?

In CloudFront mode the ALB accepts only requests with CloudFront’s secret header, and going out and back in would be slower. Service Connect keeps the call inside the VPC.

What does the 60-second grace period protect?

A task that is still starting fails its first health checks. Without the grace period, the service would kill it before it is ready, forever.

Advanced: Sizes, Exec and Container Insights

The api is 256 CPU / 512 MB when entry is off (no Service Connect proxy). Service Connect’s proxy shares the task’s CPU and memory, which is why both tasks moved to 512 / 1024. ECS Exec is on for the api, so ECS Exec can open a debug shell in the container; the task role carries the four ssmmessages actions it needs. Container Insights is off on the cluster to avoid extra metric costs (infra/src/compute/cluster.ts → createCluster).

Checkpoint

Answer these without scrolling up. If one feels hard, reread that section.

1. What is the difference between a task definition and a task?
2. What does a service do that a task started by hand does not?
3. What happens when new tasks never become healthy?
4. What are the costs and risks of FARGATE_SPOT?
5. On which ports do the Service Connect proxies listen, and who may reach each?

Redraw it from memory: cluster, task definition, service, task and target group, with the arrow for each relation

Try this: on the map, select ECS Service Connect and find the two security group rules that make it work

Mark this page as read