Amazon Elastic Container Services (ECS) : Express Mode and Custom Mode for Receipt Extraction

Hello everyone. I want to continue writing about receipt extraction application. In this blog tutorial, I want to create API on Amazon Elastic Container Services (ECS) using ECR receipt extraction image that already created before. Amazon ECS is a fully managed container orchestration service that build, manage, and run container without the complexity of infrastructure management.

REQUIREMENTS :

1. Amazon SageMaker AI blog tutorial, you can see this link
2. AWS account, you can sign up/sign in here
3. Make sure Terraform already installed. Terraform AWS provider for Infrastructure as Code, you can see this link
4. (Optional) Streamlit for UI / front-end, you can see this link

EXPRESS MODE :

ECS Express Mode using Amazon ECR private/public image (primary_container), IAM execution role/AmazonECSTaskExecutionRolePolicy and IAM infrastructure role/AmazonECSInfrastructureRoleforExpressGatewayServices only.

Additional configuration is optional such as IAM task role because I use IAM task role to invoke SageMaker endpoint only. If you don't use a custom VPC, ECS express mode automatically use default VPC. I using a custom VPC because want more control over the networking side.

Create Terraform files such as iam.tf, main.tf, vpc.tf and ecs.tf in ONE folder (available on GitHub). The AWS console is only for viewing the results of this process.

This is ecs.tf file for creating ECS cluster and ECS service express mode.

# Create ECS Cluster
resource "aws_ecs_cluster" "fastapiecs" {
  name = "fastapiecs"
}

# Create ECS Express Service that linked with receipt extraction ECR image
resource "aws_ecs_express_gateway_service" "fastapi" {
  cluster                 = aws_ecs_cluster.fastapiecs.name
  execution_role_arn      = aws_iam_role.execution.arn
  infrastructure_role_arn = aws_iam_role.infrastructure.arn
  task_role_arn           = aws_iam_role.task.arn
  health_check_path       = "/health"
  cpu                     = "256"
  memory                  = "512"
  region                  = data.aws_region.current.region

  primary_container {
    image          = "${local.account_id}.dkr.ecr.${local.region}.amazonaws.com/receipt-extraction-gemma-4:latest"
    container_port = 8000
  }

  network_configuration {
    subnets         = aws_subnet.public[*].id
    security_groups = [aws_security_group.alb_sg.id]
  }

  scaling_target {
    auto_scaling_metric       = "AVERAGE_CPU"
    auto_scaling_target_value = 70
    min_task_count            = 1
    max_task_count            = 3
  }
}

Terraform ecs.tf file explanation :

• execution_role_arn, infrastructure_role_arn and task_role_arn to get IAM role ARN from iam.tf

• health_check_path to check the health of ECR image API.

• container_port for ECR image API container port.

• network_configuration for configure networking such as subnet and security group in Amazon VPC.

• scaling_target for minimum and maximum auto-scaling usage based on CPU average.

This is iam.tf file for creating IAM roles for ECS express mode.

data "aws_caller_identity" "current" {}
data "aws_region" "current" {}

# Get AWS Account ID and AWS Region from above data
locals {
  account_id = data.aws_caller_identity.current.account_id
  region     = data.aws_region.current.region
}

# ECS Express Infrastructure Role
resource "aws_iam_role" "infrastructure" {
  name               = "ecsExpressInfrastructureRole"
  assume_role_policy = jsonencode({
    Version   = "2012-10-17"
    Statement = [
      {
        Effect    = "Allow"
        Principal = {
          Service = "ecs.amazonaws.com"
        }
        Action    = "sts:AssumeRole"
      }
    ]
  })
}

# ECS Express Infrastructure Policy
resource "aws_iam_role_policy_attachment" "infrastructure" {
  role       = aws_iam_role.infrastructure.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSInfrastructureRoleforExpressGatewayServices"
}

# ECS Express Execution Role
resource "aws_iam_role" "execution" {
  name               = "ecsExpressExecutionRole"
  assume_role_policy = jsonencode({
    Version   = "2012-10-17"
    Statement = [
      {
        Effect    = "Allow"
        Principal = {
          Service = "ecs-tasks.amazonaws.com"
        }
        Action    = "sts:AssumeRole"
      }
    ]
  })
}

# ECS Express Execution Policy
resource "aws_iam_role_policy_attachment" "execution" {
  role       = aws_iam_role.execution.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
}

# ECS Express Task Role
resource "aws_iam_role" "task" {
  name               = "ecsExpressTaskRole"
  assume_role_policy = jsonencode({
    Version   = "2012-10-17"
    Statement = [
      {
        Effect    = "Allow"
        Principal = {
          Service = "ecs-tasks.amazonaws.com"
        }
        Action    = "sts:AssumeRole"
      }
    ]
  })
}

# ECS Express Task Policy for SageMaker Endpoint
resource "aws_iam_role_policy" "sagemaker" {
  name   = "ecsExpressSagemaker"
  role   = aws_iam_role.task.name
  policy = jsonencode({
    Version   = "2012-10-17"
    Statement = [
      {
        Effect   = "Allow"
        Action   = [
            "sagemaker:InvokeEndpoint"
        ]
        Resource = "arn:aws:sagemaker:${local.region}:${local.account_id}:endpoint/*"
      }
    ]
  })
}

Terraform iam.tf file explanation :

• data "current" {} to get the AWS account ID and AWS region.

