Express Gateway Service

Overview

The Express Gateway Service Express Gateway Service
The aws_ecs_express_gateway_service Terraform resource that provisions an ECS service with managed ALB, auto scaling, and simplified configuration for HTTP/HTTPS web applications and APIs. is the core Terraform resource. It replaces the typical combination of aws_ecs_service, aws_lb, aws_lb_target_group, and aws_lb_listener with a single resource.

Note

The complete resource definition below is from the terraform-aws-ecs-express-mode-demo source repository.

main.tf

resource "aws_ecs_express_gateway_service" "this" {
  service_name            = "${var.prefix}-service"
  cluster                 = aws_ecs_cluster.this.arn
  task_definition         = aws_ecs_task_definition.this.arn
  infrastructure_role_arn = aws_iam_role.infrastructure.arn
  desired_count           = 1

  primary_container {
    container_name    = "${var.prefix}-container"
    container_port    = 8000
    health_check_path = "/health"
  }

  network_configuration {
    subnets         = aws_subnet.public[*].id
    security_groups = [aws_security_group.web.id]
    access_type     = "PUBLIC"
  }

  scaling_target {
    auto_scaling_metric       = "CPU"
    auto_scaling_target_value = 70
    min_task_count            = 1
    max_task_count            = 4
  }
}

Primary Container

Defines how the managed ALB Shared ALB
The Application Load Balancer shared by up to 25 Express services in the same VPC using Host header routing rules. routes traffic to your application:

main.tf

primary_container {
  container_name    = "${var.prefix}-container"
  container_port    = 8000
  health_check_path = "/health"
}

Parameter	Description
container_name	Must match the name field in the task definition’s container definitions
container_port	Port the container listens on — ALB forwards traffic here
health_check_path	HTTP path the ALB uses to verify the container is healthy

Caution

A mismatch between container_port and the application’s actual listen port is the most common cause of health check failures and rollback loops.

Network Configuration

Determines where tasks run and how the ALB is provisioned:

main.tf

network_configuration {
  subnets         = aws_subnet.public[*].id
  security_groups = [aws_security_group.web.id]
  access_type     = "PUBLIC"
}

Parameter	Description
subnets	Single list for both ALB and task placement — no split supported
security_groups	Must allow ingress on container_port from the VPC VPC Virtual Private Cloud — an isolated virtual network within AWS where resources are deployed. CIDR CIDR Block Classless Inter-Domain Routing notation specifying an IP address range for a VPC or subnet.
access_type	PUBLIC = internet-facing ALB; PRIVATE = internal ALB

Scaling Target

Configures auto scaling so the service adjusts capacity based on load:

main.tf

scaling_target {
  auto_scaling_metric       = "CPU"
  auto_scaling_target_value = 70
  min_task_count            = 1
  max_task_count            = 4
}

Parameter	Description
auto_scaling_metric	Metric for target tracking — CPU or Memory
auto_scaling_target_value	Target percentage — scales out when exceeded
min_task_count	Minimum running tasks — never scales below this
max_task_count	Maximum running tasks — ceiling for scale-out

Tip

The scaling target is built into the resource — no separate aws_appautoscaling_target or policy resources needed.

Top-Level Parameters

Parameter	Description
service_name	Immutable after creation — changing requires service replacement
cluster	ARN of the ECS cluster
task_definition	ARN of the task definition describing the container(s)
infrastructure_role_arn	Infrastructure Role Infrastructure Role An IAM role assumed by ecs.amazonaws.com that grants ECS Express Mode permissions to provision ALB, networking, and auto scaling resources. granting ECS permission to provision ALB and scaling
desired_count	Initial task count — auto scaling adjusts this between min and max