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
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
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 once
|Environment Key||Example Values||Description||Default Value|
|The cluster that this agent should check into.|
|An array of ports that should be marked as unavailable for scheduling on this container instance.|
|An array of UDP ports that should be marked as unavailable for scheduling on this container instance.|
|Required for private registry authentication. This is the type of
authentication data in ||Null|
|Required for private registry authentication. If
|The region to be used in API requests as well as to infer the correct back-end host.||Taken from EC2 instance metadata.|
|The access key used by the agent for all calls.||Taken from EC2 instance metadata.|
|The secret key used by the agent for all calls.||Taken from EC2 instance metadata.|
|Used to create a connection to the Docker daemon; behaves similarly to the environment variable as used by the Docker client.|
|The level to log at on |
|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 ||Null|
|Whether or not to save the checkpoint state to the location
specified with ||If |
|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|
|Whether to exit for ECS agent updates when they are requested.|
|The filesystem location to place update tarballs within the container when they are downloaded.|
|Whether to disable CloudWatch metrics for Amazon ECS. If this value is set
|Used to create the path to the state file of launched containers. The state file is used to read utilization metrics of containers.|
|The session token used for temporary credentials.||Taken from EC2 instance metadata.|
|32||The amount of memory, in MiB, to reserve for processes that are not managed by ECS.||0|
For information on
how to use the
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
|Whether launching privileged containers is disabled on the
container instance. If this value is set to |
|Whether SELinux is available on the container instance.|
|Whether AppArmor is available on the container instance.|
|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 |
|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.|
|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 ||Null|
|The HTTP traffic that should not be forwarded to the specified
|Whether IAM roles for tasks should be enabled on the container instance. For more information, see IAM Roles for Tasks.|
|Whether IAM roles for tasks should be enabled on the container
instance when the agent is started with the |
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
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
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
Open the Identity and Access Management (IAM) console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles.
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.
Under Managed Policies, choose Attach Policy.
On the Attach Policy page, type
S3into the Filter field to narrow the policy results.
Check the box to the left of the AmazonS3ReadOnlyAccess policy and click Attach Policy.
To store an
ecs.config file in Amazon S3
ecs.configfile 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.
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.
ecs.configfile 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
Complete the above procedures in this section to allow read-only Amazon S3 access to your container instances and store an
ecs.configfile in a private Amazon S3 bucket.
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
#!/bin/bash yum install -y aws-cli aws s3 cp s3://