Amazon ECS
AWS Fargate 用户指南 (API 版本 2014-11-13)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

任务定义参数

任务定义包括以下各部分:任务系列、IAM 任务角色、网络模式、容器定义、卷、任务放置约束和启动类型。系列和容器定义在任务定义中是必需的,而任务角色、网络模式、卷、任务放置约束和启动类型是可选的。

以下是每个任务定义参数的更详细说明。

系列

family

类型:字符串

必需:是

当您注册任务定义时,将为其提供一个系列,与任务定义的多个版本的名称类似,它是使用修订号指定的。注册到某个特定系列的第一个任务定义将获得修订 1,而随后注册的任何任务定义将获得后续修订号。

任务执行角色

executionRoleArn

类型:字符串

必需:否

注册任务定义时,您可以提供任务执行角色,允许任务中的容器代表您提取容器映像并将容器日志发送到 CloudWatch。有关更多信息,请参阅Amazon ECS 任务执行 IAM 角色

网络模式

networkMode

类型:字符串

必需:否

在任务中用于容器的 Docker 联网模式当使用 Fargate 启动类型时,需要 awsvpc 网络模式。

当网络模式为 awsvpc 时,将为任务分配弹性网络接口,并且在创建服务或运行具有任务定义的任务时必须指定 NetworkConfiguration。有关更多信息,请参阅awsvpc 网络模式的任务联网

awsvpc 网络模式可为容器提供最高联网性能,因为容器使用 Amazon EC2 网络堆栈。公开的容器端口直接映射到附加的弹性网络接口端口,因此您无法利用动态主机端口映射。

容器定义

当您注册任务定义时,必须指定将传递给容器实例上的 Docker 守护程序的容器定义的列表。容器定义中允许以下参数。

标准容器定义参数

以下任务定义参数是必需的参数或在大多数容器定义中使用。

名称

name

类型:字符串

必需:是

容器的名称。最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。如果您正在任务定义中将多个容器链接在一起,则可在一个容器的 links 中输入另一个容器的 name 以连接容器。

映像

image

类型:字符串

必需:是

用于启动容器的映像。此字符串将直接传递给 Docker 守护程序。默认情况下,Docker Hub 注册表中的映像可用。您也可以使用 repository-url/image:tagrepository-url/image@digest 指定其他存储库。允许最多 255 个字母 (大写和小写字母)、数字、连字符、下划线、冒号、句点、正斜杠和井号。此参数将映射到 Docker Remote API创建容器部分中的 Image 以及 docker runIMAGE 参数。

  • 在新任务启动时,Amazon ECS 容器代理会提取最新版本的指定映像和标签以供容器使用。但是,存储库映像的后续更新不会传播到已在运行的任务。

  • 支持私有注册表中的映像。有关更多信息,请参阅任务的私有注册表身份验证

  • Amazon ECR 存储库中的映像可通过使用完整的 registry/repository:tagregistry/repository@digest 命名约定来指定。例如,aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latestaws_account_id.dkr.ecr.region.amazonaws.com/my-web-app@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE

  • Docker Hub 上的官方存储库中的映像使用一个名称(例如,ubuntumongo)。

  • Docker Hub 上其他存储库中的映像通过组织名称(例如,amazon/amazon-ecs-agent)进行限定。

  • 其他在线存储库中的映像由域名 (例如,quay.io/assemblyline/ubuntu) 进行进一步限定。

内存

memory

类型:整数

必需:否

要提供给容器的内存量(以 MiB 为单位)。如果您的容器尝试使用超出此处指定的内存,该容器将被终止。为任务中的所有容器预留的内存总量必须低于任务 memory 值(如果指定了一个)。此参数将映射到 Docker Remote API创建容器部分中的 Memory 以及 docker run--memory 选项。

如果您的容器是使用 Fargate 启动类型的任务的一部分,则此字段是可选的。

Docker 守护程序将为容器预留最少 4 MiB 的内存,因此,您不应为容器指定 4 MiB 以下的内存。

memoryReservation

类型:整数

必需:否

要为容器预留的内存量的软限制(以 MiB 为单位)。当系统内存处于争用状态时,Docker 会尝试将容器内存保持在此软限制内;不过,您的容器可以在需要时使用更多内存,最大量可达 memory 参数指定的硬限制(如果适用),或容器实例上的所有可用内存(以先达到者为准)。此参数将映射到 Docker Remote API创建容器部分中的 MemoryReservation 以及 docker run--memory-reservation 选项。

您必须为容器定义中的 memory 和/或 memoryReservation 指定一个非零整数。如果指定两者,则 memory 必须大于 memoryReservation。如果指定 memoryReservation,则将从容器所在的容器实例的可用内存资源中减去该值;否则将使用 memory 的值。

