# Amazon ECS がタスクに使用するコンテナインスタンスを定義する
<a name="task-placement-constraints"></a>

タスク配置の制約事項は、Amazon ECS がインスタンス上でタスクを実行できるかどうかを判断するために使用するコンテナインスタンスに関するルールです。少なくとも 1 つのコンテナインスタンスが制約に一致する必要があります。制約に一致するインスタンスがない場合、タスクは `PENDING` 状態のままになります。新しいサービスを作成するか、既存のサービスを更新するときに、サービスのタスク用にタスク配置制約を指定できます。

`placementConstraint` パラメータを使用して、サービス定義、タスク定義、またはタスクでタスク配置制約事項を指定できます。

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

次の表は、パラメータの使用法の説明です。


| [Constraint type (制約タイプ)] | 次の場合に指定できます。 | 
| --- | --- | 
| distinctInstanceそれぞれのアクティブタスクを別々のコンテナインスタンスに配置します。Amazon ECS は、タスク配置におけるタスクの目的のステータスを確認します。例えば、既存のタスクの目的のステータスが `STOPPED` の場合 (ただし、最後のステータスが目的のステータスではない場合)、`distinctInstance` 配置の制約事項にもかかわらず、新しい受信タスクを同じインスタンスに配置することができます。したがって、同じインスタンスで最後のステータスが `RUNNING` のタスクが 2 つ表示される場合があります。 タスクの強力な分離を求めているお客様には、Fargate を使用することをお勧めします。Fargate はハードウェア仮想化環境で各タスクを実行します。これにより、これらのコンテナ化されたワークロードがネットワークインターフェイス、Fargate の一時ストレージ、CPU、またはメモリを他のタスクと共有しないことが保証されます。詳細については、「[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/ja_jp/AmazonECS/latest/developerguide/task-placement-constraints.html)  | 
| memberOf式を満たすコンテナインスタンスにタスクを配置します。 | [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ja_jp/AmazonECS/latest/developerguide/task-placement-constraints.html) | 

`memberOf` 制約事項タイプを使用すると、Amazon ECS がタスクを配置できるコンテナインスタンスを定義するクラスタークエリ言語を使用して式を作成できます。この式は、コンテナインスタンスを属性別にグループ化する方法です。この式は、`placementConstraint` の `expression ` パラメータに含まれます。

## Amazon ECS コンテナインスタンス属性
<a name="attributes"></a>

コンテナインスタンスに*属性*と呼ばれるカスタムメタデータを追加できます。各属性には名前とオプションの文字列値があります。Amazon ECSが提供する組み込み属性を使用することも、カスタム属性を定義することもできます。

次のセクションでは、組み込み型、オプション型、カスタム型属性のサンプルが含まれています。

### 組み込み属性
<a name="ecs-automatic-attributes"></a>

Amazon ECSは次の属性を自動的にコンテナインスタンスに適用します。

`ecs.ami-id`  
インスタンスの起動に使用される AMI の ID。この属性の値の例は「`ami-1234abcd`」です。

`ecs.availability-zone`  
インスタンスのアベイラビリティーゾーン。この属性の値の例は「`us-east-1a`」です。

`ecs.instance-type`  
インスタンスのインスタンスタイプ。この属性の値の例は「`g2.2xlarge`」です。

`ecs.os-type`  
インスタンスのオペレーティングシステム。この属性に指定できる値は `linux` と `windows` です。

