# Definição de quais instâncias de contêiner o Amazon ECS usa em tarefas
<a name="task-placement-constraints"></a>

Uma restrição no posicionamento de tarefas é uma regra sobre uma instância de contêiner que o Amazon ECS usa para determinar se a tarefa tem permissão para ser executada na instância. Pelo menos uma instância de contêiner deve corresponder à restrição. Se não houver instâncias que correspondam à restrição, a tarefa permanecerá em um estado `PENDING`. Ao criar um novo serviço ou atualizar um existente, é possível especificar restrições de posicionamento de tarefas para as tarefas do serviço. 

Você pode especificar restrições de posicionamento de tarefas na definição do serviço, na definição de tarefa ou na tarefa usando o parâmetro `placementConstraint`.

```
"placementConstraints": [
    {
        "expression": "The expression that defines the task placement constraints",
        "type": "The placement constraint type to use"
    }
]
```

A tabela a seguir descreve como usar os parâmetros.


| Constraint type | Pode ser especificado quando | 
| --- | --- | 
| distinctInstanceColoque cada tarefa ativa em uma instância de contêiner diferente.O Amazon ECS analisa o status desejado das tarefas para a colocação da tarefa. Por exemplo, se o status desejado da tarefa existente for `STOPPED` (mas o último não for), uma nova tarefa de entrada poderá ser colocada na mesma instância, apesar da restrição de colocação `distinctInstance`. Portanto, você pode ver duas tarefas com o último status de `RUNNING` na mesma instância. Recomendamos que os clientes que buscam um forte isolamento para as tarefas usem o Fargate. O Fargate executa cada tarefa em um ambiente de virtualização de hardware. Isso garante que essas workloads em contêineres não compartilhem interfaces de rede, armazenamento temporário do Fargate, CPU ou memória com outras tarefas. Para obter mais informações, consulte [Security Overview of AWS Fargate](https://d1.awsstatic.com/whitepapers/AWS_Fargate_Security_Overview_Whitepaper.pdf). |  [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonECS/latest/developerguide/task-placement-constraints.html)  | 
| memberOfPosicionar tarefas em instâncias de contêiner que atendam a uma expressão.  | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/AmazonECS/latest/developerguide/task-placement-constraints.html) | 

Ao usar o tipo de restrição `memberOf`, você pode criar uma expressão usando a linguagem de consulta do cluster, que define as instâncias de contêiner nas quais o Amazon ECS pode posicionar tarefas. A expressão é uma forma de agrupar as instâncias de contêiner por atributos. A expressão vai no parâmetro `expression ` de `placementConstraint`.

## Atributos de instância de contêiner do Amazon ECS
<a name="attributes"></a>

É possível adicionar metadados personalizados, conhecidos como *atributos*, às instâncias de contêiner. Cada atributo tem um nome e um valor de string opcional. É possível usar os atributos integrados fornecidos pelo Amazon ECS ou definir atributos personalizados.

As seções a seguir contêm exemplos de atributos internos, opcionais e personalizados.

### Atributos integrados
<a name="ecs-automatic-attributes"></a>

O Amazon ECS aplica automaticamente os seguintes atributos às instâncias de contêiner.

`ecs.ami-id`  
A ID do AMI usado para executar a instância. Um exemplo de valor do atributo é `ami-1234abcd`.

`ecs.availability-zone`  
A zona de disponibilidade para a instância. Um exemplo de valor do atributo é `us-east-1a`.

`ecs.instance-type`  
O tipo de instância para a instância. Um exemplo de valor do atributo é `g2.2xlarge`.

`ecs.os-type`  
O sistema operacional para a instância. Os valores possíveis para esse atributo são `linux` e `windows`.

