Amazon ECS task placement constraints
A task placement constraint is a rule that's considered
during task placement. At least one container instance must match the constraint. If
there are no instances that match the constraint, the task remains in a
PENDING
state. When you create a new service or update an existing
one, you can specify task placement constraints for the service's tasks. You can
also specify task placement constraints for standalone tasks. For more information,
see Amazon ECS task placement.
Constraints consists of a constraint type and a expression in the cluster query language. The constraint type is required, but the expression is optional.
Constraint types
Amazon ECS supports the following types of task placement constraints:
distinctInstance
-
Place each task on a different container instance. This task placement constraint can be specified when either running a task or creating a new service.
memberOf
-
Place tasks on container instances that satisfy an expression. For more information about the expression syntax for constraints, see Cluster query language.
The
memberOf
task placement constraint can be specified with the following actions:-
Running a task
-
Creating a new service
-
Creating a new task definition
-
Creating a new revision of an existing task definition
-
Attributes
You can add custom metadata to your container instances, known as attributes. Each attribute has a name and an optional string value. You can use the built-in attributes provided by Amazon ECS or define custom attributes.
The following sections contain sample built-in, optional, and custom attributes.
Built-in attributes
Amazon ECS automatically applies the following attributes to your container instances.
ecs.ami-id
-
The ID of the AMI used to launch the instance. An example value for this attribute is
ami-1234abcd
. ecs.availability-zone
-
The Availability Zone for the instance. An example value for this attribute is
us-east-1a
. ecs.instance-type
-
The instance type for the instance. An example value for this attribute is
g2.2xlarge
. ecs.os-type
-
The operating system for the instance. The possible values for this attribute are
linux
andwindows
. ecs.os-family
-
The operating system version for the instance.
For Linux instances, the valid value is
LINUX
. For Windows instances, ECS sets the value in theWINDOWS_SERVER_<
format. The valid values areOS_Release
>_<FULL or CORE
>WINDOWS_SERVER_2022_FULL
,WINDOWS_SERVER_2022_CORE
,WINDOWS_SERVER_20H2_CORE
,WINDOWS_SERVER_2019_FULL
,WINDOWS_SERVER_2019_CORE
, andWINDOWS_SERVER_2016_FULL
.This is important for Windows containers and Windows containers on AWS Fargate because the OS version of every Windows container must match that of the host. If the Windows version of the container image is different than the host, the container doesn't start. For more information, see Windows container version compatibility
on the Microsoft documentation website. If your cluster runs multiple Windows versions, you can ensure that a task is placed on an EC2 instance running on the same version by using the placement constraint:
memberOf(attribute:ecs.os-family == WINDOWS_SERVER_<OS_Release>_<FULL or CORE>)
. For more information, see Retrieving Amazon ECS-Optimized AMI metadata. ecs.cpu-architecture
-
The CPU architecture for the instance. Example values for this attribute are
x86_64
andarm64
. ecs.vpc-id
-
The VPC the instance was launched into. An example value for this attribute is
vpc-1234abcd
. ecs.subnet-id
-
The subnet the instance is using. An example value for this attribute is
subnet-1234abcd
.
Optional attributes
Amazon ECS may add the following attributes to your container instances.
ecs.awsvpc-trunk-id
-
If this attribute exists, the instance has a trunk network interface. For more information, see Elastic network interface trunking.
ecs.outpost-arn
-
If this attribute exists, it contains the Amazon Resource Name (ARN) of the Outpost. For more information, see Amazon Elastic Container Service on AWS Outposts.
ecs.capability.external
-
If this attribute exists, the instance is identified as an external instance. For more information, see External instances (Amazon ECS Anywhere).
Custom attributes
You can apply custom attributes to your container instances. For example, you can define an attribute with the name "stack" and a value of "prod".
When specifying custom attributes, you must consider the following.
-
The
name
must contain between 1 and 128 characters and name may contain letters (uppercase and lowercase), numbers, hyphens, underscores, forward slashes, back slashes, or periods. -
The
value
must contain between 1 and 128 characters and may contain letters (uppercase and lowercase), numbers, hyphens, underscores, periods, at signs (@), forward slashes, back slashes, colons, or spaces. The value can't contain any leading or trailing whitespace.
Adding an attribute using the classic console
You can add custom attributes at instance registration time using the container agent or manually, using the AWS Management Console. For more information about container agent attributes, Amazon ECS container agent configuration
To add custom attributes using the classic console
Open the Amazon ECS classic console at https://console.aws.amazon.com/ecs/
. -
In the navigation pane, choose Clusters and select a cluster.
-
On the ECS Instances tab, select the check box for the container instance.
-
Choose Actions, View/Edit Attributes.
-
For each attribute, do the following:
-
Choose Add attribute.
-
Enter a name and a value for the attribute and choose the checkmark icon.
-
-
When you're finished adding attributes, choose Close.
Adding custom attributes using the AWS CLI
The following examples demonstrate how to add custom attributes using the put-attributes command.
Example: Single Attribute
The following example adds the custom attribute "stack=prod" to the specified container instance in the default cluster.
aws ecs put-attributes --attributes name=stack,value=prod,targetId=
arn
Example: Multiple Attributes
The following example adds the custom attributes "stack=prod" and "project=a" to the specified container instance in the default cluster.
aws ecs put-attributes --attributes name=stack,value=prod,targetId=
arn
name=project,value=a,targetId=arn
Filtering by attribute using the console
You can apply a filter for your container instances, allowing you to see custom attributes.
Filter container instances by attribute using the classic console
Open the Amazon ECS classic console at https://console.aws.amazon.com/ecs/
. -
Choose a cluster that has container instances.
-
Choose ECS Instances.
-
Set column visibility preferences by choosing the gear icon and selecting the attributes to display. This setting persists across all container clusters associated with your account.
-
Using the Filter by attributes text field, enter or select the attributes you want to filter by. The format must be AttributeName:AttributeValue.
For Filter by attributes, enter or select the attributes to filter by. After you select the attribute name, you're prompted for the attribute value.
-
Add additional attributes to the filter as needed. Remove an attribute by choosing the X next to it.
Filter container instances by attribute using the AWS CLI
The following examples demonstrate how to filter container instances by attribute using the list-constainer-instances command. For more information about the filter syntax, see Cluster query language.
Example: Built-in attribute
The following example uses built-in attributes to list the g2.2xlarge instances.
aws ecs list-container-instances --filter "attribute:ecs.instance-type == g2.2xlarge"
Example: Custom attribute
The following example lists the instances with the custom attribute "stack=prod".
aws ecs list-container-instances --filter "attribute:stack == prod"
Example: Exclude an attribute value
The following example lists the instances with the custom attribute "stack" unless the attribute value is "prod".
aws ecs list-container-instances --filter "attribute:stack != prod"
Example: Multiple attribute values
The following example uses built-in attributes to list the instances of
type t2.small
or t2.medium
.
aws ecs list-container-instances --filter "attribute:ecs.instance-type in [t2.small, t2.medium]"
Example: Multiple attributes
The following example uses built-in attributes to list the T2 instances in the us-east-1a Availability Zone.
aws ecs list-container-instances --filter "attribute:ecs.instance-type =~ t2.* and attribute:ecs.availability-zone == us-east-1a"
Example constraints
The following are task placement constraint examples.
This example uses the memberOf
constraint to place tasks on T2
instances. It can be specified with the following actions: CreateService, UpdateService, RegisterTaskDefinition, and RunTask.
"placementConstraints": [ { "expression": "attribute:ecs.instance-type =~ t2.*", "type": "memberOf" } ]
The example uses the memberOf
constraint to place tasks on
instances with other tasks in the databases
task group, respecting
any task placement strategies that are also specified. For more information
about task groups, see Task groups. It can be specified with the following actions: CreateService, UpdateService, RegisterTaskDefinition, and RunTask.
"placementConstraints": [ { "expression": "task:group == databases", "type": "memberOf" } ]
The distinctInstance
constraint places each task in the group on
a different instance. It can be specified with the following actions: CreateService, UpdateService, and RunTask
"placementConstraints": [ { "type": "distinctInstance" } ]