• resource "aws_iam_role" "infrastructure" to create IAM infrastructure role.

• resource "aws_iam_role_policy_attachment" "infrastructure" to create IAM infrastructure policy for creating load balancer, target group and etc.

• resource "aws_iam_role" "execution" to create IAM execution role.

• resource "aws_iam_role_policy_attachment" "execution" to create IAM execution policy for get ECR image, create CloudWatch logs and etc.

• resource "aws_iam_role" "task" to create IAM task role.

• resource "aws_iam_role_policy" "sagemaker" to create IAM task policy for invoke SageMaker endpoint.

This is main.tf file for define Terraform AWS provider version and AWS region.

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "6.45.0"
    }
  }
}

provider "aws" {
  region = "us-west-2"
}

This is vpc.tf file for creating VPC resources such as public subnet, private subnet, internet gateway, route table and security group.

data "aws_availability_zones" "available" {}

resource "aws_vpc" "main" {
  cidr_block           = "10.0.0.0/16"
  enable_dns_support   = true
  enable_dns_hostnames = true

  tags = {
    Name = "ecs-express-vpc"
  }
}

resource "aws_internet_gateway" "igw" {
  vpc_id = aws_vpc.main.id
}

resource "aws_subnet" "public" {
  count                   = 2
  vpc_id                  = aws_vpc.main.id
  cidr_block              = "10.0.${count.index + 10}.0/24"
  availability_zone       = data.aws_availability_zones.available.names[count.index]
  map_public_ip_on_launch = true
  tags = {
      Name = "express-mode-public-subnet-${count.index}"
  }
}

resource "aws_subnet" "private" {
  count                   = 2
  vpc_id                  = aws_vpc.main.id
  cidr_block              = "10.0.${count.index}.0/24"
  availability_zone       = data.aws_availability_zones.available.names[count.index]
  map_public_ip_on_launch = false
  tags = {
      Name = "express-mode-private-subnet-${count.index}"
  }
}

resource "aws_route_table" "public" {
  vpc_id = aws_vpc.main.id

  route {
    cidr_block = "0.0.0.0/0"
    gateway_id = aws_internet_gateway.igw.id
  }
}

resource "aws_route_table_association" "public" {
  count          = 2
  subnet_id      = aws_subnet.public[count.index].id
  route_table_id = aws_route_table.public.id
}

resource "aws_route_table" "private" {
  vpc_id = aws_vpc.main.id
}

resource "aws_route_table_association" "private" {
  count          = 2
  subnet_id      = aws_subnet.private[count.index].id
  route_table_id = aws_route_table.private.id
}

resource "aws_security_group" "alb_sg" {
  name   = "alb-sg"
  vpc_id = aws_vpc.main.id

  ingress {
    from_port   = 80
    to_port     = 80
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  ingress {
    from_port   = 443
    to_port     = 443
    protocol    = "tcp"
    cidr_blocks = ["0.0.0.0/0"]
  }

  egress {
    from_port   = 0
    to_port     = 0
    protocol    = "-1"
    cidr_blocks = ["0.0.0.0/0"]
  }
}

After 4 Terraform files is available, write and run this Terraform script.

terraform init

terraform init is initialize Terraform latest version in main.tf

terraform plan

terraform plan is check make sure your Terraform file is true and right format. If false and wrong format, you must check your Terraform file again.

terraform apply --auto-approve

terraform apply is apply/create all AWS service resources based all Terraform file. If not write --auto-approve, you must write/enter "yes" every want to apply Terraform file.

Wait until ECS services express mode to become available. The results of this Terraform process can see in AWS console like this screenshots.

I copy and use ECS express service application URL, try test predict API using FastAPI/Streamlit and this is worked. I copy and use public load balancer URL, try test predict API also using FastAPI/Streamlit and this is not worked also load balancer can not be used.

Then I tried using a private subnet and a public load balancer to make the ECS express service application URL private (can't connected to the internet) and using the public load balancer URL. However, both were private and inaccessible. To fix this issue, I choose ECS custom mode.

If you provide custom public subnets, Express Mode will provision an internet-facing ALB and turn on assignPublicIP for your tasks. If you provide private subnets (subnets without an internet gateway in their route table), Express Mode will provision an internal ALB. (from ECS express mode documentation)

If want to delete ECS express mode, write and run this Terraform script.

terraform destroy --auto-approve

terraform destroy is destroy/delete all AWS service resources based all Terraform file. If not write --auto-approve, you must write/enter "yes" every want to apply Terraform file.

CUSTOM MODE :

Create Terraform files such as iam.tf, main.tf, vpc.tf, ecs.tf, load-balancer.tf, security-groups.tf and vpc-endpoint.tf in ONE folder (available on GitHub). The AWS console is only for viewing the results of this process but some screenshots is same results, I uploaded some different screenshots.

I copy and use ECS express service application URL, try test predict API using FastAPI/Streamlit and this is failed because private-subnet based that no need connected to internet. I copy and use public load balancer URL, try test predict API also using FastAPI/Streamlit and this is worked means load balancer can be used.

CONCLUSION :

• ECS express mode is used to build web application and API faster.
• ECS custom mode is used for custom use case such as private subnet and public load balancer.

DOCUMENTATION :

• ECS Express Mode documentation
• ECS Custom Mode documentation
• Terraform AWS (Amazon ECS) documentation

Thank you,
Budi.