Amazon ECS フォールトインジェクションエンドポイント - Amazon Elastic Container Service
ネットワークブラックホールポートエンドポイントネットワークレイテンシーエンドポイントネットワークパケット損失エンドポイント

Amazon ECS フォールトインジェクションエンドポイント

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

注記

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

フォールトインジェクションで使用する 3 つのエンドポイントは以下のとおりです。

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

{
    "Status": <string>
}

リクエストが成功しなかった場合は、以下のいずれかのエラーコードを返します。

  • 400 – Bad request・

  • 409 – フォールトインジェクションリクエストが別の実行中の障害と競合する

  • 429 – リクエストがスロットリングされました

  • 500 – サーバーに予期しないエラーが発生しました

{
	"Error":  <string message> 
}
注記

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

ネットワークブラックホールポートエンドポイント

{ECS_AGENT_URI}/fault/v1/network-blackhole-port エンドポイントは、タスクのネットワーク名前空間内の特定のポートとプロトコルの受信トラフィックまたは送信トラフィックをドロップし、次の 2 つのモードと互換性があります。

  • awsvpc — 変更がタスクネットワーク名前空間に適用されます

  • ホスト — 変更はデフォルトのネットワーク名前空間コンテナインスタンスに適用されます

{ECS_AGENT_URI}/fault/v1/network-blackhole-port/start

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

ポート

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

タイプ: 整数

必須: はい

プロトコル

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

タイプ: 文字列

有効な値: 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}", ...],
}

{ECS_AGENT_URI}/fault/v1/network-blackhole-port/stop

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

ポート

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

タイプ: 整数

必須: はい

プロトコル

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

タイプ: 文字列

有効な値: 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", 
}

{ECS_AGENT_URI}/fault/v1/network-blackhole-port/status

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

ポート

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

タイプ: 整数

必須: はい

プロトコル

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

タイプ: 文字列

有効な値: 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",
}

ネットワークレイテンシーエンドポイント

{ECS_AGENT_URI}/fault/v1/network-latency エンドポイントは、特定のソースへのトラフィックに対してタスクのネットワークインターフェイスに遅延とジッターを追加します。このエンドポイントは 2 つのモードと互換性があります。

  • awsvpc — 変更がタスクネットワークインターフェイスに適用されます

  • ホスト — 変更はデフォルトのネットワークインターフェイスに適用されます

{ECS_AGENT_URI}/fault/v1/network-latency/start

この/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}", ...],
}

{ECS_AGENT_URI}/fault/v1/network-latency/stop and /status

{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

ネットワークパケット損失エンドポイント

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

  • awsvpc — 変更がタスクネットワークインターフェイスに適用されます

  • ホスト — 変更はデフォルトのネットワークインターフェイスに適用されます

{ECS_AGENT_URI}/fault/v1/network-packet-loss/start

この /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}", ...],
}

{ECS_AGENT_URI}/fault/v1/network-packet-loss/stop and /status

{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