ECS & Fargate via SDK Best Practices

Q: What is the single most important deployment setting?

The deployment circuit breaker with rollback: true. It detects a deployment whose tasks keep failing and automatically reverts to the last working revision instead of looping on a broken image.

Q: How do I stop the load balancer from killing slow tasks?

Set healthCheckGracePeriodSeconds above your worst-case cold start. ECS then ignores load balancer health checks during warm-up so a booting task is not deregistered before it can serve.

Q: What is the safest way to pass secrets to a container?

The secrets field referencing a Secrets Manager or SSM ARN via valueFrom. The value is injected at startup and never appears in the task definition, the API, or CloudTrail, unlike a plaintext env var.

Q: Which log driver should I use?

awslogs for most workloads - it ships stdout/stderr to a CloudWatch log group you name. Standardizing on it gives every service consistent, queryable logs without extra infrastructure.

Q: How do I delete a service cleanly?

Scale it to zero with UpdateService (desiredCount: 0), wait for it to stabilize, then call DeleteService. Deleting a service with running tasks is blocked, so drain first.

Q: How do I wait for a deployment or task instead of sleeping?

Use waiters: tasks_running/tasks_stopped for tasks and services_stable for deployments in boto3, or waitUntilTasksRunning/waitUntilServicesStable in SDK v3. They poll for you until the target state or a timeout.

ECS is forgiving to start with and unforgiving to run carelessly. An oversized task bills every second, a deployment with no safety net can loop on a broken image, a plaintext secret leaks into CloudTrail, and forgotten services quietly accrue cost.

Walk this list once now, then use it as a review checklist before shipping any code that registers, runs, deploys, or tears down ECS tasks and services.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: sizing and provisioning first, then deployment safety, networking, security, cost, and cleanup.
Check the boxes against your own code as a quick audit.
Revisit whenever you add a new service or move a workload to a new account, region, or cluster.

A - Task Sizing & Definitions

Pick a valid Fargate CPU/memory pair. Each CPU value permits only a specific memory range; an invalid pair is rejected at registration, so size deliberately.
Right-size to real usage plus headroom. Fargate bills per vCPU-second and GB-second, so an oversized task wastes money every second it runs.
Separate the execution role from the task role. The execution role pulls images, writes logs, and reads secrets; the task role is your app's least-privilege runtime identity.
Treat task definitions as immutable revisions. Never try to edit one; register a new revision and deploy that.
Set a container stop timeout you can meet. Handle SIGTERM and finish within stopTimeout so graceful stops actually complete.

# --- Python (boto3) ---
import boto3
 
ecs = boto3.client("ecs", region_name="us-east-1")
ecs.register_task_definition(
    family="api",
    requiresCompatibilities=["FARGATE"],
    networkMode="awsvpc",
    cpu="512", memory="1024",                       # valid Fargate pair
    executionRoleArn="arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
    taskRoleArn="arn:aws:iam::111122223333:role/apiTaskRole",  # least privilege
    containerDefinitions=[{
        "name": "api",
        "image": "111122223333.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0",
        "essential": True,
    }],
)

// --- TypeScript (AWS SDK v3) ---
import { ECSClient, RegisterTaskDefinitionCommand } from "@aws-sdk/client-ecs";
 
const ecs = new ECSClient({ region: "us-east-1" });
await ecs.send(new RegisterTaskDefinitionCommand({
  family: "api",
  requiresCompatibilities: ["FARGATE"],
  networkMode: "awsvpc",
  cpu: "512", memory: "1024",                       // valid Fargate pair
  executionRoleArn: "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
  taskRoleArn: "arn:aws:iam::111122223333:role/apiTaskRole",  // least privilege
  containerDefinitions: [{
    name: "api",
    image: "111122223333.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0",
    essential: true,
  }],
}));

B - Deployment Safety

Enable the deployment circuit breaker with rollback. A broken image otherwise loops forever launching crashing tasks; the breaker fails the deploy and reverts.
Set a health-check grace period. Give slow-starting tasks time to boot so the load balancer does not deregister them before they are ready.
Keep minimumHealthyPercent at 100 in production. A surge-style rollout never drops below current capacity; 0 risks an outage mid-deploy.
Wait for services to stabilize. Use the services_stable waiter (or poll rolloutState) so your pipeline sees a real pass or fail, not fire-and-forget.
Use forceNewDeployment for same-tag rebuilds. If the task definition did not change, force a redeploy to pick up a rebuilt image.

Deploy with the circuit breaker on and wait for the result.

