Amazon ECS マネージドインスタンスの Amazon ECS タスク定義パラメータ

family

タイプ: 文字列

必須: はい

タスク定義を登録するときに、ファミリー (複数バージョンのタスク定義の名前のようなもの) を指定する必要があります。登録したタスク定義には、リビジョン番号が与えられます。特定のファミリーに登録した最初のタスク定義には、リビジョン 1 が与えられます。その後に登録したタスク定義には、連番でリビジョン番号が与えられます。

requiresCompatibilities

型: 文字列配列

必須: いいえ

有効な値: MANAGED_INSTANCES

タスク定義が検証された容量。これにより、タスク定義で使用されているすべてのパラメータが、Amazon ECS マネージドインスタンスの要件を満たしていることの確認処理が開始されます。

taskRoleArn

タイプ: 文字列

必須: いいえ

タスク定義を登録するときに、IAM ロールのタスクロールを割り当てて、タスクのコンテナに、関連するポリシーに指定された AWS API を呼び出すためのアクセス権限を付与できます。詳細については、「Amazon ECS タスクの IAM ロール」を参照してください。

executionRoleArn

タイプ: 文字列

必須: 条件による

ユーザーに代わって AWS API コールを実行するアクセス許可を Amazon ECS コンテナエージェントに付与するタスク実行ロールの Amazon リソースネーム (ARN)。詳細については、「Amazon ECS タスク実行IAM ロール」を参照してください。

注記

タスク実行 IAM ロールは、タスクの要件に応じて必要です。ロールは、プライベート ECR イメージのプルと awslogs ログドライバーの使用に必要です。

networkMode

タイプ: 文字列

必須: いいえ

デフォルト: awsvpc

タスクのコンテナで使用するネットワークモード。Amazon ECS マネージドインスタンスでホストされている Amazon ECS タスクの場合、有効な値は awsvpc と host となります。ネットワークモードが指定されていない場合、デフォルトのネットワークモードは awsvpc です。

ネットワークモードが host である場合、タスクはネットワークの分離をバイパスし、コンテナはホストのネットワークスタックを直接使用します。

重要

host ネットワークモードをによりタスクを実行する場合、より良いセキュリティーのために、ルートユーザー (UID 0) を使用してコンテナを実行しないでください。セキュリティのベストプラクティスとしては、常にルート以外のユーザーを使用します。

ネットワークモードが awsvpc の場合は、タスクに Elastic Network Interface が割り当てられるため、タスク定義を使用したサービスの作成時またはタスクの実行時に NetworkConfiguration を指定する必要があります。詳細については、「Amazon ECS マネージドインスタンスの Amazon ECS タスクネットワーキング」を参照してください。

host および awsvpc のネットワークモードは、Amazon EC2 のネットワークスタックを使用するので、コンテナのネットワークパフォーマンスが最大限発揮されます。host および awsvpc ネットワークモードにおいて公開されるコンテナポートは、対応するホストポート (host ネットワークモードの場合)、またはアタッチされた Elastic Network Interface ポート (awsvpc ネットワークモードの場合) に直接マッピングされます。このため、動的ホストポートマッピングは使用できません。

operatingSystemFamily

タイプ: 文字列

必須: いいえ

デフォルト: LINUX

タスク定義を登録する際、オペレーティングシステムファミリを指定します。

このフィールドで有効な値は LINUX です。

サービスで使用されるすべてのタスク定義は、このパラメータに対して同じ値を設定する必要があります。

タスク定義がサービスの一部である場合、この値はサービスの platformFamily 値と一致する必要があります。

cpuArchitecture

タイプ: 文字列

必須: 条件による

タスク定義を登録する際は、CPU アーキテクチャを指定します。有効な値は X86_64 および ARM64 です。

値を指定しない場合、Amazon ECS はキャパシティプロバイダーの設定に基づいて、使用可能な CPU アーキテクチャにタスクを配置しようとします。タスクが特定の CPU アーキテクチャに配置されるようにするには、タスク定義で cpuArchitecture の値を指定します。

サービスで使用されるすべてのタスク定義は、このパラメータに対して同じ値を設定する必要があります。

ARM64 の詳細については、「64 ビット ARM ワークロードでの Amazon ECS タスク定義」を参照してください。

cpu

タイプ: 文字列

必須: 条件による

タスクに適用される CPU ユニットのハード制限。JSON ファイルでは、CPU 値を CPU ユニットまたは仮想 CPU (vCPU) の文字列として指定できます。例えば、CPU 値を 1 vCPU (vCPU) または 1024 (CPU ユニット) として指定できます。タスク定義が登録されると、vCPU 値は、CPU ユニットを示す整数に変換されます。

このフィールドはオプションです。クラスターに、要求された CPU ユニットが利用できる登録済みのコンテナインスタンスがない場合、タスクは失敗します。サポートされている値は、0.125 vCPU から 10 vCPU までです。

memory

タイプ: 文字列

必須: 条件による

タスクに適用されるメモリのハード制限です。タスク定義のメモリの値は、メビバイト (MiB) またはギガバイト (GB) の文字列として指定できます。例えば、メモリの値を 3072 (MiB) または 3 GB (GB) のいずれかで指定できます。タスク定義が登録されると、GB 値は、MiB を示す整数に変換されます。

このフィールドはオプションです。任意の値を使用できます。タスクレベルでメモリ値が指定されている場合、コンテナレベルのメモリ値の設定は省略可能です。クラスターに、要求されたメモリが利用できる登録済みのコンテナインスタンスがない場合、タスクは失敗します。特定のインスタンスタイプについて、タスクにできるだけ多くのメモリを提供することで、リソースの使用率を最大化することができます。詳細については、「Amazon ECS Linux コンテナインスタンスのメモリを予約する」を参照してください。

ephemeralStorage

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: EphemeralStorage オブジェクト

必須: いいえ

タスクに割り当てるエフェメラルストレージの容量(GB 単位)。このパラメーターは、AWS Fargate でホストされるタスクにおいて、利用可能なエフェメラルストレージの総量をデフォルトの容量を超えて拡張する際に使用します。詳細については、「Amazon ECS でのバインドマウントの使用」を参照してください。

ipcMode

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: 文字列

必須: いいえ

タスクのコンテナで使用する IPC リソースの名前空間。有効な値は host、task または none です。host が指定されている場合、同一のコンテナインスタンス上にある (host IPC モードを指定した) タスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じ IPC リソースを共有します。task が指定されている場合、指定されたタスク内のすべてのコンテナは同じ IPC リソースを共有します。none が指定されている場合、タスクのコンテナ内の IPC リソースはプライベートです。タスク内またはコンテナインスタンスの他のコンテナと共有されることはありません。値を指定しない場合、IPC リソース名前空間の共有はコンテナランタイム設定によって異なります。

pidMode

型: 文字列

必須: いいえ

タスクのコンテナで使用するプロセス名前空間。有効な値は host または task です。host が指定されている場合、同じコンテナインスタンスで host PID モードを指定したタスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じプロセス名前空間を共有します。task が指定されている場合、指定したタスク内のすべてのコンテナは同じプロセス名前空間を共有します。値が指定されていない場合、デフォルトはプライベート名前空間です。

host PID モードを使用する場合は、意図せずプロセス名前空間が公開されるリスクが高いことに注意してください。

proxyConfiguration

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: ProxyConfiguration オブジェクト

必須: いいえ

App Mesh プロキシ設定の詳細。

key

タイプ: 文字列

必須: いいえ

タグを構成するキーと値のペアの一部。キーは、より具体的なタグ値のカテゴリのように動作する、一般的なラベルです。

value

タイプ: 文字列

必須: いいえ

タグを構成するキーと値のペアのオプションの一部。値はタグカテゴリ (キー) の記述子として機能します。

inferenceAccelerator

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: InferenceAccelerator オブジェクト

必須: いいえ

タスク内のコンテナに使用する Elastic Inference アクセラレーター。

placementConstraints

タイプ: TaskDefinitionPlacementConstraint オブジェクトの配列

必須: いいえ

タスクに使用する、配置制約オブジェクトの配列。タスクごとに最大 10 個の制約を指定できます (この制限数には、タスク定義内の制約と、実行時に指定される制約が含まれます)。

Amazon ECS は、Amazon ECS マネージドインスタンスで実行されるタスクの distinctInstace および memberOf の配置制約に対応しています。memberOf 配置制約を使用するタスクでは、次の属性がサポートされています。

