ECS Deployments, Scaling and Networking

On Fargate every task uses the awsvpc network mode (EC2 and Managed Instances tasks should use it too): each task gets its own elastic network interface (ENI) and a private IP address from the subnet it is placed in, and its own security group. The task is a first-class VPC citizen, so security group rules, VPC Flow Logs and route tables apply to a single task rather than to a shared host. The consequences that matter in practice:

A service registers its tasks with an Application Load Balancer target group of type ip, because each awsvpc task is an IP address rather than an instance. ECS adds a task to the target group when it starts and removes it (with connection draining) when it stops; the load balancer, not ECS, decides when traffic reaches it. Settings worth getting right:

Listener, rule and TLS configuration, and the load-balancer decision tree, are in Load Balancers and Gateways; the target group used here was created with the service in ECS and Fargate. To tune the target group:

See modify-target-group, modify-target-group-attributes and Use load balancing to distribute Amazon ECS service traffic.

A deployment, a scale-in or a Spot interruption all end the same way: ECS sends SIGTERM to the container’s main process, waits up to stopTimeout seconds, then sends SIGKILL. The default is 30 seconds and Fargate allows at most 120 seconds. A task that ignores SIGTERM drops its in-flight requests, so make the application finish them first.

For Spring Boot, enable graceful shutdown and keep the shutdown phase shorter than stopTimeout and than the deregistration delay budget:

and in the container definition set "stopTimeout": 35. Run the application as PID 1 (an exec form ENTRYPOINT, not a shell wrapper) so it actually receives the signal; if it cannot be PID 1, set linuxParameters.initProcessEnabled to true. The Spring-side details are in Metrics and Observability: Micrometer, Actuator, and Distributed Tracing.

ECS has two health-check layers and both can replace a task. A container health check (healthCheck in the container definition: a command run inside the container, with interval, timeout, retries and startPeriod) marks the task unhealthy and ECS replaces it. The load balancer health check removes it from rotation, and when healthCheckGracePeriodSeconds has passed ECS also replaces it. Use the container check for "the process is wedged", the ALB check for "this instance cannot serve requests".

See the task definition parameters reference.

An Amazon ECS service replaces its tasks with a new service revision whenever the task definition, the image or the configuration changes. The strategy decides how the old (blue) and new (green) revisions overlap. Older guides and tutorials show only rolling updates and a CodeDeploy-driven blue/green; the current options are built into ECS itself:

The three traffic-shifting strategies need an Application Load Balancer, a Network Load Balancer or Service Connect to manage the shift; a service with none of them (a headless worker) can still use them, but ECS then replaces the tasks without managing any traffic. They also temporarily run both revisions, so budget roughly double the task count (and subnet IPs) during a deployment.

ECS scales the number of tasks (the service’s desired count) through Application Auto Scaling: you register the service as a scalable target with a minimum and a maximum, then attach scaling policies. ECS publishes the service metrics ECSServiceAverageCPUUtilization and ECSServiceAverageMemoryUtilization, and the ALB provides ALBRequestCountPerTarget. Scaling and deployments interact: while a deployment is in progress, scale-in is disabled and scale-out continues, so a deploy never removes tasks under load.

Target tracking aims at keeping the metric at the target; it scales in only after the metric has been well below the target for a sustained period, and the scale-out cooldown and scale-in cooldown seconds stop it reacting to every spike. A minimum capacity of 0 lets a service scale to zero. Choose a minimum of at least two for a production service so it spans two Availability Zones. Application Auto Scaling needs a service-linked role, created automatically the first time you register a target.

Bookshelf’s orders-api needs to call catalog-api for book details. There are three ways to do that on ECS, and they are not interchangeable:

Service Connect is the recommended default for ECS-to-ECS calls. A task definition names the port it exposes, and each service joins the namespace and says what it publishes (a client-server service) or only consumes (a client service):

The port name and appProtocol are required for Service Connect; appProtocol of http or http2 or grpc also turns on request-level metrics instead of connection-level ones.

A capacity provider tells ECS where tasks run. Fargate and Fargate Spot are available on every cluster; you can add Auto Scaling group capacity providers for self-managed EC2 and ECS Managed Instances capacity providers, where AWS runs and patches EC2 instances for you. A service’s capacity provider strategy combines them with two numbers: base is the number of tasks that go to a provider first (only one provider in a strategy can have a base), and weight is the relative share of the rest. The strategy is the recommended way to choose capacity; the older launch type should only be used to declare what a task definition is compatible with.

