Installing the Amazon ECS container agent
If your container instance was not launched using an Amazon ECS-optimized AMI, you can install the Amazon ECS container agent manually using one of the following procedures. The Amazon ECS container agent is included in the Amazon ECS-optimized AMIs and does not require installation.
-
For Amazon Linux 2 instances, you can install the agent using the
amazon-linux-extrascommand. For more information, see Installing the Amazon ECS container agent on an Amazon Linux 2 EC2 instance. -
For Amazon Linux AMI instances, you can install the agent using the Amazon YUM repo. For more information, see Installing the Amazon ECS container agent on an Amazon Linux AMI EC2 instance.
-
For non-Amazon Linux instances, you can either download the agent from one of the regional S3 buckets or from Amazon Elastic Container Registry Public. If you download from one of the regional S3 buckets, you can optionally verify the validity of the container agent file using the PGP signature. For more information, see Installing the Amazon ECS container agent on a non-Amazon Linux EC2 instance.
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 an Amazon Linux 2 EC2 instance
To install the Amazon ECS container agent on an Amazon Linux 2 EC2 instance using
the amazon-linux-extras command, use the following steps.
To install the Amazon ECS container agent on an Amazon Linux 2 EC2 instance
-
Launch an Amazon Linux 2 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.
-
Disable the
dockerAmazon Linux extra repository. TheecsAmazon Linux extra repository ships with its own version of Docker, so thedockerextra must be turned off to avoid any potential future conflicts. This ensures that you are always using the Docker version that Amazon ECS intends for you to use with a particular version of the container agent.[ec2-user ~]$sudo amazon-linux-extras disable docker -
Install and enable the
ecsAmazon Linux extra repository.[ec2-user ~]$sudo amazon-linux-extras install -y ecs; sudo systemctl enable --now ecs -
(Optional) You can verify that the agent is running and see some information about your new container instance with the agent introspection API. For more information, see Amazon ECS container agent introspection.
[ec2-user ~]$curl -s http://localhost:51678/v1/metadata | python -mjson.toolNote
If you get no response, ensure that you associated the Amazon ECS container instance IAM role when launching the instance. For more information, see Amazon ECS container instance IAM role.
Installing the Amazon ECS container agent on an Amazon Linux AMI EC2 instance
To install the Amazon ECS container agent on an Amazon Linux AMI EC2 instance using the Amazon YUM repo, use the following steps.
To install the Amazon ECS container agent on an Amazon Linux AMI EC2 instance
-
Launch an Amazon Linux AMI 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
ecs-initpackage. For more information aboutecs-init, see the source code on GitHub. [ec2-user ~]$sudo yum install -y ecs-init -
Start the Docker daemon.
[ec2-user ~]$sudo service docker startOutput:
Starting cgconfig service: [ OK ] Starting docker: [ OK ]
-
Start the
ecs-initupstart job.[ec2-user ~]$sudo service ecs startOutput:
ecs start/running, process
2804 -
(Optional) You can verify that the agent is running and see some information about your new container instance with the agent introspection API. For more information, see Amazon ECS container agent introspection.
[ec2-user ~]$curl -s http://localhost:51678/v1/metadata | python -mjson.tool
Installing the Amazon ECS container agent on a non-Amazon Linux EC2 instance
To install the Amazon ECS container agent on a non-Amazon Linux EC2 instance, you can download the agent from one of the regional 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.13and newer, which is included in Amazon ECS-optimized AMI20220607and newer.Amazon ECS agent versions
1.20.0and 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
debarchitectures:ubuntu:~$curl -O https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.amd64.debubuntu:~$sudo dpkg -i amazon-ecs-init-latest.amd64.debFor
rpmarchitectures:fedora:~$curl -O https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.x86_64.rpmfedora:~$sudo yum localinstall -y amazon-ecs-init-latest.x86_64.rpm -
Edit the
/lib/systemd/system/ecs.servicefile 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
defaultcluster, edit the/etc/ecs/ecs.configfile and add the following contents. The following example specifies theMyClustercluster.ECS_CLUSTER=MyClusterFor 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 container instance configuration in Amazon S3 and Private registry authentication for tasks.
-
Start the
ecsservice.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 Task IAM role.
This also makes it so the container agent doesn't contend for connections and
network traffic on the docker0 bridge.