Terraform – Deploying a Spring Boot API to ECS Fargate

resource "aws_ecr_repository" "this" {
  name = var.name_prefix

  # Pushing :abc123 twice becomes an error rather than silently moving the tag.
  # It is what makes "which image is running?" a question with an answer.
  image_tag_mutability = "IMMUTABLE"

  image_scanning_configuration {
    scan_on_push = true
  }

  # So `terraform destroy` works. Default is false, and ECR refuses to delete a
  # repository that still has images in it — which it always will by then.
  force_delete = true
}

resource "aws_ecr_lifecycle_policy" "this" {
  repository = aws_ecr_repository.this.name

  policy = jsonencode({
    rules = [{
      rulePriority = 1
      description  = "Expire untagged images after 1 day"
      selection = {
        tagStatus   = "untagged"
        countType   = "sinceImagePushed"
        countUnit   = "days"
        countNumber = 1
      }
      action = { type = "expire" }
    }]
  })
}

# 1. the registry alone. One of the few legitimate uses of -target, which
#    Terraform warns about and is right to.
terraform apply -target=module.service.aws_ecr_repository.this

# 2. build and push
SHA=$(git rev-parse --short HEAD)
aws ecr get-login-password --region us-west-2 \
  | docker login --username AWS --password-stdin 329580012644.dkr.ecr.us-west-2.amazonaws.com
docker buildx build --platform linux/arm64 \
  -t 329580012644.dkr.ecr.us-west-2.amazonaws.com/pizza-tf:$SHA --push .

# 3. everything else
terraform apply -var "image_tag=$SHA"

exec /usr/bin/java: exec format error

resource "aws_ecs_task_definition" "this" {
  family = var.name_prefix

  requires_compatibilities = ["FARGATE"]
  network_mode             = "awsvpc"
  cpu                      = "512"     # 0.5 vCPU
  memory                   = "1024"    # valid pairings are fixed: 512 CPU allows 1024-4096

  runtime_platform {
    cpu_architecture        = "ARM64"
    operating_system_family = "LINUX"
  }

  # The full container definition is below; this much is enough to plan.
  container_definitions = jsonencode([{
    name      = "api"
    image     = "example:latest"
    essential = true
  }])
}

$ docker buildx build --platform linux/amd64 ...

tar: apache-maven-3.9.16/lib/asm-9.9.1.jar: Cannot open: Function not implemented
tar: Exiting with failure status due to previous errors
ERROR: failed to solve: process "/bin/sh -c ./mvnw -B clean package -DskipTests"
       did not complete successfully: exit code: 1

data "aws_iam_policy_document" "ecs_assume" {
  statement {
    actions = ["sts:AssumeRole"]
    principals {
      type        = "Service"
      identifiers = ["ecs-tasks.amazonaws.com"]
    }
  }
}

resource "aws_iam_role" "execution" {
  name               = "${var.name_prefix}-execution"
  assume_role_policy = data.aws_iam_policy_document.ecs_assume.json
}

resource "aws_iam_role" "task" {
  name               = "${var.name_prefix}-task"
  assume_role_policy = data.aws_iam_policy_document.ecs_assume.json
}

execution role   assumed by the ECS AGENT, BEFORE your container starts.
                 pulls the image, fetches secrets, creates log streams.

task role        assumed by YOUR CODE, once running. what the AWS SDK
                 inside the application picks up.

resource "aws_iam_role_policy_attachment" "execution_managed" {
  role       = aws_iam_role.execution.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
}

# ⚠️ Its absence is one of the most confusing ECS failures there is: the task
# stops during provisioning with ResourceInitializationError and the application
# logs are EMPTY, because the container never started.
data "aws_iam_policy_document" "execution_secrets" {
  statement {
    actions = ["secretsmanager:GetSecretValue"]
    resources = [
      aws_secretsmanager_secret.jwt.arn,
      var.db_secret_arn,
    ]
  }
}

resource "random_password" "jwt" {
  length = 64

  # No punctuation. The value reaches the app through an environment variable,
  # and a shell-quoting bug anywhere along the way turns a $ or a ` into a silent
  # truncation. 64 alphanumeric characters is ~380 bits.
  special = false
}

resource "aws_secretsmanager_secret" "jwt" {
  name = "${var.name_prefix}/jwt-secret"

  # ⚠️ Secrets Manager SCHEDULES deletion, with a 30-day recovery window by
  # default. A destroy followed by an apply then fails with "already scheduled
  # for deletion", because the name is still taken. Zero forces it immediately,
  # which is what a stack that gets torn down and rebuilt needs.
  recovery_window_in_days = 0
}

locals {
  container = [{
    name      = "api"
    image     = "${aws_ecr_repository.this.repository_url}:${var.image_tag}"
    essential = true

    portMappings = [{ containerPort = 8085, protocol = "tcp" }]

    # Visible to anyone who can call DescribeTaskDefinition. Nothing secret here.
    environment = [
      # Deliberately NOT "local": application.properties defaults to the `local`
      # profile, whose properties file is GITIGNORED — so it is present in an
      # image built on a laptop and absent from one built in CI. That difference
      # is invisible until the two images behave differently.
      { name = "SPRING_PROFILES_ACTIVE", value = "aws" },
      { name = "SERVER_PORT", value = "8085" },
    ]

    # Resolved by the ECS AGENT before the container starts, using the execution
    # role, and injected as environment variables. The values never appear in the
    # task definition, in state, or in the console.
    #
    # The `:key::` suffix selects one field out of a JSON secret — RDS stores its
    # managed password as {"username":…,"password":…}, so without it the app would
    # receive the whole JSON document as its password. The two trailing colons are
    # version-stage and version-id, left empty to mean "current", and are required
    # even when empty.
    secrets = [
      { name = "SPRING_DATASOURCE_USERNAME", valueFrom = "${var.db_secret_arn}:username::" },
      { name = "SPRING_DATASOURCE_PASSWORD", valueFrom = "${var.db_secret_arn}:password::" },
      { name = "PIZZA_JWT_SECRET", valueFrom = aws_secretsmanager_secret.jwt.arn },
    ]

    logConfiguration = {
      logDriver = "awslogs"
      options = {
        "awslogs-group"         = aws_cloudwatch_log_group.this.name
        "awslogs-region"        = data.aws_region.current.region
        "awslogs-stream-prefix" = "ecs"
      }
    }
  }]
}