例如,如果您的容器通常使用 128 MiB 内存,但有时会在短时间内会迸发至 256 MiB 内存,则您可以设置 128 MiB 的 memoryReservation 以及 300 MiB 的 memory 硬限制。此配置不仅允许容器从容器实例上的剩余资源中预留 128 MiB 内存,而且允许容器在需要时使用更多内存资源。

Docker 守护程序将为容器预留最少 4 MiB 的内存,因此,您不应为容器指定 4 MiB 以下的内存。

端口映射

portMappings

类型:对象数组

必需:否

端口映射可让容器访问主机容器实例上的端口以发送或接收流量。

对于使用 awsvpc 网络模式的任务定义,您只应指定 containerPorthostPort 可以留空或值必须与 containerPort 相同。

此参数将映射到 Docker Remote API创建容器部分中的 PortBindings 以及 docker run--publish 选项。如果将任务定义的网络模式设置为 host,则主机端口必须是未定义的或者必须与端口映射中的容器端口匹配。

注意

在任务达到 RUNNING 状态之后,手动和自动主机及容器端口分配在以下位置可见:

  • 控制台:所选任务的容器说明的网络绑定部分。

  • AWS CLI:describe-tasks 命令输出的 networkBindings 部分。

  • API:DescribeTasks 响应。

containerPort

类型:整数

必需:是,当使用 portMappings

绑定到用户指定的或自动分配的主机端口的容器上的端口号。

如果在具有 Fargate 的任务中使用容器,公开的端口应使用 containerPort 指定。

如果在具有 EC2 启动类型的任务中使用容器,且指定了容器端口而不是主机端口,则您的容器将自动接收临时端口范围中的主机端口。有关更多信息,请参阅hostPort。通过此方式自动分配的端口映射不计入容器实例的 100 个预留端口限制。

重要

您不能为多个协议公开相同的容器端口。如果您尝试这样做,则会返回错误。

hostPort

类型:整数

必需:否

要为您的容器预留的容器实例上的端口号。

如果在具有 Fargate 启动类型的任务中使用容器,则 hostPort 可以留空或为与 containerPort 相同的值。

如果在具有 EC2 启动类型的任务中使用容器,则您可以为容器端口映射指定非预留主机端口(这称为静态主机端口映射),也可以在指定 containerPort 时省略 hostPort(或将它设置为 0),您的容器将自动接收容器实例操作系统和 Docker 版本的临时端口范围中的端口(这称为动态主机端口映射)。

默认临时端口范围为 49153–65535,此范围用于 1.6.0 版本之前的 Docker。对于 Docker 版本 1.6.0 及更高版本,Docker 守护程序将尝试读取 /proc/sys/net/ipv4/ip_local_port_range 中的临时端口范围(此范围在最新Amazon ECS-optimized AMI 上为 32768–61000);如果此内核参数不可用,则将使用默认临时端口范围。不要尝试指定位于临时端口范围中的主机端口,因为这些端口保留供自动分配。通常,低于 32768 的端口位于临时端口范围之外。

默认预留端口为适用于 SSH 的端口 22、Docker 端口 23752376 以及 Amazon ECS 容器代理端口 51678-51680。针对正在运行的任务的之前由用户指定的任何主机端口在任务运行时也将预留(在任务停止后,将发布主机端口)。当前预留端口将显示在 describe-container-instances 输出的 remainingResources 中,并且一个容器实例一次最多可拥有 100 个预留端口,包括默认预留端口。自动分配的端口不计入 100 个预留端口限制。

protocol

类型:字符串

必需:否

用于端口映射的协议。有效值为 tcpudp。默认为 tcp

如果您指定的是主机端口,请使用以下语法:

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

如果您需要自动分配的主机端口,请使用以下语法:

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

高级容器定义参数

以下高级容器定义参数提供用于在 Amazon ECS 容器实例上启动容器的 docker run 命令的扩展功能。

运行状况检查

healthCheck

容器的运行状况检查命令和关联的配置参数。该参数映射到 Docker Remote API创建容器 部分中的 HealthCheck 以及 docker runHEALTHCHECK 参数。

注意

Amazon ECS 容器代理仅监控和报告在任务定义中指定的运行状况检查。Amazon ECS 不监控嵌入到容器映像中和未在容器定义中指定的 Docker 运行状况检查。在容器定义中指定的运行状况检查参数覆盖容器映像中存在的任意 Docker 运行状况检查。

任务运行状况由任务的 healthStatus 报告,它由任务中的主要容器的运行状况确定。如果任务中的所有主要容器报告为 HEALTHY,则任务状态也报告为 HEALTHY。如果任务中的任意主要容器报告为 UNHEALTHYUNKNOWN,则任务状态也报告为相应报告为 UNHEALTHYUNKNOWN。如果服务的任务报告为不正常,则从服务中删除该任务并替换。