# --- Python (boto3) ---
import boto3
 
ecs = boto3.client("ecs", region_name="us-east-1")
ecs.update_service(
    cluster="prod", service="api", taskDefinition="api:8",
    deploymentConfiguration={
        "minimumHealthyPercent": 100, "maximumPercent": 200,
        "deploymentCircuitBreaker": {"enable": True, "rollback": True},
    },
    healthCheckGracePeriodSeconds=60,
)
ecs.get_waiter("services_stable").wait(cluster="prod", services=["api"])

// --- TypeScript (AWS SDK v3) ---
import { ECSClient, UpdateServiceCommand, waitUntilServicesStable } from "@aws-sdk/client-ecs";
 
const ecs = new ECSClient({ region: "us-east-1" });
await ecs.send(new UpdateServiceCommand({
  cluster: "prod", service: "api", taskDefinition: "api:8",
  deploymentConfiguration: {
    minimumHealthyPercent: 100, maximumPercent: 200,
    deploymentCircuitBreaker: { enable: true, rollback: true },
  },
  healthCheckGracePeriodSeconds: 60,
}));
await waitUntilServicesStable({ client: ecs, maxWaitTime: 600 }, { cluster: "prod", services: ["api"] });

C - Networking & Discovery

Use ip target groups for Fargate. awsvpc networking gives each task its own IP; an instance target group cannot attach to a Fargate service.
Match containerName/containerPort to a port mapping. The load balancer config must reference a port the task definition actually exposes.
Prefer Cloud Map (or Service Connect) for internal calls. Let ECS keep DNS in sync with healthy task IPs instead of hardcoding addresses.
Open the container port to the load balancer only. Scope the task security group tightly; do not expose the port to the world.
Keep discovery DNS TTLs short. A short TTL lets clients pick up membership changes quickly after a deploy or scale event.

D - Security

Inject secrets, never plaintext env. Use the secrets field with a Secrets Manager or SSM ARN so values stay out of the task definition and CloudTrail.
Least-privilege the task role. Grant only the AWS actions the app truly needs; the task role is your runtime blast radius.
Enable ECS Exec deliberately, with logging. Turn on exec only when needed, put ssmmessages on the task role, and log sessions to CloudWatch or S3.
Scope the execution role to its job. It needs ECR pull, log write, and GetSecretValue for the specific secrets - nothing more.
Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) for support and correlation.

Reference secrets by ARN, never inline.

# --- Python (boto3) ---
container = {
    "name": "api",
    "image": "…/api:1.4.0",
    "essential": True,
    "secrets": [
        {"name": "DB_PASSWORD",
         "valueFrom": "arn:aws:secretsmanager:us-east-1:111122223333:secret:prod/db-AbCdEf"},
    ],
}

// --- TypeScript (AWS SDK v3) ---
const container = {
  name: "api",
  image: "…/api:1.4.0",
  essential: true,
  secrets: [
    { name: "DB_PASSWORD",
      valueFrom: "arn:aws:secretsmanager:us-east-1:111122223333:secret:prod/db-AbCdEf" },
  ],
};

E - Observability & Cost

Standardize on the awslogs driver. Ship every container's stdout/stderr to a named CloudWatch log group with a stream prefix.
Blend Fargate and Fargate Spot. A capacity provider strategy runs interruptible work on Spot at a large discount with a small on-demand base for resilience.
Auto scale services on real metrics. Application Auto Scaling target-tracking on CPU or request count matches capacity to demand instead of paying for idle tasks.
Wait on transitions with waiters. Use tasks_running/tasks_stopped and services_stable rather than hand-rolled sleeps.
Handle SIGTERM for Spot and deploys. Drain and checkpoint within two minutes so reclaimed or replaced tasks lose no in-flight work.

F - Cleanup & Hygiene

Scale a service to zero before deleting it. UpdateService with desiredCount: 0, then DeleteService, avoids a delete that is blocked by running tasks.
Delete empty clusters you no longer use. DeleteCluster after services and tasks are gone keeps the account tidy.
Deregister stale task definition revisions. Old revisions accumulate; deregister ones no service references to reduce clutter.
Tag clusters, services, and task definitions. A consistent tag schema (Environment, Owner, Cost-Center) makes cost allocation and cleanup possible.
Rely on built-in SDK retries. Both SDKs retry throttling and transient errors with backoff; tune max_attempts instead of reimplementing retries.

Scale to zero, then delete, so nothing blocks teardown.

# --- Python (boto3) ---
import boto3
 
