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
You can add custom attributes at instance registration time using the
container agent or manually, using the AWS Management Console. For information about the available
Amazon ECS container agent configuration parameters, see Amazon ECS
Container Agent
To add custom attributes using the console
Open the console at https://console.aws.amazon.com/ecs/v2
. -
In the navigation pane, choose Clusters, and then choose the cluster.
-
Choose Infrastructure.
-
Choose the container instance, and then coose Attributes.
-
Choose Add custom attribute.
-
For Attribute name and Value, enter a name and a value for the attribute, and then choose Submit.
Repeat for each attribute that you want to add.
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 console
Open the console at https://console.aws.amazon.com/ecs/v2
. -
In the navigation pane, choose Clusters, and then choose the cluster.
-
Choose Infrastructure,
-
Choose the container instance.
-
Using the Filter custom attributes by key or value text field, enter the attributes you want to filter by. The format must be AttributeName:AttributeValue.
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 replica tasks
on instances with tasks in the daemon service daemon-service
task group,
respecting any task placement strategies that are also specified. This constraint
ensures that the daemon service tasks get placed on the EC2 instance prior to the
replica service tasks.
Replace daemon-service
with the name of the daemon service.
"placementConstraints": [ { "expression": "task:group == service:
daemon-service
", "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" } ]