Constraint types Attributes Adding an attribute Filtering by attribute using the console Example constraints

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 and windows.

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 the WINDOWS_SERVER_<OS_Release>_<FULL or CORE> format. The valid values are WINDOWS_SERVER_2022_FULL, WINDOWS_SERVER_2022_CORE, WINDOWS_SERVER_20H2_CORE, WINDOWS_SERVER_2019_FULL, WINDOWS_SERVER_2019_CORE, and WINDOWS_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 and arm64.

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 on GitHub.

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"
    }
]

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Task placement strategies

Cluster query language