AWS::ECS::TaskDefinition
AWS::ECS::TaskDefinition
リソースは、Amazon Elastic Container Service (Amazon ECS) タスクのコンテナとボリュームの定義について説明します。Amazon
ECS サービスまたはタスクを通じて、使用する Docker イメージ、必要なリソース、タスク定義の開始に関連する他の設定を指定できます。
構文
AWS CloudFormation テンプレートでこのエンティティを宣言するには、次の構文を使用します。
JSON
{ "Type" : "AWS::ECS::TaskDefinition", "Properties" : { "ContainerDefinitions" :
[ ContainerDefinition, ... ]
, "Cpu" :String
, "ExecutionRoleArn" :String
, "Family" :String
, "InferenceAccelerators" :[ InferenceAccelerator, ... ]
, "IpcMode" :String
, "Memory" :String
, "NetworkMode" :String
, "PidMode" :String
, "PlacementConstraints" :[ TaskDefinitionPlacementConstraint, ... ]
, "ProxyConfiguration" :ProxyConfiguration
, "RequiresCompatibilities" :[ String, ... ]
, "Tags" :[ Tag, ... ]
, "TaskRoleArn" :String
, "Volumes" :[ Volume, ... ]
} }
YAML
Type: AWS::ECS::TaskDefinition Properties: ContainerDefinitions:
- ContainerDefinition
Cpu:String
ExecutionRoleArn:String
Family:String
InferenceAccelerators:- InferenceAccelerator
IpcMode:String
Memory:String
NetworkMode:String
PidMode:String
PlacementConstraints:- TaskDefinitionPlacementConstraint
ProxyConfiguration:ProxyConfiguration
RequiresCompatibilities:- String
Tags:- Tag
TaskRoleArn:String
Volumes:- Volume
プロパティ
ContainerDefinitions
-
タスクを構成するさまざまなコンテナを記述する JSON 形式のコンテナの定義のリスト。コンテナの定義パラメータとデフォルト値の詳細については、『Amazon Elastic Container Service 開発者ガイド』の「Amazon ECS のタスク定義」を参照してください。
必須: いいえ
タイプ: ContainerDefinition のリスト
Update requires: Replacement
Cpu
-
タスクで使用されている
cpu
ユニットの数。EC2 起動タイプを使用する場合、このフィールドはオプションであり、任意の値を使用できます。Fargate 起動タイプを使用している場合、このフィールドは必須であり、次のいずれかの値を使用する必要があります。この値によりmemory
パラメータの有効な値の範囲が決まります。-
256 (.25 vCPU) - 使用可能な
memory
値: 512 (0.5 GB)、1024 (1 GB)、2048 (2 GB) -
512 (.5 vCPU) - 使用可能な
memory
値: 1024 (1 GB)、2048 (2 GB)、3072 (3 GB)、4096 (4 GB) -
1024 (1 vCPU) - 使用可能な
memory
値: 2048 (2 GB)、3072 (3 GB)、4096 (4 GB)、5120 (5 GB)、6144 (6 GB)、7168 (7 GB)、8192 (8 GB) -
2048 (2 vCPU) - 使用可能な
memory
値: 4096 (4 GB) ~ 16384 (16 GB) (1024 (1 GB) のインクリメント) -
4096 (4 vCPU) - 使用可能な
memory
値: 8192 (8 GB) ~ 30720 (30 GB) (1024 (1 GB) のインクリメント)
必須: いいえ
タイプ: 文字列
Update requires: Replacement
-
ExecutionRoleArn
-
ユーザーに代わって AWS API コールを実行するアクセス許可を Amazon ECS コンテナエージェントに付与するタスク実行ロールの Amazon リソースネーム (ARN)。タスク実行 IAM ロールは、タスクの要件に応じて必要です。詳細については、Amazon Elastic Container Service 開発者ガイドの「Amazon ECS タスク実行 IAM ロール」を参照してください。
必須: いいえ
タイプ: 文字列
Update requires: Replacement
Family
-
このタスク定義が登録されたファミリーの名前。最大 255 文字の英字 (大文字と小文字)、数字、ハイフン、アンダースコアを使用できます。
ファミリーはタスク定義の複数のバージョンをグループ化します。Amazon ECS は、ファミリーに登録した最初のタスク定義にリビジョン番号 1 を付与します。Amazon ECS は、追加された各タスク定義に順番にリビジョン番号を付与していきます。
注記 タスク定義を更新するときにリビジョン番号を使用するには、このプロパティを指定します。値を指定しない場合、更新するたびに AWS CloudFormation によって新しいタスク定義が生成されます。
必須: いいえ
タイプ: 文字列
Update requires: Replacement
InferenceAccelerators
-
タスク内のコンテナに使用する Elastic Inference アクセラレーター。
必須: いいえ
タイプ: InferenceAccelerator のリスト
Update requires: Replacement
IpcMode
-
タスクのコンテナで使用する IPC リソースの名前空間。有効な値は
host
、task
またはnone
です。host
が指定されている場合、同じコンテナインスタンスでhost
IPC モードを指定したタスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じ IPC リソースを共有します。task
が指定されている場合、指定したタスク内のすべてのコンテナは同じ IPC リソースを共有します。none
が指定されている場合、タスクのコンテナ内の IPC リソースはプライベートです。タスク内またはコンテナインスタンスの他のコンテナと共有されることはありません。値を指定しない場合、IPC リソース名前空間の共有はコンテナインスタンスの Docker デーモンの設定によって異なります。詳細については、Docker run reference の「IPC settings」を参照してください。 host
IPC モードを使用する場合は、意図せず IPC 名前空間が公開されるリスクが高いことに注意してください。詳細については、「Docker security」を参照してください。 タスクのコンテナに
systemControls
を使用して名前空間のカーネルパラメータを設定している場合は、次のように IPC リソース名前空間に適用されます。詳細については、「Amazon Elastic Container Service 開発者ガイド」の「システムコントロール」を参照してください。-
host
IPC モードを使用するタスクの場合、systemControls
に関連する IPC 名前空間はサポートされていません。 -
task
IPC モードを使用するタスクでは、systemControls
に関連する IPC 名前空間はタスク内のすべてのコンテナに適用されます。
注記 このパラメータは、Windows コンテナ、または Fargate 起動タイプを使用するタスクではサポートされていません。
必須: いいえ
タイプ: 文字列
許可された値:
host | none | task
Update requires: Replacement
-
Memory
-
タスクが使用するメモリの量 (MiB 単位)。
EC2 起動タイプを使用する場合、タスクレベルのメモリ値またはコンテナレベルのメモリ値を指定する必要があります。このフィールドはオプションです。任意の値を使用できます。タスクレベルのメモリ値が指定されている場合、コンテナレベルのメモリ値はオプションです。コンテナレベルのメモリとメモリ予約の詳細については、「ContainerDefinition」を参照してください。
Fargate 起動タイプを使用している場合、このフィールドは必須であり、次のいずれかの値を使用する必要があります。この値により
cpu
パラメータの有効な値の範囲が決まります。-
512 (0.5 GB)、1024 (1 GB)、2048 (2 GB) - 使用可能な
cpu
値: 256 (.25 vCPU) -
1024 (1 GB)、2048 (2 GB)、3072 (3 GB)、4096 (4 GB) - 使用可能な
cpu
値: 512 (.5 vCPU) -
2048 (2 GB)、3072 (3 GB)、4096 (4 GB)、5120 (5 GB)、6144 (6 GB)、7168 (7 GB)、8192 (8 GB) - 使用可能な
cpu
値: 1024 (1 vCPU) -
4096 (4 GB) ~ 16384 (16 GB) (1024 (1 GB) のインクリメント) - 使用可能な
cpu
値: 2048 (2 vCPU) -
8192 (8 GB) ~ 30720 (30 GB) (1024 (1 GB) のインクリメント) - 使用可能な
cpu
値: 4096 (4 vCPU)
必須: いいえ
タイプ: 文字列
Update requires: Replacement
-
NetworkMode
-
タスクのコンテナで使用する Docker ネットワーキングモード。有効な値は、
none
、bridge
、awsvpc
、およびhost
です。デフォルトの Docker ネットワークモードはbridge
です。Fargate 起動タイプを使用している場合、awsvpc
ネットワークモードが必要です。EC2 起動タイプを使用している場合、どのネットワークモードも使用できます。ネットワークモードをnone
に設定した場合、コンテナの定義にポートマッピングを指定することはできず、タスクのコンテナに外部接続がなくなります。host
およびawsvpc
ネットワークモードでは、コンテナのネットワークパフォーマンスは最大限に高まります。bridge
モードとは異なり、仮想化ネットワークスタックではなく、EC2 ネットワークスタックを使用するためです。host
およびawsvpc
ネットワークモードでは、公開されるコンテナポートは対応するホストポート (host
ネットワークモードの場合) またはアタッチされた Elastic Network Interface ポート (awsvpc
ネットワークモードの場合) に直接マッピングされるため、動的ホストポートマッピングは利用できません。ネットワークモードが
awsvpc
の場合、タスクに Elastic Network Interface が割り当てられるため、タスク定義を使用したサービスの作成時またはタスクの実行時に、NetworkConfiguration 値を指定する必要があります。詳細については、Amazon Elastic Container Service 開発者ガイドの「タスクネットワーキング」を参照してください。注記 現在、Amazon ECS に最適化された AMI、
ecs-init
パッケージがある他の Amazon Linux バリアント、または AWS Fargate インフラストラクチャのみが、awsvpc
ネットワークモードをサポートします。host
ネットワークモードでポートマッピングが使用されている場合は、1 つのコンテナインスタンスで同じタスクの複数のインスタンスを実行することはできません。Windows 用の Docker では Linux 用の Docker とは異なるネットワークモードを使用します。Windows コンテナにタスク定義を登録するときに、ネットワークモードを指定しないでください。コンソールを使用して Windows コンテナにタスク定義を登録する場合は、
<default>
ネットワークモードオブジェクトを選択する必要があります。詳細については、『Docker run リファレンス』の「ネットワーク設定
」を参照してください。 必須: いいえ
タイプ: 文字列
許可された値:
awsvpc | bridge | host | none
Update requires: Replacement
PidMode
-
タスクのコンテナで使用するプロセス名前空間。有効な値は
host
またはtask
です。host
が指定されている場合、同じコンテナインスタンスでhost
PID モードを指定したタスク内のすべてのコンテナは、ホスト Amazon EC2 インスタンスと同じ IPC リソースを共有します。task
が指定されている場合、指定したタスク内のすべてのコンテナは同じプロセス名前空間を共有します。値が指定されていない場合、デフォルトはプライベート名前空間です。詳細については、Docker run reference の「PID settings」を参照してください。 host
PID モードを使用する場合は、意図せずプロセス名前空間が公開されるリスクが高いことに注意してください。詳細については、「Docker security」を参照してください。 注記 このパラメータは、Windows コンテナ、または Fargate 起動タイプを使用するタスクではサポートされていません。
必須: いいえ
タイプ: 文字列
許可された値:
host | task
Update requires: Replacement
PlacementConstraints
-
タスクに使用する、配置制約オブジェクトの配列。Fargate 起動タイプを使用している場合、このフィールドは有効ではありません。
必須: いいえ
タイプ: TaskDefinitionPlacementConstraint のリスト
Update requires: Replacement
ProxyConfiguration
-
ProxyConfiguration
プロパティは、App Mesh プロキシの設定の詳細を指定します。プロキシ設定を有効にするには、Amazon ECS コンテナインスタンスにコンテナエージェントのバージョン 1.26.0 以上と
ecs-init
パッケージのバージョン 1.26.0-1 以上が必要です。コンテナインスタンスが Amazon ECS に最適化された AMI バージョン20190301
以降から起動される場合、コンテナエージェントおよびecs-init
の必要なバージョンが含まれます。詳細については、Amazon Elastic Container Service 開発者ガイドの「Amazon ECS に最適化された Linux AMI」を参照してください。必須: いいえ
タイプ: ProxyConfiguration
Update requires: Replacement
RequiresCompatibilities
-
タスクに必要な起動タイプ。値を指定しない場合、デフォルト値は
EC2
です。有効な値は、EC2
およびFARGATE
です。必須: いいえ
タイプ: 文字列のリスト
Update requires: Replacement
Tags
-
タスク定義に適用し、サービスの分類と整理に役立つメタデータ。タグはそれぞれ、1 つのキーとオプションの 1 つの値で構成されており、どちらもお客様側が定義します。
タグには以下のような基本制限があります。
-
リソースあたりのタグの最大数は 50 です
-
タグキーは、リソースごとにそれぞれ一意である必要があります。また、各タグキーに設定できる値は 1 つのみです。
-
キーの最大長 - 128 文字 (Unicode) (UTF-8)
-
値の最大長 - 256 文字 (Unicode) (UTF-8)
-
複数のサービス間およびリソース間でタグ付けスキーマを使用する場合、他のサービスでも許可される文字に制限が適用されることがあるのでご注意ください。一般的に使用が許可される文字は、UTF-8 で表現できる文字、数字、スペース、および +、-、=、.、_、:、/、@。
-
タグのキーと値は大文字と小文字が区別されます。
-
aws:
、AWS:
、またはその大文字または小文字の組み合わせを、キーまたは値のプレフィックスとして使用しないでください。これらの文字列は AWS による使用のために予約されています。このプレフィックスが含まれるタグのキーや値を編集または削除することはできません。このプレフィックスを持つタグは、リソースあたりのタグ数の制限時には計算されません。
必須: いいえ
タイプ: Tag のリスト
最大:
50
Update requires: No interruption
-
TaskRoleArn
-
ユーザーに代わってタスク内のコンテナに AWS API を 呼び出す許可を与える AWS Identity and Access Management (IAM) ロールの短い名前または完全な Amazon リソースネーム (ARN)。詳細については、Amazon Elastic Container Service 開発者ガイドの「Amazon ECS のタスクロール」を参照してください。
Windows 上のタスクの IAM ロールでは、Amazon ECS に最適化された Windows AMI を起動するときに
-EnableTaskIAMRole
オプションを設定する必要があります。また、コンテナでは、この機能を利用するために一部の設定コードを実行する必要があります。詳細については、『Amazon Elastic Container Service 開発者ガイド』の「Windows タスク用の IAM ロール」を参照してください。必須: いいえ
タイプ: 文字列
Update requires: Replacement
Volumes
-
タスクのボリューム定義のリスト。
タスクが Fargate 起動タイプを使用している場合、
host
およびsourcePath
パラメータはサポートされません。ボリューム定義パラメータとデフォルト値の詳細については、『Amazon Elastic Container Service 開発者ガイド』の「Amazon ECS のタスク定義」を参照してください。
必須: いいえ
タイプ: Volume のリスト
Update requires: Replacement
戻り値
Ref
このリソースの論理 ID を組み込みの Ref
関数に渡すと、Ref
は次を返します: Amazon リソースネーム (ARN)。
次のサンプルでは、Ref
関数が MyTaskDefinition
タスク定義の ARN (arn:aws:ecs:us-west-2:123456789012:task-definition/TaskDefinitionFamily:1
など) を返します。
{ "Ref": "MyTaskDefinition" }
For more information about using the Ref
function, see Ref.
Fn::GetAtt
例
Amazon ECS タスク定義の作成
次の例では、コンテナの定義 2 つとボリューム定義 1 つを含む Amazon ECS タスク定義を定義します。
JSON
"taskdefinition": { "Type": "AWS::ECS::TaskDefinition", "Properties" : { "ContainerDefinitions" : [ { "Name": {"Ref": "AppName"}, "MountPoints": [ { "SourceVolume": "my-vol", "ContainerPath": "/var/www/my-vol" } ], "Image":"amazon/amazon-ecs-sample", "Cpu": 256, "PortMappings":[ { "ContainerPort": {"Ref":"AppContainerPort"}, "HostPort": {"Ref":"AppHostPort"} } ], "EntryPoint": [ "/usr/sbin/apache2", "-D", "FOREGROUND" ], "Memory": 512, "Essential": true }, { "Name": "busybox", "Image": "busybox", "Cpu": 256, "EntryPoint": [ "sh", "-c" ], "Memory": 512, "Command": [ "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\"" ], "Essential" : false, "VolumesFrom": [ { "SourceContainer": {"Ref":"AppName"} } ] }], "Volumes": [ { "Host": { "SourcePath": "/var/lib/docker/vfs/dir/" }, "Name": "my-vol" }] } }
YAML
taskdefinition: Type: AWS::ECS::TaskDefinition Properties: ContainerDefinitions: - Name: Ref: "AppName" MountPoints: - SourceVolume: "my-vol" ContainerPath: "/var/www/my-vol" Image: "amazon/amazon-ecs-sample" Cpu: 256 PortMappings: - ContainerPort: Ref: "AppContainerPort" HostPort: Ref: "AppHostPort" EntryPoint: - "/usr/sbin/apache2" - "-D" - "FOREGROUND" Memory: 512 Essential: true - Name: "busybox" Image: "busybox" Cpu: 256 EntryPoint: - "sh" - "-c" Memory: 512 Command: - "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\"" Essential: false VolumesFrom: - SourceContainer: Ref: "AppName" Volumes: - Host: SourcePath: "/var/lib/docker/vfs/dir/" Name: "my-vol"
Amazon ECS タスク定義の作成
次の例では、必要な互換性として EC2 と FARGATE を指定する Amazon ECS タスク定義を指定します。
JSON
{ "AWSTemplateFormatVersion": "2010-09-09", "Resources": { "taskdefinition": { "Type": "AWS::ECS::TaskDefinition", "Properties": { "RequiresCompatibilities": [ "EC2", "FARGATE" ], "ContainerDefinitions": [ { "Name": "my-app", "MountPoints": [ { "SourceVolume": "my-vol", "ContainerPath": "/var/www/my-vol" } ], "Image": "amazon/amazon-ecs-sample", "Cpu": 256, "EntryPoint": [ "/usr/sbin/apache2", "-D", "FOREGROUND" ], "Memory": 512, "Essential": true }, { "Name": "busybox", "Image": "busybox", "Cpu": 256, "EntryPoint": [ "sh", "-c" ], "Memory": 512, "Command": [ "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\"" ], "Essential": false, "DependsOn": [ { "ContainerName": "my-app", "Condition": "START" } ], "VolumesFrom": [ { "SourceContainer": "my-app" } ] } ], "Volumes": [ { "Host": { "SourcePath": "/var/lib/docker/vfs/dir/" }, "Name": "my-vol" } ] } } } }
YAML
AWSTemplateFormatVersion: 2010-09-09 Resources: taskdefinition: Type: AWS::ECS::TaskDefinition Properties: RequiresCompatibilities: - "EC2" - "FARGATE" ContainerDefinitions: - Name: "my-app" MountPoints: - SourceVolume: "my-vol" ContainerPath: "/var/www/my-vol" Image: "amazon/amazon-ecs-sample" Cpu: 256 EntryPoint: - "/usr/sbin/apache2" - "-D" - "FOREGROUND" Memory: 512 Essential: true - Name: "busybox" Image: "busybox" Cpu: 256 EntryPoint: - "sh" - "-c" Memory: 512 Command: - "/bin/sh -c \"while true; do /bin/date > /var/www/my-vol/date; sleep 1; done\"" Essential: false DependsOn: - ContainerName: my-app Condition: START VolumesFrom: - SourceContainer: "my-app" Volumes: - Host: SourcePath: "/var/lib/docker/vfs/dir/" Name: "my-vol"