ALB Port Configuration: Listener Port, Target Group Port, and Per-Instance Port Overrides

Four port settings and what they each control

An ALB involves four distinct port settings:

1. Listener port: the port the ALB listens on for incoming client traffic (typically 80 and 443)
2. Target group port: the default port ALB forwards traffic to, used when a target doesn't specify its own port
3. Target instance port: the specific port ALB uses for a particular registered target (overrides target group port)
4. Health check port: the port used for health check requests (defaults to target's traffic port)

Static port configuration (most common)

When all targets in a target group use the same port (a typical setup):

resource "aws_lb_target_group" "api" {
  name        = "api"
  port        = 8080      # all targets use port 8080
  protocol    = "HTTP"
  vpc_id      = aws_vpc.main.id
  target_type = "instance"

  health_check {
    port = "traffic-port"  # health check on the same port as traffic (8080)
    path = "/health"
  }
}

resource "aws_lb_target_group_attachment" "api_1" {
  target_group_arn = aws_lb_target_group.api.arn
  target_id        = aws_instance.api_1.id
  # No port specified → uses target group default port (8080)
}

resource "aws_lb_target_group_attachment" "api_2" {
  target_group_arn = aws_lb_target_group.api.arn
  target_id        = aws_instance.api_2.id
  # Same — uses 8080
}

Per-instance port override: running multiple containers per EC2 instance

When multiple containers run on the same EC2 instance (bridge network mode in ECS), each container gets a dynamically assigned host port. Registering all containers to the same target group requires per-instance port overrides:

EC2 instance (10.0.1.5):
  Container A: app port 8080 → host port 32768
  Container B: app port 8080 → host port 32769
  Container C: app port 8080 → host port 32770

All three register to the same target group with different ports:

Target group registration:
  Target: 10.0.1.5:32768
  Target: 10.0.1.5:32769
  Target: 10.0.1.5:32770

ECS handles this automatically when you configure the service with an ALB. The ECS agent registers task containers with the correct dynamic host port at task startup and deregisters at task shutdown.

resource "aws_lb_target_group" "api" {
  name        = "api"
  port        = 8080       # this value only matters if a target is registered without explicit port
  protocol    = "HTTP"
  vpc_id      = aws_vpc.main.id
  target_type = "instance"  # "ip" for awsvpc mode (Fargate, ECS with awsvpc)
}

# ECS service automatically handles target registration with dynamic ports
resource "aws_ecs_service" "api" {
  name            = "api"
  cluster         = aws_ecs_cluster.main.id
  task_definition = aws_ecs_task_definition.api.arn

  load_balancer {
    target_group_arn = aws_lb_target_group.api.arn
    container_name   = "api"
    container_port   = 8080  # container's port, not host port
  }
}

The container definition specifies containerPort: 8080 with no hostPort (or hostPort: 0), which causes ECS to assign a random host port. When the task starts, ECS registers the task with the ALB target group using the actual assigned host port.

resource "aws_lb_target_group" "api" {
  name        = "api"
  port        = 8080
  protocol    = "HTTP"
  vpc_id      = aws_vpc.main.id
  target_type = "ip"     # required for awsvpc/Fargate
}

Health check port configuration

The health check port defaults to traffic-port (same as where traffic goes). Override it if your health endpoint is on a different port than your traffic endpoint:

health_check {
  port     = "8081"    # health check on management port
  path     = "/health"
  protocol = "HTTP"

  # Traffic goes to port 8080, but health checks go to 8081
  # This keeps health check traffic separate from production traffic
}

Separate health check ports are useful when your application's management interface (metrics, health) is on a different port than the main application traffic. It also isolates health check traffic from production load.