mgarden

ALB Target Group Health Checks

5 min read

aws alb networking claude-curated

Application Load Balancer (ALB) routes traffic to targets in a target group. The ALB only sends traffic to targets it considers healthy, and the definition of healthy is configurable per target group. Getting the health check wrong is one of the most common causes of avoidable outages and cascading failures.

Health check parameters

ParameterWhat it controls
ProtocolHTTP, HTTPS, or gRPC
PathURL path the ALB requests (HTTP/S only)
Porttraffic-port (same port targets receive traffic on) or a fixed port
HealthyThresholdCountConsecutive successes before a target flips to healthy
UnhealthyThresholdCountConsecutive failures before a target flips to unhealthy
IntervalSeconds between checks (default 30, min 5)
TimeoutSeconds to wait for a response (default 5)
MatcherSuccess codes — 200, 200-299, 200,301

Defaults are conservative. For a tight feedback loop on a fast-deploying service, drop interval and threshold counts; for a slow-starting service, raise them.

Common pitfalls

Hitting a heavy endpoint

A health check path that hits the homepage (/) or any endpoint that touches the database, calls downstream services, or renders templates ties target health to the health of every dependency. A blip in a downstream cache marks all targets unhealthy and the ALB returns 503 even though the service is fine.

A dedicated /healthz (or /health, /_health) endpoint that returns 200 if the process is up — without touching dependencies — is the safe default. A separate /readyz endpoint can include dependency checks for orchestrator readiness probes, but the ALB usually wants liveness, not readiness.

Host header rejection

Many web frameworks reject requests whose Host header is not on an allowed list. The ALB sends health checks with Host: <target-ip> by default, which fails this check.

Fixes:

  • Configure the framework to allow the target’s IP or a wildcard for the health check path.
  • Use a path the framework serves before host validation (some frameworks have a pre-routing healthz).
  • On HTTPS health checks, SNI is set to the target’s hostname; behaviour varies.

Slow start time

A new target that receives full traffic immediately after passing health checks can be overwhelmed by JIT compilation, cache warming, or connection pool initialisation. Two knobs:

  • Slow start duration — ramps traffic to a new healthy target over N seconds (0–900). Disabled by default.
  • Deregistration delay (connection draining) — how long the ALB keeps sending in-flight requests to a deregistering target. Default 300 s.

Both apply per target group.

Matcher too narrow

Default matcher is 200. If the health endpoint redirects (302) or the framework returns 204 No Content, all targets fail health checks. Adjust Matcher accordingly.

Multi-tenant SaaS routing

A single ALB can serve many customer hostnames using listener rules with host conditions.

Rule 1: Host = customer-a.example.com  →  TG-customer-a
Rule 2: Host = customer-b.example.com  →  TG-customer-b
Rule 3: Host = *.example.com           →  TG-default
Default action:                        →  fixed 404

Rules evaluate in priority order; first match wins.

For TLS, the ALB supports SNI with multiple ACM certificates on a single HTTPS listener (up to 25 certs by default, raisable). The client’s SNI selects the right cert; the listener rule then routes by host. Wildcard certs (*.example.com) cover many tenants with one cert; per-tenant subject-alternative-name certs are an alternative when wildcards are not desirable.

Health checks are per target group, not per host. Each tenant target group has its own health check tuned to that tenant’s deployment.

Protocols

  • HTTP — plain text health check; the most common.
  • HTTPS — useful when the target only listens on HTTPS. ALB does not validate the target’s certificate (which would be a chicken-and-egg problem with self-signed internal certs).
  • gRPC — health check uses the gRPC Health Checking Protocol (grpc.health.v1.Health/Check). Matcher uses gRPC status codes (0 = OK).

Connection draining (deregistration delay)

When a target is deregistered (scale-in, deploy, manual removal), the ALB stops sending new connections immediately and waits up to the deregistration delay for in-flight requests to complete before fully removing the target.

Default 300 s. Reduce for short-request services to speed up deploys; raise for long-polling, file uploads, or WebSocket-heavy traffic.

ECS rolling deployments rely on deregistration delay for graceful task replacement. If the delay is longer than the ECS stopTimeout, the task is killed mid-drain. The two settings need to be reconciled: ECS task stopTimeout should be at least the ALB deregistration delay plus a buffer for application graceful shutdown.

Diagnostic flow when targets go unhealthy

  1. ALB target group → check the target health view. The reason string is specific (Target.Timeout, Target.ResponseCodeMismatch, Target.FailedHealthChecks).
  2. From an instance in the same VPC, hit the target’s health path directly: curl http://TARGET_IP:PORT/healthz. This isolates ALB-vs-target.
  3. Security groups: ALB SG must be allowed inbound on the health check port of the target SG.
  4. Application logs: did the request arrive? Was the response code expected?
  5. NACLs and route tables for cross-subnet quirks. See Networking basics if needed.

See also

References

Graph View

Backlinks