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

Manually Updating the Amazon ECS Container Agent (for Non-Amazon ECS-optimized AMIs)

To manually update the Amazon ECS container agent (for non-Amazon ECS-optimized AMIs)

  1. Log in to your container instance via SSH.

  2. Check to see if your agent uses the ECS_DATADIR environment variable to save its state.

    Copy
    ubuntu:~$ docker inspect ecs-agent | grep ECS_DATADIR

    Output:

    "ECS_DATADIR=/data",

    Important

    If the previous command does not return the ECS_DATADIR environment variable, you must stop any tasks running on this container instance before updating your agent. Newer agents with the ECS_DATADIR environment variable save their state and you can update them while tasks are running without issues.

  3. Stop the Amazon ECS container agent.

    Copy
    ubuntu:~$ docker stop ecs-agent
  4. Delete the agent container.

    Copy
    ubuntu:~$ docker rm ecs-agent
  5. Ensure that the /etc/ecs directory and Amazon ECS container agent configuration file exist at /etc/ecs/ecs.config.

    Copy
    ubuntu:~$ sudo mkdir -p /etc/ecs && sudo touch /etc/ecs/ecs.config

  6. Edit the /etc/ecs/ecs.config file and ensure that it contains at least the following variable declarations. If you do not want your container instance to register with the default cluster, specify your cluster name as the value for ECS_CLUSTER.

    Copy
    ECS_DATADIR=/data ECS_ENABLE_TASK_IAM_ROLE=true ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST=true ECS_LOGFILE=/log/ecs-agent.log ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"] ECS_LOGLEVEL=info ECS_CLUSTER=default
    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 Container Instance Configuration in Amazon S3 and Private Registry Authentication.

  7. Pull the latest Amazon ECS container agent image from Docker Hub.

    Copy
    ubuntu:~$ docker pull amazon/amazon-ecs-agent:latest

    Output:

    Pulling repository amazon/amazon-ecs-agent
    a5a56a5e13dc: Download complete
    511136ea3c5a: Download complete
    9950b5d678a1: Download complete
    c48ddcf21b63: Download complete
    Status: Image is up to date for amazon/amazon-ecs-agent:latest
  8. 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. For example systemd unit files for Ubuntu 16.04 and CentOS 7, see Example Container Instance User Data Configuration Scripts.

    The following example agent run command is broken into separate lines to show each option. For more information about these and other agent runtime options, see Amazon ECS Container Agent Configuration.

    Important

    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
      ubuntu:~$ sudo mkdir -p /var/log/ecs /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.

    Copy
    ubuntu:~$ sudo docker run --name ecs-agent \ --detach=true \ --restart=on-failure:10 \ --volume=/var/run:/var/run \ --volume=/var/log/ecs/:/log \ --volume=/var/lib/ecs/data:/data \ --volume=/etc/ecs:/etc/ecs \ --net=host \ --env-file=/etc/ecs/ecs.config \ 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.