Fargate Spot runs the same tasks at a discount on spare capacity that AWS can reclaim. When it does, ECS sends SIGTERM and the task has two minutes of warning (bounded by its stopTimeout) to drain. It suits stateless, retry-safe work: batch tasks, queue workers and the non-base capacity of a web service. A strategy that keeps a base on regular Fargate gives you the saving without making the service’s availability depend on Spot. Fargate Spot is not available for every platform configuration (for example Windows tasks), so check the guide.

Configuration reaches the container at task start. The environment list injects plain values; the secrets list injects values that the task execution role fetches from Secrets Manager or Systems Manager Parameter Store before the container starts:

The values are resolved once, when the task starts. After a secret is rotated or a parameter changes, running tasks keep the old value until you deploy a new task or force one with update-service --force-new-deployment. For values that must refresh without a restart, read them in the application with the task role instead; the execution role, task role and exact key syntax are in Secrets Manager, Parameter Store and KMS and Runtime Configuration.

For storage, a Fargate task gets 20 GiB of ephemeral storage by default (configurable up to 200 GiB with ephemeralStorage.sizeInGiB) that disappears with the task. For data that must outlive tasks or be shared between them, mount an Amazon EFS file system through a task definition volumes entry with efsVolumeConfiguration and mountPoints; see Block and File Storage on AWS and Use Amazon EFS volumes with Amazon ECS.

ECS Exec opens an interactive shell or runs one command inside a running container without SSH, open inbound ports or a bastion host. It uses AWS Systems Manager Session Manager: the ECS agent starts a managed SSM agent in the task, the task role authorizes the channel, and every session is auditable in CloudTrail and optionally logged to CloudWatch Logs or S3. Commands run as root in the container; the root filesystem must be writable, and sessions idle out after 20 minutes. ECS Exec cannot be turned on for tasks that are already running, only for new ones.

The task role (not the execution role) needs the Session Manager channel permissions:

People who may run it need ecs:ExecuteCommand and ecs:DescribeTasks, ideally restricted by tag or cluster with the ecs:ResourceTag or ecs:cluster condition keys, and a separate deny on ssm:StartSession for the cluster’s tasks so that sessions cannot bypass the ECS Exec logging.

Not everything is a long-running service. A standalone task runs once to completion and is billed only while it runs: a database migration, a nightly report, or the Bookshelf catalogue re-index. Run it by hand with run-task or start it from a schedule or an event.

See run-task and the scheduled tasks guide. For a recurring run use Amazon EventBridge Scheduler, which supports cron, rate and one-time schedules, time zones and retries and has a native ECS target; the older EventBridge rule with a schedule expression still works but Scheduler is the current choice.

A pipeline deploys by registering a new task definition revision with the new image and updating the service. With the Docker and GitHub Actions basics in Docker CI/CD with GitHub Actions and the OIDC role from Identity and Access, the ECS-specific steps are:

See the render and deploy action repositories. With the built-in strategies the action simply updates the service and ECS performs the blue/green, canary or linear shift; wait-for-service-stability then waits for the whole deployment, including the bake time. A deploy role that can do only this, and nothing more, looks like this:

The iam:PassRole statement is the one people forget: a service update that changes the task definition passes the task and execution roles to ECS, and the condition stops the deploy role from passing them to any other service. A service using the blue/green strategies also needs iam:PassRole on the infrastructure and hook roles if the deploy changes them. See Container Registry for the repository side of the pipeline.

ECS exposes health at three levels, and an alarm at each keeps a deployment honest:

See update-cluster-settings, put-metric-alarm, events put-rule and Monitor Amazon ECS using CloudWatch. Alarm destinations, dashboards and tracing are in Monitoring and Observability; the Spring Boot side is in Metrics and Observability: Micrometer, Actuator, and Distributed Tracing.

Nothing on this page adds a charge of its own beyond the capacity it uses. Check the Amazon ECS pricing and AWS Fargate pricing pages for current rates; this page deliberately quotes none.

Quotas (tasks per service, services per cluster, Fargate task and vCPU concurrency, ENIs, Service Connect namespaces and services, ALB targets and rules) are adjustable in Service Quotas and listed in the ECS service quotas page. Hitting the Fargate vCPU or concurrency quota during a blue/green deployment (which temporarily doubles the tasks) is a classic cause of a stuck deployment.

Start with the service’s Events tab (or describe-services) and the stopped task’s Stopped reason. Then:

See describe-services, describe-tasks and Troubleshooting Amazon ECS.

Remove what this page created, in dependency order, so nothing keeps billing: the scheduled and scaling resources, the service (scaled to zero first), then the load balancer pieces, networking and roles that exist only for the demo.

The Service Connect namespace can only be deleted after every service that uses it is gone. Delete the green and blue target groups, listeners and the ALB (see Load Balancers and Gateways) if they were created for this exercise only. See delete-service and application-autoscaling.