How to Move Your ECS Fargate from x86 to Arm64 (Graviton) with CDK Code

Photo by Slejven Djurakovic on Unsplash


The rapid advancements in technology have led to the emergence of new processors, such as Arm64-based processors like Graviton, that offer improved performance, power efficiency, and cost-effectiveness. Migrating your containerized applications to utilize Arm-based processors can result in significant benefits. In this blog post, we will explore the process of moving your ECS Fargate infrastructure from x86 to Arm64 (Graviton) using CDK (AWS Cloud Development Kit) code. We will also discuss the challenges you may encounter during this migration and provide code examples to help you along the way.

Why Migrate to Arm64 (Graviton)?

Arm64-based processors, such as the Graviton family offered by AWS, provide several advantages over traditional x86 processors. These advantages include:

  1. Improved Performance: Arm64 processors offer excellent performance for specific workloads, such as web servers, microservices, and containerized applications.
  2. Cost Savings: Arm64 processors are known for their increased power efficiency, which translates into cost savings on your AWS bill.
  3. Compatibility: Many popular open-source projects and frameworks now offer support for Arm64 architecture, ensuring that your applications can run seamlessly on Graviton-based instances.
  4. Future-proofing: As more organizations adopt Arm64 architecture, investing in migrating your infrastructure early will ensure you stay ahead of the curve.

Challenges in Migrating to Arm64:

  1. Docker Images: One of the primary challenges when migrating to Arm64 is the need to rebuild and repackage your Docker images specifically for Arm64 architecture. This is necessary as Arm64 and x86 have different instruction sets.
  2. ECR Repository: As part of the migration, you will need to create a new ECR (Elastic Container Registry) repository for Arm64-based images. You will then have to update your CDK code to point to the new repository.
  3. Compatibility Issues: Some third-party libraries or dependencies used in your application might not have native Arm64 support. This could require additional effort to ensure compatibility or the need to find alternative solutions.

Migrating ECS Fargate to Arm64 (Graviton) with CDK Code:

Step 1: Update CDK Dependencies: Ensure that your CDK dependencies are up to date by running the following command:

npm install aws-cdk-lib

Step 2: Create a new ECS Fargate Cluster with Arm64 (Graviton) Capacity Providers: Update your CDK code to include a new Fargate cluster with Arm64 capacity providers. This will enable your tasks to run on Arm64-based instances.

import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as ec2 from 'aws-cdk-lib/aws-ec2';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');

const vpc = new ec2.Vpc(stack, 'MyVpc');

const cluster = new ecs.Cluster(stack, 'MyCluster', {

cluster.addCapacity('Arm64Capacity', {
instanceType: new ec2.InstanceType('c6g.medium'),
machineImageType: ecs.MachineImageType.ARM64,

Step 3: Update Task Definitions and Services: Update your task definitions and services to use the new Arm64-compatible Docker images. Be sure to rebuild and push the updated images to the new ECR repository for Arm64 architecture.

const taskDefinition = new ecs.FargateTaskDefinition(stack, 'MyTaskDefinition', {
memoryLimitMiB: 2048

Migrating ECS Image to Arm64 (Graviton) with CDK Code:

Step 1: Install Docker for Arm64 First, you need to have Docker installed on your Arm64 machine or instance. You can do this by following the instructions provided by the Docker website to install Docker for Arm64.

Step 2: Modify Dockerfile to Build for Arm64 To build an Arm64-compatible Docker image, you will need to modify your Dockerfile. The main modification is to change the base image to one that supports Arm64 architecture. For example, instead of using a base image like FROM ubuntu:latest, you can use FROM arm64v8/ubuntu:latest.

Step 3: Build and Push Arm64 Docker Image Once you have modified your Dockerfile, you can build your Arm64-compatible Docker image by running the following command:

docker buildx build --platform linux/arm64 -t <new-image-name> .

This command builds the Docker image for the Arm64 architecture and tags it with the new image name you have provided. You can then push the Arm64 Docker image to your ECR repository by running the following command:

docker push <new-image-name>

Step 4: Update ECS Task Definition Finally, you need to update your ECS task definition to use the new Arm64-based Docker image. In your CDK code, update the container image field for your task definition to point to the new image in the Arm64-compatible ECR repository.

const taskDefinition = new ecs.FargateTaskDefinition(stack, 'MyTaskDefinition', {
memoryLimitMiB: 2048,

const container = taskDefinition.addContainer('MyContainer', {
image: ecs.ContainerImage.fromEcrRepository(ecrRepository, 'arm64-image-tag'),

Challenges while using Buildx

While using buildx to build Arm64 Docker images, you may face a few challenges. Here are some of the common challenges and how to address them:

  1. buildx not installed: buildx is not included in the Docker installation by default, and you may need to install it separately. You can do this by running the following command:
docker buildx install
  1. Unsupported Dockerfile instructions: Some Dockerfile instructions are not supported by the Arm64 platform. For example, if your Dockerfile includes RUN apt-get update && apt-get install -y curl, you may run into issues because the curl package may not be available for Arm64. In this case, you may need to modify your Dockerfile to use a different package or find an alternative solution.
  2. Base image not available for Arm64: Some base images may not be available for Arm64, which can make it difficult to build Arm64-compatible Docker images. In this case, you can search for alternative base images that support Arm64 or create a custom base image that supports Arm64.
  3. Build failures: It’s possible that your Dockerfile may have syntax errors or other issues that can cause build failures. In this case, you can use the --progress plain flag when running the docker buildx build command to get more detailed error messages.

By being aware of these challenges and taking the necessary steps to address them, you can successfully use buildx to build Arm64 Docker images.


Migrating your ECS Fargate infrastructure from x86 to Arm64 (Graviton) can provide significant benefits, including improved performance, cost savings, and future-proofing. While there are challenges involved in the migration process, with the help of CDK code and the steps outlined above, you can successfully convert your architecture and Docker images to Arm64-based processors.



THE HOW TO BLOG |Siddhanth Dwivedi

Siddhanth Dwivedi | Senior Security Engineer & AWS Community Builder 👨🏾‍💻