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

Amazon ECS Container Agent Configuration

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, and all of them are optional.

If your container instance was launched with the Amazon ECS-optimized AMI, you can set these environment variables in the /etc/ecs/ecs.config file and then restart the agent. You can also create a custom ecs.config file that contains these configuration variables and store it in Amazon S3 for container instances to download at run time using Amazon EC2 user data. For more information, see Storing Container Instance Configuration in Amazon S3.

If you are manually starting the Amazon ECS container agent (for non-Amazon ECS-optimized AMIs), you can use these environment variables in the docker run command that you use to start the agent with the syntax --env=VARIABLE_NAME=VARIABLE_VALUE. For sensitive information, such as authentication credentials for private repositories, you should store your agent environment variables in a file and pass them all at one time with the --env-file path_to_env_file option.

Available Parameters

Environment KeyExample ValuesDescriptionDefault Value
ECS_CLUSTERMyClusterThe cluster that this agent should check into.default
ECS_RESERVED_PORTS[22, 80, 5000, 8080]An array of ports that should be marked as unavailable for scheduling on this container instance.[22, 2375, 2376, 51678]
ECS_RESERVED_PORTS_UDP[53, 123]An array of UDP ports that should be marked as unavailable for scheduling on this container instance.[]
ECS_ENGINE_AUTH_TYPEdockercfg | dockerRequired for private registry authentication. This is the type of authentication data in ECS_ENGINE_AUTH_DATA. For more information, see Authentication Formats.Null

Example (ECS_ENGINE_AUTH_TYPE=dockercfg):


Example (ECS_ENGINE_AUTH_TYPE=docker):


Required for private registry authentication. If ECS_ENGINE_AUTH_TYPE=dockercfg, then the ECS_ENGINE_AUTH_DATA value should be the contents of a Docker configuration file (~/.dockercfg or ~/.docker/config.json) created by running docker login. If ECS_ENGINE_AUTH_TYPE=docker, then the ECS_ENGINE_AUTH_DATA value should be a JSON representation of the registry server to authenticate against, as well as the authentication parameters required by that registry (such as user name, password, and email address for that account).Null
AWS_DEFAULT_REGIONus-east-1The region to be used in API requests as well as to infer the correct back-end host.Taken from EC2 instance metadata.
AWS_ACCESS_KEY_IDAKIAIOSFODNN7EXAMPLEThe access key used by the agent for all calls.Taken from EC2 instance metadata.
AWS_SECRET_ACCESS_KEYwJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEYThe secret key used by the agent for all calls.Taken from EC2 instance metadata.
DOCKER_HOSTunix:///var/run/docker.sockUsed to create a connection to the Docker daemon; behaves similarly to the environment variable as used by the Docker client.unix:///var/run/docker.sock
ECS_LOGLEVELcrit | error | warn | info | debugThe level to log at on
ECS_LOGFILE/ecs-agent.logThe path to output full debugging information to. If blank, no logs are recorded. If this value is set, logs at the debug level (regardless of ECS_LOGLEVEL) are written to that file.Null
ECS_CHECKPOINTtrue | falseWhether or not to save the checkpoint state to the location specified with ECS_DATADIR.If ECS_DATADIR is explicitly set to a non-empty value, then ECS_CHECKPOINT is set to true; otherwise, it is set to false.
ECS_DATADIR/dataThe name of the persistent data directory on the container that is running the Amazon ECS container agent. The directory is used to save information about the cluster and the agent state.Null
ECS_UPDATES_ENABLEDtrue | falseWhether to exit for ECS agent updates when they are requested.false
ECS_UPDATE_DOWNLOAD_DIR/cacheThe filesystem location to place update tarballs within the container when they are downloaded. 
ECS_DISABLE_METRICStrue | falseWhether to disable CloudWatch metrics for Amazon ECS. If this value is set to true, CloudWatch metrics are not collected.false
ECS_DOCKER_GRAPHPATH/var/lib/dockerUsed to create the path to the state file of launched containers. The state file is used to read utilization metrics of containers./var/lib/docker
AWS_SESSION_TOKEN The session token used for temporary credentials.Taken from EC2 instance metadata.
ECS_RESERVED_MEMORY32The amount of memory, in MiB, to reserve for processes that are not managed by ECS.0

For information about how to use the awslogs log driver, see Using the awslogs Log Driver.

For more information about the different log drivers available for your Docker version and how to configure them, see Configure logging drivers in the Docker documentation.

