Running CoreOS Container Linux with AWS EC2 Container Service

Amazon EC2 Container Service (ECS) is a container management service which provides a set of APIs for scheduling container workloads across EC2 clusters. It supports Container Linux with Docker containers.

Your Container Linux machines communicate with ECS via an agent. The agent interacts with Docker to start new containers and gather information about running containers.

Set up a new cluster

When booting your Container Linux Machines on EC2, configure the ECS agent to be started via Ignition.

Be sure to change ECS_CLUSTER to the cluster name you've configured via the ECS CLI or leave it empty for the default. Here's a full config example:

This is the human-readable config file. This should not be immediately passed to Container Linux. Learn more.
# This config is meant to be consumed by the config transpiler, which will
# generate the corresponding Ignition config. Do not pass this config directly
# to instances of Container Linux.

   - name: amazon-ecs-agent.service
     enable: true
     contents: |
       Description=AWS ECS Agent

       ExecStartPre=-/bin/mkdir -p /var/log/ecs /var/ecs-data /etc/ecs
       ExecStartPre=-/usr/bin/touch /etc/ecs/ecs.config
       ExecStartPre=-/usr/bin/docker kill ecs-agent
       ExecStartPre=-/usr/bin/docker rm ecs-agent
       ExecStartPre=/usr/bin/docker pull amazon/amazon-ecs-agent:${ECS_VERSION}
       ExecStart=/usr/bin/docker run \
           --name ecs-agent \
           --env-file=/etc/ecs/ecs.config \
           --volume=/var/run/docker.sock:/var/run/docker.sock \
           --volume=/var/log/ecs:/log \
           --volume=/var/ecs-data:/data \
           --volume=/sys/fs/cgroup:/sys/fs/cgroup:ro \
           --volume=/run/docker/execdriver/native:/var/lib/docker/execdriver/native:ro \
           --publish= \
           --env=ECS_LOGFILE=/log/ecs-agent.log \
           --env=ECS_LOGLEVEL=${ECS_LOGLEVEL} \
           --env=ECS_DATADIR=/data \
           --env=ECS_CLUSTER=${ECS_CLUSTER} \

This is the raw machine configuration, which is not intended for editing. Learn more. Validate the config here.
  "ignition": {
    "version": "2.0.0",
    "config": {}
  "storage": {},
  "systemd": {
    "units": [
        "name": "amazon-ecs-agent.service",
        "enable": true,
        "contents": "[Unit]\nDescription=AWS ECS Agent\nDocumentation=\nRequires=docker.socket\nAfter=docker.socket\n\n[Service]\nEnvironment=ECS_CLUSTER=your_cluster_name\nEnvironment=ECS_LOGLEVEL=info\nEnvironment=ECS_VERSION=latest\nRestart=on-failure\nRestartSec=30\nRestartPreventExitStatus=5\nSyslogIdentifier=ecs-agent\nExecStartPre=-/bin/mkdir -p /var/log/ecs /var/ecs-data /etc/ecs\nExecStartPre=-/usr/bin/touch /etc/ecs/ecs.config\nExecStartPre=-/usr/bin/docker kill ecs-agent\nExecStartPre=-/usr/bin/docker rm ecs-agent\nExecStartPre=/usr/bin/docker pull amazon/amazon-ecs-agent:${ECS_VERSION}\nExecStart=/usr/bin/docker run \\\n    --name ecs-agent \\\n    --env-file=/etc/ecs/ecs.config \\\n    --volume=/var/run/docker.sock:/var/run/docker.sock \\\n    --volume=/var/log/ecs:/log \\\n    --volume=/var/ecs-data:/data \\\n    --volume=/sys/fs/cgroup:/sys/fs/cgroup:ro \\\n    --volume=/run/docker/execdriver/native:/var/lib/docker/execdriver/native:ro \\\n    --publish= \\\n    --env=ECS_LOGFILE=/log/ecs-agent.log \\\n    --env=ECS_LOGLEVEL=${ECS_LOGLEVEL} \\\n    --env=ECS_DATADIR=/data \\\n    --env=ECS_CLUSTER=${ECS_CLUSTER} \\\n    amazon/amazon-ecs-agent:${ECS_VERSION}\n\n[Install]\"
  "networkd": {},
  "passwd": {}

The example above pulls the latest official Amazon ECS agent container from the Docker Hub when the machine starts. If you ever need to update the agent, it’s as simple as restarting the amazon-ecs-agent service or the Container Linux machine.

If you want to configure SSH keys in order to log in, mount disks or configure other options, see the Container Linux Configs documentation.

Connect ECS to an existing cluster

Connecting an existing cluster to ECS is simple with fleet — the agent can be run as a global unit. The unit looks similar to the example above:


Description=Amazon ECS Agent

ExecStartPre=-/usr/bin/docker kill ecs-agent
ExecStartPre=-/usr/bin/docker rm ecs-agent
ExecStartPre=/usr/bin/docker pull amazon/amazon-ecs-agent
ExecStart=/usr/bin/docker run --name ecs-agent --env=ECS_CLUSTER=${ECS_CLUSTER} --env=ECS_LOGLEVEL=${ECS_LOGLEVEL} --publish= --volume=/var/run/docker.sock:/var/run/docker.sock amazon/amazon-ecs-agent
ExecStop=/usr/bin/docker stop ecs-agent


Be sure to change ECS_CLUSTER to the cluster name you've configured in the AWS console or leave it empty for the default.

To run this unit on each machine, all you have to do is submit it to the cluster:

$ fleetctl start amazon-ecs-agent.service
Triggered global unit amazon-ecs-agent.service start

You should see all of your machines show up in the ECS CLI output.

For more information on using ECS, check out the official Amazon documentation.