The Amazon ECS Container Agent is software developed for Amazon EC2 Container Service (Amazon ECS).

It runs on container instances and starts containers on behalf of Amazon ECS.

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

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

The Amazon ECS Container Agent may also be run in a Docker container on an EC2 instance with a recent Docker version installed. A Docker image is available in our Docker Hub Repository.

$ # 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

See also the Advanced Usage section below.

On Windows Server 2016, the Amazon ECS Container Agent runs as a process on the host. Unlike Linux, the agent may not run inside a container as it uses the host's registry and the named pipe at \\.\pipe\docker_engine to communicate with the Docker daemon.

PS C:\> # Set up directories the agent uses
PS C:\> New-Item -Type directory -Path $ProgramFiles\Amazon\ECS
PS C:\> New-Item -Type directory -Path $ProgramData\Amazon\ECS
PS C:\> # Set up configuration
PS C:\> $ecsExeDir = "$env:ProgramFiles\Amazon\ECS"
PS C:\> [Environment]::SetEnvironmentVariable("ECS_CLUSTER", "my-windows-cluster", "Machine")
PS C:\> [Environment]::SetEnvironmentVariable("ECS_LOGFILE", "$ProgramData\Amazon\ECS\log\ecs-agent.log", "Machine")
PS C:\> [Environment]::SetEnvironmentVariable("ECS_DATADIR", "$ProgramData\Amazon\ECS\data", "Machine")
PS C:\> # Set this environment variable to "true" to enable IAM roles.  Note that enabling IAM roles will make port 80 unavailable for tasks.
PS C:\> [Environment]::SetEnvironmentVariable("ECS_ENABLE_TASK_IAM_ROLE", "false", "Machine")
PS C:\> # Download the agent
PS C:\> $agentVersion = "latest"
PS C:\> $agentZipUri = "https://s3.amazonaws.com/amazon-ecs-agent/ecs-agent-windows-$agentVersion.zip"
PS C:\> $zipFile = "$env:TEMP\ecs-agent.zip"
PS C:\> Invoke-RestMethod -OutFile $zipFile -Uri $agentZipUri
PS C:\> # Put the executables in the executable directory.
PS C:\> Expand-Archive -Path $zipFile -DestinationPath $ecsExeDir -Force
PS C:\> # Run the agent
PS C:\> cd '$ecsExeDir'; .\amazon-ecs-agent.ps1

Running the Amazon ECS Container Agent outside of Amazon EC2 is not supported.

The Amazon ECS Container Agent may be built by typing make with the Docker daemon (v1.5.0) running.

This produces an image tagged amazon/ecs-container-agent:make that you may run as described above.

The Amazon ECS Container Agent may also be run outside of a Docker container as a go binary. 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

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

The Amazon ECS Container Agent may be built by typing go build -o amazon-ecs-agent.exe ./agent.

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
• scripts\run-functional-tests.ps1 - Runs all functional tests
• misc\windows-deploy\amazon-ecs-agent.ps1 - Helper script to set up the host and run the agent
• misc\windows-deploy\user-data.ps1 - Sample user-data that can be used with the Windows Server 2016 with Containers AMI

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

The following environment variables are available. All of them are optional. They are listed in a general order of likelihood that a user may want to configure them as something other than the defaults.

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.

The agent also supports the following flags:

• -k — The agent will not require valid SSL certificates for the services that it communicates with.
• -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.

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

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

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