GET /actuator/health  ->  503  {"status":"DOWN"}

  jms            DOWN   jakarta.jms.JMSException: Failed to create session factory
  elasticsearch  UP     ... only because another container happened to be on :9200
  diskSpace      UP

management.endpoints.web.exposure.include=health
management.endpoint.health.show-details=never

# `ping` is UP whenever the context is serving — exactly the question a load
# balancer is asking. Disabling the failing indicators one at a time instead
# would work today and break the next time somebody adds a starter.
management.endpoint.health.group.alb.include=ping

.requestMatchers("/actuator/health", "/actuator/health/**")
.permitAll()

resource "aws_lb_target_group" "this" {
  name     = var.name_prefix
  port     = 8085
  protocol = "HTTP"
  vpc_id   = var.vpc_id

  # ⚠️ "ip", not "instance". Fargate tasks use awsvpc networking and each gets
  # its own ENI and private IP — there is no EC2 instance to register. With
  # "instance" the service fails to register targets at all.
  target_type = "ip"

  health_check {
    enabled             = true
    path                = "/actuator/health/alb"
    matcher             = "200"
    interval            = 30
    timeout             = 5
    healthy_threshold   = 2
    unhealthy_threshold = 3
  }

  # The default is 300s, which makes every deploy five minutes longer than it
  # needs to be. This is how long the ALB waits for in-flight requests before
  # removing a draining target.
  deregistration_delay = 30
}

resource "aws_ecs_service" "this" {
  name            = var.name_prefix
  cluster         = aws_ecs_cluster.this.id
  task_definition = aws_ecs_task_definition.this.arn
  desired_count   = 1
  launch_type     = "FARGATE"

  network_configuration {
    subnets         = var.private_subnet_ids
    security_groups = [var.app_security_group_id]

    # false, because the tasks are in private subnets and reach the internet
    # through the NAT gateway. Setting this true in a private subnet does NOT
    # help — there is no internet gateway route — and it is a common wrong fix
    # for "cannot pull image", whose real cause is missing routing.
    assign_public_ip = false
  }

  load_balancer {
    target_group_arn = aws_lb_target_group.this.arn
    container_name   = "api"
    container_port   = 8085
  }

  # How long ECS waits before honouring the ALB health check at all. A Spring
  # Boot app running Liquibase migrations needs well over the 0-second default,
  # and without it the service kills each task just before it finishes booting.
  health_check_grace_period_seconds = 180

  # ⚠️ Without this, apply races IAM. ECS validates that it can assume the
  # execution role at service-creation time, and IAM is eventually consistent —
  # a role created moments earlier may not be visible yet. Terraform sees no
  # dependency because the service references the role only indirectly.
  depends_on = [
    aws_lb_listener.http,
    aws_iam_role_policy_attachment.execution_managed,
  ]
}

[1] initial   Elb.RegistrationInProgress
[2] draining  Target.DeregistrationInProgress
[3] draining  Target.DeregistrationInProgress
[4] initial   Elb.RegistrationInProgress
...

aws ecs list-tasks --cluster pizza-tf --desired-status STOPPED
aws ecs describe-tasks --cluster pizza-tf --tasks <arn> \
  --query 'tasks[0].{stopped:stoppedReason,code:stopCode,exit:containers[0].exitCode}'

{ "stopped": "Essential container in task exited",
  "code": "EssentialContainerExited",
  "exit": 1 }

APPLICATION FAILED TO START

Property: pizza.cors.allowedOrigins
Value: "[]"
Reason: must not be empty

locals {
  # Non-empty by construction: fall back to the load balancer's own hostname.
  cors_origin = var.cors_allowed_origins != "" ? var.cors_allowed_origins : "http://${aws_lb.this.dns_name}"
}

1. describe-services  -> events. usually unhelpful, but free.
2. describe-tasks     -> stopCode and exitCode. THIS narrows it:
                         ResourceInitializationError  = secrets/IAM/networking
                         CannotPullContainerError     = ECR access or routing
                         EssentialContainerExited + 1 = your app failed to start
3. CloudWatch logs    -> the actual reason. always.

$ curl "$(terraform output -raw app_url)/actuator/health/alb"
{"status":"UP"}

$ curl "$(terraform output -raw app_url)/api/products" | jq 'length'
14

$ curl -o /dev/null -w '%{http_code}\n' "$(terraform output -raw app_url)/api/admin/users"
403

terraform destroy

aws rds describe-db-instances --db-instance-identifier pizza-tf-mysql   # NotFound
aws ec2 describe-nat-gateways --filter Name=state,Values=available --query 'length(NatGateways)'
aws elbv2 describe-load-balancers --query "length(LoadBalancers[?starts_with(LoadBalancerName,'pizza-tf')])"