Solve: Safely Updating ECS Task Definitions After the First Deploy

Solve: Safely Updating ECS Task Definitions After the First Deploy

Once you’ve gotten past the ECS-CDK bootstrap problem—by deploying with a placeholder image and letting your pipeline build the real one—you’re faced with a quieter but equally important moment: how do you safely update your ECS service to use your real container image?

It’s tempting to treat this like a simple swap, but under the hood, Amazon ECS manages your service through versioned task definitions, and AWS CDK interacts with those in subtle ways. In this post, we’ll walk through what really happens during an image update and how to avoid common pitfalls during rollout.

CDK and Task Definitions: What's Actually Happening?

Each ECS service in your CDK stack points to a task definition, which is a versioned blueprint of how your container should run. This includes the image URI, memory limits, port mappings, environment variables, and more.

What many developers miss is that every update to this config creates a new revision. CDK handles this quietly. If you update the container image, CDK generates a new task definition behind the scenes and redeploys your service to use it.

But here's the gotcha: just pushing a new image to ECR with the same tag (like latest) doesn’t count as a change in CDK. CDK doesn’t know that the contents have changed—it only compares the image URI string. If it hasn’t changed, it won’t trigger a new deploy.

Replacing the Placeholder Image with the Real Thing

Now that your CI/CD pipeline has pushed the real image to ECR, you’ll need to update your CDK code to reference it. If you used a public placeholder image like amazon/amazon-ecs-sample, now’s the time to replace it with something like: 

typescript

image: ecs.ContainerImage.fromEcrRepository(myRepo, 'latest')

You have a few options here:

• latest tag: Quick and simple, but hard to trace and risky in production.
• Versioned tags: e.g. 'v1.0.3' or '2025-06-23', which give you more control and repeatability.
• Immutable digests: For maximum precision, use the image digest SHA. CDK supports this via:

typescript

ecs.ContainerImage.fromDockerImageAsset(...).imageName + '@sha256:<digest>'

Once you’ve made the change, run: 

bash

cdk diff 
cdk deploy

The new image reference will trigger a new task definition revision, and ECS will roll it out automatically.

How ECS Handles Rollouts (and How to Stay in Control)

ECS uses a rolling update strategy by default. When you update a service, ECS will start new tasks using the new definition, wait for them to become healthy, and then stop the old ones.

You can control how aggressive this is by adjusting:

• minimumHealthyPercent: how many old tasks must remain during the update
• maximumPercent: how many extra tasks ECS is allowed to run temporarily

For example: 

typescript

new ecs.FargateService(this, 'AppService', {
  cluster,
  taskDefinition,
  desiredCount: 2,
  deploymentController: {
    type: ecs.DeploymentControllerType.ECS,
  },
  healthCheckGracePeriod: Duration.seconds(60),
  circuitBreaker: { rollback: true }, // optional safeguard
});

Want to be cautious? Set minimumHealthyPercent to 100 and maximumPercent to 200. This ensures old tasks stay alive until new ones are confirmed healthy.

Want fast rollouts in dev? Drop minimumHealthyPercent to 50 and accept more risk.

Manual Overrides and Smarter Automation

In some teams, especially with tight pipelines, you may want more fine-grained control. Here are a few ideas:

• Update with CLI instead of CDK:

bash

aws ecs update-service \
  --cluster my-cluster \
  --service my-service \
  --force-new-deployment

• Use Parameter Store for dynamic image tags, and have CDK reference the value using: 

typescript

const tag = ssm.StringParameter.valueForStringParameter(this, '/image/tag');

• Trigger deploys via GitHub Actions or CodePipeline by committing the new image tag into CDK code and re-running cdk deploy.

In production environments, separating infrastructure deploys from service rollouts can be a smart move. But in smaller stacks or pipelines, CDK can still handle both—just be aware of what it does and doesn’t observe.

Conclusion: Move Forward With Confidence

Updating ECS services isn’t just about changing one line of code—it’s about understanding what that line controls. CDK makes it easy to define your infrastructure, but ECS enforces the runtime. Knowing how they interact—especially when it comes to task definitions, rollouts, and image versions—gives you peace of mind and clean deploys.

Now that you’ve made it past the first deploy, you’re not guessing anymore. You’re in command.

* * * 

Written by Aaron Rose, software engineer and technology writer at Tech-Reader.blog.