ecs.subnet-id
ecs.availability-zone
ecs.cpu-architecture
ecs.instance-type

配置制約について、詳細は「Amazon ECS がタスクに使用するコンテナインスタンスを定義する」を参照してください。

name

タイプ: 文字列

必須: はい

ボリュームの名前。最大 255 文字の英字 (大文字と小文字)、数字、ハイフンを使用できます。この名前は、コンテナ定義 sourceVolume の mountPoints パラメータで参照されます。

host

タイプ: HostVolumeProperties オブジェクト

必須: いいえ

このパラメータは、バインドマウントのホストボリュームを使用する場合に指定します。host パラメータの内容により、バインドマウントのホストボリュームがホストコンテナインスタンスで保持されるかどうかと、その保存場所が決まります。host パラメータが空の場合は、システムがデータボリュームにホストパスを割り当てます。ただし、関連付けられたコンテナが実行を停止した後も、データが保持されるという保証はありません。

dockerVolumeConfiguration

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: DockerVolumeConfiguration オブジェクト

必須: いいえ

このパラメータは、Docker ボリュームを使用する場合に指定します。

efsVolumeConfiguration

タイプ: EFSVolumeConfiguration オブジェクト

必須: いいえ

このパラメータは、タスクストレージに Amazon EFS ファイルシステムを使用するときに指定します。

fsxWindowsFileServerVolumeConfiguration

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: FSxWindowsFileServerVolumeConfiguration オブジェクト

必須: いいえ

このパラメータは、タスクストレージに Amazon FSx for Windows File Server ファイルシステムを使用する場合に指定します。

configuredAtLaunch

型: ブール値

必須: いいえ

起動時にボリュームを設定するかどうかを示します。これは、スタンドアロンタスクまたはサービスの一部として作成されたタスクの Amazon EBS ボリュームを作成するために使用されます。各タスク定義リビジョンでは、ボリューム設定で起動時に設定できるボリュームは 1 つだけです。

name

タイプ: 文字列

必須: はい

コンテナの名前。最大 255 文字の英字 (大文字と小文字)、数字、ハイフン、アンダースコアを使用できます。タスク定義で複数のコンテナをリンクしている場合、あるコンテナの name を別のコンテナの links に入力できます。これにより、コンテナ同士を接続します。

image

タイプ: 文字列

必須: はい

コンテナの開始に使用するイメージ。この文字列は Docker デーモンに直接渡されます。デフォルトでは、Docker Hub レジストリのイメージを使用できます。repository-url/image:tag または repository-url/image@digest で他のリポジトリを指定することもできます。最大 255 文字の英字 (大文字と小文字)、数字、ハイフン、アンダースコア、コロン、ピリオド、スラッシュ、シャープ記号を使用できます。このパラメータは、docker create-container コマンドの Image と docker run コマンドの IMAGE パラメータにマッピングされます。

新しいタスクが開始されると、Amazon ECS コンテナエージェントは、指定されたイメージおよびタグの最新バージョンをプルしてコンテナで使用します。ただし、リポジトリイメージの後続の更新がすでに実行されているタスクに反映されることはありません。
タスク定義のイメージパスでタグまたはダイジェストを指定しない場合、Amazon ECS コンテナエージェントは latest タグを使用して指定されたイメージを取り込みます。
リポジトリイメージに後から加えられた更新内容が、実行中のタスクに反映されることはありません。
プライベートレジストリのイメージがサポートされています。詳細については、「Amazon ECS での AWS 以外のコンテナイメージの使用」を参照してください。
Amazon ECR リポジトリのイメージは、registry/repository:tag または registry/repository@digest の完全な命名規則 (例えば、aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latest や、aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE) を使用して指定します。
Docker Hub の公式リポジトリのイメージでは、1 つの名前 (例: ubuntu または mongo) を使用します。
Docker Hub の他のリポジトリのイメージは、組織名で修飾されます (例: amazon/amazon-ecs-agent)。
他のオンラインリポジトリのイメージは、さらにドメイン名で修飾されます (例: quay.io/assemblyline/ubuntu)。

versionConsistency

タイプ: 文字列

有効な値: enabled|disabled

必須: いいえ

コンテナ定義で指定されたコンテナイメージタグを Amazon ECS がイメージダイジェストに解決するかどうかを指定します。デフォルトでは、この動作は enabled です。コンテナの値を disabled として設定した場合、Amazon ECS はコンテナイメージタグをダイジェストに解決せず、コンテナ定義で指定された元のイメージ URI をデプロイ用に使用します。コンテナイメージの解決の詳細については、「コンテナイメージの解決」を参照してください。

memory

タイプ: 整数

必須: いいえ

コンテナに適用されるメモリの量 (MiB 単位)。コンテナは、ここで指定したメモリを超えようとすると、強制終了されます。タスク内のすべてのコンテナ用に予約されるメモリの合計量は、タスクの memory 値より小さくする必要があります (指定されている場合)。このパラメータは docker create-container コマンドの Memory にマッピングされ、--memory オプションは docker run にマッピングされます。

Docker デーモン 20.10.0 以降によって、コンテナ用として 6 MiB 以上のメモリが予約されます。従って、このコンテナに対しては 6 MiB 未満のメモリは指定しないようにします。

Docker デーモン 19.03.13-ce 以降では、コンテナ用として 4 MiB 以上のメモリが予約されます。このため、このコンテナ用には 4 MiB 未満のメモリを指定しないようにします。

注記

リソースの使用率を最大化することを目的に、特定のインスタンスタイプにおいて、タスクにできるだけ多くのメモリを提供する場合には、「Amazon ECS Linux コンテナインスタンスのメモリを予約する」を参照してください。

memoryReservation

タイプ: 整数

必須: いいえ

コンテナ用に予約するメモリのソフト制限 (MiB 単位)。システムメモリに競合がある場合、Docker はコンテナのメモリ量をこのソフト制限値内に維持しようとします。ただし、コンテナは必要に応じてより多くのメモリを使用することができます。コンテナは、memory パラメーターで指定されたハード制限 (該当する場合) またはコンテナインスタンス上の利用可能なすべてのメモリのいずれか早く達する方まで使用できます。このパラメータは docker create-container コマンドの MemoryReservation にマッピングされ、--memory-reservation オプションは docker run にマッピングされます。

タスクレベルでメモリ値を指定しない場合、コンテナ定義で memory または memoryReservation の一方または両方に 0 以外の整数を指定する必要があります。両方を指定する場合、memory は memoryReservation より大きいことが必要です。memoryReservation を指定する場合、コンテナが配置されているコンテナインスタンスで使用可能なメモリリソース量から、上記の値が減算されます。それ以外の場合は、memory の値が使用されます。

例えば、コンテナが通常 128 MiB のメモリを使用しているが、短期間にメモリが 256 MiB にバーストする場合があるとします。128 MiB の memoryReservation と 300 MiB の memory ハード制限を設定できます。この設定では、コンテナが、コンテナインスタンスの残りのリソースから 128 MiB のメモリのみを予約できます。同時に、この構成により、コンテナは必要に応じてより多くのメモリリソースを使用できるようになります。

Docker デーモン 20.10.0 以降によって、コンテナ用として 6 MiB 以上のメモリが予約されます。従って、このコンテナに対しては 6 MiB 未満のメモリは指定しないようにします。

Docker デーモン 19.03.13-ce 以降では、コンテナ用として 4 MiB 以上のメモリが予約されます。このため、このコンテナ用には 4 MiB 未満のメモリを指定しないようにします。

注記

リソースの使用率を最大化することを目的に、特定のインスタンスタイプにおいて、タスクにできるだけ多くのメモリを提供する場合には、「Amazon ECS Linux コンテナインスタンスのメモリを予約する」を参照してください。

cpu

タイプ: 整数

必須: いいえ

コンテナ用に予約されている cpu ユニットの数。このパラメータは docker create-container コマンドの CpuShares にマッピングされ、--cpu-shares オプションは docker run にマッピングされます。

EC2 キャパシティプロバイダーを使用するタスクでは、このフィールドはオプションです。その場合、タスク内のすべてのコンテナ用に予約される CPU の合計量が、タスクレベルの cpu の値を下回ることが唯一の要件となります。

注記

