Amazon ECS Container Instances
An Amazon ECS container instance is an Amazon EC2 instance that is running the Amazon ECS container agent and has been registered into a cluster. When you run tasks with Amazon ECS, your tasks are placed on your active container instances.
- Container Instance Concepts
- Container Instance Lifecycle
- Check the Instance Role for Your Account
- Container Instance AMIs
- Launching an Amazon ECS Container Instance
- Bootstrapping Container Instances with Amazon EC2 User Data
- Connect to Your Container Instance
- Using CloudWatch Logs with Container Instances
- Container Instance Draining
- Managing Container Instances Remotely
- Starting a Task at Container Instance Launch Time
- Deregister a Container Instance
Container Instance Concepts
Your container instance must be running the Amazon ECS container agent to register into one of your clusters. If you are using the Amazon ECS-optimized AMI, the agent is already installed. To use a different operating system, install the agent. For more information, see Amazon ECS Container Agent.
Because the Amazon ECS container agent makes calls to Amazon ECS on your behalf, you must launch container instances with an IAM role that authenticates to your account and provides the required resource permissions. For more information, see Amazon ECS Container Instance IAM Role.
If any of the containers associated with your tasks require external connectivity, you can map their network ports to ports on the host Amazon ECS container instance so they are reachable from the Internet. Your container instance security group must allow inbound access to the ports you want to expose. For more information, see Create a Security Group in the Amazon VPC Getting Started Guide.
We strongly recommend launching your container instances inside a VPC, because Amazon VPC delivers more control over your network and offers more extensive configuration capabilities. For more information, see Amazon EC2 and Amazon Virtual Private Cloud in the Amazon EC2 User Guide for Linux Instances.
Container instances need external network access to communicate with the Amazon ECS service endpoint. If your container instances do not have public IP addresses, then they must use network address translation (NAT) or an HTTP proxy to provide this access. For more information, see NAT Instances in the Amazon VPC User Guide and HTTP Proxy Configuration in this guide.
The type of EC2 instance that you choose for your container instances determines the resources available in your cluster. Amazon EC2 provides different instance types, each with different CPU, memory, storage, and networking capacity that you can use to run your tasks. For more information, see Amazon EC2 Instances.
Because each container instance has unique state information that is stored locally on the container instance and within Amazon ECS, they should not be deregistered from one cluster and re-registered into another. To relocate container instance resources, we recommend that you terminate container instances from one cluster and launch new container instances with the latest Amazon ECS-optimized AMI in the new cluster. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances and Launching an Amazon ECS Container Instance.
Because each container instance has unique state information that is stored locally on the container instance and within Amazon ECS, you cannot stop a container instance and change its instance type. Instead, we recommend that you terminate the container instance and launch a new container instance with the desired instance size and the latest Amazon ECS-optimized AMI in your desired cluster. For more information, see Terminate Your Instance in the Amazon EC2 User Guide for Linux Instances and Launching an Amazon ECS Container Instance in this guide.
Container Instance Lifecycle
When the Amazon ECS container agent registers an instance into your cluster, the container
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) an Amazon ECS 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
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. To update 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 Container Instance Draining.
If you deregister or terminate a container instance, the container instance status
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.
Check the Instance Role for Your Account
The Amazon ECS container agent makes calls to the Amazon ECS APIs on your behalf. Container instances that run the agent require an IAM policy and role for the service to know that the agent belongs to you.
In most cases, the Amazon ECS instance role is automatically created for you in the console first-run experience. You can use the following procedure to check and see if your account already has an Amazon ECS service role.
To check for the
ecsInstanceRole in the IAM console
Sign in to the IAM console at https://console.aws.amazon.com/iam/.
In the navigation pane, choose Roles.
Search the list of roles for
ecsInstanceRole. If the role exists, you do not need to create it. If the role does not exist, follow the procedures in Amazon ECS Container Instance IAM Role to create the role.