The logging drivers available on the container instance. The Amazon ECS container agent running on a container instance must register the logging drivers available on that instance with the ECS_AVAILABLE_LOGGING_DRIVERS environment variable before containers placed on that instance can use log configuration options for those drivers in tasks.["json-file"]
ECS_DISABLE_PRIVILEGEDtrue | falseWhether launching privileged containers is disabled on the container instance. If this value is set to true, privileged containers are not permitted.false
ECS_SELINUX_CAPABLEtrue | falseWhether SELinux is available on the container instance.false
ECS_APPARMOR_CAPABLEtrue | falseWhether AppArmor is available on the container instance.false
ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION1h (Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", and "h".)Time duration to wait from when a task is stopped until the docker container is removed. As this removes the docker container data, be aware that if this value is set too low, you may not be able to inspect your stopped containers or view the logs before they are removed. The minimum duration is 1m; any value shorter than 1 minute is ignored.3h
ECS_CONTAINER_STOP_TIMEOUT10m (Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", and "h".)Time duration to wait from when a task is stopped before its containers are forcefully killed if they do not exit normally on their own.30s
HTTP_PROXY10.0.0.131:3128The hostname (or IP address) and port number of an HTTP proxy to use for the ECS agent to connect to the Internet (for example, if your container instances do not have external network access through an Amazon VPC Internet gateway or NAT gateway or instance). If this variable is set, you must also set the NO_PROXY variable to filter EC2 instance metadata and Docker daemon traffic from the proxy. For more information, see HTTP Proxy Configuration.Null
NO_PROXY169.254.169.254,/var/run/docker.sockThe HTTP traffic that should not be forwarded to the specified HTTP_PROXY. You must specify,/var/run/docker.sock to filter EC2 instance metadata and Docker daemon traffic from the proxy. For more information, see HTTP Proxy Configuration.Null
ECS_ENABLE_TASK_IAM_ROLEtrue | falseWhether IAM roles for tasks should be enabled on the container instance. For more information, see IAM Roles for Tasks.false
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOSTtrue | falseWhether IAM roles for tasks should be enabled on the container instance when the agent is started with the host network mode.false
ECS_DISABLE_IMAGE_CLEANUPtrueWhether to disable automated image cleanup for the Amazon ECS agent. For more information, see Automated Task and Image Cleanup.false
ECS_IMAGE_CLEANUP_INTERVAL30mThe time interval between automated image cleanup cycles. If set to less than 10 minutes, the value is ignored.30m
ECS_IMAGE_MINIMUM_CLEANUP_AGE30mThe minimum time interval between when an image is pulled and when it can be considered for automated image cleanup.1h
ECS_NUM_IMAGES_DELETE_PER_CYCLE5The maximum number of images to delete in a single automated image cleanup cycle. If set to less than 1, the value is ignored.5
ECS_INSTANCE_ATTRIBUTES{"custom attribute": "custom_attribute_value"}

For information about custom attributes to use, see Attributes.

A list of custom attributes, in JSON form, to apply to your container instances. Using this attribute at instance registration will add the custom attributes allowing you to skip the manual method of adding custom attributes via the AWS Management Console.

An invalid JSON value for this variable will cause the agent to exit with a code of 5 and a message will appear in the agent logs. If the JSON value is valid but there is an issue detected when validating the attribute (for example if the value is too long or contains invalid characters) then the container instance registration will happen but the agent will exit with a code 5 and a message will be written to the agent logs. For information on how to locate the agent logs, see Amazon ECS Container Agent Log.


Storing Container Instance Configuration in Amazon S3

Amazon ECS container agent configuration is controlled with the environment variables described above. The Amazon ECS-optimized AMI checks for these variables in /etc/ecs/ecs.config when the container agent starts and configures the agent accordingly. Certain innocuous environment variables, such as ECS_CLUSTER, can be passed to the container instance at launch time through Amazon EC2 user data and written to this file without consequence. However, other sensitive information, such as your AWS credentials or the ECS_ENGINE_AUTH_DATA variable, should never be passed to an instance in user data or written to /etc/ecs/ecs.config in a way that they would show up in a .bash_history file.

Storing configuration information in a private bucket in Amazon S3 and granting read-only access to your container instance IAM role is a secure and convenient way to allow container instance configuration at launch time. You can store a copy of your ecs.config file in a private bucket, and then use Amazon EC2 user data to install the AWS CLI and copy your configuration information to /etc/ecs/ecs.config when the instance launches.

To allow Amazon S3 read-only access for your container instance role

  1. Open the IAM console at

  2. In the navigation pane, choose Roles.

  3. Choose the IAM role you use for your container instances (this role is likely titled ecsInstanceRole). For more information, see Amazon ECS Container Instance IAM Role.

  4. Under Managed Policies, choose Attach Policy.

  5. On the Attach Policy page, type S3 into the Filter field to narrow the policy results.

  6. Check the box to the left of the AmazonS3ReadOnlyAccess policy and click Attach Policy.

To store an ecs.config file in Amazon S3

  1. Create an ecs.config file with valid environment variables and values from Amazon ECS Container Agent Configuration using the following format. This example configures private registry authentication. For more information, see Private Registry Authentication.

  2. Create a private bucket in Amazon S3 to store your configuration file. For more information, see Create a Bucket in the Amazon Simple Storage Service Getting Started Guide.

  3. Upload the ecs.config file to your Amazon S3 bucket. For more information, see Add an Object to a Bucket in the Amazon Simple Storage Service Getting Started Guide.

To load an ecs.config file from Amazon S3 at launch

  1. Complete the above procedures in this section to allow read-only Amazon S3 access to your container instances and store an ecs.config file in a private Amazon S3 bucket.

  2. Launch new container instances by following the steps in Launching an Amazon ECS Container Instance. In Step 10, use the following example script that installs the AWS CLI and copies your configuration file to /etc/ecs/ecs.config.

    yum install -y aws-cli
    aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config