`ecs.os-family`  
A versão do sistema operacional para a instância.  
Para instâncias de Linux, o valor válido é `LINUX`. Para instâncias de Windows, o ECS define o valor no formato `WINDOWS_SERVER_<OS_Release>_<FULL or CORE>`. Os valores válidos são `WINDOWS_SERVER_2022_FULL`, `WINDOWS_SERVER_2022_CORE`, `WINDOWS_SERVER_20H2_CORE`, `WINDOWS_SERVER_2019_FULL`, `WINDOWS_SERVER_2019_CORE` e `WINDOWS_SERVER_2016_FULL`.  
Isso é importante para contêineres do Windows e Windows containers on AWS Fargate, pois porque a versão do sistema operacional de cada contêiner do Windows deve corresponder à do host. Se a versão Windows da imagem do contêiner for diferente da do host, o contêiner não será iniciado. Para obter mais informações, consulte [Compatibilidade de versão do contêiner do Windows](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-2022%2Cwindows-11) no site de documentação da Microsoft.  
Caso seu cluster execute várias versões do Windows, é possível garantir que uma tarefa seja colocada em uma instância do EC2 em execução na mesma versão usando a restrição de posicionamento: `memberOf(attribute:ecs.os-family == WINDOWS_SERVER_<OS_Release>_<FULL or CORE>)`. Para obter mais informações, consulte [Recuperação de metadados da AMI do Windows otimizada para o Amazon ECS](retrieve-ecs-optimized_windows_AMI.md).

`ecs.cpu-architecture`  
A arquitetura da CPU para a instância. São exemplos de valores do atributo `x86_64` e `arm64`.

`ecs.vpc-id`  
A VPC na qual a instância foi executada. Um exemplo de valor do atributo é `vpc-1234abcd`.

`ecs.subnet-id`  
A sub-rede que a instância está usando. Um exemplo de valor do atributo é `subnet-1234abcd`.

**nota**  
As instâncias gerenciadas do Amazon ECS oferecem suporte ao seguinte subconjunto de atributos:  
`ecs.subnet-id`
`ecs.availability-zone`
`ecs.instance-type`
`ecs.cpu-architecture`

### Atributos opcionais
<a name="ecs-optional-attributes"></a>

O Amazon ECS pode adicionar os seguintes atributos às instâncias de contêiner.

`ecs.awsvpc-trunk-id`  
Se esse atributo existir, a instância terá uma interface de rede de tronco. Para obter mais informações, consulte [Aumento das interfaces de rede de instâncias de contêiner do Linux no Amazon ECS](container-instance-eni.md).

`ecs.outpost-arn`  
Se esse atributo existir, ele conterá o nome de recurso da Amazon (ARN) do Outpost. Para obter mais informações, consulte [Amazon Elastic Container Service no AWS Outposts](using-outposts.md).

`ecs.capability.external`  
Se esse atributo existir, a instância será identificada como uma instância externa. Para obter mais informações, consulte [Clusters do Amazon ECS para instâncias externas](ecs-anywhere.md).

### Atributos personalizados
<a name="ecs-custom-attributes"></a>

É possível aplicar atributos personalizados às instâncias de contêiner. Por exemplo, você pode definir um atributo com o nome “pilha” e um valor de “prod”.

Ao especificar atributos personalizados, considere o descrito a seguir.
+ O `name` deve conter entre 1 e 128 caracteres e o nome pode conter letras (maiúsculas e minúsculas), números, hifens, sublinhados, barras “/”, barras “\$1” ou pontos.
+ O `value` deve conter entre 1 e 128 caracteres e pode conter letras (maiúsculas e minúsculas), números, hifens, sublinhados, pontos, arrobas (@), barras “/”, barras “\$1” dois pontos (:) ou espaços. O valor não pode conter espaço em branco no começo ou no fim.

# Criação de expressões para definir instâncias de contêiner em tarefas do Amazon ECS
<a name="cluster-query-language"></a>