以下是有关容器运行状况检查支持的注意事项:

  • 如果使用平台版本 1.1.0 或更高版本,则 Fargate 任务支持容器运行状况检查。有关更多信息,请参阅AWS Fargate 平台版本

  • 如果任务属于配置为使用 传统负载均衡器 的服务的一部分,则此类任务不支持容器运行状况检查。

command

一个表示容器运行的命令的字符串数组,用于确定其运行状况是否正常。字符串数组可以以 CMD 开头以直接执行命令参数,或者以 CMD-SHELL 开头以使用容器的默认 Shell 来运行命令。如果两者都未指定,将默认使用 CMD

在 AWS 管理控制台中注册任务定义时,请使用命令的逗号分隔列表,这些命令在创建任务定义后将自动转换为字符串。运行状况检查的示例输入可以是:

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

在使用 AWS 管理控制台 JSON 面板、AWS CLI 或 API 注册任务定义时,您应将命令列表包含在括号中。运行状况检查的示例输入可以是:

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

退出代码 0 表示成功,非零退出代码表示失败。有关更多信息,请参阅 Docker Remote API创建容器部分中的 HealthCheck

interval

执行每次运行状况检查间隔的时间,以秒为单位。您可以指定 5 到 300 秒之间的值。默认值为 30 秒。

timeout

等待运行状况检查成功执行的时间长度,以秒为单位,超过该时间则视为失败。您可以指定 2 到 60 秒之间的值。默认值为 5 秒。

retries

重试失败的运行状况检查的次数,超过该次数将容器视为不正常。您可以指定 1 到 10 秒之间的重试次数。默认值为三次重试。

startPeriod

可选的宽限期,这让容器有时间来引导,不将失败的运行状况检查计数计入最大重试次数中。您可以指定 0 到 300 秒之间的值。默认情况下禁用 startPeriod

环境

cpu

类型:整数

必需:否

Amazon ECS 容器代理将为容器预留的 cpu 单元的数量。此参数将映射到 Docker Remote API创建容器部分中的 CpuShares 以及 docker run--cpu-shares 选项。

此字段对于使用 Fargate 启动类型的任务为可选,而且唯一的要求是任务内为所有容器保留的 CPU 总量低于任务级 cpu 值。

注意

您可以通过将 Amazon EC2 实例详细信息页面上列出的每个 Amazon EC2 实例类型的 vCPU 数乘以 1024 来确定该实例类型可用的 CPU 单元数。

Linux 容器会按照与其分配的量相同的比例,与容器实例上的其他容器共享未分配的 CPU 单元。例如,如果您在单核实例类型上运行一个单容器任务,同时为该容器指定 512 个 CPU 单元,而且这是在容器实例上运行的唯一任务,则该容器可在任何给定间使用完整的 1024 个 CPU 单元份额。但是,如果您在该容器实例上启动了同一任务的另一个副本,则保证为每个任务提供最少 512 个 CPU 单元(如果需要),而且每个容器的 CPU 使用量会上浮到更高的值(如果另一容器未在使用它),但如果两个任务都始终处于完全活动状态,则它们将限于 512 个 CPU 单元。

在 Linux 容器实例上,容器实例上的 Docker 守护程序使用 CPU 值来计算正在运行的容器的相对 CPU 共享比例。有关更多信息,请参阅 Docker 文档中的 CPU 共享约束。Linux 内核允许的最小有效 CPU 共享值为 2。不过,CPU 参数不是必需的,您可以在容器定义中使用小于 2 的 CPU 值。对于小于 2 的 CPU 值(包括 null),此行为因您的 Amazon ECS 容器代理版本而异:

  • 代理版本 <= 1.1.0:Null 和零 CPU 值将作为 0 传递给 Docker,然后 Docker 将其转换为 1,024 个 CPU 份额。CPU 值 1 将作为 1 传递给 Docker,然后 Linux 内核将其转换为 2 个 CPU 份额。

  • 代理版本 >= 1.2.0:Null、零和 CPU 值 1 将作为 2 个 CPU 份额传递给 Docker。

在 Windows 容器实例上,此 CPU 限制将作为绝对限制或配额强制实施。Windows 容器只能访问任务定义中所述的指定的 CPU 量。

essential

类型:布尔值

必需:否

如果将容器的 essential 参数标记为 true,并且该容器出于任何原因发生故障或停止,则属于此任务的所有其他容器将停止。如果将容器的 essential 参数标记为 false,则容器发生故障不会影响任务中的剩余容器。如果省略此参数,则假定容器是主要容器。

所有任务都必须具有至少一个主要容器。如果您有一个由多个容器组成的应用程序,则应将用于相同目的的容器分成多个组件,然后将不同的组件分为多个任务定义。有关更多信息,请参阅应用程序架构

"essential": true|false
entryPoint

重要

Amazon ECS 容器代理的早期版本无法正确处理 entryPoint 参数。如果您在使用 entryPoint 时遇到问题,请更新您的容器代理或改为输入命令和参数作为 command 数组项。

类型:字符串数组

必需:否

传递给容器的入口点。此参数将映射到 Docker Remote API创建容器部分中的 Entrypoint 以及 docker run--entrypoint 选项。有关 Docker ENTRYPOINT 参数的更多信息,请转到 https://docs.docker.com/engine/reference/builder/#entrypoint

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

类型:字符串数组

必需:否

传递给容器的命令。此参数将映射到 Docker Remote API创建容器部分中的 Cmd 以及 docker runCOMMAND 参数。有关 Docker CMD 参数的更多信息,请转到 https://docs.docker.com/engine/reference/builder/#cmd。如果有多个参数,则每个参数应该是数组中的分隔字符串。

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

类型:字符串

必需:否

容器中用于运行命令的工作目录。此参数将映射到 Docker Remote API创建容器部分中的 WorkingDir 以及 docker run--workdir 选项。

"workingDirectory": "string"
environment

类型:对象数组

必需:否

要传递给容器的环境变量。此参数将映射到 Docker Remote API创建容器部分中的 Env 以及 docker run--env 选项。

重要

建议不要对敏感信息 (如凭证数据) 使用纯文本环境变量。

name

类型:字符串

必需:是,当使用 environment

环境变量的名称。

value

类型:字符串

必需:是,当使用 environment

环境变量的值。

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

类型:对象数组

必需:否

一个表示用于对您的容器开放的密钥的对象。有关更多信息,请参阅指定敏感数据

name

类型:字符串

必需:是

要在容器上设置为环境变量的值。

valueFrom

类型:字符串

必需:是

要向容器公开的密钥。支持的值为 AWS Secrets Manager 密钥的完整 ARN 或 AWS Systems Manager Parameter Store 中的参数的完整 ARN。

注意

如果 Systems Manager Parameter Store 参数存在于要启动的任务所在的区域,则可以使用密钥的完整 ARN 或名称。如果参数存在于不同的区域,则必须指定完整的 ARN。

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

网络设置

dnsServers

类型:字符串数组

必需:否

提供给容器的 DNS 服务器的列表。此参数将映射到 Docker Remote API创建容器部分中的 Dns 以及 docker run--dns 选项。

注意

使用 awsvpc 网络模式的 Windows 容器或任务不支持此参数。

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

存储和日志记录

readonlyRootFilesystem

类型:布尔值

必需:否

当此参数为 true 时,将对此容器提供对其根文件系统的只读访问权。此参数将映射到 Docker Remote API创建容器部分中的 ReadonlyRootfs 以及 docker run--read-only 选项。

注意

This parameter is not supported for Windows containers.

"readonlyRootFilesystem": true|false
mountPoints

Type: Object

Required: No

The mount points for data volumes in your container.

This parameter maps to Volumes in the Create a container section of the Docker Remote API and the --volume option to docker run.

Windows containers can mount whole directories on the same drive as $env:ProgramData. Windows containers cannot mount directories on a different drive, and mount point cannot be across drives.

sourceVolume

Type: String

Required: Yes, when mountPoints are used

The name of the volume to mount.

containerPath

Type: String

Required: Yes, when mountPoints are used

The path on the container to mount the volume at.

readOnly

Type: Boolean

Required: No

If this value is true, the container has read-only access to the volume. If this value is false, then the container can write to the volume. The default value is false.

volumesFrom

类型:对象数组

必需:否

要从其他容器挂载的数据卷。此参数将映射到 Docker Remote API创建容器部分中的 VolumesFrom 以及 docker run--volumes-from 选项。

sourceContainer

类型:字符串

必需:是,当使用 volumesFrom

要从其中挂载卷的容器的名称。

readOnly

类型:布尔值

必需:否

如果此值为 true,则容器具有对卷的只读访问权。如果此值为 false,则容器可对卷进行写入。默认值为 false

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

类型:LogConfiguration 对象

必需:否

容器的日志配置规范。

有关在任务定义中使用 awslogs 日志驱动程序以将容器日志发送到 CloudWatch Logs 的更多信息,请参阅使用 awslogs 日志驱动程序

有关使用日志配置的示例任务定义,请参阅示例任务定义