ecs = boto3.client("ecs", region_name="us-east-1")
ecs.update_service(cluster="prod", service="api", desiredCount=0)
ecs.get_waiter("services_stable").wait(cluster="prod", services=["api"])
ecs.delete_service(cluster="prod", service="api")

// --- TypeScript (AWS SDK v3) ---
import { ECSClient, UpdateServiceCommand, waitUntilServicesStable, DeleteServiceCommand } from "@aws-sdk/client-ecs";
 
const ecs = new ECSClient({ region: "us-east-1" });
await ecs.send(new UpdateServiceCommand({ cluster: "prod", service: "api", desiredCount: 0 }));
await waitUntilServicesStable({ client: ecs, maxWaitTime: 600 }, { cluster: "prod", services: ["api"] });
await ecs.send(new DeleteServiceCommand({ cluster: "prod", service: "api" }));

FAQs

How do I size a Fargate task correctly?

Choose a valid CPU/memory pair (each CPU value allows only a set memory range), sized to the container's real footprint plus headroom. Oversizing bills per vCPU-second and GB-second for capacity you never use.

What is the single most important deployment setting?

The deployment circuit breaker with rollback: true. It detects a deployment whose tasks keep failing and automatically reverts to the last working revision instead of looping on a broken image.

Why should the task role and execution role be different?

They serve different phases. The execution role pulls images, writes logs, and reads secrets before your app runs. The task role is your application's runtime identity and should be least-privilege to limit blast radius.

How do I stop the load balancer from killing slow tasks?

Set healthCheckGracePeriodSeconds above your worst-case cold start. ECS then ignores load balancer health checks during warm-up so a booting task is not deregistered before it can serve.

What is the safest way to pass secrets to a container?

The secrets field referencing a Secrets Manager or SSM ARN via valueFrom. The value is injected at startup and never appears in the task definition, the API, or CloudTrail, unlike a plaintext env var.

How do I cut Fargate cost?

Right-size tasks, auto scale services to demand, and use a capacity provider strategy that runs interruptible work on Fargate Spot with a small on-demand base for resilience.

Which log driver should I use?

awslogs for most workloads - it ships stdout/stderr to a CloudWatch log group you name. Standardizing on it gives every service consistent, queryable logs without extra infrastructure.

How do I delete a service cleanly?

Scale it to zero with UpdateService (desiredCount: 0), wait for it to stabilize, then call DeleteService. Deleting a service with running tasks is blocked, so drain first.

Should I write my own retry logic for ECS calls?

Usually no. Both SDKs retry throttling and transient errors with backoff. Tune retry mode and max attempts rather than reimplementing it, and log the request id on failure for support.

How do I wait for a deployment or task instead of sleeping?

Use waiters: tasks_running/tasks_stopped for tasks and services_stable for deployments in boto3, or waitUntilTasksRunning/waitUntilServicesStable in SDK v3. They poll for you until the target state or a timeout.

Task Definitions & Container Definitions - the sizing, roles, and secrets in group A and D.
ECS Services, Deployments & Health Checks - the deployment safety in group B.
Fargate Capacity Providers & Spot - the cost strategy in group E.
Service Discovery & Load Balancer Integration - the networking in group C.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

Walk this list once now, then use it as a review checklist before shipping any code that registers, runs, deploys, or tears down ECS tasks and services.

How to Use This List

Each item is a rule stated positively, with a one-line rationale.
Groups run roughly in order of impact: sizing and provisioning first, then deployment safety, networking, security, cost, and cleanup.
Check the boxes against your own code as a quick audit.
Revisit whenever you add a new service or move a workload to a new account, region, or cluster.

A - Task Sizing & Definitions

Pick a valid Fargate CPU/memory pair. Each CPU value permits only a specific memory range; an invalid pair is rejected at registration, so size deliberately.
Right-size to real usage plus headroom. Fargate bills per vCPU-second and GB-second, so an oversized task wastes money every second it runs.
Separate the execution role from the task role. The execution role pulls images, writes logs, and reads secrets; the task role is your app's least-privilege runtime identity.
Treat task definitions as immutable revisions. Never try to edit one; register a new revision and deploy that.
Set a container stop timeout you can meet. Handle SIGTERM and finish within stopTimeout so graceful stops actually complete.

# --- Python (boto3) ---
import boto3
 
