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

このタスクでコンテナが引き受けることのできるタスク実行ロールの Amazon リソースネーム (ARN)。このタスクのすべてのコンテナには、このロールに指定されているアクセス許可が付与されます。

必須: いいえ

タイプ: 文字列

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 起動タイプを使用している場合、このフィールドはオプションであり、任意の値を使用できます。タスクレベルのメモリ値が指定されている場合、コンテナレベルのメモリ値はオプションです。

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

戻り値

参照番号

このリソースの論理 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.

例

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": "10",
      "PortMappings":[
        {
          "ContainerPort": {"Ref":"AppContainerPort"},
          "HostPort": {"Ref":"AppHostPort"}
        }
      ],
      "EntryPoint": [
        "/usr/sbin/apache2",
        "-D",
        "FOREGROUND"
      ],
      "Memory":"0.5GB",
      "Essential": "true"
    },
    {
      "Name": "busybox",
      "Image": "busybox",
      "Cpu": "10",
      "EntryPoint": [
        "sh",
        "-c"
      ],
      "Memory": "0.5GB",
      "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: "10"
        PortMappings: 
          - 
            ContainerPort: 
              Ref: "AppContainerPort"
            HostPort: 
              Ref: "AppHostPort"
        EntryPoint: 
          - "/usr/sbin/apache2"
          - "-D"
          - "FOREGROUND"
        Memory: "0.5GB"
        Essential: true
      - 
        Name: "busybox"
        Image: "busybox"
        Cpu: "10"
        EntryPoint: 
          - "sh"
          - "-c"
        Memory: "0.5GB"
        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": "10",
            "EntryPoint": [
              "/usr/sbin/apache2",
              "-D",
              "FOREGROUND"
            ],
            "Memory": "0.5GB",
            "Essential": "true"
          },
          {
            "Name": "busybox",
            "Image": "busybox",
            "Cpu": "10",
            "EntryPoint": [
              "sh",
              "-c"
            ],
            "Memory": "0.5GB",
            "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: "10"
          EntryPoint: 
            - "/usr/sbin/apache2"
            - "-D"
            - "FOREGROUND"
          Memory: "0.5GB"
          Essential: true
        - 
          Name: "busybox"
          Image: "busybox"
          Cpu: "10"
          EntryPoint: 
            - "sh"
            - "-c"
          Memory: "0.5GB"
          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"