[Amazon EC2 インスタンス] 詳細ページのインスタンスタイプに一覧表示されている vCPU 数に 1,024 を乗算して、EC2 インスタンスタイプごとに使用可能な CPU ユニットの数を判断できます。

Linux コンテナは、割り当てられた CPU ユニットと同じ比率を使用して、割り当てられていない CPU ユニットをコンテナインスタンス上の他コンテナと共有します。例えば、単一コンテナタスクを単一コアインスタンスタイプで実行する場合、そのコンテナ用に 512 個の CPU ユニットを指定しており、そのタスクがコンテナインスタンスで実行される唯一のタスクであると、そのコンテナは 1,024 個の CPU ユニットすべてをいつでも使用できます。ただし、そのコンテナインスタンスで同じタスクの別のコピーを起動した場合、各タスクについて、必要に応じて最低で 512 CPU ユニットが保証されます。さらに、各コンテナは他のコンテナが使用していなければ、より高い CPU 使用率にフロートする可能性があります。両方のタスクが常に 100% アクティブであった場合、512 CPU ユニットに制限されます。

Linux コンテナインスタンスでは、コンテナインスタンス上の Docker デーモンは、CPU 値を使用して、実行中のコンテナに対する相対 CPU 配分比率を計算します。詳細については、Docker ドキュメントの「CPU 配分の制約」を参照してください。Linux kernel が許可する CPU の有効な最小共有値は 2 です。ただし、CPU のパラメータは必要なく、コンテナ定義で 2 以下の CPU 値を使用できます。CPU 値が 2 未満の場合 (null を含む)、動作は Amazon ECS コンテナエージェントのバージョンによって異なります。

エージェントのバージョンが 1.1.0 以下である: Null と 0 の CPU 値は Docker に 0 として渡され、Docker はそれを 1,024 個の CPU 配分に変換します。1 の CPU 値は Docker に 1 として渡され、Linux カーネルはそれを 2 個の CPU 配分に変換します。
エージェントのバージョンが 1.2.0 以上である: Null、0、1 の CPU 値は Docker に 2 として渡されます。

Windows コンテナインスタンスでは、CPU 制限は絶対制限またはクォータとして適用されます。Windows コンテナはタスク定義で指定された一定量の CPU にのみアクセスします。ヌルまたはゼロの CPU 値は 0 として Docker に渡され、これを Windows は 1 つの CPU の 1％として解釈します。

portMappings

タイプ: オブジェクト配列

必須: いいえ

ポートマッピングは、コンテナのネットワークポートを外部に公開します。これは、クライアントがアプリケーションにアクセスすることを可能にします。これは、同じタスク内にあるコンテナ間の通信にも使用されます。

awsvpc ネットワークモードを使用するタスク定義では、containerPort のみを指定します。hostPort は常に無視され、コンテナポートはホスト上の番号が大きいランダムなポートに自動的にマップされます。

このパラメータのほとんどのフィールド (containerPort、hostPort、protocol を含む) は docker create-container コマンドの PortBindings にマッピングされ、--publish オプションは docker run にマッピングされます。タスク定義でネットワークモードを host に設定している場合、ホストポートは未定義とするか、ポートマッピングのコンテナポートと一致させる必要があります。

注記

タスクが RUNNING ステータスに達すると、手動および自動で割り当てられたホストとコンテナポートが次の場所で表示されます:

コンソール: 指定されたタスクのコンテナ詳細の [Network Bindings] セクション。
AWS CLI: networkBindings コマンド出力の describe-tasks セクション。
API: DescribeTasks レスポンス。
メタデータ: タスクメタデータのエンドポイント。

appProtocol

タイプ: 文字列

必須: いいえ

ポートマッピングに使用されるアプリケーションプロトコル。このパラメータは Service Connect にのみ適用されます。アプリケーションが使用するプロトコルと一貫性を持つように、このパラメータを設定することをお勧めします。このパラメータを設定すると、Amazon ECS はサーバーコネクトプロキシにプロトコル固有の接続処理を追加します。このパラメータを設定すると、Amazon ECS は Amazon ECS コンソールと CloudWatch にプロトコル固有のテレメトリを追加します。

このパラメータ値を設定しないと、TCP が使用されます。ただし、Amazon ECS では、TCP 用のプロトコル固有のテレメトリーは追加されません。

詳細については、「Service Connect を使用して Amazon ECS サービスを短縮名で接続する」を参照してください。

有効なプロトコル値: "HTTP" | "HTTP2" | "GRPC"

containerPort

タイプ: 整数

必須: はい (portMappings を使用する場合)

ユーザーが指定したホストポートまたは自動的に割り当てられたホストポートにバインドされるコンテナポートの番号。

awsvpc ネットワークモードを使用するタスクの場合は、containerPort を使用して公開ポートを指定します。

containerPortRange

タイプ: 文字列

必須: いいえ

動的にマッピングされたホストポート範囲にバインドされるコンテナのポート番号の範囲。

このパラメータは、register-task-definition API を使用してのみ設定できます。このオプションは、portMappings パラメータで使用できます。詳細については、「AWS Command Line Interface リファレンス」の「register-task-definition」を参照してください。

containerPortRange を指定するときは、以下のルールが適用されます。

awsvpc ネットワークモードを使用する必要があります。
コンテナインスタンスには、少なくともコンテナエージェントのバージョン 1.67.0 と ecs-init パッケージのバージョン 1.67.0-1 が必要です。
各コンテナにつき、最大 100 のポートレンジを指定できます。
hostPortRange は指定しません。hostPortRange の値は次のように設定されます。
- awsvpc ネットワークモードのタスク内のコンテナでは、hostPort は containerPort と同じ値に設定されます。これは静的マッピング戦略です。
containerPortRange の有効な値は 1～65535 です。
1 つのポートは、コンテナごとに 1 つのポートマッピングにのみ含められます。
重複するポート範囲は指定できません。
範囲内の最初のポートは、最後のポートよりも小さくなければなりません。
Docker では、ポートの数が多い場合は、Docker デーモン設定ファイルの docker-proxy をオフにすることをお勧めします。

詳細については、GitHub の Issue #11185 を参照してください。

Docker デーモン設定ファイルの docker-proxy をオフにする方法については、Amazon ECS 開発者ガイドの「Docker デーモン」を参照してください。

DescribeTasks を呼び出すと、コンテナポートにバインドされているホストポートである hostPortRange を表示できます。

ポート範囲は、EventBridge に送信される Amazon ECS タスクイベントに含まれません。詳細については、「EventBridge を使用して Amazon ECS エラーへの対応を自動化する」を参照してください。

hostPortRange

型: 文字列

必須: いいえ

ネットワークバインディングで使用されるホストのポート番号範囲。これは Docker によって割り当てられ、Amazon ECS エージェントによって配信されます。

hostPort

タイプ: 整数

必須: いいえ

コンテナ用に予約するコンテナインスタンスのポート番号。

hostPort は、空白のままにするか、containerPort と同じ値にできます。

Docker バージョン 1.6.0 以降のデフォルトの一時ポート範囲は、インスタンスの /proc/sys/net/ipv4/ip_local_port_range にリストされています。このカーネルパラメータが使用できない場合、49153–65535 から始まるデフォルトのエフェメラルポート範囲が使用されます。エフェメラルポート範囲では、ホストポートを指定しないでください。これらの範囲は自動割り当て用に予約済みです。一般的に、32768 より小さい番号のポートは一時ポート範囲に含まれません。

デフォルトの予約済みポートは、SSH 用の 22、Docker ポートの 2375 および 2376、Amazon ECS コンテナエージェントポートの 51678-51680 です。実行中のタスクに対して以前にユーザーが指定したホストポートも、タスクの実行中に予約されます。タスクが停止すると、ホストポートはリリースされます。現在の予約済みポートは、describe-container-instances 出力の remainingResources に表示されます。コンテナインスタンスには、デフォルトの予約済みポートを含めて、一度に最大 100 個の予約済みポートを割り当てられます。自動的に割り当てられるポートは、この 100 個の予約済みポートクォータにはカウントされません。

name

タイプ: 文字列

必須: いいえ。サービスに Service Connect および VPC Lattice を設定する場合は必要です。

ポートマッピングに使用される名前。このパラメータは Service Connect および VPC Lattice にのみ適用されます。このパラメータは、サービスの Service Connect および VPC Lattice 設定で使用する名前です。

詳細については、「Service Connect を使用して Amazon ECS サービスを短縮名で接続する」を参照してください。

