Amazon ECS Container Agent

The Amazon ECS Container Agent is a component of Amazon Elastic Container Service (Amazon ECS) and is responsible for managing containers on behalf of Amazon ECS.

This repository comes with ECS-Init, which is a systemd based service to support the Amazon ECS Container Agent and keep it running. It is used for systems that utilize systemd as init systems and is packaged as deb or rpm. The source for ECS-Init is available in this repository at ./ecs-init while the packaging is available at ./packaging.

Usage

The best source of information on running this software is the Amazon ECS documentation.

On the Amazon Linux AMI

On the Amazon Linux AMI, we provide an installable RPM which can be used via sudo yum install ecs-init && sudo start ecs. This is the recommended way to run it in this environment.

On Other Linux AMIs

Amazon ECS docs provides deb and rpm packages and instructions to install ECS Container Agent on non-Amazon Linux instances.

The Amazon ECS Container Agent may also be run in a Docker container on an EC2 instance with a recent Docker version installed. Docker images are available in Docker Hub Repository and ECR Public Gallery.

$ # Set up directories the agent uses
$ mkdir -p /var/log/ecs /etc/ecs /var/lib/ecs/data
$ touch /etc/ecs/ecs.config
$ # Set up necessary rules to enable IAM roles for tasks
$ sysctl -w net.ipv4.conf.all.route_localnet=1
$ iptables -t nat -A PREROUTING -p tcp -d 169.254.170.2 --dport 80 -j DNAT --to-destination 127.0.0.1:51679
$ iptables -t nat -A OUTPUT -d 169.254.170.2 -p tcp -m tcp --dport 80 -j REDIRECT --to-ports 51679
$ # Run the agent
$ docker run --name ecs-agent \
    --detach=true \
    --restart=on-failure:10 \
    --volume=/var/run/docker.sock:/var/run/docker.sock \
    --volume=/var/log/ecs:/log \
    --volume=/var/lib/ecs/data:/data \
    --net=host \
    --env-file=/etc/ecs/ecs.config \
    --env=ECS_LOGFILE=/log/ecs-agent.log \
    --env=ECS_DATADIR=/data/ \
    --env=ECS_ENABLE_TASK_IAM_ROLE=true \
    --env=ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true \
    amazon/amazon-ecs-agent:latest

On Other Linux AMIs when awsvpc networking mode is enabled

For the AWS VPC networking mode, ECS agent requires CNI plugin and dhclient to be available. ECS also needs the ecs-init to run as part of its startup. The following is an example of docker run configuration for running ecs-agent with Task ENI enabled. Note that ECS agent currently only supports cgroupfs for cgroup driver.

$ # Run the agent
$ /usr/bin/docker run --name ecs-agent \
--init \
--restart=on-failure:10 \
--volume=/var/run:/var/run \
--volume=/var/log/ecs/:/log:Z \
--volume=/var/lib/ecs/data:/data:Z \
--volume=/etc/ecs:/etc/ecs \
--volume=/sbin:/host/sbin \
--volume=/lib:/lib \
--volume=/lib64:/lib64 \
--volume=/usr/lib:/usr/lib \
--volume=/usr/lib64:/usr/lib64 \
--volume=/proc:/host/proc \
--volume=/sys/fs/cgroup:/sys/fs/cgroup \
--net=host \
--env-file=/etc/ecs/ecs.config \
--cap-add=sys_admin \
--cap-add=net_admin \
--env ECS_ENABLE_TASK_ENI=true \
--env ECS_UPDATES_ENABLED=true \
--env ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION=1h \
--env ECS_DATADIR=/data \
--env ECS_ENABLE_TASK_IAM_ROLE=true \
--env ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true \
--env ECS_LOGFILE=/log/ecs-agent.log \
--env ECS_AVAILABLE_LOGGING_DRIVERS='["json-file","awslogs","syslog","none"]' \
--env ECS_LOGLEVEL=info \
--detach \
amazon/amazon-ecs-agent:latest

See also the Advanced Usage section below.

On the ECS Optimized Windows AMI