`ecs.os-family`  
インスタンスのオペレーティングシステムのバージョン。  
Linux インスタンスの場合、有効な値は `LINUX` です。Windows インスタンスの場合、ECS は値を `WINDOWS_SERVER_<OS_Release>_<FULL or CORE>` 形式で設定します。有効な値は、`WINDOWS_SERVER_2022_FULL`、`WINDOWS_SERVER_2022_CORE`、`WINDOWS_SERVER_20H2_CORE`、`WINDOWS_SERVER_2019_FULL`、`WINDOWS_SERVER_2019_CORE`、および `WINDOWS_SERVER_2016_FULL` です。  
これは、Windows コンテナおよび Windows containers on AWS Fargate にとって重要です。なぜなら、すべての Windows コンテナの OS バージョンがホストのそれと一致する必要があるからです。コンテナイメージの Windows バージョンがホストと異なる場合、コンテナは起動しません。詳細については、マイクロソフトのドキュメント Web サイトの「[Windows コンテナバージョンの互換性](https://learn.microsoft.com/en-us/virtualization/windowscontainers/deploy-containers/version-compatibility?tabs=windows-server-2022%2Cwindows-11)」を参照してください。  
クラスターが複数の Windows バージョンを実行している場合、次の配置制約を使用して、同じバージョンで実行されている EC2 インスタンスにタスクが配置されるようにすることができます: `memberOf(attribute:ecs.os-family == WINDOWS_SERVER_<OS_Release>_<FULL or CORE>)`。詳細については、「[Amazon ECS に最適化された Windows AMI メタデータを取得する](retrieve-ecs-optimized_windows_AMI.md)」を参照してください。

`ecs.cpu-architecture`  
インスタンスの CPU アーキテクチャ。この属性の値の例は`x86_64` と `arm64` です。

`ecs.vpc-id`  
インスタンスが起動された VPC。この属性の値の例は「`vpc-1234abcd`」です。

`ecs.subnet-id`  
インスタンスが使用しているサブネット。この属性の値の例は「`subnet-1234abcd`」です。

**注記**  
Amazon ECS マネージドインスタンスは、次の属性のサブセットをサポートしています。  
`ecs.subnet-id`
`ecs.availability-zone`
`ecs.instance-type`
`ecs.cpu-architecture`

### オプションの属性
<a name="ecs-optional-attributes"></a>

Amazon ECS では、コンテナインスタンスに次の属性を追加することができます。

`ecs.awsvpc-trunk-id`  
この属性が存在する場合、インスタンスにトランクネットワークインターフェイスがあります。詳細については、「[Amazon ECS Linux コンテナインスタンスのネットワークインターフェイスを増やす](container-instance-eni.md)」を参照してください。

`ecs.outpost-arn`  
この属性が存在する場合は、Outpost の Amazon Resource Name (ARN) が含まれます。詳細については、「[AWS OutpostsのAmazon Elastic Container Service](using-outposts.md)」を参照してください。

`ecs.capability.external`  
この属性が存在する場合、インスタンスは外部インスタンスとして識別されます。詳細については、「[外部インスタンスの Amazon ECS クラスター](ecs-anywhere.md)」を参照してください。

### カスタム属性
<a name="ecs-custom-attributes"></a>

コンテナインスタンスに、カスタム属性を適用できます。例えば、「stack」という名前で「prod」という値の属性を定義できます。

カスタム属性を指定するとき、次の点を考慮する必要があります。
+ `name` は、1～128 文字で指定する必要があります。文字 (大文字と小文字)、数字、ハイフン、アンダースコア、スラッシュ、バックスラッシュ、ピリオドを使用できます。
+ `value` は、1 ～ 128 文字で指定する必要があります。文字 (大文字と小文字)、数字、ハイフン、アンダースコア、ピリオド、アットマーク (@)、スラッシュ、バックスラッシュ、コロン、またはスペースを使用できます。値の先頭または末尾にホワイトスペースを含めることはできません。

# Amazon ECS タスク用のコンテナインスタンスを定義する式を作成する
<a name="cluster-query-language"></a>

クラスタークエリは、オブジェクトをグループ化できる式です。例えば、アベイラビリティーゾーン、インスタンスタイプ、カスタムメタデータなどの属性でコンテナインスタンスをグループ化できます。詳細については、「[Amazon ECS コンテナインスタンス属性](task-placement-constraints.md#attributes)」を参照してください。

コンテナインスタンスのグループを定義した後、グループに基づいてコンテナインスタンスのタスクを配置するように Amazon ECS をカスタマイズできます。詳細については「[Amazon ECS タスクとしてのアプリケーションの実行](standalone-task-create.md)」および「[Amazon ECS のローリング更新デプロイの作成](create-service-console-v2.md)」を参照してください。また、コンテナインスタンスをリスト表示する際にグループフィルタを適用できます。

## 式の構文
<a name="expression-syntax"></a>

式の構文は次のとおりです。

```
subject operator [argument]
```

**件名**  
評価する属性またはフィールド。

`agentConnected`  
Amazon ECS コンテナエージェント接続ステータスでコンテナインスタンスを選択します。このフィルタを使用して、切断されたコンテナエージェントでインスタンスを検索します。  
有効な演算子: equals (==)、not\$1equals (\$1=)、in、not\$1in (\$1in)、matches (=\$1)、not\$1matches (\$1\$1)

`agentVersion`  
Amazon ECS コンテナエージェントバージョンでコンテナインスタンスを選択します。このフィルタを使用して、Amazon ECS コンテナエージェントの古くなったバージョンを実行しているインスタンスを検索します。  
有効な演算子: equals (==)、not\$1equals (\$1=)、greater\$1than (>)、greater\$1than\$1equal (>=)、less\$1than (<)、less\$1than\$1equal (<=)

`attribute:attribute-name`  
属性でコンテナインスタンスを選択します。詳細については、「[Amazon ECS コンテナインスタンス属性](task-placement-constraints.md#attributes)」を参照してください。

`ec2InstanceId`  
Amazon EC2 インスタンス ID で、コンテナインスタンスを選択します。  
有効な演算子: equals (==)、not\$1equals (\$1=)、in、not\$1in (\$1in)、matches (=\$1)、not\$1matches (\$1\$1)

`registeredAt`  
コンテナインスタンス登録日で、コンテナインスタンスを選択します。このフィルタを使用して、新しく登録されたインスタンスまたは古いインスタンスを検索します。  
有効な演算子: equals (==)、not\$1equals (\$1=)、greater\$1than (>)、greater\$1than\$1equal (>=)、less\$1than (<)、less\$1than\$1equal (<=)  
有効な日付形式: 2018-06-18T22:28:28\$100:00、2018-06-18T22:28:28Z、2018-06-18T22:28:28、2018-06-18

`runningTasksCount`  
実行中のタスクの数でコンテナインスタンスを選択します。このフィルタを使用して、空またはほぼ空 (実行中のタスクがほぼない) のインスタンスを検索します。  
有効な演算子: equals (==)、not\$1equals (\$1=)、greater\$1than (>)、greater\$1than\$1equal (>=)、less\$1than (<)、less\$1than\$1equal (<=)

`task:group`  
コンテナインスタンスをタスクグループで選択します。詳細については、「[Amazon ECS タスクをグループ化する](task-groups.md)」を参照してください。

**オペレーター**  
比較演算子。以下の演算子がサポートされています。


|  演算子  |  説明  | 
| --- | --- | 
|  ==, が  |  文字列が等価  | 
|  \$1=、not\$1equals  |  文字列が不等価  | 
|  >、greater\$1than  |  以上  | 
|  >=、greater\$1than\$1equal  |  以上  | 
|  <、less\$1than  |  未満  | 
|  <=、less\$1than\$1equal  |  以下  | 
|  exists  |  対象が存在  | 
|  \$1exists、not\$1exists  |  サブジェクトが存在しません  | 
|  情報  |  引数リストの値  | 
|  \$1in、not\$1in  |  引数リストにない値  | 
|  =\$1、matches  |  パターンが一致  | 
|  \$1\$1、not\$1matches  |  パターンが不一致  | 

**注記**  
1 つの式に括弧を含めることはできません。ただし、複合式で優先順位を指定するために括弧を使用できます。

**引数**  
多くの演算子は、引数がリテラル値です。

`in` および `not_in` 演算子は、引数として引数リストを想定しています。次のように引数リストを指定します。

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

matches と not\$1matches 演算子は、Java の正規表現構文に準拠する引数を想定しています。詳細については、[java.util.regex.Pattern](http://docs.oracle.com/javase/6/docs/api/java/util/regex/Pattern.html) を参照してください。

**複合式**

次のブール演算子を使用して式を結合できます。
+ &&, および
+ \$1\$1, または
+ \$1, 先頭の文字に

括弧を使用して、優先度を指定できます。

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

## 式の例
<a name="expression-examples"></a>

以下に式の例を示します。

**例: 文字列が等価**  
次の式は指定されたインスタンスタイプのインスタンスを選択します。

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

**例: 引数リスト**  
次の式は、アベイラビリティーゾーンが us-east-1a または us-east-1b のインスタンスを選択します。

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

**例: 複合式**  
次の表現は、us-east-1d アベイラビリティーゾーンにはない G2 インスタンスを選択します。

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

**例: タスクのアフィニティ**  
次の式は、`service:production` グループのタスクをホストするインスタンスを選択します。

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

**例: タスクのアンチアフィニティ**  
次の表現は、データベースグループでタスクをホストしないインスタンスを選択します。

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

**例: 実行中のタスクの数**  
次の式は、1 つのタスクのみを実行しているインスタンスを選択します。

```
runningTasksCount == 1
```

**Amazon ECS コンテナエージェントバージョン**  
次の式は、コンテナエージェントバージョン 1.14.5 より前のバージョンを実行しているインスタンスを選択します。

```
agentVersion < 1.14.5
```

**例: インスタンス登録時**  
次の式は、2018 年 2 月 13 日以前に登録されているインスタンスを選択します。

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

**例: Amazon EC2 インスタンス ID**  
次の式は、以下の Amazon EC2 インスタンス ID のインスタンスを選択します。

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

# Amazon ECS タスク配置の制約事項の例
<a name="constraint-examples"></a>

以下はタスク配置の制約事項の例です。

この例では、`memberOf` 制約を使用して T2 インスタンスにタスクを配置します。次のアクションを使用して指定できます。[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)、および [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html)。

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

この例では、`memberOf` 制約を使用して、指定されたタスク配置方法に従って、`daemon-service` タスクグループ内のデーモンサービスタスクを持つインスタンスに、レプリカタスクを配置します。この制約により、デーモンサービスタスクはレプリカサービスタスクよりも前に EC2 インスタンスに配置されます。

`daemon-service` を デーモンサービスの名前に置き換えます。

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

この例では、`memberOf` 制約を使用して、指定されたタスク配置方法に従って、`databases` タスクグループ内の他のタスクとともにインスタンスにタスクを配置します。タスクグループの詳細については、「[Amazon ECS タスクをグループ化する](task-groups.md)」を参照してください。次のアクションを使用して指定できます。[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)、および [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html)。

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

`distinctInstance` 制約は、グループ内の各タスクを別のインスタンスに配置します。次のアクションを使用して指定できます。[CreateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_CreateService.html)、[UpdateService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_UpdateService.html)、および [RunTask](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RunTask.html)。

Amazon ECS は、タスク配置におけるタスクの目的のステータスを確認します。例えば、既存のタスクの目的のステータスが `STOPPED` の場合 (ただし、最後のステータスが目的のステータスではない場合)、`distinctInstance` 配置の制約事項にもかかわらず、新しい受信タスクを同じインスタンスに配置することができます。したがって、同じインスタンスで最後のステータスが `RUNNING` のタスクが 2 つ表示される場合があります。

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