次の例では、Service Connect および VPC Lattice の 2 つの必須フィールドが使用されています。



"portMappings": [
    {
        "name": string,
        "containerPort": integer
    }
]

protocol

タイプ: 文字列

必須: いいえ

ポートマッピングに使用されるプロトコル。有効な値は、tcp および udp です。デフォルト: tcp。

重要

tcp は Service Connect でのみサポートされます。このフィールドが設定されていない場合は、tcp が暗示されることに注意してください。

ホストポートを指定する際は、以下の構文を使用します。


"portMappings": [
    {
        "containerPort": integer,
        "hostPort": integer
    }
    ...
]

自動割り当てのホストポートが必要な場合は、以下の構文を使用します。


"portMappings": [
    {
        "containerPort": integer
    }
    ...
]

repositoryCredentials

タイプ: RepositoryCredentials オブジェクト

必須: いいえ

プライベートレジストリ認証用のリポジトリ認証情報。

詳細については、「Amazon ECS での AWS 以外のコンテナイメージの使用」を参照してください。

credentialsParameter

タイプ: 文字列

必須: はい (repositoryCredentials を使用する場合)

プライベートリポジトリの認証情報が含まれているシークレットの Amazon リソースネーム (ARN)。

詳細については、「Amazon ECS での AWS 以外のコンテナイメージの使用」を参照してください。

注記

Amazon ECS API、AWS CLI、または AWS SDK を使用する場合、起動するタスクと同じリージョンにシークレットが存在する場合は、シークレットの完全な ARN または名前のどちらも使用できます。AWS マネジメントコンソールを使用する場合は、シークレットの完全な ARN を指定する必要があります。

必要なパラメータが含まれるタスク定義のスニペットを、以下に示します。



"containerDefinitions": [
    {
        "image": "private-repo/private-image",
        "repositoryCredentials": {
            "credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
        }
    }
]

essential

型: ブール値

必須: いいえ

コンテナの essential パラメータが true とマークされている場合、そのコンテナが何らかの理由で失敗または停止すると、タスクに含まれる他のすべてのコンテナは停止されます。コンテナの essential パラメータが false とマークされている場合、その失敗はタスクに含まれる残りのコンテナに影響を与えません。このパラメータを省略した場合、コンテナは必須と見なされます。

すべてのタスクには少なくとも 1 つの必須コンテナが必要です。アプリケーションが複数のコンテナで構成される場合は、用途が共通するコンテナをコンポーネントにグループ化し、それらのコンポーネントを複数のタスク定義に分ける必要があります。詳細については、「Amazon ECS 用のアプリケーションの構築」を参照してください。

entryPoint

型: 文字列配列

必須: いいえ

コンテナに渡されるエントリポイント。このパラメータは docker create-container コマンドの Entrypoint にマッピングされ、--entrypoint オプションは docker run にマッピングされます。


"entryPoint": ["string", ...]

command

型: 文字列配列

必須: いいえ

コンテナに渡されるコマンド。このパラメータは docker create-container コマンドの Cmd にマッピングされ、COMMAND パラメータは docker run にマッピングされます。複数の引数がある場合、各引数は配列において区切られた文字列である必要があります。


"command": ["string", ...]

workingDirectory

タイプ: 文字列

必須: いいえ

コマンドを実行するコンテナ内の作業ディレクトリ。このパラメータは docker create-container コマンドの WorkingDir にマッピングされ、--workdir オプションは docker run にマッピングされます。

restartPolicy

コンテナ再起動ポリシーと関連する設定パラメータ。コンテナの再起動ポリシーを設定すると、Amazon ECS はタスクを置き換えることなくコンテナを再起動できます。詳細については、「コンテナ再起動ポリシーを使用して Amazon ECS タスク内の個々のコンテナを再起動する」を参照してください。

enabled

型: ブール値

必須: はい

コンテナに対して再起動ポリシーを有効にするかどうかを指定します。

ignoredExitCodes

タイプ: 整数配列

必須: いいえ

Amazon ECS が無視し、再起動を試みない終了コードのリスト。最大 50 個のコンテナ終了コードを指定できます。デフォルトでは、Amazon ECS はいずれの終了コードも無視しません。

restartAttemptPeriod

タイプ: 整数

必須: いいえ

