Ultimate Guide: How to manually modify the ECS agent version

Amazon Elastic Container Service (ECS) is a fully managed container orchestration service that allows you to run and scale containerized applications easily. The ECS agent plays a crucial role in managing the state of containers on ECS instances. There might be scenarios where you need to manually modify the ECS agent version, such as to resolve a specific bug or to test new features.

In this article, we’ll walk you through the steps to manually update the ECS agent on your Amazon ECS instances.

SSM/SSH into the container instances, and perform the below steps.

Step 1: Check the current ECS agent version

curl -s 127.0.0.1:51678/v1/metadata | python -mjson.tool

Sample output:
{
    "Cluster": "testECS",
    "ContainerInstanceArn": "arn:aws:ecs:eu-west-1:111111111111:container-instance/testECS/18460b8165056440332fe86ed2d53c09",
    "Version": "Amazon ECS Agent - v1.86.2 (*4e8af8ac)"
}

Step 2: Stop the ECS Agent

To update or modify the ECS agent, stop the current ECS agent service:

sudo systemctl stop ecs

Step 3: Remove the Existing ECS Agent Container

Next, remove any containers running the ECS agent. Identify the container ID and remove it:

sudo docker ps -a | grep -i amazon/amazon-ecs-agent

Sample output:
93fd7a365f55   amazon/amazon-ecs-agent:latest   "/agent"   21 minutes ago   Exited (0) 4 minutes ago             ecs-agent

sudo docker rm 93fd7a365f55

Step 4: Delete the ECS Agent Image

Remove the ECS agent Docker image from the instance:

sudo docker rmi amazon/amazon-ecs-agent

Step 5: Download the Desired ECS Agent Version

Note down the desired ECS agent version from the official Github release page.
Lets say, if you wish to use ECS agent of version 1.86.0, then to pull that ECS agent version, use the below command:

sudo docker pull amazon/amazon-ecs-agent:v1.86.0

# if you wish to use the latest ecs agent version, then run "sudo docker pull amazon/amazon-ecs-agent"
sudo docker images

#Sample output:
EPOSITORY                  TAG            IMAGE ID       CREATED       SIZE
ebs-csi-driver              latest         7c09023cbab9   2 days ago    57MB
amazon/amazon-ecs-agent     v1.86.0        3451a5e7f8e7   11 days ago   87.2MB

Tag the downloaded image:

sudo docker tag 3451a5e7f8e7 amazon/amazon-ecs-agent

Now, start the ECS agent, and check its status:
sudo systemctl start ecs

sudo systemctl status ecs

Step 6: Verify the ECS Agent Version

Finally, confirm that the ECS agent is running the correct version:

curl -s 127.0.0.1:51678/v1/metadata | python -mjson.tool

The output should reflect the version you intended to use.

That’s it. Thank you for taking the time to read this article! Keep up the great work, and happy deploying! 🚀 😊