ecs = boto3.client("ecs", region_name="us-east-1")
ecs.register_task_definition(
    family="api",
    requiresCompatibilities=["FARGATE"],
    networkMode="awsvpc",
    cpu="512", memory="1024",                       # valid Fargate pair
    executionRoleArn="arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
    taskRoleArn="arn:aws:iam::111122223333:role/apiTaskRole",  # least privilege
    containerDefinitions=[{
        "name": "api",
        "image": "111122223333.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0",
        "essential": True,
    }],
)

// --- TypeScript (AWS SDK v3) ---
import { ECSClient, RegisterTaskDefinitionCommand } from "@aws-sdk/client-ecs";
 
const ecs = new ECSClient({ region: "us-east-1" });
await ecs.send(new RegisterTaskDefinitionCommand({
  family: "api",
  requiresCompatibilities: ["FARGATE"],
  networkMode: "awsvpc",
  cpu: "512", memory: "1024",                       // valid Fargate pair
  executionRoleArn: "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
  taskRoleArn: "arn:aws:iam::111122223333:role/apiTaskRole",  // least privilege
  containerDefinitions: [{
    name: "api",
    image: "111122223333.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0",
    essential: true,
  }],
}));

B - Deployment Safety

Enable the deployment circuit breaker with rollback. A broken image otherwise loops forever launching crashing tasks; the breaker fails the deploy and reverts.
Set a health-check grace period. Give slow-starting tasks time to boot so the load balancer does not deregister them before they are ready.
Keep minimumHealthyPercent at 100 in production. A surge-style rollout never drops below current capacity; 0 risks an outage mid-deploy.
Wait for services to stabilize. Use the services_stable waiter (or poll rolloutState) so your pipeline sees a real pass or fail, not fire-and-forget.
Use forceNewDeployment for same-tag rebuilds. If the task definition did not change, force a redeploy to pick up a rebuilt image.

Deploy with the circuit breaker on and wait for the result.

# --- Python (boto3) ---
import boto3
 
ecs = boto3.client("ecs", region_name="us-east-1")
ecs.update_service(
    cluster="prod", service="api", taskDefinition="api:8",
    deploymentConfiguration={
        "minimumHealthyPercent": 100, "maximumPercent": 200,
        "deploymentCircuitBreaker": {"enable": True, "rollback": True},
    },
    healthCheckGracePeriodSeconds=60,
)
ecs.get_waiter("services_stable").wait(cluster="prod", services=["api"])

// --- TypeScript (AWS SDK v3) ---
import { ECSClient, UpdateServiceCommand, waitUntilServicesStable } from "@aws-sdk/client-ecs";
 
const ecs = new ECSClient({ region: "us-east-1" });
await ecs.send(new UpdateServiceCommand({
  cluster: "prod", service: "api", taskDefinition: "api:8",
  deploymentConfiguration: {
    minimumHealthyPercent: 100, maximumPercent: 200,
    deploymentCircuitBreaker: { enable: true, rollback: true },
  },
  healthCheckGracePeriodSeconds: 60,
}));
await waitUntilServicesStable({ client: ecs, maxWaitTime: 600 }, { cluster: "prod", services: ["api"] });

C - Networking & Discovery

Use ip target groups for Fargate. awsvpc networking gives each task its own IP; an instance target group cannot attach to a Fargate service.
Match containerName/containerPort to a port mapping. The load balancer config must reference a port the task definition actually exposes.
Prefer Cloud Map (or Service Connect) for internal calls. Let ECS keep DNS in sync with healthy task IPs instead of hardcoding addresses.
Open the container port to the load balancer only. Scope the task security group tightly; do not expose the port to the world.
Keep discovery DNS TTLs short. A short TTL lets clients pick up membership changes quickly after a deploy or scale event.

D - Security

Inject secrets, never plaintext env. Use the secrets field with a Secrets Manager or SSM ARN so values stay out of the task definition and CloudTrail.
Least-privilege the task role. Grant only the AWS actions the app truly needs; the task role is your runtime blast radius.
Enable ECS Exec deliberately, with logging. Turn on exec only when needed, put ssmmessages on the task role, and log sessions to CloudWatch or S3.
Scope the execution role to its job. It needs ECR pull, log write, and GetSecretValue for the specific secrets - nothing more.
Log the request id on failure. Capture ResponseMetadata.RequestId (boto3) or $metadata.requestId (SDK v3) for support and correlation.

Reference secrets by ARN, never inline.

# --- Python (boto3) ---
container = {
    "name": "api",
    "image": "…/api:1.4.0",
    "essential": True,
    "secrets": [
        {"name": "DB_PASSWORD",
         "valueFrom": "arn:aws:secretsmanager:us-east-1:111122223333:secret:prod/db-AbCdEf"},
    ],
}

