Amazon ECS Linux container agent - Amazon Elastic Container Service
LifecycleAmazon ECS-optimized AMIAdditional informationContainer agent log configuration parameters

Amazon ECS Linux container agent

The Amazon ECS agent is a process that runs on every container instance that is registered with your cluster. It facilitates the communication between your container instances and Amazon ECS.

Each Amazon ECS container agent version supports a different feature set and provides bug fixes from previous versions. When possible, we always recommend using the latest version of the Amazon ECS container agent. To update your container agent to the latest version, see Updating the Amazon ECS container agent.

To see which features and enhancements are included with each agent release, see https://github.com/aws/amazon-ecs-agent/releases.

Important

The minimum Docker version for reliable metrics is Docker version v20.10.13 and newer, which is included in Amazon ECS-optimized AMI 20220607 and newer.

Amazon ECS agent versions 1.20.0 and newer have deprecated support for Docker versions older than 1.9.0.

Lifecycle

When the Amazon ECS container agent registers an Amazon EC2 instance to your cluster, the Amazon EC2 instance reports its status as ACTIVE and its agent connection status as TRUE. This container instance can accept run task requests.

If you stop (not terminate) a container instance, the status remains ACTIVE, but the agent connection status transitions to FALSE within a few minutes. Any tasks that were running on the container instance stop. If you start the container instance again, the container agent reconnects with the Amazon ECS service, and you are able to run tasks on the instance again.

Important

If you stop and start a container instance, or reboot that instance, some older versions of the Amazon ECS container agent register the instance again without deregistering the original container instance ID. In this case, Amazon ECS lists more container instances in your cluster than you actually have. (If you have duplicate container instance IDs for the same Amazon EC2 instance ID, you can safely deregister the duplicates that are listed as ACTIVE with an agent connection status of FALSE.) This issue is fixed in the current version of the Amazon ECS container agent. For more information about updating to the current version, see Updating the Amazon ECS container agent.

If you change the status of a container instance to DRAINING, new tasks are not placed on the container instance. Any service tasks running on the container instance are removed, if possible, so that you can perform system updates. For more information, see Draining Amazon ECS container instances.

If you deregister or terminate a container instance, the container instance status changes to INACTIVE immediately, and the container instance is no longer reported when you list your container instances. However, you can still describe the container instance for one hour following termination. After one hour, the instance description is no longer available.

Important

You can drain the instances manually, or build an Auto Scaling group lifecycle hook to set the instance status to DRAINING. See Amazon EC2 Auto Scaling lifecycle hooks for more information about Auto Scaling lifecycle hooks.

Amazon ECS-optimized AMI

The Linux variants of the Amazon ECS-optimized AMI use the Amazon Linux 2 AMI as their base. The Amazon Linux 2 source AMI name for each variant can be retrieved by querying the Systems Manager Parameter Store API. For more information, see Retrieving Amazon ECS-optimized Linux AMI metadata. When you launch our container instances from the most recent Amazon ECS-optimized Amazon Linux 2 AMI you receive the current container agent version. To launch a container instance with the latest Amazon ECS-optimized Amazon Linux 2 AMI, see Launching an Amazon ECS Linux container instance.

Additional information

The following pages provide additional information about the changes:

Amazon ECS container agent log configuration parameters

The Amazon ECS container agent stores logs on your container instances.

For container agent version 1.36.0 and later, by default the logs are located at /var/log/ecs/ecs-agent.log on Linux instances and at C:\ProgramData\Amazon\ECS\log\ecs-agent.log on Windows instances.

For container agent version 1.35.0 and earlier, by default the logs are located at /var/log/ecs/ecs-agent.log.timestamp on Linux instances and at C:\ProgramData\Amazon\ECS\log\ecs-agent.log.timestamp on Windows instances.

By default, the agent logs are rotated hourly with a maximum of 24 logs being stored.

The following are the container agent configuration variables that can be used to change the default agent logging behavior. For more information, see Amazon ECS container agent configuration.

ECS_LOGFILE

Example values: /ecs-agent.log

Default value on Linux: Null

Default value on Windows: Null

The location where agent logs should be written. If you are running the agent via ecs-init, which is the default method when using the Amazon ECS-optimized AMI, the in-container path is /log, and ecs-init mounts that out to /var/log/ecs/ on the host.

ECS_LOGLEVEL

Example values: crit, error, warn, info, debug

Default value on Linux: info

Default value on Windows: info