此参数将映射到 Docker Remote API创建容器部分中的 LogConfig 以及 docker run--log-driver 选项。默认情况下,容器使用 Docker 守护程序所用的同一日志记录驱动程序;但容器可能通过在容器定义中使用此参数指定日志驱动程序来使用不同于 Docker 守护程序的日志记录驱动程序。要对容器使用不同的日志记录驱动程序,必须在容器实例上正确配置日志系统(或者在不同的日志服务器上使用远程日志记录选项)。有关其他支持的日志驱动程序选项的更多信息,请参阅 Docker 文档中的配置日志记录驱动程序

指定容器的日志配置时,应注意以下事项:

  • Amazon ECS 目前支持提供给 Docker 守护程序的一小部分日志记录驱动程序(如以下有效值所示)。可能会在 Amazon ECS 容器代理的未来版本中提供其他日志驱动程序。

  • 此参数要求您容器实例上的 Docker Remote API 版本为 1.18 或更高。

  • 对于使用 Fargate 启动类型的任务,因为您无权访问托管您的任务的底层基础设施,所以必须在此任务之外安装任何所需的其他软件。例如,Fluentd 输出聚合函数或运行 Logstash 以将 Gelf 日志发送到的远程主机。

"logConfiguration": { "logDriver": "awslogs","fluentd","gelf","json-file","journald","logentries","splunk","syslog", "options": {"string": "string" ...}, "secretOptions": [{ "name": "string", "valueFrom": "string" }] }
logDriver

类型:字符串

有效值:"awslogs","fluentd","gelf","json-file","journald","logentries","splunk","syslog"

必需:是,当使用 logConfiguration

要用于容器的日志驱动程序。之前列出的有效值是默认情况下 Amazon ECS 容器代理可与之通信的日志驱动程序。

对于使用 Fargate 启动类型的任务,受支持的日志驱动程序为 awslogssplunk

This parameter requires version 1.18 of the Docker Remote API or greater on your container instance.

options

类型:字符串到字符串映射

必需:否

要发送到日志驱动程序的配置选项。

This parameter requires version 1.19 of the Docker Remote API or greater on your container instance.

secretOptions

类型:对象数组

必需:否

一个对象,表示要传递到日志配置的密钥。有关更多信息,请参阅指定敏感数据

name

类型:字符串

必需:是

要在容器上设置为环境变量的值。

valueFrom

类型:字符串

必需:是

要向容器的日志配置公开的密钥。

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

安全性

user

类型:字符串

必需:否

要在容器内使用的用户名。此参数将映射到 Docker Remote API创建容器部分中的 User 以及 docker run--user 选项。

您可以使用以下格式。如果指定 UID 或 GID,您必须将其指定为一个正整数。

  • user

  • user:group

  • uid

  • uid:gid

  • user:gid

  • uid:group

注意

This parameter is not supported for Windows containers.

"user": "string"

资源限制

ulimits

类型:对象数组

必需:否

要在容器中设置的 ulimits 的列表。此参数将映射到 Docker Remote API创建容器部分中的 Ulimits 以及 docker run--ulimit 选项。

This parameter requires version 1.18 of the Docker Remote API or greater on your container instance.

注意

This parameter is not supported for Windows containers.

"ulimits": [ { "name": "core"|"cpu"|"data"|"fsize"|"locks"|"memlock"|"msgqueue"|"nice"|"nofile"|"nproc"|"rss"|"rtprio"|"rttime"|"sigpending"|"stack", "softLimit": integer, "hardLimit": integer } ... ]
name

类型:字符串

有效值:"core" | "cpu" | "data" | "fsize" | "locks" | "memlock" | "msgqueue" | "nice" | "nofile" | "nproc" | "rss" | "rtprio" | "rttime" | "sigpending" | "stack"

必需:是,当使用 ulimits

ulimittype

hardLimit

类型:整数

必需:是,当使用 ulimits

ulimit 类型的硬限制。

softLimit

类型:整数

必需:是,当使用 ulimits

ulimit 类型的软限制。

Docker 标签

dockerLabels

类型:字符串到字符串映射

必需:否

要添加到容器的标签的键值映射。此参数将映射到 Docker Remote API创建容器部分中的 Labels 以及 docker run--label 选项。

This parameter requires version 1.18 of the Docker Remote API or greater on your container instance.

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

其他容器定义参数

以下容器定义参数可在 Amazon ECS 控制台中注册任务定义时使用,方法是使用 Configure via JSON (通过 JSON 配置) 选项。有关更多信息,请参阅创建任务定义

Linux 参数

linuxParameters

类型:LinuxParameters 对象

必需:否

应用于容器的特定于 Linux 的选项,如 KernelCapabilities

注意

Windows 容器不支持此参数。

"linuxParameters": { "capabilities": { "add": ["string", ...], "drop": ["string", ...] } }
capabilities

