ECS Task Definition: Production Fields, Best Practices

A task definition is the JSON blueprint ECS uses to launch containers — images, CPU/memory, networking, IAM, logging, secrets, health checks. The tutorial version hides the production details that distinguish a reliable deployment from a fragile one.

The fields that matter in production

Networking

• networkMode: awsvpc is mandatory for Fargate; each task gets its own ENI and Security Group

IAM — two roles, not one

• executionRoleArn: ECS agent uses this to pull ECR images, read secrets, write logs; standard shared role
• taskRoleArn: the application's IAM role for AWS SDK calls inside the container; per-service least privilege

Secrets — never env vars

• Use the secrets block referencing Secrets Manager or Parameter Store ARNs
• Env vars show up in ecs describe-tasks, CloudFormation state, APM traces, stack traces; secrets block keeps values hidden
• The executionRole needs permission to read the secret

Resources

• Fargate has fixed valid CPU/memory combos; mismatched values fail at launch
• ephemeralStorage defaults to 20GiB; raise to 30–200GiB if your app writes temp files
• Use ARM64 via runtimePlatform.cpuArchitecture: ARM64; Graviton is 20% cheaper for most Java workloads

Graceful shutdown

• stopTimeout: 30 means ECS sends SIGTERM, waits 30 seconds, then SIGKILL
• Spring Boot requires server.shutdown=graceful and spring.lifecycle.timeout-per-shutdown-phase=25s to drain connections on SIGTERM
• Without these, deploys drop in-flight requests

Health checks at two levels

• Container healthCheck: a command like curl the actuator health; ECS kills and restarts if it fails
• Service healthCheckGracePeriodSeconds: 120 gives Spring Boot time to boot before ALB starts probing
• Mismatched values kill healthy-but-still-booting tasks

Logging

• awslogs driver to CloudWatch Logs; always set retention (7 to 30 days) or costs are unbounded
• firelens for third-party (Datadog, Splunk); more flexibility, slight overhead

The service-level configuration

• minimumHealthyPercent: 100 plus maximumPercent: 200 gives zero-downtime rolling deploy — new tasks start before old are killed
• deploymentCircuitBreaker with rollback: true auto-rolls back stuck deployments
• Capacity providers: 25% FARGATE + 75% FARGATE_SPOT for 70% Spot discount on non-critical workloads

The JVM detail most teams miss

• Without -XX:MaxRAMPercentage=75, the JVM may not respect container memory limits
• Heap grows until OOMKill
• Always pass JAVA_OPTS with MaxRAMPercentage and UseG1GC

Operational discipline

• Never edit task definitions in the console; always Terraform, CDK, or CloudFormation
• Pin image tags to immutable SHAs or explicit versions, never :latest
• Enable enableExecuteCommand for ECS Exec debugging into running containers via SSM
• Service Connect is worth evaluating for new multi-service architectures — lower cost than internal ALBs, built-in retries and client-side load balancing

The strategic answer

• Task definition reviews are a critical gate; a malformed task def causes real outages
• Standardize via Terraform modules or CDK constructs so every service inherits good defaults
• Audit existing task defs for: env var secrets, missing stopTimeout, missing circuit breaker, log retention, health check grace period, JVM memory settings