Menu
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 write these configuration variables to your container instances with Amazon EC2 user data at launch time. For more information, see Bootstrapping Container Instances with Amazon EC2 User Data.

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 Key Example Values Description Default Value
ECS_CLUSTER MyCluster The cluster that this agent should check into. If this value is undefined, then the default cluster is assumed. If the default cluster does not exist, the Amazon ECS container agent attempts to create it. If a non-default cluster is specified and it does not exist, registration fails. 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_TYPE dockercfg | docker Required for private registry authentication. This is the type of authentication data in ECS_ENGINE_AUTH_DATA. For more information, see Authentication Formats. Null
ECS_ENGINE_AUTH_DATA

Example (ECS_ENGINE_AUTH_TYPE=dockercfg):

{"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}

Example (ECS_ENGINE_AUTH_TYPE=docker):

{"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}

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). For more information, see Authentication Formats. Null
AWS_DEFAULT_REGION us-east-1 The 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_ID AKIAIOSFODNN7EXAMPLE The access key used by the agent for all calls. Taken from EC2 instance metadata.
AWS_SECRET_ACCESS_KEY wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY The secret key used by the agent for all calls. Taken from EC2 instance metadata.
DOCKER_HOST unix:///var/run/docker.sock Used 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_LOGLEVEL crit | error | warn | info | debug The level to log at on stdout. info
ECS_LOGFILE /ecs-agent.log The 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_CHECKPOINT true | false Whether 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 /data The 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_ENABLED true | false Whether to exit for ECS agent updates when they are requested. false
ECS_UPDATE_DOWNLOAD_DIR /cache The filesystem location to place update tarballs within the container when they are downloaded.
ECS_DISABLE_METRICS true | false Whether 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/docker Used 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_MEMORY 32 The amount of memory, in MiB, to reserve for processes that are not managed by ECS. 0
ECS_AVAILABLE_LOGGING_DRIVERS ["json-file","awslogs"]

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","awslogs"]
ECS_DISABLE_PRIVILEGED true | false Whether launching privileged containers is disabled on the container instance. If this value is set to true, privileged containers are not permitted. false
ECS_SELINUX_CAPABLE true | false Whether SELinux is available on the container instance. false
ECS_APPARMOR_CAPABLE true | false Whether AppArmor is available on the container instance. false
ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION 1h (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_TIMEOUT 10m (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_PROXY 10.0.0.131:3128 The 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_PROXY
  • Linux: 169.254.169.254,169.254.170.2,/var/run/docker.sock

  • Windows: 169.254.169.254,169.254.170.2,\\.\pipe\docker_engine

The HTTP traffic that should not be forwarded to the specified HTTP_PROXY. You must specify 169.254.169.254,/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_ROLE true | false Whether IAM roles for tasks should be enabled on the container instance for task containers with the bridge or default network modes. For more information, see IAM Roles for Tasks. false
ECS_ENABLE_TASK_IAM_ROLE_NETWORK_HOST true | false Whether IAM roles for tasks should be enabled on the container instance for task containers with the host network mode. This variable is only supported on agent versions 1.12.0 and later. For more information, see IAM Roles for Tasks. false
ECS_DISABLE_IMAGE_CLEANUP true Whether to disable automated image cleanup for the Amazon ECS agent. For more information, see Automated Task and Image Cleanup. false
ECS_IMAGE_CLEANUP_INTERVAL 30m The time interval between automated image cleanup cycles. If set to less than 10 minutes, the value is ignored. 30m
ECS_IMAGE_MINIMUM_CLEANUP_AGE 30m The 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_CYCLE 5 The 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.

Null

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 https://console.aws.amazon.com/iam/.

  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.

    Copy
    ECS_ENGINE_AUTH_TYPE=dockercfg ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
  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 7, use the following example script that installs the AWS CLI and copies your configuration file to /etc/ecs/ecs.config.

    Copy
    #!/bin/bash yum install -y aws-cli aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config