Consultas ao cluster são expressões que permitem agrupar objetos. Por exemplo, você pode agrupar instâncias de contêiner por atributos, como Zona de disponibilidade, tipo de instância ou metadados personalizados. Para obter mais informações, consulte [Atributos de instância de contêiner do Amazon ECS](task-placement-constraints.md#attributes).

Depois de definir um grupo de instâncias de contêiner, você pode personalizar o Amazon ECS para posicionar tarefas em instâncias de contêiner baseadas no grupo. Para obter mais informações, consulte [Execução de uma aplicação como uma tarefa do Amazon ECS](standalone-task-create.md) e [Criação de uma implantação de atualização contínua do Amazon ECS](create-service-console-v2.md). Também é possível aplicar um filtro de grupo ao listar instâncias de contêiner.

## Sintaxe da expressão
<a name="expression-syntax"></a>

As expressões têm a seguinte sintaxe:

```
subject operator [argument]
```

**Assunto**  
O atributo ou o campo a ser avaliado.

`agentConnected`  
Selecione instâncias de contêiner pelo status da conexão do agente de contêiner do Amazon ECS. É possível usar esse filtro para pesquisar instâncias com agentes de contêiner desconectados.  
Operadores válidos: equals (==), not\$1equals (\$1=), in, not\$1in (\$1in), matches (=\$1), not\$1matches (\$1\$1)

`agentVersion`  
Selecione instâncias de contêiner pela versão do agente de contêiner do Amazon ECS. É possível usar esse filtro para encontrar instâncias que estejam executando versões desatualizadas do agente de contêiner do Amazon ECS.  
Operadores válidos: equals (==), not\$1equals (\$1=), greater\$1than (>), greater\$1than\$1equal (>=), less\$1than (<), less\$1than\$1equal (<=)

`attribute:attribute-name`  
Selecione instâncias de contêiner por atributo. Para obter mais informações, consulte [Atributos de instância de contêiner do Amazon ECS](task-placement-constraints.md#attributes).

`ec2InstanceId`  
Selecione instâncias de contêiner pelo ID da instância do Amazon EC2.  
Operadores válidos: equals (==), not\$1equals (\$1=), in, not\$1in (\$1in), matches (=\$1), not\$1matches (\$1\$1)

`registeredAt`  
Selecione instâncias de contêiner na data de registro da instância de contêiner. É possível usar esse filtro para encontrar instâncias recém-registradas ou instâncias muito antigas.  
Operadores válidos: equals (==), not\$1equals (\$1=), greater\$1than (>), greater\$1than\$1equal (>=), less\$1than (<), less\$1than\$1equal (<=)  
Formatos de data válidos: 2018-06-18T22:28:28\$100:00, 2018-06-18T22:28:28Z, 2018-06-18T22:28:28, 2018-06-18

`runningTasksCount`  
Selecione instâncias de contêiner pelo número de tarefas em execução. É possível usar esse filtro para encontrar instâncias vazias ou quase vazias (algumas tarefas em execução).  
Operadores válidos: equals (==), not\$1equals (\$1=), greater\$1than (>), greater\$1than\$1equal (>=), less\$1than (<), less\$1than\$1equal (<=)

`task:group`  
Selecione instâncias de contêiner por grupo de tarefas. Para obter mais informações, consulte [Tarefas do Amazon ECS relacionadas a grupos](task-groups.md).

**Operador**  
O operador de comparação. Os operadores a seguir são aceitos.


|  Operador  |  Descrição  | 
| --- | --- | 
|  ==, equals  |  Igualdade de strings  | 
|  \$1=, not\$1equals  |  Desigualdade de strings  | 
|  >, greater\$1than  |  Maior que  | 
|  >=, greater\$1than\$1equal  |  Maior ou igual a  | 
|  <, less\$1than  |  Menor que  | 
|  <=, less\$1than\$1equal  |  Menor ou igual a  | 
|  exists  |  O sujeito existe  | 
|  \$1exists, not\$1exists  |  O sujeito não existe  | 
|  em  |  Valor na lista de argumentos  | 
|  \$1in, not\$1in  |  Valor fora da lista de argumentos  | 
|  =\$1, matches  |  Correspondência de padrão  | 
|  \$1\$1, not\$1matches  |  Divergência de padrão  | 

**nota**  
Uma expressão individual não pode conter parênteses. No entanto, os parênteses podem ser usados para especificar precedência em expressões compostas.

**Argumento**  
Para muitos operadores, o argumento é um valor literal.

Os operadores `in` e `not_in` esperam uma lista de argumentos como argumento. Você especifica uma lista de argumentos da seguinte forma:

```
[argument1, argument2, ..., argumentN]
```

Os operadores matches e not\$1matches um argumento que se conforme à sintaxe de expressões regulares em Java. Para mais informações, consulte [java.util.regex.Pattern.](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html)

**Expressões compostas**

É possível combinar expressões usando os operadores booleanos a seguir:
+ &&, e
+ \$1\$1, ou
+ \$1, not

É possível especificar a precedência usando parênteses:

```
(expression1 or expression2) and expression3
```

## Exemplo de expressões
<a name="expression-examples"></a>

Veja a seguir exemplos de expressões.

**Exemplo: igualdade de strings**  
A expressão a seguir seleciona instâncias com o tipo de instância especificado.

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

**Exemplo: lista de argumentos**  
A expressão a seguir seleciona instâncias na Zona de disponibilidade us-east-1a ou us-east-1b.

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

**Exemplo: expressão composta**  
A expressão a seguir seleciona as instâncias G2 que não estiverem na zona de disponibilidade us-east-1d.

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

**Exemplo: afinidade de tarefas**  
A expressão a seguir seleciona as instâncias que são tarefas de hospedagem no grupo `service:production`.

```
task:group == service:production
```

**Exemplo: antiafinidade de tarefas**  
A expressão a seguir seleciona as instâncias que não são tarefas de hospedagem no grupo de bancos de dados.

```
not(task:group == database)
```

**Exemplo: contagem de tarefas em execução**  
A expressão a seguir seleciona as instâncias que estão executando apenas uma tarefa.

```
runningTasksCount == 1
```

**Exemplo: versão do agente de contêiner do Amazon ECS**  
A expressão a seguir seleciona instâncias que estão executando uma versão do agente de contêiner abaixo de 1.14.5.

```
agentVersion < 1.14.5
```

**Exemplo: tempo de registro da instância**  
A expressão a seguir seleciona instâncias que foram registradas antes de 13 de fevereiro de 2018.

```
registeredAt < 2018-02-13
```

**Exemplo: ID de instância do Amazon EC2**  
A expressão a seguir seleciona instâncias com os IDs de instância do Amazon EC2 a seguir.

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

# Exemplo de restrições de posicionamento de tarefas do Amazon ECS
<a name="constraint-examples"></a>

Os exemplos de restrição de colocação da tarefa são os seguintes.

Esse exemplo usa a restrição `memberOf` para colocar tarefas em instâncias t2. Ele pode ser especificado com as seguintes ações: [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html), [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html), [RegisterTaskDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html) e [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html).

```
"placementConstraints": [
    {
        "expression": "attribute:ecs.instance-type =~ t2.*",
        "type": "memberOf"
    }
]
```

O exemplo usa a restrição `memberOf` para posicionar tarefas de réplica em instâncias com tarefas no grupo de tarefas `daemon-service` de serviço de daemon, respeitando quaisquer estratégias de posicionamento de tarefas que também estejam especificadas. Essa restrição garante que as tarefas do serviço de daemon sejam colocadas na instância do EC2 antes das tarefas do serviço de réplica.

Substitua `daemon-service` pelo nome do serviço de daemon.

```
"placementConstraints": [
    {
        "expression": "task:group == service:daemon-service",
        "type": "memberOf"
    }
]
```

O exemplo usa a restrição `memberOf` para posicionar tarefas em instâncias com outras tarefas no grupo de tarefas `databases`, respeitando quaisquer estratégias de posicionamento de tarefas que também estejam especificadas. Para obter mais informações sobre grupos de tarefas, consulte [Tarefas do Amazon ECS relacionadas a grupos](task-groups.md). Ele pode ser especificado com as seguintes ações: [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html), [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html), [RegisterTaskDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RegisterTaskDefinition.html) e [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html).

```
"placementConstraints": [
    {
        "expression": "task:group == databases",
        "type": "memberOf"
    }
]
```

A limitação `distinctInstance` posiciona cada tarefa no grupo em uma instância diferente. Ele pode ser especificado com as seguintes ações: [CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html), [UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html) e [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html)

O Amazon ECS analisa o status desejado das tarefas para a colocação da tarefa. Por exemplo, se o status desejado da tarefa existente for `STOPPED` (mas o último não for), uma nova tarefa de entrada poderá ser colocada na mesma instância, apesar da restrição de colocação `distinctInstance`. Portanto, você pode ver duas tarefas com o último status de `RUNNING` na mesma instância.

```
"placementConstraints": [
    {
        "type": "distinctInstance"
    }
]
```