Menu
AWS CloudFormation
User Guide (API Version 2010-05-15)

AWS::ECS::TaskDefinition

The AWS::ECS::TaskDefinition resource describes the container and volume definitions of an Amazon EC2 Container Service (Amazon ECS) task. You can specify which Docker images to use, the required resources, and other configurations related to launching the task definition through an Amazon ECS service or task.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

Copy
{ "Type" : "AWS::ECS::TaskDefinition", "Properties" : { "Volumes" : [ Volume Definition, ... ], "Family" : String, "NetworkMode" : String, "TaskRoleArn" : String, "ContainerDefinitions" : [ Container Definition, ... ] } }

YAML

Copy
Type: "AWS::ECS::TaskDefinition" Properties: Volumes: - Volume Definition Family: String NetworkMode: String TaskRoleArn: String ContainerDefinitions: - Container Definition

Properties

Volumes

A list of volume definitions in JSON format for volumes that you can use in your container definitions.

Required: Yes

Type: List of Amazon EC2 Container Service TaskDefinition Volumes

Update requires: Replacement

Family

The name of a family that this task definition is registered to. A family groups multiple versions of a task definition. Amazon ECS gives the first task definition that you registered to a family a revision number of 1. Amazon ECS gives sequential revision numbers to each task definition that you add.

Note

To use revision numbers when you update a task definition, specify this property. If you don't specify a value, AWS CloudFormation generates a new task definition each time you update it.

Required: No

Type: String

Update requires: Replacement

NetworkMode

The Docker networking mode to use for the containers in the task, such as none, bridge, or host. For information about network modes, see NetworkMode in the Task Definition Parameters topic in the Amazon EC2 Container Service Developer Guide.

Required: No

Type: String

Update requires: Replacement

TaskRoleArn

The Amazon Resource Name (ARN) of an AWS Identity and Access Management (IAM) role that grants containers in the task permission to call AWS APIs on your behalf. For more information, see IAM Roles for Tasks in the Amazon EC2 Container Service Developer Guide.

Required: No

Type: String

Update requires: Replacement

ContainerDefinitions

A list of container definitions in JSON format that describe the containers that make up your task.

Required: Yes

Type: List of Amazon EC2 Container Service TaskDefinition ContainerDefinitions

Update requires: Replacement

Return Value

Ref

When the logical ID of this resource is provided to the Ref intrinsic function, Ref returns the Amazon Resource Name (ARN).

In the following sample, the Ref function returns the ARN of the MyTaskDefinition task, such as arn:aws:ecs:us-west-2:123456789012:task/1abf0f6d-a411-4033-b8eb-a4eed3ad252a.

Copy
{ "Ref": "MyTaskDefinition" }

For more information about using the Ref function, see Ref.

Examples

The following examples define an Amazon ECS task definition, which includes two container definitions and one volume definition:

JSON

Copy
"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":"500", "Essential": "true" }, { "Name": "busybox", "Image": "busybox", "Cpu": "10", "EntryPoint": [ "sh", "-c" ], "Memory": "500", "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

Copy
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: "500" Essential: "true" - Name: "busybox" Image: "busybox" Cpu: "10" EntryPoint: - "sh" - "-c" Memory: "500" 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"

Related Resources

For a complete sample template that shows how you can create an Amazon ECS cluster and service, see Amazon EC2 Container Service Template Snippets.