The level of detail to log.

ECS_LOGLEVEL_ON_INSTANCE

Example values: none, crit, error, warn, info, debug

Default value on Linux: none, if ECS_LOG_DRIVER is explicitly set to a non-empty value; otherwise the same value as ECS_LOGLEVEL

Default value on Windows: none, if ECS_LOG_DRIVER is explicitly set to a non-empty value; otherwise the same value as ECS_LOGLEVEL

Can be used to override ECS_LOGLEVEL and set a level of detail that should be logged in the on-instance log file, separate from the level that is logged in the logging driver. If a logging driver is explicitly set, on-instance logs are turned off by default. They can be turned back on with this variable.

ECS_LOG_DRIVER

Example values: awslogs, fluentd, gelf, json-file, journald, logentries syslog, splunk

Default value on Linux: json-file

Default value on Windows: Not applicable

Determines the logging driver the agent container uses.

ECS_LOG_ROLLOVER_TYPE

Example values: size, hourly

Default value on Linux: hourly

Default value on Windows: hourly

Determines whether the container agent log file is rotated hourly or based on size. By default, the agent log file is rotated each hour.

ECS_LOG_OUTPUT_FORMAT

Example values: logfmt, json

Default value on Linux: logfmt

Default value on Windows: logfmt

Determines the log output format. When the json format is used, each line in the log is a structured JSON map.

ECS_LOG_MAX_FILE_SIZE_MB

Example values: 10

Default value on Linux: 10

Default value on Windows: 10

When the ECS_LOG_ROLLOVER_TYPE variable is set to size, this variable determines the maximum size (in MB) of the log file before it's rotated. If the rollover type is set to hourly, then this variable is ignored.

ECS_LOG_MAX_ROLL_COUNT

Example values: 24

Default value on Linux: 24

Default value on Windows: 24

Determines the number of rotated log files to keep. Older log files are deleted after this limit is reached.

For container agent version 1.36.0 and later, the following is an example log file when the logfmt format is used.

level=info time=2019-12-12T23:43:29Z msg="Loading configuration" module=agent.go
level=info time=2019-12-12T23:43:29Z msg="Image excluded from cleanup: amazon/amazon-ecs-agent:latest" module=parse.go
level=info time=2019-12-12T23:43:29Z msg="Image excluded from cleanup: amazon/amazon-ecs-pause:0.1.0" module=parse.go
level=info time=2019-12-12T23:43:29Z msg="Amazon ECS agent Version: 1.36.0, Commit: ca640387" module=agent.go
level=info time=2019-12-12T23:43:29Z msg="Creating root ecs cgroup: /ecs" module=init_linux.go
level=info time=2019-12-12T23:43:29Z msg="Creating cgroup /ecs" module=cgroup_controller_linux.go
level=info time=2019-12-12T23:43:29Z msg="Loading state!" module=statemanager.go
level=info time=2019-12-12T23:43:29Z msg="Event stream ContainerChange start listening..." module=eventstream.go
level=info time=2019-12-12T23:43:29Z msg="Restored cluster 'auto-robc'" module=agent.go
level=info time=2019-12-12T23:43:29Z msg="Restored from checkpoint file. I am running as 'arn:aws:ecs:us-west-2:0123456789:container-instance/auto-robc/3330a8a91d15464ea30662d5840164cd' in cluster 'auto-robc'" module=agent.go

The following is an example log file when the JSON format is used.

{"time": "2019-11-07T22:52:02Z", "level": "info", "msg": "Starting Amazon Elastic Container Service Agent", "module": "engine.go"}

For container agent versions 1.35.0 and earlier, the following is the format of the log file.

2016-08-15T15:54:41Z [INFO] Starting Agent: Amazon ECS Agent - v1.12.0 (895f3c1)
2016-08-15T15:54:41Z [INFO] Loading configuration
2016-08-15T15:54:41Z [WARN] Invalid value for task cleanup duration, will be overridden to 3h0m0s, parsed value 0, minimum threshold 1m0s
2016-08-15T15:54:41Z [INFO] Checkpointing is enabled. Attempting to load state
2016-08-15T15:54:41Z [INFO] Loading state! module="statemanager"
2016-08-15T15:54:41Z [INFO] Detected Docker versions [1.17 1.18 1.19 1.20 1.21 1.22]
2016-08-15T15:54:41Z [INFO] Registering Instance with ECS
2016-08-15T15:54:41Z [INFO] Registered! module="api client"