再起動を試みる前にコンテナが実行する必要がある時間 (秒単位）。コンテナを再起動できるのは、restartAttemptPeriod 秒に 1 回のみです。コンテナがこの期間実行できずに早く終了した場合、コンテナは再起動されません。最小の restartAttemptPeriod は 60 秒、最大の restartAttemptPeriod は 604,800 秒 (7 日間) を指定できます。デフォルトでは、コンテナは再起動の前に 300 秒間実行する必要があります。

healthCheck

コンテナに対するヘルスチェックのコマンドと、コンテナのための関連する設定パラメータです。詳細については、「コンテナのヘルスチェックを使用して Amazon ECS タスク状態を判定する」を参照してください。

command

正常状態かどうかを決定するために、コンテナが実行するコマンドが格納された文字列配列。この文字列配列の先頭には、コマンド引数を直接実行するための CMD、またはコンテナのデフォルトシェルでコマンドを実行するための CMD-SHELL を付加できます。これらのいずれも指定しない場合は CMD が使用されます。

AWS マネジメントコンソールにタスク定義を登録する場合は、カンマで区切ったコマンドリストを使用してください。これらのコマンドは、タスク定義が作成された後に文字列に変換されます。ヘルスチェックに対する入力の例を次に示します。


CMD-SHELL, curl -f http://localhost/ || exit 1

AWS マネジメントコンソール JSON パネル、AWS CLI、または API を使用してタスク定義を登録するときは、コマンドのリストを角かっこで囲みます。ヘルスチェックに対する入力の例を次に示します。


[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]

stderr が出力されない終了コード 0 は成功を示し、0 以外の終了コードは失敗を示します。

interval

各ヘルスチェック間の時間間隔 (秒単位)。5 〜 300 秒を指定できます。デフォルトの値は 30 秒です。

timeout

成功まで待機しているヘルスチェックが、失敗したと見なされるまでの期間 (秒単位) です。2 〜 60 秒を指定できます。デフォルト値は 5 秒です。

retries

コンテナが異常と見なされるまでに、失敗したヘルスチェックを再試行する回数です。1〜10 回を指定できます。デフォルト値は 3 回の再試行です。

startPeriod

失敗したヘルスチェックの再試行が最大回数に達する前に、コンテナにブートストラップための時間を提供するオプションの猶予期間です。0～300 秒の値を指定できます。デフォルトでは、startPeriod は無効となっています。

ヘルスチェックが startPeriod 内で成功した場合、コンテナは正常であるとみなされ、その後の失敗は最大再試行回数にカウントされます。

cpu

タイプ: 整数

必須: いいえ

Amazon ECS コンテナエージェントがコンテナ用に予約した cpu ユニットの数。Linux では、このパラメータは「Create a container」セクションの CpuShares にマッピングされます。

このフィールドは、Amazon ECS マネージドインスタンスで実行されるタスクではオプションです。タスク内のすべてのコンテナのために予約されている CPU の合計量は、タスクレベルの cpu 値以上にはできません。

Linux コンテナは、割り当てられた CPU ユニットと同じ比率を使用して、割り当てられていない CPU ユニットをコンテナインスタンス上の他コンテナと共有します。例えば、そのコンテナ用に 512 個の CPU ユニットが指定された単一コアインスタンスタイプで、唯一のコンテナタスクを実行するとします。さらに、そのタスクはコンテナインスタンスで実行される唯一のタスクです。この場合のコンテナは、1,024 個の CPU ユニット配分を任意のタイミングで使用できます。一方、そのコンテナインスタンスで同じタスクのコピーを別途起動したと仮定します。各タスクには、必要に応じて少なくとも 512 個の CPU ユニットが保証されます。同様に、その他のコンテナが残りの CPU を使用していない場合、各コンテナは CPU 使用率を高められます。ただし、両方のタスクが常に 100% アクティブである場合、使用できるのは 512 CPU ユニットに制限されます。

Linux コンテナインスタンスでは、コンテナインスタンス上の Docker デーモンは、CPU 値を使用して、実行中のコンテナに対する相対 CPU 配分比率を計算します。Linux カーネルが許可する最小の有効な CPU 共有値は 2 で、Linux カーネルが許可する最大の有効な CPU 共有値は 262,144 です。ただし、CPU のパラメータは必須ではなく、コンテナ定義では 2 未満の CPU 値および 262144 より大きな CPU 値を使用できます。CPU 値が 2 未満 (null を含む) および 262144 より大きな値である場合、動作は Amazon ECS コンテナエージェントのバージョンによって異なります。

その他の例については、「Amazon ECS で CPU およびメモリリソースの管理方法」を参照してください。

gpu

タイプ: ResourceRequirement オブジェクト

必須: いいえ

Amazon ECS コンテナエージェントがコンテナ用に予約した物理 GPUs の数。タスク内でコンテナ用に予約されているすべての GPU の数は、タスクが起動されたコンテナインスタンスで使用できる GPU の数を超えることはできません。詳細については、「GPU ワークロード向けの Amazon ECS タスク定義」を参照してください。

Elastic Inference accelerator

注記

このパラメータは、Amazon ECS マネージドインスタンスがホストするコンテナではサポートされていません。

タイプ: ResourceRequirement オブジェクト

必須: いいえ

InferenceAccelerator タイプでは、value はタスク定義で指定される InferenceAccelerator の deviceName と一致します。詳細については、「Elastic Inference アクセラレーター名 (廃止)」を参照してください。

essential

型: ブール値

必須: いいえ

コンテナの essential パラメーターが true としてマークされており、そのコンテナが何らかの理由で失敗するか停止するとします。その後、タスクの一部である他のすべてのコンテナが停止されます。コンテナの essential パラメータを false にマークしておくと、そのコンテナ失敗はタスク内にある残りのコンテナに影響を与えません。このパラメータを省略した場合、コンテナは必須と見なされます。

すべてのタスクには少なくとも 1 つの必須コンテナが必要です。複数のコンテナで構成されるアプリケーションがあるとします。次に、共通の目的で使用されるコンテナをコンポーネントにグループ化し、さまざまなコンポーネントを複数のタスク定義に分離します。詳細については、「Amazon ECS 用のアプリケーションの構築」を参照してください。


"essential": true|false

entryPoint

重要

初期のバージョンの Amazon ECS コンテナエージェントは、entryPoint パラメータを正しく処理しません。entryPoint の使用時に問題が発生する場合は、コンテナエージェントを更新するか、代わりに command 配列項目としてコマンドと引数を入力します。

型: 文字列配列

必須: いいえ

コンテナに渡されるエントリポイント。


"entryPoint": ["string", ...]

command

型: 文字列配列

必須: いいえ

コンテナに渡されるコマンド。このパラメータは create-container コマンドの Cmd にマッピングされ、 COMMAND パラメータは docker run にマッピングされます。複数の引数がある場合、各引数は配列内で、区切られた文字列により指定する必要があります。


"command": ["string", ...]

workingDirectory

タイプ: 文字列

必須: いいえ

コマンドを実行するコンテナ内の作業ディレクトリ。このパラメータは、Docker Remote API の Create a container (コンテナを作成する) セクションの WorkingDir にマップされ、--workdir オプションは docker run にマップされます。


"workingDirectory": "string"

environmentFiles

タイプ: オブジェクト配列

必須: いいえ

コンテナに渡す環境変数が含まれるファイルのリスト。このパラメータは docker run コマンドの --env-file オプションにマッピングされます。

最大 10 個の環境ファイルを指定できます。ファイルには、ファイル拡張子 .env が必要です。環境ファイルの各行には、VARIABLE=VALUE 形式で環境変数が含まれています。# で始まる行はコメントとして扱われ、無視されます。

コンテナ定義に個別の環境変数が指定されている場合は、環境ファイルに含まれる変数よりも優先されます。同じ変数を含む複数の環境ファイルが指定されている場合、それらのファイルは上から下に処理されます。一意の変数名を使用することをお勧めします。詳細については、「個々の環境変数を Amazon ECS コンテナに渡す」を参照してください。

value

型: 文字列

必須: はい

環境変数ファイルを含む Amazon S3 オブジェクトの Amazon リソースネーム (ARN)。

type

型: 文字列

必須: はい

使用するファイルのタイプ。s3 はサポートされる唯一の値です。

environment

タイプ: オブジェクト配列

必須: いいえ

コンテナに渡す環境変数。このパラメータは docker create-container コマンドの Env にマッピングされ、--env オプションは docker run コマンドにマッピングされます。

重要

認証情報データなどの機密情報にプレーンテキストの環境変数を使用することはお勧めしません。

name

型: 文字列

必須: はい (environment を使用する場合)

環境変数の名前。

value

型: 文字列

必須: はい (environment を使用する場合)

環境変数の値。


"environment" : [
    { "name" : "string", "value" : "string" },
    { "name" : "string", "value" : "string" }
]

secrets

タイプ: オブジェクト配列

必須: いいえ

コンテナに公開するシークレットを表すオブジェクトです。詳細については、「Amazon ECS コンテナに機密データを渡す」を参照してください。

name

型: 文字列

必須: はい

コンテナの環境変数として設定する値。

valueFrom

型: 文字列

必須: はい

コンテナに公開するシークレット。サポートされている値は、AWS Secrets Manager シークレットの完全な Amazon リソースネーム (ARN)、または AWS Systems Manager Parameter Store 内のパラメータの完全な ARN のいずれかです。

注記

起動するタスクと同じ AWS リージョンに Systems Manager パラメータストアのパラメータまたは Secrets Manager のパラメータが存在する場合は、シークレットの完全な ARN または名前のいずれかを使用できます。パラメータが別のリージョンに存在する場合は、完全な ARN を指定する必要があります。


"secrets": [
    {
        "name": "environment_variable_name",
        "valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
    }
]

privileged

型: ブール値

必須: いいえ

このパラメータが true のとき、コンテナには、ホストコンテナインスタンスに対する昇格されたアクセス権限 (root ユーザーと同様) が付与されます。このパラメータは docker create-container コマンドの Privileged にマッピングされ、--privileged オプションは docker run にマッピングされます。

user

タイプ: 文字列

必須: いいえ

コンテナ内で使用するユーザー。このパラメータは docker create-container コマンドの User にマッピングされ、--user オプションは docker run にマッピングされます。

重要

host ネットワークモードを使用してタスクを実行する場合、ルートユーザー (UID 0) を使用してコンテナを実行しないでください。セキュリティを強化するために、ルート以外のユーザーを使用することをお勧めします。

以下の形式を使用して、user を指定できます。UID または GID を指定する場合は、正の整数として指定する必要があります。

user
user:group
uid
uid:gid
user:gid
uid:group

readonlyRootFilesystem

型: ブール値

必須: いいえ

このパラメータが true のとき、コンテナは読み取り専用のルートファイルシステムを付与されます。このパラメータは docker create-container コマンドの ReadonlyRootfs にマッピングされ、--read-only オプションは docker run にマッピングされます。

dockerSecurityOptions

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

型: 文字列配列

必須: いいえ

SELinux および AppArmor のマルチレベルセキュリティシステム向けのカスタムラベルに提供する文字列のリスト。このフィールドは、Fargate を使用するタスク内のコンテナには無効です。

ulimits

タイプ: Ulimit オブジェクトの配列

必須: いいえ

コンテナで設定する ulimits のリスト。タスク定義で ulimit 値を指定すると、Docker によって設定されたデフォルト値が上書きされます。このパラメータは docker create-container コマンドの Ulimits にマッピングされ、--ulimit オプションは docker run にマッピングされます。有効な命名値は Ulimit データ型で表示されます。

Fargate でホストされる Amazon ECS タスクは、オペレーションシステムで設定されたデフォルトのリソース制限値を使用します。ただし、Fargate がオーバーライドする nofile リソース制限パラメータを除きます。nofile リソース制限は、コンテナが使用できるオープンファイルの数の制限を設定します。デフォルトの nofile ソフト制限は 1024 で、ハード制限は 65535 です。

このパラメータは、コンテナインスタンスで Docker Remote API バージョン 1.18 以上を使用する必要があります。コンテナインスタンスの Docker Remote API のバージョンを確認するには、コンテナインスタンスにログインし、sudo docker version --format '{{.Server.APIVersion}}' コマンドを実行します。

dockerLabels

注記

このパラメータは、Amazon ECS マネージドインスタンスがホストするコンテナではサポートされていません。

型: 文字列間のマッピング

必須: いいえ

コンテナに追加するラベルのキー/値マップ。このパラメータは docker create-container コマンドの Labels にマッピングされ、--label オプションは docker run にマッピングされます。

このパラメータは、コンテナインスタンスで Docker Remote API バージョン 1.18 以上を使用する必要があります。


"dockerLabels": {"string": "string"
      ...}

disableNetworking

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

型: ブール値

必須: いいえ

このパラメータが true のとき、ネットワークはコンテナ内でオフになります。

デフォルトは false です。


"disableNetworking": true|false

links

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

型: 文字列配列

必須: いいえ

link パラメータでは、コンテナがポートマッピングを必要とせずに互いに通信することを許可します。このパラメータは、タスク定義のネットワークモードが bridge に設定されている場合にのみサポートされます。name:internalName コンストラクトは Docker リンクの name:alias に似ています。最大 255 文字の英字 (大文字と小文字)、数字、ハイフン、アンダースコアを使用できます。

重要

同じコンテナインスタンスに配置されたコンテナ同士は、リンクやホストポートマッピングを必要とせずに、互いに通信する場合があります。コンテナインスタンスでのネットワークの分離は、セキュリティグループと VPC 設定によって制御されます。


"links": ["name:internalName", ...]

hostname

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: 文字列

必須: いいえ

コンテナに使用するホスト名。このパラメータは docker create-container の Hostname にマッピングされ、--hostname オプションは docker run にマッピングされます。


"hostname": "string"

dnsServers

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

型: 文字列配列

必須: いいえ

コンテナに提示する DNS サーバーのリスト。


"dnsServers": ["string", ...]

extraHosts

注記

このパラメータは、awsvpc ネットワークモードを使用するタスクではサポートされていません。

タイプ: オブジェクト配列

必須: いいえ

コンテナ上の /etc/hosts ファイルに追加する、ホスト名と IP アドレスのマッピングリスト。

このパラメータは docker create-container コマンドの ExtraHosts にマッピングされ、--add-host オプションは docker run にマッピングされます。


"extraHosts": [
      {
        "hostname": "string",
        "ipAddress": "string"
      }
      ...
    ]

hostname

タイプ: 文字列

必須: はい (extraHosts を使用する場合)

/etc/hosts エントリで使用するホスト名。

ipAddress

タイプ: 文字列

必須: はい (extraHosts を使用する場合)

/etc/hosts エントリで使用する IP アドレス。

readonlyRootFilesystem

タイプ: ブール値

必須: いいえ

このパラメータが true のとき、コンテナはそのルートファイルシステムへの読み取り専用アクセスを許可されます。このパラメータは docker create-container コマンドの ReadonlyRootfs にマッピングされ、--read-only オプションは docker run にマッピングされます。

デフォルトは false です。


"readonlyRootFilesystem": true|false

mountPoints

タイプ: オブジェクト配列

必須: いいえ

コンテナでのデータボリュームのマウントポイント。このパラメータは creat-container Docker API の Volumes にマッピングされ、docker run の --volume オプションにマッピングされます。

Windows コンテナは $env:ProgramData と同じドライブに全部のディレクトリをマウントできます。Windows コンテナは、別のドライブにディレクトリをマウントすることはできません。また、マウントポイントは複数のドライブにまたがることはできません。Amazon EBS ボリュームを Amazon ECS タスクに直接アタッチするには、マウントポイントを指定する必要があります。

sourceVolume

タイプ: 文字列

必須: はい (mountPoints を使用する場合)

マウントするボリュームの名前。

containerPath

型: 文字列

必須: はい (mountPoints を使用する場合)

ボリュームをマウントするコンテナ内のパス。

readOnly

型: ブール値

必須: いいえ

この値が true の場合、コンテナはボリュームへの読み取り専用アクセスを許可されます。この値が false の場合、コンテナはボリュームに書き込むことができます。デフォルト値は false です。

Windows オペレーティングシステムを実行している EC2 インスタンスで実行されるタスクの場合、値をデフォルトの false のままにします。

volumesFrom

タイプ: オブジェクト配列

必須: いいえ

別コンテナからマウントするデータボリューム。このパラメータは docker create-container コマンドの VolumesFrom にマッピングされ、--volumes-from オプションは docker run にマッピングされます。

sourceContainer

タイプ: 文字列

必須: はい (volumesFrom を使用する場合)

ボリュームのマウント元のコンテナの名前。

readOnly

タイプ: ブール値

必須: いいえ

この値が true の場合、コンテナはボリュームへの読み取り専用アクセスを許可されます。この値が false の場合、コンテナはボリュームに書き込むことができます。デフォルト値は false です。


"volumesFrom": [
                {
                  "sourceContainer": "string",
                  "readOnly": true|false
                }
              ]

logConfiguration

タイプ: LogConfiguration オブジェクト

必須: いいえ

コンテナに対するログ構成の仕様です。

ログ設定を使用したタスク定義の例については、「Amazon ECS のタスク定義の例」を参照してください。

このパラメータは docker create-container コマンドの LogConfig にマッピングされ、--log-driver オプションは docker run にマッピングされます。デフォルトでは、コンテナは Docker デーモンで使用されるのと同じロギングドライバーを使用します。ただし、コンテナ定義の中で、このパラメータによりログドライバーを指定することで、Docker デーモンとは異なるログドライバーをコンテナに使用させることも可能です。コンテナに異なるロギングドライバーを使用するには、コンテナインスタンス (またはリモートログ記録オプションの別のログサーバー) でログシステムを適切に設定する必要があります。

コンテナのログ設定を指定する際には、以下の点に注意してください。

現在、Amazon ECS では Docker デーモンに使用可能なログドライバーがいくつかサポートされています。
このパラメータを使用するには、コンテナインスタンスで Docker Remote API のバージョン 1.18 以降が必要です。


"logConfiguration": {
      "logDriver": "awslogs",""splunk", "awsfirelens",
      "options": {"string": "string"
        ...},
	"secretOptions": [{
		"name": "string",
		"valueFrom": "string"
	}]
}

logDriver

型: 文字列

有効な値: "awslogs","splunk","awsfirelens"

必須: はい (logConfiguration を使用する場合)

コンテナに使用するログドライバー。デフォルトでは、上記の有効な値は Amazon ECS コンテナエージェントが通信できるログドライバーです。

サポートされているログドライバーは awslogs、splunk、awsfirelens です。

タスク定義で awslogs ログドライバーを使用してコンテナログを CloudWatch Logs に送信する方法については、「Amazon ECS ログを CloudWatch に送信する」を参照してください。

awsfirelens ログドライバーの使用について、詳細は「Amazon ECS ログを AWS サービスまたは AWS Partner に送信する」を参照してください。

注記

上記に示されていないカスタムドライバーがある場合、GitHub で入手できる Amazon ECS コンテナエージェントプロジェクトを fork し、そのドライバーを使用するようにカスタマイズできます。含めたい変更については、プルリクエストを送信することをお勧めします。ただし、現時点では、このソフトウェアの変更されたコピーの実行はサポートされていません。

このパラメータは、コンテナインスタンスで Docker Remote API バージョン 1.18 以上を使用する必要があります。

options

型: 文字列間のマッピング

必須: いいえ

ログドライバーに送信する設定オプションの Key-Value マップ。

指定できるオプションは、ログドライバーに応じて異なります。awslogs ルーターを使用して Amazon CloudWatch にログをルーティングするときに指定できるオプションには、以下が含まれます。

awslogs-create-group

必須: いいえ

ロググループを自動的に作成させるかどうかを指定します。このオプションを指定しない場合、デフォルトは false です。

注記

awslogs-create-group を使用する前に、IAM ポリシーにはアクセス許可 logs:CreateLogGroup が含まれている必要があります。

awslogs-region

必須: はい

awslogs ログドライバが Docker ログを送信する先の、AWS リージョンを指定します。CloudWatch Logs では、異なるリージョンのクラスターからすべてのログを 1 つのリージョンに送信するように選択できます。これにより、すべてのログを一元的な場所で確認できるようになります。他にも、リージョンごとにそれらを分離して、より細分化することが可能です。このオプションで指定するリージョンに、対象のロググループが存在することを確認してください。

awslogs-group

必須: はい

awslogs ログドライバーがログストリームを送信する先の、ロググループを指定する必要があります。

awslogs-stream-prefix

必須: はい

指定したプレフィックス、コンテナ名、コンテナが属する Amazon ECS タスクの ID にログストリームを関連付けるには、awslogs-stream-prefix オプションを使用します。このオプションでプレフィックスを指定した場合、ログストリームの形式は以下のようになります。


prefix-name/container-name/ecs-task-id

このオプションでプレフィックスを指定しない場合、ログストリームには、コンテナインスタンスの Docker デーモンによって割り当てられたコンテナ ID に基づいた名前が付けられます。Docker コンテナ ID (コンテナインスタンスでのみ使用可能) だけでそのログを送信したコンテナを追跡するのは難しいため、このオプションでプレフィックスを指定することをお勧めします。

Amazon ECS サービスでは、サービス名をプレフィックスとして使用できます。これにより、コンテナが属するサービスへのログストリームと、それを送信したコンテナの名前、そのコンテナが所属するタスクの ID を追跡できます。

Amazon ECS コンソールを使用する際に [Log] ペインにログを表示するためには、ログのストリームプレフィックスを指定する必要があります。

awslogs-datetime-format

必須: いいえ

このオプションは、Python strftime 形式で複数行起動パターンを定義します。ログメッセージは、パターンに一致する 1 行と、それに続くパターンに一致しない行で構成されます。一致する 1 行とは、ログメッセージ間の区切りです。

この形式を使用する場合のユースケースの例としては、スタックダンプなどの解析された出力があり、これを使用しなければ、複数のエントリに記録されることになります。適切なパターンにより、単一のエントリにキャプチャさせます。

詳細については、awslogs-datetime-formatを参照してください。

awslogs-datetime-format と awslogs-multiline-pattern オプションの両方を設定することはできません。

注記

複数行のログ記録は、すべてのログメッセージの正規表現の解析とマッチングを実行します。これによりログ記録のパフォーマンスに悪影響が及ぶ可能性があります。

awslogs-multiline-pattern

必須: いいえ

このオプションでは、正規表現を使用する複数行起動パターンを定義します。ログメッセージは、パターンに一致する 1 行と、それに続くパターンに一致しない行で構成されます。一致する 1 行とは、ログメッセージ間の区切りです。

詳細については、「awslogs-multiline-pattern」を参照してください。

awslogs-datetime-format も設定されている場合は、このオプションは無視されます。

awslogs-datetime-format と awslogs-multiline-pattern オプションの両方を設定することはできません。

注記

複数行のログ記録は、すべてのログメッセージの正規表現の解析とマッチングを実行します。これによりログ記録のパフォーマンスに悪影響が及ぶ可能性があります。

mode

必須: いいえ

有効な値: non-blocking | blocking

このオプションは、コンテナから awslogs ログドライバーへのログメッセージの配信モードを定義します。選択した配信モードは、コンテナからンテナーからのログの流れが中断されたときのアプリケーションの可用性に影響します。

blocking モードを使用しており、CloudWatch へのログのフローが中断されると、stdout ストリームと stderr ストリームに書き込むためのコンテナコードからの呼び出しがブロックされます。その結果、アプリケーションのロギングスレッドがブロックされます。これにより、アプリケーションが応答しなくなり、コンテナのヘルスチェックが失敗する可能性があります。

non-blocking モードを使用する場合、コンテナのログは代わりに max-buffer-size オプションで設定されたメモリ内の中間バッファに保存されます。これにより、ログを CloudWatch に送信できない場合にアプリケーションが応答しなくなるのを防ぎます。サービスの可用性を確保したいが、多少のログ損失があっても問題ない場合は、このモードを使用することをおすすめします。詳細については、「Preventing log loss with non-blocking mode in the awslogs container log driver」を参照してください。

max-buffer-size

必須: いいえ

デフォルト値: 1m

non-blocking モードが使用されている場合、max-buffer-size ログオプションは、中間メッセージ用のストレージに使用されるバッファのサイズを制御します。アプリケーションに基づいて、必ず適切なバッファサイズを指定してください。バッファがいっぱいになると、それ以上ログを保存できなくなります。保存できないログは失われます。

splunk ログルーターを使用してログをルーティングするには、splunk-token と splunk-url を指定する必要があります。

ログの保存と分析のための AWS のサービスまたは AWS Partner Network を送信先としたログのルーティングに awsfirelens ログルーターを使用するときは、log-driver-buffer-limit オプションを設定して、イベントがログルーターコンテナに送信される前に、メモリでバッファリングされるイベントの数を制限できます。この制限は、スループットが高い場合に発生する可能性がある、Docker 内のバッファのメモリ不足による、潜在的なログ損失の問題を解決するのに役立ちます。詳細については、「高スループットの Amazon ECS ログの設定」を参照してください。

awsfirelens を使用してログをルーティングするときに指定できるその他のオプションは、送信先に応じて異なります。Amazon Data Firehose にログをエクスポートするときは、region を使用して AWS リージョンを指定し、delivery_stream を使用してログストリームの名前を指定することができます。

Amazon Kinesis Data Streams にログをエクスポートするときは、region を使用して AWS リージョンを指定し、stream を使用してデータストリーム名を指定することができます。

Amazon OpenSearch Service にログをエクスポートするときは、Name、Host (プロトコルを使用しない OpenSearch Service エンドポイント)、Port、Index、Type、Aws_auth、Aws_region、Suppress_Type_Name、および tls といったオプションを指定できます。

Amazon S3 にログをエクスポートするときは、bucket オプションを使用してバケットを指定できます。また、region、total_file_size、upload_timeout、および use_put_object をオプションとして指定することもできます。

このパラメータは、コンテナインスタンスで Docker Remote API バージョン 1.19 以上を使用する必要があります。

secretOptions

タイプ: オブジェクト配列

必須: いいえ

ログ設定に渡すシークレットを示すオブジェクト。ログ構成で使用されるシークレットには、認証トークン、証明書、または暗号化キーを含められます。詳細については、「Amazon ECS コンテナに機密データを渡す」を参照してください。

name

型: 文字列

必須: はい

コンテナの環境変数として設定する値。

valueFrom

型: 文字列

必須: はい

コンテナのログ設定に公開するシークレット。


"logConfiguration": {
	"logDriver": "splunk",
	"options": {
		"splunk-url": "https://cloud.splunk.com:8080",
		"splunk-token": "...",
		"tag": "...",
		...
	},
	"secretOptions": [{
		"name": "splunk-token",
		"valueFrom": "/ecs/logconfig/splunkcred"
	}]
}

firelensConfiguration

タイプ: FirelensConfiguration オブジェクト

必須: いいえ

コンテナの FireLens 構成。これは、コンテナログのログルーターの指定と設定に使用されます。詳細については、「Amazon ECS ログを AWS サービスまたは AWS Partner に送信する」を参照してください。


{
    "firelensConfiguration": {
        "type": "fluentd",
        "options": {
            "KeyName": ""
        }
    }
}

options

型: 文字列間のマッピング

必須: いいえ

ログルーターの設定時に使用するオプションの Key-Value マップ。このフィールドはオプションで、カスタム設定ファイルを指定するか、タスク、タスク定義、クラスター、コンテナインスタンスの詳細などのメタデータをログイベントに追加するために使用できます。指定した場合、使用する構文は "options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf|filepath"} です。詳細については、「Amazon ECS タスク定義の例: FireLens にログをルーティングする」を参照してください。

