# Amazon ECS EC2 Container Instances
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.
**Note**
On Linux container instances, the agent container mounts top-level directories such as `/lib`, `/lib64`, and `/proc`. This is necessary for ECS features and functionalities such as Amazon EBS volumes, `awsvpc` network mode, Amazon ECS Service Connect, and FireLens for 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](ecs-agent-update.md).
The Amazon ECS container agent contains the `amazon-ecs-pause` image.Amazon ECS uses this image for tasks that use `awsvpc` network mode.
To see which features and enhancements are included with each agent release, see [https://github.com/aws/amazon-ecs-agent/releases](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 `18.01.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.
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](container-instance-draining.md).
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.
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](https://docs.aws.amazon.com/autoscaling/ec2/userguide/lifecycle-hooks.html) for more information about Auto Scaling lifecycle hooks.
## Docker Support
Amazon ECS supports the last two major versions of Docker published on Amazon Linux. Currently, this includes Docker 20.10.x and Docker 25.x.
The minimum required Docker version for Amazon ECS can be found in the [Amazon ECS Agent specification file](https://github.com/aws/amazon-ecs-agent/blob/dev/packaging/amazon-linux-ami-integrated/ecs-agent.spec#L53) on GitHub.
When using the Amazon ECS-optimized AMI, Docker is pre-installed and configured to work with the Amazon ECS container agent. The AMI includes a Docker version that is tested and supported by Amazon ECS.
**Note**
While Amazon ECS supports multiple Docker versions, we recommend using the Docker version that comes with the Amazon ECS-optimized AMI for the best compatibility and support.
## Amazon ECS-optimized AMI
For more information about the Amazon ECS-optimized AMI, see [Amazon ECS-optimized Linux AMIs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html).
## Additional information
The following pages provide additional information about the changes:
+ [Amazon ECS Agent changelog](https://github.com/aws/amazon-ecs-agent/blob/master/CHANGELOG.md) on GitHub
+ [Amazon Linux 2 release notes](https://docs.aws.amazon.com/AL2/latest/relnotes/relnotes-al2.html).
+ [Docker Engine release notes](https://docs.docker.com/engine/release-notes/27/) in the Docker documentation
+ [NVIDIA Driver Documentation](https://docs.nvidia.com/datacenter/tesla/index.html) in the NVIDIA documentation
# Amazon ECS container agent configuration
**Applies to**: EC2 instances
The Amazon ECS container agent supports a number of configuration options, most of which you set through environment variables.
If your container instance was launched with a Linux variant of 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 Amazon ECS Linux container instances to pass data](bootstrap_container_instance.md).
If your container instance was launched with a Windows variant of the Amazon ECS-optimized AMI, you can set these environment variables with the PowerShell SetEnvironmentVariable command and then restart the agent. For more information, see [Run commands when you launch an EC2 instance with user data input](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html) in the *Amazon EC2 User Guide* and [Bootstrapping Amazon ECS Windows container instances to pass data](bootstrap_windows_container_instance.md).
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. Use these variables 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. You can use the following commands to add the variables.
```
sudo systemctl stop ecs
sudo vi /etc/ecs/ecs.config
# And add the environment variables with VARIABLE_NAME=VARIABLE_VALUE format.
sudo systemctl start ecs
```
## Run the Amazon ECS agent with the host PID namespace
By default, the Amazon ECS agent runs with its own PID namespace. In the following configurations, you can configure the Amazon ECS agent to run with the host PID namespace:
+ SELinux enforcing mode is enabled.
+ Docker's SELinux security policy is set to true.
You can configure this behavior by setting the `ECS_AGENT_PID_NAMESPACE_HOST` environment variable to `true` in your `/etc/ecs/ecs.config` file. When this variable is enabled, `ecs-init` will start the Amazon ECS agent container with the host's PID namespace (`--pid=host`), allowing the agent to bootstrap itself properly in SELinux-enforcing environments. This feature is available in Amazon ECS agent version `1.94.0` and later.
To enable this feature, add the following line to your `/etc/ecs/ecs.config` file:
```
ECS_AGENT_PID_NAMESPACE_HOST=true
```
After making this change, restart the Amazon ECS agent for the change to take effect:
```
sudo systemctl restart ecs
```
The following features will not work SELinux enforcing mode is enabled and the Docker security policy is set to true, even when `ECS_AGENT_PID_NAMESPACE_HOST=true` is set.
+ Amazon ECS Exec
+ Amazon EBS task attach
+ Service Connect
+ FireLens for Amazon ECS
## Available parameters
For information about the available Amazon ECS container agent configuration parameters, see [Amazon ECS Container Agent](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
# Storing Amazon ECS container instance configuration in Amazon S3
Amazon ECS container agent configuration is controlled with the environment variable. Linux variants of the Amazon ECS-optimized AMI look for these variables in `/etc/ecs/ecs.config` when the container agent starts and configure the agent accordingly. Non-sensative environment variables, such as `ECS_CLUSTER`, can be passed to the container instance at launch 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 would allow them to 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. You can store a copy of your `ecs.config` file in a private bucket. You can 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 store an `ecs.config` file in Amazon S3**
1. You must grant the container instance role (**ecsInstanceRole**) permissions to have read only access to Amazon S3. You can do this by assigning the **AmazonS3ReadOnlyAccess** to the `ecsInstanceRole` role. For information about how to attach a policy to a role, see [Update permissions for a role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_update-role-permissions.html) in the *AWS Identity and Access Management User Guide*
1. Create an `ecs.config` file with valid Amazon ECS agent configuration variables using the following format. This example configures private registry authentication. For more information, see [Using non-AWS container images in Amazon ECS](private-auth.md).
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
```
**Note**
For a full list of available Amazon ECS agent configuration variables, see [Amazon ECS Container Agent](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
1. To store your configuration file, create a private bucket in Amazon S3. For more information, see [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) in the *Amazon Simple Storage Service User Guide*.
1. Upload the `ecs.config` file to your S3 bucket. For more information, see [Uploading objects](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html) in the *Amazon Simple Storage Service User Guide*.
**To load an `ecs.config` file from Amazon S3 at launch**
1. Complete the earlier procedures in this section to allow read-only Amazon S3 access to your container instances and store an `ecs.config` file in a private S3 bucket.
1. Launch new container instances and use the following example script in the EC2 User data. The script installs the AWS CLI and copies your configuration file to `/etc/ecs/ecs.config`. For more information, see [Launching an Amazon ECS Linux container instance](launch_container_instance.md).
```
#!/bin/bash
yum install -y aws-cli
aws s3 cp s3://your_bucket_name/ecs.config /etc/ecs/ecs.config
```
# Installing the Amazon ECS container agent
If you want to register an Amazon EC2 instance with your Amazon ECS cluster and that instance is not using an AMI based on the Amazon ECS-optimized AMI, you can install the Amazon ECS container agent manually using the following procedure. To do this, you can either download the agent from one of the regional Amazon S3 buckets or from Amazon Elastic Container Registry Public. If you download from one of the regional Amazon S3 buckets, you can optionally verify the validity of the container agent file using the PGP signature.
**Note**
The `systemd` units for both Amazon ECS and Docker services have a directive to wait for `cloud-init` to finish before starting both services. The `cloud-init` process is not considered finished until your Amazon EC2 user data has finished running. Therefore, starting Amazon ECS or Docker via Amazon EC2 user data may cause a deadlock. To start the container agent using Amazon EC2 user data you can use `systemctl enable --now --no-block ecs.service`.
## Installing the Amazon ECS container agent on a non-Amazon Linux EC2 instance
To install the Amazon ECS container agent on an Amazon EC2 instance, you can download the agent from one of the regional Amazon S3 buckets and install it.
**Note**
When using a non-Amazon Linux AMI, your Amazon EC2 instance requires `cgroupfs` support for the `cgroup` driver in order for the Amazon ECS agent to support task level resource limits. For more information, see [Amazon ECS agent on GitHub](https://github.com/aws/amazon-ecs-agent).
The latest Amazon ECS container agent files, by Region, for each system architecture are listed below for reference.
| Region | Region name | Amazon ECS init deb files | Amazon ECS init rpm files |
| --- | --- | --- | --- |
| us-east-2 | US East (Ohio) | [Amazon ECS init amd64](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-east-2.amazonaws.com/amazon-ecs-agent-us-east-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-east-1 | US East (N. Virginia) | [Amazon ECS init amd64](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-east-1.amazonaws.com/amazon-ecs-agent-us-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-west-1 | US West (N. California) | [Amazon ECS init amd64](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-west-1.amazonaws.com/amazon-ecs-agent-us-west-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-west-2 | US West (Oregon) | [Amazon ECS init amd64](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-east-1 | Asia Pacific (Hong Kong) | [Amazon ECS init amd64](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-east-1.amazonaws.com/amazon-ecs-agent-ap-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-northeast-1 | Asia Pacific (Tokyo) | [Amazon ECS init amd64](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-northeast-1.amazonaws.com/amazon-ecs-agent-ap-northeast-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-northeast-2 | Asia Pacific (Seoul) | [Amazon ECS init amd64](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-northeast-2.amazonaws.com/amazon-ecs-agent-ap-northeast-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-south-1 | Asia Pacific (Mumbai) | [Amazon ECS init amd64](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-south-1.amazonaws.com/amazon-ecs-agent-ap-south-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-southeast-1 | Asia Pacific (Singapore) | [Amazon ECS init amd64](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-southeast-1.amazonaws.com/amazon-ecs-agent-ap-southeast-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ap-southeast-2 | Asia Pacific (Sydney) | [Amazon ECS init amd64](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ap-southeast-2.amazonaws.com/amazon-ecs-agent-ap-southeast-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| ca-central-1 | Canada (Central) | [Amazon ECS init amd64](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.ca-central-1.amazonaws.com/amazon-ecs-agent-ca-central-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-central-1 | Europe (Frankfurt) | [Amazon ECS init amd64](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-central-1.amazonaws.com/amazon-ecs-agent-eu-central-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-west-1 | Europe (Ireland) | [Amazon ECS init amd64](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-west-1.amazonaws.com/amazon-ecs-agent-eu-west-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-west-2 | Europe (London) | [Amazon ECS init amd64](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-west-2.amazonaws.com/amazon-ecs-agent-eu-west-2/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| eu-west-3 | Europe (Paris) | [Amazon ECS init amd64](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.eu-west-3.amazonaws.com/amazon-ecs-agent-eu-west-3/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| sa-east-1 | South America (São Paulo) | [Amazon ECS init amd64](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.x86_64.rpm) [Amazon ECS init aarch64](https://s3.sa-east-1.amazonaws.com/amazon-ecs-agent-sa-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-gov-east-1 | AWS GovCloud (US-East) | [Amazon ECS init amd64](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-gov-east-1.amazonaws.com/amazon-ecs-agent-us-gov-east-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
| us-gov-west-1 | AWS GovCloud (US-West) | [Amazon ECS init amd64](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.amd64.deb) (amd64) [Amazon ECS init arm64](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.arm64.deb) (arm64) | [Amazon ECS init x86\$164](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.x86_64.rpm) (x86\$164) [Amazon ECS init aarch64](https://s3.us-gov-west-1.amazonaws.com/amazon-ecs-agent-us-gov-west-1/amazon-ecs-init-latest.aarch64.rpm) (aarch64) |
**To install the Amazon ECS container agent on an Amazon EC2 instance using a non-Amazon Linux AMI**
1. Launch an Amazon EC2 instance with an IAM role that allows access to Amazon ECS. For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md).
1. Connect to your instance.
1. Install the latest version of Docker on your instance.
1. Check your Docker version to verify that your system meets the minimum version requirement. For more information about Docker support, see [Amazon ECS EC2 Container Instances](ecs-agent-versions.md).
```
docker --version
```
1. Download the appropriate Amazon ECS agent file for your operating system and system architecture and install it.
For `deb` architectures:
```
ubuntu:~$ curl -O https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.amd64.deb
ubuntu:~$ sudo dpkg -i amazon-ecs-init-latest.amd64.deb
```
For `rpm` architectures:
```
fedora:~$ curl -O https://s3.us-west-2.amazonaws.com/amazon-ecs-agent-us-west-2/amazon-ecs-init-latest.x86_64.rpm
fedora:~$ sudo yum localinstall -y amazon-ecs-init-latest.x86_64.rpm
```
1. Edit the `/lib/systemd/system/ecs.service` file and add the following line at the end of the `[Unit]` section.
```
After=cloud-final.service
```
1. (Optional) To register the instance with a cluster other than the `default` cluster, edit the `/etc/ecs/ecs.config` file and add the following contents. The following example specifies the `MyCluster` cluster.
```
ECS_CLUSTER=MyCluster
```
For more information about these and other agent runtime options, see [Amazon ECS container agent configuration](ecs-agent-config.md).
**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 Amazon ECS container instance configuration in Amazon S3](ecs-config-s3.md) and [Using non-AWS container images in Amazon ECS](private-auth.md).
1. Start the `ecs` service.
```
ubuntu:~$ sudo systemctl start ecs
```
## Running the Amazon ECS agent with host network mode
When running the Amazon ECS container agent, `ecs-init` will create the container agent container with the `host` network mode. This is the only supported network mode for the container agent container.
This allows you to block access to the [Amazon EC2 instance metadata service endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) (`http://169.254.169.254`) for the containers started by the container agent. This ensures that containers cannot access IAM role credentials from the container instance profile and enforces that tasks use only the IAM task role credentials. For more information, see [Amazon ECS task IAM role](task-iam-roles.md).
This also makes it so the container agent doesn't contend for connections and network traffic on the `docker0` bridge.
## 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 detailed information about all available configuration parameters, see [Amazon ECS container agent configuration](ecs-agent-config.md) or the [Amazon ECS Agent README](https://github.com/aws/amazon-ecs-agent/blob/master/README.md) on GitHub.
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"}
```
# Configuring Amazon ECS container instances for private Docker images
The Amazon ECS container agent can authenticate with private registries, using basic authentication. When you enable private registry authentication, you can use private Docker images in your task definitions. This feature is only supported by tasks using EC2.
Another method of enabling private registry authentication uses AWS Secrets Manager to store your private registry credentials securely and then reference them in your container definition. This allows your tasks to use images from private repositories. This method supports tasks using either EC2 or Fargate. For more information, see [Using non-AWS container images in Amazon ECS](private-auth.md).
The Amazon ECS container agent looks for two environment variables when it launches:
+ `ECS_ENGINE_AUTH_TYPE`, which specifies the type of authentication data that is being sent.
+ `ECS_ENGINE_AUTH_DATA`, which contains the actual authentication credentials.
Linux variants of the Amazon ECS-optimized AMI scan the `/etc/ecs/ecs.config` file for these variables when the container instance launches, and each time the service is started (with the **sudo start ecs** command). AMIs that are not Amazon ECS-optimized should store these environment variables in a file and pass them with the `--env-file path_to_env_file` option to the **docker run** command that starts the container agent.
**Important**
We do not recommend that you inject these authentication environment variables at instance launch with Amazon EC2 user data or pass them with the `--env` option to the **docker run** command. These methods are not appropriate for sensitive data, such as authentication credentials. For information about safely adding authentication credentials to your container instances, see [Storing Amazon ECS container instance configuration in Amazon S3](ecs-config-s3.md).
## Authentication formats
There are two available formats for private registry authentication, `dockercfg` and `docker`.
**dockercfg authentication format**
The `dockercfg` format uses the authentication information stored in the configuration file that is created when you run the **docker login** command. You can create this file by running **docker login** on your local system and entering your registry user name, password, and email address. You can also log in to a container instance and run the command there. Depending on your Docker version, this file is saved as either `~/.dockercfg` or `~/.docker/config.json`.
```
cat ~/.docker/config.json
```
Output:
```
{
"auths": {
"https://index.docker.io/v1/": {
"auth": "zq212MzEXAMPLE7o6T25Dk0i"
}
}
}
```
**Important**
Newer versions of Docker create a configuration file as shown above with an outer `auths` object. The Amazon ECS agent only supports `dockercfg` authentication data that is in the below format, without the `auths` object. If you have the **jq** utility installed, you can extract this data with the following command: **cat \$1/.docker/config.json \$1 jq .auths**
```
cat ~/.docker/config.json | jq .auths
```
Output:
```
{
"https://index.docker.io/v1/": {
"auth": "zq212MzEXAMPLE7o6T25Dk0i",
"email": "email@example.com"
}
}
```
In the above example, the following environment variables should be added to the environment variable file (`/etc/ecs/ecs.config` for the Amazon ECS-optimized AMI) that the Amazon ECS container agent loads at runtime. If you are not using an Amazon ECS-optimized AMI and you are starting the agent manually with **docker run**, specify the environment variable file with the `--env-file path_to_env_file` option when you start the agent.
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example.com"}}
```
You can configure multiple private registries with the following syntax:
```
ECS_ENGINE_AUTH_TYPE=dockercfg
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"auth":"zq212MzEXAMPLE7o6T25Dk0i","email":"email@example-01.com"},"repo.example-02.com":{"auth":"fQ172MzEXAMPLEoF7225DU0j","email":"email@example-02.com"}}
```
**docker authentication format**
The `docker` format uses a JSON representation of the registry server that the agent should authenticate with. It also includes the authentication parameters required by that registry (such as user name, password, and the email address for that account). For a Docker Hub account, the JSON representation looks like the following:
```
{
"https://index.docker.io/v1/": {
"username": "my_name",
"password": "my_password",
"email": "email@example.com"
}
}
```
In this example, the following environment variables should be added to the environment variable file (`/etc/ecs/ecs.config` for the Amazon ECS-optimized AMI) that the Amazon ECS container agent loads at runtime. If you are not using an Amazon ECS-optimized AMI, and you are starting the agent manually with **docker run**, specify the environment variable file with the `--env-file path_to_env_file` option when you start the agent.
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
```
You can configure multiple private registries with the following syntax:
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"repo.example-01.com":{"username":"my_name","password":"my_password","email":"email@example-01.com"},"repo.example-02.com":{"username":"another_name","password":"another_password","email":"email@example-02.com"}}
```
## Procedure
Use the following procedure to turn on private registries for your container instances.
**To enable private registries in the Amazon ECS-optimized AMI**
1. Log in to your container instance using SSH.
1. Open the `/etc/ecs/ecs.config` file and add the `ECS_ENGINE_AUTH_TYPE` and `ECS_ENGINE_AUTH_DATA` values for your registry and account:
```
sudo vi /etc/ecs/ecs.config
```
This example authenticates a Docker Hub user account:
```
ECS_ENGINE_AUTH_TYPE=docker
ECS_ENGINE_AUTH_DATA={"https://index.docker.io/v1/":{"username":"my_name","password":"my_password","email":"email@example.com"}}
```
1. Check to see if your agent uses the `ECS_DATADIR` environment variable to save its state:
```
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 stopping the agent. Newer agents with the `ECS_DATADIR` environment variable save their state and you can stop and start them while tasks are running without issues. For more information, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
1. Stop the `ecs` service:
```
sudo stop ecs
```
Output:
```
ecs stop/waiting
```
1. Restart the `ecs` service.
+ For the Amazon ECS-optimized Amazon Linux 2 AMI:
```
sudo systemctl restart ecs
```
+ For the Amazon ECS-optimized Amazon Linux AMI:
```
sudo stop ecs && sudo start ecs
```
1. (Optional) You can verify that the agent is running and see some information about your new container instance by querying the agent introspection API operation. For more information, see [Amazon ECS container introspection](ecs-agent-introspection.md).
```
curl http://localhost:51678/v1/metadata
```
# Automatic Amazon ECS task and image cleanup
Each time a task is placed on a container instance, the Amazon ECS container agent checks to see if the images referenced in the task are the most recent of the specified tag in the repository. If not, the default behavior allows the agent to pull the images from their respective repositories. If you frequently update the images in your tasks and services, your container instance storage can quickly fill up with Docker images that you are no longer using and may never use again. For example, you may use a continuous integration and continuous deployment (CI/CD) pipeline.
**Note**
The Amazon ECS agent image pull behavior can be customized using the `ECS_IMAGE_PULL_BEHAVIOR` parameter. For more information, see [Amazon ECS container agent configuration](ecs-agent-config.md).
Likewise, containers that belong to stopped tasks can also consume container instance storage with log information, data volumes, and other artifacts. These artifacts are useful for debugging containers that have stopped unexpectedly, but most of this storage can be safely freed up after a period of time.
By default, the Amazon ECS container agent automatically cleans up stopped tasks and Docker images that are not being used by any tasks on your container instances.
**Note**
The automated image cleanup feature requires at least version 1.13.0 of the Amazon ECS container agent. To update your agent to the latest version, see [Updating the Amazon ECS container agent](ecs-agent-update.md).
The following agent configuration variables are available to tune your automated task and image cleanup experience. For more information about how to set these variables on your container instances, see [Amazon ECS container agent configuration](ecs-agent-config.md).
`ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION`
The default time to wait to delete containers for a stopped task. If the value is set to less than 1 second, the value is ignored. By default, this parameter is set to 3 hours, but you can reduce this period to as low as 1 second if you need to for your application.
The image cleanup process cannot delete an image as long as there is a container that references it. After containers are removed, any unreferenced images become candidates for cleanup based on the image cleanup configuration parameters.
`ECS_DISABLE_IMAGE_CLEANUP`
If you set this variable to `true`, then automated image cleanup is turned off on your container instance and no images are automatically removed.
`ECS_IMAGE_CLEANUP_INTERVAL`
This variable specifies how frequently the automated image cleanup process should check for images to delete. The default is every 30 minutes but you can reduce this period to as low as 10 minutes to remove images more frequently.
`ECS_IMAGE_MINIMUM_CLEANUP_AGE`
This variable specifies the minimum amount of time between when an image was pulled and when it may become a candidate for removal. This is used to prevent cleaning up images that have just been pulled. The default is 1 hour.
`ECS_NUM_IMAGES_DELETE_PER_CYCLE`
This variable specifies how many images may be removed during a single cleanup cycle. The default is 5 and the minimum is 1.
When the Amazon ECS container agent is running and automated image cleanup is not turned off, the agent checks for Docker images that are not referenced by running or stopped containers at a frequency determined by the `ECS_IMAGE_CLEANUP_INTERVAL` variable. If unused images are found and they are older than the minimum cleanup time specified by the `ECS_IMAGE_MINIMUM_CLEANUP_AGE` variable, the agent removes up to the maximum number of images that are specified with the `ECS_NUM_IMAGES_DELETE_PER_CYCLE` variable. The least-recently referenced images are deleted first. After the images are removed, the agent waits until the next interval and repeats the process again.