Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

Task Networking with the awsvpc Network Mode

The task networking features provided by the awsvpc network mode give Amazon ECS tasks the same networking properties as Amazon EC2 instances. When you use the awsvpc network mode in your task definitions, every task that is launched from that task definition gets its own elastic network interface (ENI), a primary private IP address, and an internal DNS hostname. The task networking feature simplifies container networking and gives you more control over how containerized applications communicate with each other and other services within your VPCs.

Note

For information about the other available network modes for tasks, see Network Mode.

Task networking also provides greater security for your containers by allowing you to use security groups and network monitoring tools at a more granular level within your tasks. Because each task gets its own ENI, you can also take advantage of other Amazon EC2 networking features like VPC Flow Logs so that you can monitor traffic to and from your tasks. Additionally, containers that belong to the same task can communicate over the localhost interface. A task can only have one ENI associated with it at a given time.

The task ENI that is created is fully managed by Amazon ECS. Amazon ECS creates the ENI and attaches it to the container instance with the specified security group. The task sends and receives network traffic on the ENI in the same way that Amazon EC2 instances do with their primary network interfaces. These ENIs are visible in the Amazon EC2 console for your account, but they cannot be detached manually or modified by your account. This is to prevent accidental deletion of an ENI that is associated with a running task. You can view the ENI attachment information for tasks in the Amazon ECS console or with the DescribeTasks API operation. When the task stops or if the service is scaled down, the task ENI is detached and deleted.

If your account, IAM user, or role has opted in to the awsvpcTrunking account setting and you have launched a container instance with the increased ENI density, Amazon ECS also creates and attaches a "trunk" network interface for your container instance. The trunk network is fully managed by Amazon ECS. The trunk ENI is deleted when you either terminate or deregister your container instance from the Amazon ECS cluster. For more information on optin in to the awsvpcTrunking account setting, see Account Settings. For more information on ENI trunking, see Elastic Network Interface Trunking.

Task Networking Considerations

There are several things to consider when using task networking.

  • Tasks and services that use the awsvpc network mode require the Amazon ECS service-linked role to provide Amazon ECS with the permissions to make calls to other AWS services on your behalf. This role is created for you automatically when you create a cluster, or if you create or update a service in the AWS Management Console. For more information, see Using Service-Linked Roles for Amazon ECS. You can also create the service-linked role with the following AWS CLI command:

    aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com
  • Amazon ECS allows the launch of container instances using supported Amazon EC2 instance types with increased ENI density. When you use these instance types and opt in to the awsvpcTrunking account setting, newly launched container instances have higher ENI limits. This configuration allows you to place more tasks on each container instance. For more information on optin in to the awsvpcTrunking account setting, see Account Settings. For more information on ENI trunking, see Elastic Network Interface Trunking.

  • Your Amazon ECS container instances require at least version 1.15.0 of the container agent to enable task networking. To take advantage of the increased ENI density with the trunking feature, your container instances require at least version 1.28.1 of the container agent. However, we recommend using the latest container agent version. For information about checking your agent version and updating to the latest version, see Updating the Amazon ECS Container Agent. If you are using an Amazon ECS-optimized AMI, your instance needs at least version 1.15.0-4 (or 1.28.1-2 for the ENI trunking feature) of the ecs-init package. For more information, see Amazon ECS-optimized AMIs.

  • Currently, only Linux variants of the Amazon ECS-optimized AMI, or other Amazon Linux variants with the ecs-init package, support task networking.

  • The awsvpc network mode does not provide task ENIs with public IP addresses for tasks that use the EC2 launch type. To access the internet, tasks that use the EC2 launch type must be launched in a private subnet that is configured to use a NAT gateway. For more information, see NAT Gateways in the Amazon VPC User Guide. Inbound network access must be from within the VPC using the private IP address or DNS hostname, or routed through a load balancer from within the VPC. Tasks launched within public subnets do not have outbound network access.

    Note

    The above limitation does not apply to tasks that use the Fargate launch type. You can configure these tasks to receive public IP addresses.

  • Each Amazon ECS task that uses the awsvpc network mode receives its own ENI, which is attached to the container instance that hosts it. There is a default limit to the number of network interfaces that can be attached to an Amazon EC2 instance, and the primary network interface counts as one. For example, by default a c5.large instance may have up to three ENIs attached to it. The primary network interface for the instance counts as one, so you can attach an additional two ENIs to the instance. Because each task using the awsvpc network mode requires an ENI, you can typically only run two such tasks on this instance type. For more information on the default ENI limits for each instance type, see IP Addresses Per Network Interface Per Instance Type in the Amazon EC2 User Guide for Linux Instances.

  • Amazon ECS supports launching container instances with increased ENI density using supported Amazon EC2 instance types. When you use these instance types and opt in to the awsvpcTrunking account setting, additional ENIs are available on newly launched container instances. This configuration allows you to place more tasks using the awsvpc network mode on each container instance. Using this feature, a c5.large instance with awsvpcTrunking enabled has an increased ENI limit of twelve. The container instance will have the primary network interface and Amazon ECS creates and attaches a "trunk" network interface to the container instance. So this configuration allows you to launch ten tasks on the container instance instead of the current two tasks. For more information, see Elastic Network Interface Trunking.

  • There is a limit of 16 subnets and 5 security groups that are able to be specified in the awsvpcConfiguration when running a task or creating a service that uses the awsvpc network mode. For more information, see AwsVpcConfiguration in the Amazon Elastic Container Service API Reference.

  • Amazon ECS only accounts for the ENIs that it attaches to your container instances for you. If you have attached ENIs to your container instances manually, then Amazon ECS could try to place a task on an instance with too few available network adapter attachments. In this case, the task would time out, move from PROVISIONING to DEPROVISIONING, and then to STOPPED. We recommend that you do not attach ENIs to your container instances manually.

  • Container instances must be registered with the ecs.capability.task-eni to be considered for placement of tasks with the awsvpc network mode. Container instances running version 1.15.0-4 or later of ecs-init are registered with this attribute.

  • The ENIs that are created and attached to your container instances cannot be detached manually or modified by your account. This is to prevent the accidental deletion of an ENI that is associated with a running task. To release the ENIs for a task, stop the task.

  • When a task is started with the awsvpc network mode, the Amazon ECS container agent creates an additional pause container for each task before starting the containers in the task definition. It then configures the network namespace of the pause container by executing the amazon-ecs-cni-plugins CNI plugins. The agent then starts the rest of the containers in the task so that they share the network stack of the pause container. This means that all containers in a task are addressable by the IP addresses of the ENI, and they can communicate with each other over the localhost interface.

  • Services with tasks that use the awsvpc network mode, such as those with the Fargate launch type, only support Application Load Balancers and Network Load Balancers; Classic Load Balancers are not supported. Also, when you create any target groups for these services, you must choose ip as the target type, not instance. This is because tasks that use the awsvpc network mode are associated with an ENI, not with an Amazon EC2 instance. For more information, see Service Load Balancing.

Enabling Task Networking

In order for tasks to use task networking you must specify the awsvpc network mode in your task definition. For more information, see Network Mode. Then, when you run a task or create a service, specify a network configuration that includes one or more subnets in which to place your tasks and one or more security groups to attach to its associated ENI. The tasks are placed on valid container instances in the same Availability Zones as those subnets, and the specified security groups are associated with the ENI that is provisioned for the task.