ECS Optimized Windows AMI ships with a pre-installed PowerShell module called ECSTools to install, configure, and run the ECS Agent as a Windows service. To install the service, you can run the following PowerShell commands on an EC2 instance. To launch into another cluster instead of windows, replace the 'windows' in the script below with the name of your cluster.

PS C:\> Import-Module ECSTools
PS C:\> # The -EnableTaskIAMRole option is required to enable IAM roles for tasks.
PS C:\> Initialize-ECSAgent -Cluster 'windows' -EnableTaskIAMRole

Downloading Different Version of ECS Agent

To download different version of ECS Agent, you can do the following:

PS C:\> # use agentVersion = "latest" for the latest available agent version
PS C:\> $agentVersion = "v1.20.4"
PS C:\> Initialize-ECSAgent -Cluster 'windows' -EnableTaskIAMRole -Version $agentVersion

Build ECS Agent from source

Build ECS Agent Image (Linux)

ECS Agent can also be built locally from source on a linux machine. Use the following steps to build ECS Agent

• Get ECS Agent source

git clone https://github.com/aws/amazon-ecs-agent.git

• Build Agent image using release-agent make target

make release-agent

This installs the required build dependencies, builds ECS Agent image and saves it at a path ecs-agent-v${AGENT_VERSION}.tar. Load this using

docker load < ecs-agent-v${AGENT_VERSION}.tar

Follow the instructions above to continue with the installation

Build and run standalone (Linux)

The Amazon ECS Container Agent may also be run outside of a Docker container as a Go binary. At this time, this is not recommended for production on Linux, but it can be useful for development or easier integration with your local Go tools.

The following commands run the agent outside of Docker:

make gobuild
./out/amazon-ecs-agent

Standalone (Windows)

The Amazon ECS Container Agent may be built by invoking scripts\build_agent.ps1

Scripts (Windows)

The following scripts are available to help develop the Amazon ECS Container Agent on Windows:

• scripts\run-integ-tests.ps1 - Runs all integration tests in the engine and stats packages
• misc\windows-deploy\Install-ECSAgent.ps1 - Install the ECS agent as a Windows service
• misc\windows-deploy\amazon-ecs-agent.ps1 - Helper script to set up the host and run the agent as a process
• misc\windows-deploy\user-data.ps1 - Sample user-data that can be used with the Windows Server 2016 with Containers AMI to run the agent as a process

Build ECS-Init Package (Linux)

ECS-Init package can also be built as a deb or rpm depending on the linux system you are running. Follow instructions at generic-deb-integrated or generic-rpm-integrated to build and install ECS Agent with Init using deb or rpm.

Advanced Usage

The Amazon ECS Container Agent supports a number of configuration options, most of which should be set through environment variables.

Environment Variables

The table below provides an overview of optional environment variables that can be used to configure the ECS agent. See the Amazon ECS developer guide for additional details on each available environment variable.

Additionally, the following environment variable(s) can be used to configure the behavior of the ecs-init service. When using ECS-Init, all env variables, including the ECS Agent variables above, are read from path /etc/ecs/ecs.config:

Persistence

When you run the Amazon ECS Container Agent in production, its datadir should be persisted between runs of the Docker container. If this data is not persisted, the agent registers a new container instance ARN on each launch and is not able to update the state of tasks it previously ran.

Flags

The agent also supports the following flags:

• -k — The agent will not require valid SSL certificates for the services that it communicates with. We recommend against using this flag.
• -loglevel — Options: [<crit>|<error>|<warn>|<info>|<debug>]. The agent will output on stdout at the given level. This is overridden by the ECS_LOGLEVEL environment variable, if present.

Make Targets (on Linux)

The following targets are available. Each may be run with make <target>.

Contributing

Contributions and feedback are welcome! Proposals and pull requests will be considered and responded to. For more information, see the CONTRIBUTING.md file.

If you have a bug/and issue around the behavior of the ECS agent, please open it here.

If you have a feature request, please open it over at the AWS Containers Roadmap.

Amazon Web Services does not currently provide support for modified copies of this software.

Security disclosures

If you think you’ve found a potential security issue, please do not post it in the Issues. Instead, please follow the instructions here or email AWS security directly.

License

The Amazon ECS Container Agent is licensed under the Apache 2.0 License.