Installing the Amazon ECS container agent
If you want to register an Amazon EC2 instance with your Amazon ECS cluster and that instance is not using an AMI based on the Amazon ECS-optimized AMI, you can install the Amazon ECS container agent manually using the following procedure. To do this, you can either download the agent from one of the regional Amazon S3 buckets or from Amazon Elastic Container Registry Public. If you download from one of the regional Amazon S3 buckets, you can optionally verify the validity of the container agent file using the PGP signature.
Note
The systemd
units for both Amazon ECS and Docker services have a directive to
wait for cloud-init
to finish before starting both services. The
cloud-init
process is not considered finished until your Amazon EC2 user
data has finished running. Therefore, starting Amazon ECS or Docker via Amazon EC2 user data may
cause a deadlock. To start the container agent using Amazon EC2 user data you can use
systemctl enable --now --no-block ecs.service
.
Installing the Amazon ECS container agent on a non-Amazon Linux EC2 instance
To install the Amazon ECS container agent on an Amazon EC2 instance, you can download the agent from one of the regional Amazon S3 buckets and install it.
Note
When using a non-Amazon Linux AMI, your Amazon EC2 instance requires cgroupfs
support for the cgroup
driver in order for the Amazon ECS agent to support
task level resource limits. For more information, see Amazon ECS agent on
GitHub
The latest Amazon ECS container agent files, by Region, for each system architecture are listed below for reference.
To install the Amazon ECS container agent on an Amazon EC2 instance using a non-Amazon Linux AMI
-
Launch an Amazon EC2 instance with an IAM role that allows access to Amazon ECS. For more information, see Amazon ECS container instance IAM role.
-
Connect to your instance.
-
Install the latest version of Docker on your instance.
-
Check your Docker version to verify that your system meets the minimum version requirement.
Note
The minimum Docker version for reliable metrics is Docker version
v20.10.13
and newer, which is included in Amazon ECS-optimized AMI20220607
and newer.Amazon ECS agent versions
1.20.0
and newer have deprecated support for Docker versions older than1.9.0
.docker --version
-
Download the appropriate Amazon ECS agent file for your operating system and system architecture and install it.
For
deb
architectures:ubuntu:~$
curl -O https://s3.
us-west-2
.amazonaws.com/amazon-ecs-agent-us-west-2
/amazon-ecs-init-latest.amd64.deb
ubuntu:~$
sudo dpkg -i amazon-ecs-init-latest.
amd64.deb
For
rpm
architectures:fedora:~$
curl -O https://s3.
us-west-2
.amazonaws.com/amazon-ecs-agent-us-west-2
/amazon-ecs-init-latest.x86_64.rpm
fedora:~$
sudo yum localinstall -y amazon-ecs-init-latest.
x86_64.rpm
-
Edit the
/lib/systemd/system/ecs.service
file and add the following line at the end of the[Unit]
section.After=cloud-final.service
-
(Optional) To register the instance with a cluster other than the
default
cluster, edit the/etc/ecs/ecs.config
file and add the following contents. The following example specifies theMyCluster
cluster.ECS_CLUSTER=
MyCluster
For more information about these and other agent runtime options, see Amazon ECS container agent configuration.
Note
You can optionally store your agent environment variables in Amazon S3 (which can be downloaded to your container instances at launch time using Amazon EC2 user data). This is recommended for sensitive information such as authentication credentials for private repositories. For more information, see Storing Amazon ECS container instance configuration in Amazon S3 and Using non-Amazon container images in Amazon ECS.
-
Start the
ecs
service.ubuntu:~$
sudo systemctl start ecs
Running the Amazon ECS agent with host network mode
When running the Amazon ECS container agent, ecs-init
will create the
container agent container with the host
network mode. This is the only
supported network mode for the container agent container.
This allows you to block access to the Amazon EC2 instance metadata service
endpoint (http://169.254.169.254
) for the containers started by
the container agent. This ensures that containers cannot access IAM role credentials
from the container instance profile and enforces that tasks use only the IAM task role
credentials. For more information, see Amazon ECS task IAM role.
This also makes it so the container agent doesn't contend for connections and network
traffic on the docker0
bridge.