类型:KernelCapabilities 对象

必需:否

容器的 Linux 功能,这些功能已在 Docker 提供的默认配置中删除。有关默认功能和非默认的可用功能,请参阅 Docker 运行参考 中的运行时特权和 Linux 功能。有关这些 Linux 功能的更多详细信息,请参阅 capabilities(7) Linux 手册页面。

drop

类型:字符串数组

有效值:"ALL" | "AUDIT_CONTROL" | "AUDIT_WRITE" | "BLOCK_SUSPEND" | "CHOWN" | "DAC_OVERRIDE" | "DAC_READ_SEARCH" | "FOWNER" | "FSETID" | "IPC_LOCK" | "IPC_OWNER" | "KILL" | "LEASE" | "LINUX_IMMUTABLE" | "MAC_ADMIN" | "MAC_OVERRIDE" | "MKNOD" | "NET_ADMIN" | "NET_BIND_SERVICE" | "NET_BROADCAST" | "NET_RAW" | "SETFCAP" | "SETGID" | "SETPCAP" | "SETUID" | "SYS_ADMIN" | "SYS_BOOT" | "SYS_CHROOT" | "SYS_MODULE" | "SYS_NICE" | "SYS_PACCT" | "SYS_PTRACE" | "SYS_RAWIO" | "SYS_RESOURCE" | "SYS_TIME" | "SYS_TTY_CONFIG" | "SYSLOG" | "WAKE_ALARM"

必需:否

容器的 Linux 功能,这些功能将从 Docker 提供的默认配置中删除。该参数映射到 Docker Remote API创建容器 部分中的 CapDrop 以及 docker run--cap-drop 选项。

initProcessEnabled

在容器内运行 init 进程,转发信号和获得进程。此参数会将 --init 选项映射到 docker run

This parameter requires version 1.25 of the Docker Remote API or greater on your container instance.

容器依赖项

dependsOn

类型:ContainerDependency 对象的数组

必需:否

针对容器启动和关闭定义的依赖项。一个容器可以包含多个依赖项。当针对容器启动定义依赖项时,对于容器关闭,将反转此项。有关示例,请参阅示例:容器依赖项

对于使用 Fargate 启动类型的任务,此参数需要任务或服务使用平台版本 1.3.0 或更高版本。

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

类型:字符串

必需:是

必须符合指定条件的容器名称。

condition

类型:字符串

必需:是

容器的依赖项条件。以下是可用的条件及其行为:

  • START – 此条件将立即模拟链接和卷的行为。它将验证从属容器是否是在允许其他容器启动前启动的。

  • COMPLETE – 此条件将验证从属容器是否在允许其他容器启动前运行完成(退出)。这对于运行脚本然后退出的非主要容器非常有用。

  • SUCCESS – 此条件与 COMPLETE 相同,但它还要求容器退出并具有 zero 状态。

  • HEALTHY – 此条件将验证从属容器是否在允许其他容器启动前传递其 Docker 运行状况检查。这要求从属容器已配置运行状况检查。仅在任务启动时确认此条件。

容器超时

startTimeout

类型:整数

必需:否

在放弃解析容器的依赖项之前要等待的持续时间。例如,您在一个任务定义中指定两个容器,其中 containerA 需要依赖 containerB 达到 COMPLETESUCCESSHEALTHY 状态。如果为 containerB 指定了一个 startTimeout 值并且它未在指定的超时时间内达到所需状态,则 containerA 将放弃并且不会启动。这会导致任务转换到 STOPPED 状态。

对于使用 Fargate 启动类型的任务,此参数需要任务或服务使用平台版本 1.3.0 或更高版本。

stopTimeout

类型:整数

必需:否

示例值:120

容器由于未自行正常退出而被强制终止前要等待的持续时间(以秒为单位)。对于使用 Fargate 启动类型的任务,最大停止超时值为 120 秒。对于使用 Fargate 启动类型的任务,此参数需要任务或服务使用平台版本 1.3.0 或更高版本。

系统控制

systemControls

类型:SystemControl 对象

必需:否

要在容器中设置的具有命名空间的内核参数的列表。此参数将映射到 Docker Remote API创建容器部分中的 Sysctls 以及 docker run--sysctl 选项。

不建议在使用了 awsvpchost 网络模式的单个任务中为多个容器指定与网络相关的 systemControls 参数,原因如下:

  • 对于使用 awsvpc 网络模式的任务,如果为任何容器设置了 systemControls,则它将应用于该任务中的所有容器。如果您为单个任务中的多个容器设置了不同的 systemControls,最后启动的容器将确定哪个 systemControls 生效。

  • 对于使用 host 网络模式的任务,不支持网络命名空间 systemControls

如果您要设置 IPC 资源命名空间以用于任务中的容器,则以下内容将适用于您的系统控制。有关更多信息,请参阅 IPC 模式

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

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

注意

This parameter is not supported for Windows containers or tasks using the Fargate launch type.

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

类型:字符串

必需:否

需要为其设置 value 的具有命名空间的内核参数。

有效 IPC 命名空间值:"kernel.msgmax" | "kernel.msgmnb" | "kernel.msgmni" | "kernel.sem" | "kernel.shmall" | "kernel.shmmax" | "kernel.shmmni" | "kernel.shm_rmid_forced",以及以 "fs.mqueue.*" 开头的 Sysctls

有效网络命名空间值:以 "net.*" 开头的 Sysctls

value

类型:字符串

必需:否

namespace 中指定的具有命名空间的内核参数的值。

交互式

interactive

类型:布尔值

必需:否

当此参数为 true 时,您可以部署需要分配 stdin 或 tty 的容器化的应用程序。此参数将映射到 Docker Remote API创建容器部分中的 OpenStdin 以及 docker run--interactive 选项。

伪终端

pseudoTerminal

类型:布尔值

必需:否

当此参数为 true 时,则分配 TTY。此参数将映射到 Docker Remote API创建容器部分中的 Tty 以及 docker run--tty 选项。

当您注册任务定义时,可以选择指定一个卷列表,这些卷将传递到容器实例上的 Docker 守护程序,然后它们将变得可供同一容器实例上的其他容器访问。

有关更多信息,请参阅 在任务中使用数据卷

容器定义中允许以下参数:

name

Type: String

Required: No

The name of the volume. Up to 255 letters (uppercase and lowercase), numbers, hyphens, and underscores are allowed. This name is referenced in the sourceVolume parameter of container definition mountPoints.

host

Required: No

This parameter is specified when using bind mounts. To use Docker volumes, specify a dockerVolumeConfiguration instead. The contents of the host parameter determine whether your bind mount data volume persists on the host container instance and where it is stored. If the host parameter is empty, then the Docker daemon assigns a host path for your data volume, but the data is not guaranteed to persist after the containers associated with it stop running.

Bind mount host volumes are supported when using either the EC2 or Fargate launch types.

Windows containers can mount whole directories on the same drive as $env:ProgramData. Windows containers cannot mount directories on a different drive, and mount point cannot be across drives. For example, you can mount C:\my\path:C:\my\path and D:\:D:\, but not D:\my\path:C:\my\path or D:\:C:\my\path.

sourcePath

Type: String

Required: No

When the host parameter is used, specify a sourcePath to declare the path on the host container instance that is presented to the container. If this parameter is empty, then the Docker daemon has assigned a host path for you. If the host parameter contains a sourcePath file location, then the data volume persists at the specified location on the host container instance until you delete it manually. If the sourcePath value does not exist on the host container instance, the Docker daemon creates it. If the location does exist, the contents of the source path folder are exported.

启动类型

当您注册任务定义时,您可以指定要用于任务的启动类型。有关更多信息,请参阅 Amazon ECS 启动类型

任务定义中允许以下参数:

requiresCompatibilities

类型:字符串数组

必需:否

有效值:EC2 | FARGATE

任务使用的启动类型。这将启用检查以确保任务定义中使用的所有参数均符合启动类型的要求。

有效值为 FARGATEEC2。有关启动类型的更多信息,请参阅 Amazon ECS 启动类型

任务大小

注册任务定义时,您可以指定用于任务的总 CPU 和内存量。这独立于容器定义级别的 cpumemory 值。如果使用的是 EC2 启动类型,则这些字段是可选字段。如果使用的是 Fargate 启动类型,则这些字段是必填字段,并且 cpumemory 具有受支持的特定值。

注意

Windows 容器将忽略任务级 CPU 和内存参数。我们建议为 Windows 容器指定容器级资源。

任务定义中允许以下参数:

cpu

类型:字符串

必需:否

注意

This parameter is not supported for Windows containers.

要为任务提供的 CPU 单位的硬限制。它在任务定义中可以表示为使用 CPU 单元时的整数(例如 1024),或表示为使用 vCPU 时的字符串(例如 1 vCPU1 vcpu)。注册任务定义时,vCPU 值将转换为指示 CPU 单元的整数。

如果使用 Fargate 启动类型,此字段为必填字段,并且必须使用以下值之一,这决定了 memory 参数支持的值范围:

CPU 值 内存值 (MiB)
256 (.25 vCPU) 512 (0.5GB)、1024 (1GB)、2048 (2GB)
512 (.5 vCPU) 1024 (1GB)、2048 (2GB)、3072 (3GB)、4096 (4GB)
1024 (1 vCPU) 2048 (2GB)、3072 (3GB)、4096 (4GB)、5120 (5GB)、6144 (6GB)、7168 (7GB)、8192 (8GB)
2048 (2 vCPU) 4096 (4GB) 到 16384 (16GB) 之间(以 1024 (1GB) 为增量)
4096 (4 vCPU) 8192 (8GB) 到 30720 (30GB) 之间(以 1024 (1GB) 为增量)
memory

类型:字符串

必需:否

注意

This parameter is not supported for Windows containers.

要向任务提供的内存的硬限制(以 MiB 为单位)。它在任务定义中可以表示为使用 MiB 时的整数(例如 1024),或表示为使用 GB 时的字符串(例如 1GB1 GB)。注册任务定义时,GB 值将转换为指示 MiB 的整数。

如果使用 Fargate 启动类型,此字段为必填字段,并且必须使用以下值之一,这决定了 cpu 参数支持的值范围:

内存值 (MiB) CPU 值
512 (0.5GB)、1024 (1GB)、2048 (2GB) 256 (.25 vCPU)
1024 (1GB)、2048 (2GB)、3072 (3GB)、4096 (4GB) 512 (.5 vCPU)
2048 (2GB)、3072 (3GB)、4096 (4GB)、5120 (5GB)、6144 (6GB)、7168 (7GB)、8192 (8GB) 1024 (1 vCPU)
4096 (4GB) 到 16384 (16GB) 之间(以 1024 (1GB) 为增量) 2048 (2 vCPU)
8192 (8GB) 到 30720 (30GB) 之间(以 1024 (1GB) 为增量) 4096 (4 vCPU)

其他任务定义参数

以下任务定义参数可在 Amazon ECS 控制台中注册任务定义时使用,方法是使用 Configure via JSON (通过 JSON 配置) 选项。有关更多信息,请参阅创建任务定义

IPC 模式

ipcMode

类型:字符串

必需:否

用于任务中的容器的 IPC 资源命名空间。有效值为 hosttasknone。如果指定了 host,则在同一容器实例上指定了 host IPC 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的 IPC 资源。如果指定了 task,则指定任务中的所有容器将共享相同的 IPC 资源。如果指定了 none,则任务的容器中的 IPC 资源是私有的,不与任务中或容器实例上的其他容器共享。如果未指定任何值,则 IPC 资源命名空间共享取决于容器实例上的 Docker 守护程序设置。有关更多信息,请参阅 Docker 运行参考 中的 IPC 设置

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

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

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

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

注意

This parameter is not supported for Windows containers or tasks using the Fargate launch type.

PID 模式

pidMode

类型:字符串

必需:否

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

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

注意

This parameter is not supported for Windows containers or tasks using the Fargate launch type.

代理配置

proxyConfiguration

类型:ProxyConfiguration 对象

必需:否

App Mesh 代理的配置详细信息。

对于使用 Fargate 启动类型的任务,此功能需要任务或服务使用平台版本 1.3.0 或更高版本。

注意

This parameter is not supported for Windows containers.

"proxyConfiguration": { "type": "APPMESH", "containerName": "string", "properties": [ { "name": "string", "value": "string" } ] }
type

类型:字符串

有效值:APPMESH

必需:否

代理类型。APPMESH 是唯一受支持的值。

containerName

类型:字符串

必需:是

将作为 App Mesh 代理的容器的名称。

properties

类型:KeyValuePair 对象的数组

必需:否

提供容器网络接口 (CNI) 插件的网络配置参数集,以键值对形式指定。

  • IgnoredUID –(必填)代理容器的用户 ID (UID),由容器定义中的 user 参数定义。此字段用于确保代理会忽略自己的流量。如果指定了 IgnoredGID,此字段可为空。

  • IgnoredGID –(必填)代理容器的组 ID (GID),由容器定义中的 user 参数定义。此字段用于确保代理会忽略自己的流量。如果指定了 IgnoredUID,此字段可为空。

  • AppPorts –(必填)应用程序使用的端口的列表。发送到这些端口的网络流量将转发到 ProxyIngressPortProxyEgressPort

  • ProxyIngressPort –(必填)指定传入到 AppPorts 的流量将定向到的端口。

  • ProxyEgressPort –(必填)指定从 AppPorts 传出的流量将定向到的端口。

  • EgressIgnoredPorts –(必填)进入这些指定端口的出口流量将被忽略但不会重定向到 ProxyEgressPort。它可以是空列表。

  • EgressIgnoredIPs –(必填)进入这些指定 IP 地址的出口流量将被忽略但不会重定向到 ProxyEgressPort。它可以是空列表。

name

类型:字符串

必需:否

键值对的名称。

value

类型:字符串

必需:否

键值对的值。