type

型: 文字列

必須: はい

使用するログルーター。有効な値は fluentd または fluentbit です。

resourceRequirements

タイプ: ResourceRequirement オブジェクトの配列

必須: いいえ

コンテナに割り当てるリソースのタイプと量。サポートされている唯一のリソースは GPU です。

type

タイプ: 文字列

必須: はい

コンテナに割り当てるリソースのタイプ。サポート対象の値は GPU です。

value

タイプ: 文字列

必須: はい

指定されたリソースタイプの値。

GPU タイプを使用する場合、値は Amazon ECS コンテナエージェントがコンテナ用に予約する物理的な GPUs の数です。タスク内でコンテナ用に予約されている、すべての GPU の数は、タスクが起動されたコンテナインスタンスで使用できる GPU の数を超えることはできません。

GPU は、Fargate 上で実行するタスクでは使用できません。

startTimeout

タイプ: 整数

必須: いいえ

値の例: 120

コンテナの依存関係解決の再試行を止めるまでの待機時間 (秒)。

例えば、タスク定義内に 2 つのコンテナを指定するとします。containerA は、COMPLETE、SUCCESS、または HEALTHY のいずれかのステータスに到達する containerB に依存関係を持ちます。startTimeout の値に containerB が指定されていて、コンテナが時間内に目標のステータスまで到達しない場合、containerA は開始しません。

