Elastic network interface trunking

• Only Linux variants of the Amazon ECS-optimized AMI, or other Amazon Linux variants with version 1.28.1 or later of the container agent and version 1.28.1-2 or later of the ecs-init package, support the increased ENI limits. If you use the latest Linux variant of the Amazon ECS-optimized AMI, these requirements will be met. Windows containers are not supported at this time.

• Only new Amazon EC2 instances launched after enabling awsvpcTrunking receive the increased ENI limits and the trunk network interface. Previously launched instances do not receive these features regardless of the actions taken.

• Amazon EC2 instances must have resource-based IPv4 DNS requests turned off. To disable this option, ensure the Enable resource-based IPV4 (A record) DNS requests option is deselected when creating a new instance using the Amazon EC2 console. To disable this option using the Amazon CLI, use the following command.

  aws ec2 modify-private-dns-name-options --instance-id i-xxxxxxx --no-enable-resource-name-dns-a-record --no-dry-run

• Amazon EC2 instances in shared subnets are not supported. They will fail to register to a cluster if they are used.

• Your Amazon ECS tasks must use the awsvpc network mode and the EC2 launch type. Tasks using the Fargate launch type always received a dedicated ENI regardless of how many are launched, so this feature is not needed.

• Your Amazon ECS tasks must be launched in the same Amazon VPC as your container instance. Your tasks will fail to start with an attribute error if they are not within the same VPC.

• When launching a new container instance, the instance transitions to a REGISTERING status while the trunk elastic network interface is provisioned for the instance. If the registration fails, the instance transitions to a REGISTRATION_FAILED status. You can troubleshoot a failed registration by describing the container instance to view the statusReason field which describes the reason for the failure. The container instance then can be manually deregistered or terminated. Once the container instance is successfully deregistered or terminated, Amazon ECS will delete the trunk ENI.

  Note

  Amazon ECS emits container instance state change events which you can monitor for instances that transition to a REGISTRATION_FAILED state. For more information, see Container instance state change events.

• Once the container instance is terminated, the instance transitions to a DEREGISTERING status while the trunk elastic network interface is deprovisioned. The instance then transitions to an INACTIVE status.

• If a container instance in a public subnet with the increased ENI limits is stopped and then restarted, the instance loses its public IP address, and the container agent loses its connection.

• When you enable awsvpcTrunking, container instances receive an additional ENI that uses the VPC's default security group, and is managed by Amazon ECS.

• The service-linked role for Amazon ECS must be created. The Amazon ECS service-linked role provides 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 account or container instance IAM role must enable the awsvpcTrunking account setting. This can be done in the following ways:

  • Any user can use the PutAccountSettingDefault API to enable all IAM users and roles on an account

  • A root user can use the PutAccountSetting API to enable the user or container instance role that will register the instance with the cluster

  • A container instance role can enable itself when the PutAccountSetting API is run on an instance prior to it being registered with a cluster

  For more information, see Account settings.

To enable all user or roles on your account to the increased ENI limits using the command line

Any user on an account can use one of the following commands to modify the default account setting for all IAM users or roles on your account. These changes apply to the entire Amazon account unless a user or role explicitly overrides these settings for themselves.

• put-account-setting-default (Amazon CLI)

  aws ecs put-account-setting-default \
  
        --name awsvpcTrunking \
        --value enabled \
        --region us-east-1

• Write-ECSAccountSettingDefault (Amazon Tools for Windows PowerShell)

  Write-ECSAccountSettingDefault -Name awsvpcTrunking -Value enabled -Region us-east-1 -Force

To enable a user or container instance IAM role to the increased ENI limits as the account owner using the command line

The account owner can use one of the following commands and specify the ARN of the principal user or container instance IAM role in the request to modify the account settings.

• put-account-setting (Amazon CLI)

  The following example is for modifying the account setting of a specific user:

  aws ecs put-account-setting \
        --name awsvpcTrunking \
        --value enabled \
        --principal-arn arn:aws:iam::aws_account_id:user/userName \
        --region us-east-1

  The following example is for modifying the account setting of a specific container instance IAM role:

  aws ecs put-account-setting \
        --name awsvpcTrunking \
        --value enabled \
        --principal-arn arn:aws:iam::aws_account_id:role/ecsInstanceRole \
        --region us-east-1

• Write-ECSAccountSetting (Amazon Tools for Windows PowerShell)

  The following example is for modifying the account setting of a specific user:

  Write-ECSAccountSetting -Name awsvpcTrunking -Value enabled -PrincipalArn arn:aws:iam::aws_account_id:user/userName -Region us-east-1 -Force

  The following example is for modifying the account setting of a specific container instance IAM role:

  Write-ECSAccountSetting -Name awsvpcTrunking -Value enabled -PrincipalArn arn:aws:iam::aws_account_id:role/ecsInstanceRole -Region us-east-1 -Force

To view your container instances with increased ENI limits with the Amazon CLI

Each container instance has a default network interface, referred to as a trunk network interface. Use the following command to list your container instances with increased ENI limits by querying for the ecs.awsvpc-trunk-id attribute, which indicates it has a trunk network interface.

• list-attributes (Amazon CLI)

  aws ecs list-attributes \
        --target-type container-instance \
        --attribute-name ecs.awsvpc-trunk-id \
        --cluster cluster_name \
        --region us-east-1

• Get-ECSAttributeList (Amazon Tools for Windows PowerShell)

  Get-ECSAttributeList -TargetType container-instance -AttributeName ecs.awsvpc-trunk-id -Region us-east-1