Task networking with the awsvpc network mode

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 Amazon 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 Amazon Web Services Management Console. For more information, see Using service-linked roles for Amazon ECS. You can also create the service-linked role with the following Amazon CLI command:

aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com

Your Amazon EC2 Linux instance requires version 1.15.0 or later of the container agent to run tasks that use the awsvpc network mode. If you're using an Amazon ECS-optimized AMI, your instance needs at least version 1.15.0-4 of the ecs-init package as well.

Amazon ECS populates the hostname of the task with an Amazon-provided (internal) DNS hostname when both the enableDnsHostnames and enableDnsSupport options are enabled on your VPC. If these options aren't enabled, the DNS hostname of the task is set to a random hostname. For more information about the DNS settings for a VPC, see Using DNS with Your VPC in the Amazon VPC User Guide.

Each Amazon ECS task that uses the awsvpc network mode receives its own elastic network interface (ENI), which is attached to the Amazon EC2 instance that hosts it. There's a default quota for the number of network interfaces that can be attached to an Amazon EC2 Linux instance. The primary network interface counts as one toward that quota. For example, by default, a c5.large instance might have only up to three ENIs that can be attached to it. The primary network interface for the instance counts as one. As such, you can attach an additional two ENIs to the instance. Because each task that uses the awsvpc network mode requires an ENI, you can typically only run two such tasks on this instance type. For more information about 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 the launch of Amazon EC2 Linux instances that use supported instance types with increased ENI density. When you opt in to the awsvpcTrunking account setting and register Amazon EC2 Linux instances that use these instance types to your cluster, these instances have higher ENI quota. Using these instances with this higher quota means that you can place more tasks on each Amazon EC2 Linux instance. To use the increased ENI density with the trunking feature, your Amazon EC2 instance must use version 1.28.1 or later of the container agent. If you're using an Amazon ECS-optimized AMI, your instance also requires at least version 1.28.1-2 of the ecs-init package. For more information about opting in to the awsvpcTrunking account setting, see Account settings. For more information about ENI trunking, see Elastic network interface trunking.

When hosting tasks that use the awsvpc network mode on Amazon EC2 Linux instances, your task ENIs aren't given public IP addresses. To access the internet, tasks must be launched in a private subnet that's 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 a VPC that uses the private IP address or routed through a load balancer from within the VPC. Tasks that are launched within public subnets do not have access to the internet.

Amazon ECS recognizes only the ENIs that it attaches to your Amazon EC2 Linux instances. If you manually attached ENIs to your instances, Amazon ECS might attempt to add a task to an instance that doesn't have enough network adapters. This can result in the task timing out and moving to a deprovisioning status and then a stopped status. We recommend that you don't attach ENIs to your instances manually.

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

The ENIs that are created and attached to your Amazon EC2 Linux 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.

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.

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 running 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 only support Application Load Balancer and Network Load Balancer. When you create any target groups for these services, you must choose ip as the target type. Do not use instance. This is because tasks that use the awsvpc network mode are associated with an ENI, not with an Amazon EC2 Linux instance. For more information, see Service load balancing.

If your VPC is updated to change the DHCP options set it uses, you can't apply these changes to existing tasks. Start new tasks with these changes applied to them, verify that they are working correctly, and then stop the existing tasks in order to safely change these network configurations.

Container instances using the Amazon ECS optimized Windows Server 2016 AMI can't host tasks that use the awsvpc network mode. If you have a cluster that contains Amazon ECS optimized Windows Server 2016 AMIs and Windows AMIs that support awsvpc network mode, tasks that use awsvpc network mode aren't launched on the Windows 2016 Server instances. Rather, they're launched on instances that support awsvpc network mode.

Your Amazon EC2 Windows instance requires version 1.57.1 or later of the container agent to use CloudWatch metrics for Windows containers that use the awsvpc network mode.

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 Amazon 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 Amazon Web Services Management Console. For more information, see Using service-linked roles for Amazon ECS. You can also create the service-linked role with the following Amazon CLI command.

aws iam create-service-linked-role --aws-service-name ecs.amazonaws.com

Your Amazon EC2 Windows instance requires version 1.54.0 or later of the container agent to run tasks that use the awsvpc network mode. When you bootstrap the instance, you must configure the options that are required for awsvpc network mode. For more information, see Bootstrapping Windows container instances with Amazon EC2 user data.

Amazon ECS populates the hostname of the task with an Amazon provided (internal) DNS hostname when both the enableDnsHostnames and enableDnsSupport options are enabled on your VPC. If these options aren't enabled, the DNS hostname of the task is a random hostname. For more information about the DNS settings for a VPC, see Using DNS with Your VPC in the Amazon VPC User Guide.

Each Amazon ECS task that uses the awsvpc network mode receives its own elastic network interface (ENI), which is attached to the Amazon EC2 Windows instance that hosts it. There is a default quota for the number of network interfaces that can be attached to an Amazon EC2 Windows instance. The primary network interface counts as one toward this quota. For example, by default a c5.large instance might have only up to three ENIs attached to it. The primary network interface for the instance counts as one of those. As such, >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 about the default ENI limits for each instance type, see IP addresses per network interface per instance type in the Amazon EC2 User Guide for Windows Instances.

When hosting tasks that use the awsvpc network mode on Amazon EC2 Windows instances, your task ENIs aren't given public IP addresses. To access the internet, launch tasks in a private subnet that's 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 that is using the private IP address or routed through a load balancer from within the VPC. Tasks that are launched within public subnets don't have access to the internet.

Amazon ECS recognizes only the ENIs that it has attached to your Amazon EC2 Windows instance. If you manually attached ENIs to your instances, Amazon ECS might attempt to add a task to an instance that doesn't have enough network adapters. This can result in the task timing out and moving to a deprovisioning status and then a stopped status. We recommend that you don't attach ENIs to your instances manually.

Amazon EC2 Windows instances must be registered with the ecs.capability.task-eni capability to be considered for placement of tasks with the awsvpc network mode.

You can't manually modify or detach ENIs that are created and attached to your Amazon EC2 Windows instances. This is to prevent you from accidentally deleting an ENI that's associated with a running task. To release the ENIs for a task, stop the task.

You can only specify up to 16 subnets and 5 security groups in awsVpcConfiguration when you run a task or create a service that uses the awsvpc network mode. For more information, see AwsVpcConfiguration in the Amazon Elastic Container Service API Reference.

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 running 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 only support Application Load Balancer and Network Load Balancer. 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 Windows instance. For more information, see Service load balancing.

If your VPC is updated to change the DHCP options set it uses, you can't apply these changes to existing tasks. Start new tasks with these changes applied to them, verify that they are working correctly, and then stop the existing tasks in order to safely change these network configurations.

The following are not supported when you use awsvpc network mode in an EC2 Windows configuration: