Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

Cluster Query Language

Cluster queries are expressions that enable you to group objects. For example, you can group container instances by attributes such as Availability Zone, instance type, or custom metadata. For more information, see Attributes.

After you have defined a group of container instances, you can customize Amazon ECS to place tasks on container instances based on group. For more information, see Running Tasks and Creating a Service. You can also apply a group filter when listing container instances. For more information, see Filtering by Attribute.

Expression Syntax

Expressions have the following syntax:

subject operator [argument]

Subject

The attribute or field to be evaluated.

agentConnected

Select container instances by their Amazon ECS container agent connection status. You can use this filter to search for instances with container agents that are disconnected.

Valid operators: equals (==), not_equals (!=), in, not_in (!in), matches (=~), not_matches (!~)

agentVersion

Select container instances by their Amazon ECS container agent version. You can use this filter to find instances that are running outdated versions of the Amazon ECS container agent.

Valid operators: equals (==), not_equals (!=), greater_than (>), greater_than_equal (>=), less_than (<), less_than_equal (<=)

attribute:attribute-name

Select container instances by attribute. For more information, see Attributes.

ec2InstanceId

Select container instances by their Amazon EC2 instance ID.

Valid operators: equals (==), not_equals (!=), in, not_in (!in), matches (=~), not_matches (!~)

registeredAt

Select container instances by their container instance registration date. You can use this filter to find newly registered instances or instances that are very old.

Valid operators: equals (==), not_equals (!=), greater_than (>), greater_than_equal (>=), less_than (<), less_than_equal (<=)

Valid date formats: 2018-06-18T22:28:28+00:00, 2018-06-18T22:28:28Z, 2018-06-18T22:28:28, 2018-06-18

runningTasksCount

Select container instances by number of running tasks. You can use this filter to find instances that are empty or near empty (few tasks running on them).

Valid operators: equals (==), not_equals (!=), greater_than (>), greater_than_equal (>=), less_than (<), less_than_equal (<=)

task:group

Select container instances by task group. For more information, see Task Groups.

Operator

The comparison operator. The following operators are supported.

Operator Description

==, equals

String equality

!=, not_equals

String inequality

>, greater_than

Greater than

>=, greater_than_equal

Greater than or equal to

<, less_than

Less than

<=, less_than_equal

Less than or equal to

exists

Subject exists

!exists, not_exists

Subject does not exist

in

Value in argument list

!in, not_in

Value not in argument list

=~, matches

Pattern match

!~, not_matches

Pattern mismatch

Note

A single expression can't contain parentheses. However, parentheses can be used to specify precedence in compound expressions.

Argument

For many operators, the argument is a literal value.

The in and not_in operators expect an argument list as the argument. You specify an argument list as follows:

[argument1, argument2, ..., argumentN]

The matches and not_matches operators expect an argument that conforms to the Java regular expression syntax. For more information, see java.util.regex.Pattern.

Compound Expressions

You can combine expressions using the following Boolean operators:

  • &&, and

  • ||, or

  • !, not

You can specify precedence using parentheses:

(expression1 or expression2) and expression3

Example Expressions

The following are example expressions.

Example: String Equality

The following expression selects instances with the specified instance type.

attribute:ecs.instance-type == t2.small

Example: Argument List

The following expression selects instances in the us-east-1a or us-east-1b Availability Zone.

attribute:ecs.availability-zone in [us-east-1a, us-east-1b]

Example: Compound Expression

The following expression selects G2 instances that are not in the us-east-1d Availability Zone.

attribute:ecs.instance-type =~ g2.* and attribute:ecs.availability-zone != us-east-1d

Example: Task Affinity

The following expression selects instances that are hosting tasks in the service:production group.

task:group == service:production

Example: Task Anti-Affinity

The following expression selects instances that are not hosting tasks in the database group.

not(task:group == database)

Example: Running task count

The following expression selects instances that are only running one task.

runningTasksCount == 1

Example: Amazon ECS container agent version

The following expression selects instances that are running a container agent version below 1.14.5.

agentVersion < 1.14.5

Example: Instance registration time

The following expression selects instances that were registered before February 13, 2018.

registeredAt < 2018-02-13

Example: Amazon EC2 instance ID

The following expression selects instances with the following Amazon EC2 instance IDs.

ec2InstanceId in ['i-abcd1234', 'i-wxyx7890']