The ECS Agent
A small agent on each EC2 instance connects it to ECS and starts your containers.
The ECS container agent runs on every EC2 container instance. It registers the instance with a cluster, receives instructions from ECS, and starts and stops containers through Docker.
How an instance joins a cluster
The agent reads the cluster name from /etc/ecs/ecs.config. On the ECS-optimized AMI it is already installed and starts on boot.
Example
#!/bin/bash
# EC2 user-data: tell the agent which cluster to join
echo 'ECS_CLUSTER=prod' >> /etc/ecs/ecs.config
# Check agent status on the instance
sudo systemctl status ecsWhen to use it
- An ops engineer checks the ECS agent version on each container instance to identify hosts running outdated agents before a critical update.
- A security team configures the ECS agent to pull images only from private ECR repositories by setting the pull-through cache in the agent config.
- A developer SSHes into a container instance and checks the ECS agent logs to diagnose why tasks on that host keep failing to start.
More examples
Check ECS Agent Version on Instance
Queries the ECS agent's local introspection endpoint to find the running agent version and the cluster it belongs to.
# Run on the EC2 container instance
curl -s http://localhost:51678/v1/metadata | python3 -m json.tool | grep -E 'Version|Cluster'View ECS Agent Logs
Shows the last 100 ECS agent log lines on an EC2 host to diagnose task-placement or image-pull failures.
# On the EC2 container instance
journalctl -u ecs -n 100 --no-pager
# Or on Amazon Linux 2:
cat /var/log/ecs/ecs-agent.log | tail -50Update ECS Agent via SSM
Uses SSM Run Command to update and restart the ECS agent on all instances in a cluster without needing direct SSH access.
aws ssm send-command \
--targets 'Key=tag:aws:ecs:cluster-name,Values=my-ec2-cluster' \
--document-name 'AWS-RunShellScript' \
--parameters 'commands=["sudo yum update -y ecs-init && sudo systemctl restart ecs"]'
Discussion