AWS::ECS::TaskDefinition - AWS CloudFormation
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

AWS::ECS::TaskDefinition

AWS::ECS::TaskDefinition 资源描述 Amazon Elastic Container Service (Amazon ECS) 任务的容器和卷定义。您可以指定要使用的 Docker 映像、所需的资源以及与通过 Amazon ECS 服务或任务启动任务定义相关的其他配置。

语法

要在 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, ... ] } }

属性

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),该角色授予 Amazon ECS 容器代理代表您进行 AWS API 调用的权限。任务执行 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 资源命名空间。有效值为 hosttasknone。如果指定了 host,则在同一容器实例上指定了 host IPC 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的 IPC 资源。如果指定了 task,则指定任务中的所有容器将共享相同的 IPC 资源。如果指定了 none,则任务的容器中的 IPC 资源是私有的,不与任务中或容器实例上的其他容器共享。如果未指定任何值,则 IPC 资源命名空间共享取决于容器实例上的 Docker 守护程序设置。有关更多信息,请参阅 Docker 运行参考 中的 IPC 设置

如果使用了 host IPC 模式,请注意,发生非预期的 IPC 命名空间公开的风险会提高。有关更多信息,请参阅 Docker 安全性

如果您使用 systemControls 为任务中的容器设置具有命名空间的内核参数,则以下内容将适用于您的 IPC 资源命名空间。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南中的系统控制

  • 对于使用 host IPC 模式的任务,不支持与 IPC 命名空间相关的 systemControls

  • 对于使用 task IPC 模式的任务,与 IPC 命名空间相关的 systemControls 将适用于任务中的所有容器。

注意

使用 Fargate 启动类型的 Windows 容器或任务不支持此参数。

必需:否

类型:字符串

允许的值host | none | task

Update requires: Replacement

Memory

任务使用的内存量 (以 MB 为单位)。

如果使用的是 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 联网模式。有效值为 nonebridgeawsvpchost。默认 Docker 网络模式为 bridge。如果使用 Fargate 启动类型,则需要 awsvpc 网络模式。如果使用 EC2 启动类型,则可以使用任何网络模式。如果将网络模式设置为 none,则无法在容器定义中指定端口映射,并且任务的容器没有外部连接性。hostawsvpc 网络模式为容器提供最高的联网性能,因为它们使用 EC2 网络堆栈,而不是 bridge 模式提供的虚拟化网络堆栈。

使用 hostawsvpc 网络模式,公开的容器端口将直接映射到相应的主机端口(用于 host 网络模式)或附加的弹性网络接口端口(用于 awsvpc 网络模式),因此您无法利用动态主机端口映射。

如果网络模式为 awsvpc,且任务已经分配了弹性网络接口,则在创建服务或运行具有任务定义的任务时必须指定 NetworkConfiguration。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的任务联网

注意

目前,只有经 Amazon ECS 优化的 AMI、包含 ecs-init 包的其他 Amazon Linux 变体或 AWS Fargate 基础设施支持 awsvpc 网络模式。

如果网络模式为 host,则在使用端口映射时,无法在单个容器实例上运行同一任务的多个实例化。

Docker for Windows 使用的网络模式不同于 Docker for Linux。在将任务定义注册到 Windows 容器时,您不得指定网络模式。如果使用控制台将任务定义注册到 Windows 容器,您必须选择 <default> 网络模式对象。

有关更多信息,请参阅 Docker 运行参考 中的 网络设置

必需:否

类型:字符串

允许的值awsvpc | bridge | host | none

Update requires: Replacement

PidMode

用于任务中的容器的过程命名空间。有效值为 hosttask。如果指定了 host,则在同一容器实例上指定了 host PID 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的进程命名空间。如果指定了 task,则指定任务中的所有容器将共享相同的过程命名空间。如果未指定任何值,则默认值为私有命名空间。有关更多信息,请参阅 Docker 运行参考 中的 PID 设置

如果使用了 host PID 模式,请注意,发生非预期的过程命名空间公开的风险会提高。有关更多信息,请参阅 Docker 安全性

注意

使用 Fargate 启动类型的 Windows 容器或任务不支持此参数。

必需:否

类型:字符串

允许的值host | task

Update requires: Replacement

PlacementConstraints

要用于任务的一组放置约束对象。如果您对任务使用 Fargate 启动类型,则此字段无效。

必需:否

类型TaskDefinitionPlacementConstraint 的列表

Update requires: Replacement

ProxyConfiguration

ProxyConfiguration 属性指定 App Mesh 代理的配置详细信息。

Amazon ECS 容器实例需要至少 1.26.0 版的容器代理和至少 1.26.0-1 版的 ecs-init 程序包才能启用代理配置。如果您的容器实例是从经 Amazon ECS 优化的 AMI 版本 20190301 或更高版本启动的,则这些实例将包含所需版本的容器代理和 ecs-init。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的 Amazon ECS 优化 Linux AMI

必需:否

类型ProxyConfiguration

Update requires: Replacement

RequiresCompatibilities

任务需要的启动类型。如果未指定值,则它将默认为 EC2。有效值包括 EC2FARGATE

必需:否

类型:字符串列表

Update requires: Replacement

Tags

您应用于任务定义以帮助您对其进行分类和组织的元数据。每个标签都包含您定义的一个键和一个可选值。

下面是适用于标签的基本限制:

  • 每个资源的最大标签数 - 50

  • 对于每个资源,每个标签键都必须是唯一的,每个标签键只能有一个值。

  • 最大键长度 - 128 个 Unicode 字符(采用 UTF-8 格式)

  • 最大值长度 - 256 个 Unicode 字符(采用 UTF-8 格式)

  • 如果您的标记方案针对多个服务和资源使用,请记得其他服务可能对允许使用的字符有限制。通常允许使用的字符包括:可用 UTF-8 格式表示的字母、数字和空格,以及以下字符:+ - = . _ : / @。

  • 标签键和值区分大小写。

  • 请不要使用 aws:AWS: 或任何大写或小写组合(例如,键或值的前缀),因为它将保留以供 AWS 使用。您无法编辑或删除带此前缀的标签键或值。具有此前缀的标签不计入每个资源的标签数限制。

必需:否

类型Tag 的列表

最高50

Update requires: No interruption

TaskRoleArn

AWS Identity and Access Management (IAM) 角色的简短名称或完整 Amazon 资源名称 (ARN),该角色向任务中的容器授予代表您调用 AWS API 的权限。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的 Amazon ECS 任务角色

Windows 上任务的 IAM 角色需要在您启动经 Amazon ECS 优化的 Windows AMI 时设置 -EnableTaskIAMRole 选项。此外,您的容器必须运行一些配置代码才能利用此功能。有关更多信息,请参阅 Amazon Elastic Container Service 开发人员指南 中的任务的 Windows IAM 角色

必需:否

类型:字符串

Update requires: Replacement

Volumes

任务的卷定义的列表。

如果您的任务使用 Fargate 启动类型,则不支持 hostsourcePath 参数。

有关卷定义参数和默认值的更多信息,请参阅 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

TaskDefinitionArn

Not currently supported by AWS CloudFormation.

示例

创建 Amazon ECS 任务定义

以下示例定义一个 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 任务定义

以下示例定义一个 Amazon ECS 任务定义,该定义指定 EC2 和 FARGATE 作为必需的兼容性。

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"