# Amazon ECS および Fargate ワークロードでフォールトインジェクションを使用する
<a name="fault-injection"></a>

お客様は、Amazon EC2 と Fargate の両方で Amazon ECS によるフォールトインジェクションを利用して、特定の障害シナリオに対するアプリケーションの反応をテストできます。これらのテストは、アプリケーションのパフォーマンスと回復力の最適化に使用できる情報を提供します。

フォールトインジェクションが有効になっている場合、Amazon ECS コンテナエージェントはタスクに新しいフォールトインジェクションエンドポイントへのアクセスを許可します。フォールトインジェクションを使用するには、`enableFaultInjection` タスク定義パラメータの値を `true` に設定してオプトインする必要があります。デフォルト値は `false` です。

```
{
    ...
   "enableFaultInjection": true
}
```

**注記**  
フォールトインジェクションは、`awsvpc` または `host` ネットワークモードを使用するタスクでのみ機能します。  
フォールトインジェクションは、Windows では使用できません。

AWS マネジメントコンソールでフォールトインジェクションを有効にする方法については、「[コンソールを使用して Amazon ECS タスク定義の作成](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-task-definition.html)」を参照してください。

AWS Fault Injection Service でテストするには、この機能を有効にする必要があります。詳細については、「[AWS FIS aws:ecs:タスクアクションを使用します](https://docs.aws.amazon.com/fis/latest/userguide/ecs-task-actions.html)」を参照してください。

**注記**  
Amazon ECS に最適化された新しい AMI を使用しない場合、またはカスタム AMI がある場合は、次の依存関係をインストールします。  
`tc`
`sch_netem` カーネルモジュール

# Amazon ECS フォールトインジェクションエンドポイント
<a name="fault-injection-endpoints"></a>

Amazon ECS コンテナエージェントは、`ECS_AGENT_URI` 環境変数を Amazon ECS タスクのコンテナに自動的に挿入して、コンテナエージェント API エンドポイントとやり取りする方法を提供します。各エンドポイントには、`/start`、`/stop`、および `/status` エンドポイントが含まれます。エンドポイントは、フォールトインジェクションを有効にしたタスクからのリクエストのみを受け入れ、各エンドポイントにはコンテナあたり **5** 秒間に **1** リクエストというレート制限があります。この制限を超えるとエラーが発生します。

**注記**  
フォールトインジェクションエンドポイントを使用するには、Amazon ECS エージェント `version 1.88.0+` が必要です。

フォールトインジェクションで使用する 3 つのエンドポイントは以下のとおりです。
+ [ネットワークブラックホールポートエンドポイント](#fis-endpoint-blackhole-ports)
+ [ネットワークパケット損失エンドポイント](#fis-endpoint-packet-loss)
+ [ネットワークレイテンシーエンドポイント](#fis-endpoint-latency)

リクエストが成功すると、`/start` エンドポイントを呼び出す場合 `running` のメッセージが記載された `200` 応答コードとなり、`/stop` エンドポイントの場合は `stopped`、`/status` エンドポイントの場合は `running` または `not-running` となります。

```
{
    "Status": <string>
}
```

リクエストが成功しなかった場合は、以下のいずれかのエラーコードを返します。
+ `400` – Bad request・
+ `409` – フォールトインジェクションリクエストが別の実行中の障害と競合する
+ `429` – リクエストがスロットリングされました
+ `500` – サーバーに予期しないエラーが発生しました

```
{
	"Error":  <string message> 
}
```

**注記**  
1 回に挿入できるのは、1 つのネットワークレイテンシー障害、または 1 つのネットワークパケット損失障害のいずれかです。複数の結果を挿入しようとすると、リクエストは拒否されます。

## ネットワークブラックホールポートエンドポイント
<a name="fis-endpoint-blackhole-ports"></a>

`{ECS_AGENT_URI}/fault/v1/network-blackhole-port` エンドポイントは、タスクのネットワーク名前空間内の特定のポートとプロトコルの受信トラフィックまたは送信トラフィックをドロップし、次の 2 つのモードと互換性があります。
+ **awsvpc** — 変更がタスクネットワーク名前空間に適用されます
+ **ホスト** — 変更はデフォルトのネットワーク名前空間コンテナインスタンスに適用されます

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-blackhole-port/start
<a name="fis-endpoint-blackhole-ports-start"></a>

このエンドポイントは、ネットワークブラックホールポートのフォールトインジェクションを開始し、次のパラメータがあります。

**ポート**  
ブラックホールポートのフォールトインジェクションに使用する指定されたポート。

タイプ: 整数

必須: はい

**プロトコル**  
ブラックホールポートのフォールトインジェクションに使用するプロトコル。

型: 文字列

有効な値: `tcp | udp`

必須: はい

**TrafficType**  
フォールトインジェクションで使用されるトラフィックタイプ。

型: 文字列

有効な値: `ingress | egress`

必須: はい

**SourcesToFilter**  
障害から保護されている IPv4 アドレスまたは IPv6 アドレス、あるいは CIDR ブロックの JSON 配列。

型: 文字列の配列

必須: いいえ

以下は `start` エンドポイントを使用するためのリクエストの例です (*赤色* の値を独自の値に置き換えてください)。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-blackhole-port/start

Http method:POST

Request payload: 
{
    "Port": 1234,
    "Protocol": "tcp|udp",
    "TrafficType": "ingress|egress"
    "SourcesToFilter": ["${IP1}", "${IP2}", ...],
}
```

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-blackhole-port/stop
<a name="fis-endpoint-blackhole-ports-stop"></a>

このエンドポイントは、リクエストで指定された障害を停止します。このエンドポイントには以下のパラメータがあります。

**ポート**  
停止する必要がある障害の影響を受けたポート。

タイプ: 整数

必須: はい

**プロトコル**  
障害を停止するために使用するプロトコル。

型: 文字列

有効な値: `tcp | udp`

必須: はい

**TrafficType**  
フォールトインジェクションで使用されるトラフィックタイプ。

型: 文字列

有効な値: `ingress | egress`

必須: はい

以下は `stop` エンドポイントを使用するためのリクエストの例です (*赤色* の値を独自の値に置き換えてください)。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-blackhole-port/stop

Http method: POST

Request payload: 
{
    "Port": 1234,
    "Protocol": "tcp|udp",
    "TrafficType": "ingress|egress", 
}
```

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-blackhole-port/status
<a name="fis-endpoint-blackhole-ports-status"></a>

このエンドポイントは、フォールトインジェクションのステータスを確認するために使用されます。このエンドポイントには以下のパラメータがあります。

**ポート**  
障害のステータスを確認するために影響を受けるポート。

タイプ: 整数

必須: はい

**プロトコル**  
障害のステータスを確認する際に使用するプロトコル。

型: 文字列

有効な値: `tcp | udp`

必須: はい

**TrafficType**  
フォールトインジェクションで使用されるトラフィックタイプ。

型: 文字列

有効な値: `ingress | egress`

必須: はい

以下は `status` エンドポイントを使用するためのリクエストの例です (*赤色* の値を独自の値に置き換えてください)。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-blackhole-port/status

Http method: POST

Request payload: 
{
   "Port": 1234,
   "Protocol": "tcp|udp",
   "TrafficType": "ingress|egress",
}
```

## ネットワークレイテンシーエンドポイント
<a name="fis-endpoint-latency"></a>

`{ECS_AGENT_URI}/fault/v1/network-latency` エンドポイントは、特定のソースへのトラフィックに対してタスクのネットワークインターフェイスに遅延とジッターを追加します。このエンドポイントは 2 つのモードと互換性があります。
+ **awsvpc** — 変更がタスクネットワークインターフェイスに適用されます
+ **ホスト** — 変更はデフォルトのネットワークインターフェイスに適用されます

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-latency/start
<a name="fis-endpoint-latency-start"></a>

この`/start` エンドポイントは、ネットワークレイテンシーのフォールトインジェクションを開始し、以下のパラメータがあります。

**DelayMilliseconds**  
フォールトインジェクションに使用するネットワークインターフェイスに追加する遅延のミリ秒数。

タイプ: 整数

必須: はい

**JitterMilliseconds**  
フォールトインジェクションに使用するネットワークインターフェイスに追加するジッターのミリ秒数。

タイプ: 整数

必須: はい

**[Sources] (出典)**  
フォールトインジェクションで使用する宛先である IPv4 アドレスまたは IPv6 アドレス、あるいは CIDR ブロックの JSON 配列。

型: 文字列の配列

必須: はい

**SourcesToFilter**  
障害から保護されている IPv4 アドレスまたは IPv6 アドレス、あるいは CIDR ブロックの JSON 配列。`SourcesToFilter` は `Sources` よりも優先されます。

型: 文字列の配列

必須: いいえ

以下は `/start` エンドポイントを使用するためのリクエストの例です (*赤色* の値を独自の値に置き換えてください)。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-latency/start

Http method: POST

Request payload: 
{
    "DelayMilliseconds": 123,
    "JitterMilliseconds": 123,
    "Sources": ["${IP1}", "${IP2}", ...],
    "SourcesToFilter": ["${IP1}", "${IP2}", ...],
}
```

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-latency/stop and /status
<a name="fis-endpoint-latency-stop-status"></a>

`{ECS_AGENT_URI}/fault/v1/network-latency/stop` エンドポイントは障害を停止し、`{ECS_AGENT_URI}/fault/v1/network-latency/status` は障害のステータスを確認します。

以下は、 `/stop` と `/status` のエンドポイントを使用する際の 2 つのリクエストの例です。どちらも `POST HTTP` メソッドを使用します。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-latency/stop
```

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-latency/status
```

## ネットワークパケット損失エンドポイント
<a name="fis-endpoint-packet-loss"></a>

`{ECS_AGENT_URI}/fault/v1/network-packet-loss` エンドポイントは、指定されたネットワークインターフェイスへのパケット損失を追加します。このエンドポイントは、次の 2 つのモードと互換性があります。
+ **awsvpc** — 変更がタスクネットワークインターフェイスに適用されます
+ **ホスト** — 変更はデフォルトのネットワークインターフェイスに適用されます

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-packet-loss/start
<a name="fis-endpoint-packet-loss-start"></a>

この `/start` エンドポイントは、ネットワークパケット損失フォールトインジェクションを開始し、以下のパラメータがあります。

**LossPercent**  
パケット損失の割合

タイプ: 整数

必須: はい

**[Sources] (出典)**  
フォールトインジェクションテストに使用する IPv4 アドレスまたは IPv6 アドレス、あるいは CIDR ブロックの JSON 配列。

型: 文字列の配列

必須: はい

**SourcesToFilter**  
障害から保護されている IPv4 アドレスまたは IPv6 アドレス、あるいは CIDR ブロックの JSON 配列。`SourcesToFilter` は `Sources` よりも優先されます。

型: 文字列の配列

必須: いいえ

以下は `start` エンドポイントを使用するためのリクエストの例です (*赤色* の値を独自の値に置き換えてください)。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-packet-loss/start

Http method: POST

{
    "LossPercent": 6,  
    "Sources": ["${IP1}", "${IP2}", ...],
    "SourcesToFilter": ["${IP1}", "${IP2}", ...],
}
```

### \$1ECS\$1AGENT\$1URI\$1/fault/v1/network-packet-loss/stop and /status
<a name="fis-endpoint-packet-loss-stop-status"></a>

`{ECS_AGENT_URI}/fault/v1/network-packet-loss/stop` エンドポイントは障害を停止し、`{ECS_AGENT_URI}/fault/v1/network-packet-loss/status` は障害のステータスを確認します。1 回でサポートされる障害のタイプは 1 つだけです。

以下は、`/stop` と `/status` のエンドポイントを使用する際の 2 つのリクエストの例です。どちらも `POST HTTP` メソッドを使用します。

```
Endpoint: ${ECS_AGENT_URI}/fault/v1/network-packet-loss/stop
```

```
Endpoint: ${{ECS_AGENT_URI}/fault/v1/network-packet-loss/status
```