Menu
Amazon EC2 Container Service
Developer Guide (API Version 2014-11-13)

Installing the Amazon ECS Container Agent

If your container instance was not launched from an AMI that includes the Amazon ECS container agent, you can install it using the following procedure.

Note

The Amazon ECS container agent is included in the Amazon ECS-optimized AMI and does not require installation.

To install the Amazon ECS container agent on an Amazon Linux EC2 Instance

  1. Launch an Amazon Linux 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 ecs-init package. For more information on ecs-init, you can view the source code on GitHub.

    Copy
    [ec2-user ~]$ sudo yum install -y ecs-init

  4. Start the Docker daemon.

    Copy
    [ec2-user ~]$ sudo service docker start Starting cgconfig service: [ OK ] Starting docker: [ OK ]

  5. Start the ecs-init upstart job.

    Copy
    [ec2-user ~]$ sudo start ecs ecs start/running, process 2804

  6. (Optional) You can verify that the agent is running and see some information on your new container instance with the agent introspection API. For more information, see Amazon ECS Container Agent Introspection.

    Copy
    [ec2-user ~]$ curl http://localhost:51678/v1/metadata { "Cluster": "default", "ContainerInstanceArn": "<container_instance_ARN>", "Version": "Amazon ECS Agent - v1.14.1 (467c3d7)" }

To install the Amazon ECS container agent on a non-Amazon Linux EC2 instance

  1. Launch an 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 Docker on your instance. Amazon ECS requires a minimum Docker version of 1.5.0 (version 1.12.6 is recommended), and the default Docker versions in many system package managers, such as yum or apt-get do not meet this minimum requirement. For information about installing the latest Docker version on your particular Linux distribution, go to https://docs.docker.com/engine/installation/.

    Note

    The Amazon Linux AMI always includes the recommended version of Docker for use with Amazon ECS. You can install Docker on Amazon Linux with the sudo yum install docker -y command.

  4. Check your Docker version to verify that your system meets the minimum version requirement.

    Copy
    ubuntu:~$ sudo docker version Client version: 1.4.1 Client API version: 1.16 Go version (client): go1.3.3 Git commit (client): 5bc2ff8 OS/Arch (client): linux/amd64 Server version: 1.4.1 Server API version: 1.16 Go version (server): go1.3.3 Git commit (server): 5bc2ff8
    In this example, the Docker version is 1.4.1, which is below the minimum version of 1.5.0. This instance needs to upgrade its Docker version before proceeding. For information about installing the latest Docker version on your particular Linux distribution, go to https://docs.docker.com/engine/installation/.

  5. Run the following commands on your container instance to enable IAM roles for tasks. For more information, see IAM Roles for Tasks.

    Copy
    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

  6. Pull and run the latest Amazon ECS container agent on your container instance.

    Note

    You should use Docker restart policies or a process manager (such as upstart or systemd) to treat the container agent as a service or a daemon and ensure that it is restarted if it exits. For more information, see Automatically start containers and Restart policies in the Docker documentation. The Amazon ECS-optimized AMI uses the ecs-init RPM for this purpose, and you can view the source code for this RPM on GitHub.

    The following example agent run command is broken into separate lines to show each option.
    • The --env=ECS_CLUSTER=cluster_name option is not required if you want to register into your default cluster.

    • You can optionally store your agent environment variables in a file (which can be downloaded to your container instances from Amazon S3 at launch time using EC2 user data) and pass them all at one time with the --env-file path_to_env_file option. 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.

    • If your task definitions specify log configuration options for a particular log driver, the Amazon ECS container agent running on your container instances must register the specified log driver with the ECS_AVAILABLE_LOGGING_DRIVERS environment variable. For example, to register a container instance with the json-file and awslogs logging drivers, add the --env=ECS_AVAILABLE_LOGGING_DRIVERS='["json-file","awslogs"]' option to the docker run command below. For more information, see Amazon ECS Container Agent Configuration.

    • Operating systems with SELinux enabled require the --privileged option in your docker run command. In addition, for SELinux-enabled container instances, we recommend that you add the :Z option to the /log and /data volume mounts; however, the host mounts for these volumes must exist before you run the command or you will receive a no such file or directory error. Take the following action if you experience difficulty running the Amazon ECS agent on an SELinux-enabled container instance:

      • Create the host volume mount points on your container instance.

        Copy
        $ sudo mkdir -p /var/log/ecs $ sudo mkdir -p /var/lib/ecs/data

      • Add the --privileged option to the docker run command below.

      • Append the :Z option to the /log and /data container volume mounts (for example, --volume=/var/log/ecs/:/log:Z) to the docker run command below.

    For more information on these and other agent runtime options, see Amazon ECS Container Agent Configuration.

    Copy
    ubuntu:~$ sudo 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=ECS_LOGFILE=/log/ecs-agent.log \ --env=ECS_LOGLEVEL=info \ --env=ECS_DATADIR=/data \ --env=ECS_CLUSTER=cluster_name \ --env=ECS_ENABLE_TASK_IAM_ROLE=true \ --env=ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true \ amazon/amazon-ecs-agent:latest

    Note

    If you receive an Error response from daemon: Cannot start container message, you can delete the failed container with the sudo docker rm ecs-agent command and try running the agent again.