Installing the Amazon ECS container agent - Amazon Elastic Container Service
Installing the Amazon ECS container agent on a non-Amazon Linux EC2 instanceRunning the Amazon ECS agent with host network mode
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

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.

Region Region name Amazon ECS init deb files Amazon ECS init rpm files
us-east-2 US East (Ohio)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
us-east-1 US East (N. Virginia)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
us-west-1 US West (N. California)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
us-west-2 US West (Oregon)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ap-east-1 Asia Pacific (Hong Kong)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ap-northeast-1 Asia Pacific (Tokyo)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ap-northeast-2 Asia Pacific (Seoul)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ap-south-1 Asia Pacific (Mumbai)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ap-southeast-1 Asia Pacific (Singapore)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ap-southeast-2 Asia Pacific (Sydney)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
ca-central-1 Canada (Central)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
cn-north-1 China (Beijing)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
cn-northwest-1 China (Ningxia)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
eu-central-1 Europe (Frankfurt)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
eu-west-1 Europe (Ireland)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
eu-west-2 Europe (London)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
eu-west-3 Europe (Paris)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64 (x86_64)

Amazon ECS init aarch64 (aarch64)
sa-east-1 South America (São Paulo)

Amazon ECS init amd64 (amd64)

Amazon ECS init arm64 (arm64)

Amazon ECS init x86_64

Amazon ECS init aarch64 (aarch64)
To install the Amazon ECS container agent on an Amazon EC2 instance using a non-Amazon Linux AMI

  1. 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.

  2. Connect to your instance.

  3. Install the latest version of Docker on your instance.

  4. 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 AMI 20220607 and newer.

    Amazon ECS agent versions 1.20.0 and newer have deprecated support for Docker versions older than 1.9.0.

    docker --version

  5. 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

  6. Edit the /lib/systemd/system/ecs.service file and add the following line at the end of the [Unit] section.

    After=cloud-final.service

  7. (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 the MyCluster 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.

  8. 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.