注記

あるコンテナが依存関係における制限事項を満たさない場合、または制限を満たす前にタイムアウトした場合、Amazon ECS は、依存関係にある他のコンテナの状態も次に遷移させることはしません。

最大値は 600 秒 (10 分) です。

stopTimeout

タイプ: 整数

必須: いいえ

値の例: 120

コンテナが正常に終了しなかった場合にコンテナが強制終了されるまでの待機時間 (秒)。

このパラメータを指定しない場合には、デフォルト値の 30 秒が適用されます。最大値は 86400 秒 (24 時間) です。

dependsOn

型: ContainerDependency オブジェクトの配列

必須: いいえ

コンテナの起動と停止に定義されている依存関係。コンテナには複数の依存関係を含めることができます。依存関係がコンテナの起動に対して定義されている場合、コンテナの停止の場合、依存関係は逆になります。例については、コンテナの依存関係を参照してください。

注記

あるコンテナが依存関係における制限事項を満たさない場合、または制限を満たす前にタイムアウトした場合、Amazon ECS は、依存関係にある他のコンテナの状態も次に遷移させることはしません。

このパラメータでは、タスクまたはサービスがプラットフォームバージョン 1.3.0 以降（Linux）または 1.0.0（Windows）を使用している必要があります。


"dependsOn": [
    {
        "containerName": "string",
        "condition": "string"
    }
]