// --- TypeScript (AWS SDK v3) ---
const container = {
  name: "api",
  image: "…/api:1.4.0",
  essential: true,
  secrets: [
    { name: "DB_PASSWORD",
      valueFrom: "arn:aws:secretsmanager:us-east-1:111122223333:secret:prod/db-AbCdEf" },
  ],
};

E - Observability & Cost

Standardize on the awslogs driver. Ship every container's stdout/stderr to a named CloudWatch log group with a stream prefix.
Blend Fargate and Fargate Spot. A capacity provider strategy runs interruptible work on Spot at a large discount with a small on-demand base for resilience.
Auto scale services on real metrics. Application Auto Scaling target-tracking on CPU or request count matches capacity to demand instead of paying for idle tasks.
Wait on transitions with waiters. Use tasks_running/tasks_stopped and services_stable rather than hand-rolled sleeps.
Handle SIGTERM for Spot and deploys. Drain and checkpoint within two minutes so reclaimed or replaced tasks lose no in-flight work.

F - Cleanup & Hygiene

Scale a service to zero before deleting it. UpdateService with desiredCount: 0, then DeleteService, avoids a delete that is blocked by running tasks.
Delete empty clusters you no longer use. DeleteCluster after services and tasks are gone keeps the account tidy.
Deregister stale task definition revisions. Old revisions accumulate; deregister ones no service references to reduce clutter.
Tag clusters, services, and task definitions. A consistent tag schema (Environment, Owner, Cost-Center) makes cost allocation and cleanup possible.
Rely on built-in SDK retries. Both SDKs retry throttling and transient errors with backoff; tune max_attempts instead of reimplementing retries.

Scale to zero, then delete, so nothing blocks teardown.

# --- Python (boto3) ---
import boto3
 
ecs = boto3.client("ecs", region_name="us-east-1")
ecs.update_service(cluster="prod", service="api", desiredCount=0)
ecs.get_waiter("services_stable").wait(cluster="prod", services=["api"])
ecs.delete_service(cluster="prod", service="api")

// --- TypeScript (AWS SDK v3) ---
import { ECSClient, UpdateServiceCommand, waitUntilServicesStable, DeleteServiceCommand } from "@aws-sdk/client-ecs";
 
const ecs = new ECSClient({ region: "us-east-1" });
await ecs.send(new UpdateServiceCommand({ cluster: "prod", service: "api", desiredCount: 0 }));
await waitUntilServicesStable({ client: ecs, maxWaitTime: 600 }, { cluster: "prod", services: ["api"] });
await ecs.send(new DeleteServiceCommand({ cluster: "prod", service: "api" }));

FAQs

How do I size a Fargate task correctly?

What is the single most important deployment setting?

The deployment circuit breaker with rollback: true. It detects a deployment whose tasks keep failing and automatically reverts to the last working revision instead of looping on a broken image.

Why should the task role and execution role be different?

How do I stop the load balancer from killing slow tasks?

Set healthCheckGracePeriodSeconds above your worst-case cold start. ECS then ignores load balancer health checks during warm-up so a booting task is not deregistered before it can serve.

What is the safest way to pass secrets to a container?

How do I cut Fargate cost?

Right-size tasks, auto scale services to demand, and use a capacity provider strategy that runs interruptible work on Fargate Spot with a small on-demand base for resilience.

Which log driver should I use?

awslogs for most workloads - it ships stdout/stderr to a CloudWatch log group you name. Standardizing on it gives every service consistent, queryable logs without extra infrastructure.

How do I delete a service cleanly?

Scale it to zero with UpdateService (desiredCount: 0), wait for it to stabilize, then call DeleteService. Deleting a service with running tasks is blocked, so drain first.

Should I write my own retry logic for ECS calls?

Usually no. Both SDKs retry throttling and transient errors with backoff. Tune retry mode and max attempts rather than reimplementing it, and log the request id on failure for support.

How do I wait for a deployment or task instead of sleeping?

Task Definitions & Container Definitions - the sizing, roles, and secrets in group A and D.
ECS Services, Deployments & Health Checks - the deployment safety in group B.
Fargate Capacity Providers & Spot - the cost strategy in group E.
Service Discovery & Load Balancer Integration - the networking in group C.

Stack versions: This page was written for boto3 1.43.x (Python 3.10+) and the AWS SDK for JavaScript v3 (Node.js 18+).

ECS & Fargate via SDK Best Practices

Buscar en la documentación

ECS & Fargate via SDK Best Practices