containerName

タイプ: 文字列

必須: はい

コンテナ名が指定された条件を満たしている必要があります。

condition

型: 文字列

必須: はい

コンテナの依存関係の条件です。使用可能な条件とその動作を以下に示します。

START - この条件は、すぐに現在のリンクとボリュームの動作をエミュレートします。この条件は、他のコンテナの開始を許可する前に、依存コンテナが開始されていることを検証します。
COMPLETE - この条件は、他のコンテナの開始を許可する前に、依存コンテナの実行が完了 (終了) することを検証します。これは、スクリプトを実行して終了するだけの、重要性の低いコンテナのために便利です。この条件は、必須コンテナには設定できません。
SUCCESS - この条件は COMPLETE と同じですが、コンテナが zero ステータスで終了していることも必要です。この条件は、必須コンテナには設定できません。
HEALTHY — この条件は、他のコンテナの開始を許可する前に、依存コンテナがそのコンテナのヘルスチェックに合格したことを検証します。これには、タスク定義に設定されているヘルスチェックが依存コンテナにある必要があります。タスクの起動時にのみ、この条件が確認されます。

systemControls

型: SystemControl オブジェクト

必須: いいえ

コンテナ内で設定する名前空間カーネルパラメータのリスト。このパラメータは docker create-container コマンドの Sysctls にマッピングされ、--sysctl オプションは docker run にマッピングされます。例えば、接続をより長く維持するように net.ipv4.tcp_keepalive_time 設定を構成できます。

awsvpc または host ネットワークモードも使用する単一のタスクで、複数のコンテナに対してネットワーク関連の systemControls パラメータを指定することは推奨されません。これを行うと、次のような欠点があります。

systemControls をいずれかのコンテナ用に設定した場合、タスク内のすべてのコンテナに適用されます。単一のタスクの複数のコンテナに対して異なる systemControls を設定すると、最後に開始されたコンテナによって、有効になる systemControls が決定します。

タスク内でコンテナに使用するため IPC リソース名前空間を設定している場合、システムコントロールには以下の条件が適用されます。詳細については、「IPC モード」を参照してください。

host IPC モードを使用するタスクの場合、IPC 名前空間の systemControls はサポートされていません。
task IPC モードを使用するタスクでは、IPC 名前空間の systemControls 値が、タスク内のすべてのコンテナに適用されます。


"systemControls": [
    {
         "namespace":"string",
         "value":"string"
    }
]

namespace

タイプ: 文字列

必須: いいえ

value を設定する名前空間カーネルパラメータ。

有効なネットワーク名前空間値: "net.*" で始まる Sysctls。Fargate では、コンテナ内に存在する名前空間 Sysctls のみが受け入れられます。

これらの値はすべて Fargate でサポートされています。

value

タイプ: 文字列

必須: いいえ

namespace で指定された名前空間カーネルパラメータの値。

interactive

型: ブール値

必須: いいえ

このパラメータが true の場合、stdin または tty を割り当てる必要がある、コンテナ化されたアプリケーションをデプロイすることができます。このパラメータは docker create-container コマンドの OpenStdin にマッピングされ、--interactive オプションは docker run にマッピングされます。

デフォルトは false です。

pseudoTerminal

タイプ: ブール値

必須: いいえ

このパラメータが true の場合、TTY が割り当てられます。このパラメータは docker create-container コマンドの Tty にマッピングされ、--tty オプションは docker run にマッピングされます。

デフォルトは false です。

linuxParameters

型: LinuxParameters オブジェクト

必須: いいえ

Linux カーネル機能など、コンテナに適用される Linux に固有の変更です。

capabilities

型: KernelCapabilities オブジェクト

必須: いいえ

Docker から提供されているデフォルト構成に追加または削除される、コンテナ用の Linux 機能。

devices

型: デバイスオブジェクト配列

必須: いいえ

コンテナに公開するすべてのホストデバイス。このパラメータは docker create-container コマンドの Devices にマッピングされ、--device オプションは docker run にマッピングされます。

initProcessEnabled

型: ブール値

必須: いいえ

信号を転送しプロセスを利用するコンテナ内で、init を実行。このパラメータは docker run の --init オプションにマッピングされます。

maxSwap

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: 整数

必須: いいえ

コンテナが使用できるスワップメモリの合計 (MiB 単位)。このパラメータは、docker run の --memory-swap オプションに変換されます。値はコンテナメモリの合計に maxSwap の値を加えた値です。

swappiness

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: 整数

必須: いいえ

これにより、コンテナのメモリスワップ動作を調整できます。swappiness 値が 0 の場合、絶対に必要な場合を除きスワップは行われません。swappiness 値が 100 の場合、ページは非常に積極的にスワップされます。有効な値は、0 と 100 の間の整数です。swappiness パラメータを指定しない場合、デフォルト値の 60 が使用されます。maxSwap の値が指定されていない場合、このパラメータは無視されます。このパラメータは、docker run の --memory-swappiness オプションにマッピングされます。

sharedMemorySize

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

タイプ: 整数

必須: いいえ

/dev/shm ボリュームのサイズ (MiB) です。このパラメータは docker run の --shm-size オプションにマッピングされます。

tmpfs

注記

このパラメータは、Amazon ECS マネージドインスタンス上で実行されるタスクには対応していません。

型: Tmpfs オブジェクト配列

必須: いいえ

Tmpfs マウントのコンテナパス、マウントオプション、およびサイズ (MiB) です。このパラメータは docker run の --tmpfs オプションにマッピングされます。

Amazon ECS マネージドインスタンスの Amazon ECS タスク定義パラメータ

ファミリー

容量

タスクロール

タスク実行ロール

注記

ネットワークモード

重要

ランタイムプラットフォーム

タスクサイズ

注記

その他のタスク定義パラメータ

トピック

エフェメラルストレージ

注記

IPC モード

注記

PID モード

プロキシ設定

注記

タグ

Elastic Inference アクセラレーター (廃止)

注記

注記

配置の制約事項

ボリューム

注記

注記

コンテナ定義

トピック

名前

イメージ

メモリ

注記

注記

CPU

注記

ポートマッピング

注記

重要

プライベートリポジトリの認証情報

注記

Essential

エントリポイント

コマンド

作業ディレクトリパス

詳細コンテナ定義パラメータ

トピック

再起動ポリシー

ヘルスチェック

環境

注記

重要

重要

注記

セキュリティ

重要

注記

注記

ネットワーク設定

注記

注記

重要

注記

注記

注記

ストレージとログ記録

注記

注記

注記

注記

リソースの要件

コンテナのタイムアウト

注記

コンテナの依存関係

注記

システムコントロール

インタラクティブ

擬似ターミナル

Linux パラメータ