Amazon EC2 Container Service
开发人员指南 (API Version 2014-11-13)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

任务定义参数

任务定义分为四个基本部分:任务系列、IAM 任务角色、容器定义和卷。系列是任务的名称,每个系列可具有多个修订。IAM 任务角色指定任务中的容器应拥有的权限。容器定义指定要使用的映像、为容器分配的 CPU 和内存量以及更多其他选项。卷允许您在容器之间共享数据,甚至在容器不再运行时将数据保留在容器实例上。系列和容器定义在任务定义中是必需的,而任务角色、网络模式和卷是可选的。

系列

family

类型:字符串

必需:是

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

任务角色

taskRoleArn

类型:字符串

必需:否

当您注册任务定义时,可以为 IAM 角色提供任务角色,此角色可使任务中的容器有权代表您调用其关联策略中指定的 AWS API。有关更多信息,请参阅 任务的 IAM 角色

网络模式

networkMode

类型:字符串

必需:否

当您注册任务定义时,可以指定 Docker 联网模式以与其容器一起使用。默认 Docker 网络模式为 bridge。如果将网络模式设置为 none,则无法在容器定义中指定端口映射,并且任务的容器没有外部连接性。host 网络模式为容器提供了最高联网性能,因为容器使用的是主机网络堆栈而不是由 bridge 模式提供的虚拟化网络堆栈;不过,公开的容器端口将直接映射到相应的主机端口,因此,您无法利用动态主机端口映射或在单个容器实例上运行同一任务的多个实例化(如果使用了端口映射)。

容器定义

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

标准容器定义参数

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

name

类型:字符串

必需:是

容器的名称。如果您正在任务定义中将多个容器链接在一起,则可在一个容器的 links 中输入另一个容器的 name 以连接容器。最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。 此参数将映射到 Docker Remote API创建容器部分中的 namedocker run--name 选项。

image

类型:字符串

必需:是

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

  • Amazon ECR 存储库中的映像使用完整的 registry/repository:tag 命名约定。例如,aws_account_id.dkr.ecr.region.amazonaws.com/my-web-app:latest

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

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

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

memory

类型:整数

必需:否

要提供给容器的内存的硬限制(以 MiB 为单位)。如果您的容器尝试使用超出此处指定的内存,该容器将被终止。此参数将映射到 Docker Remote API创建容器部分中的 Memorydocker run--memory 选项。

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

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

memoryReservation

类型:整数

必需:否

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

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

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

portMappings

类型:对象数组

必需:否

端口映射可让容器访问主机容器实例上的端口以发送或接收流量。此参数将映射到 Docker Remote API创建容器部分中的 PortBindingsdocker run--publish 选项。如果将任务定义的网络模式设置为 none,则无法指定端口映射。如果将任务定义的网络模式设置为 host,则主机端口必须是未定义的或者必须与端口映射中的容器端口匹配。

注意

在任务达到 RUNNING 状态后,手动和自动主机和容器端口分配将显示在 Amazon ECS 控制台中所选任务的容器描述的 Network Bindings 部分中或者 describe-tasks AWS CLI 命令输出或 DescribeTasks API 响应的 networkBindings 部分中。

hostPort

类型:整数

必需:否

要为您的容器预留的容器实例上的端口号。您可以为容器端口映射指定非预留主机端口(这称为静态 主机端口映射),也可以在指定 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 优化的 AMI 上为 32768 到 61000);如果此内核参数不可用,则将使用默认临时端口范围。您不应尝试指定临时端口范围中的主机端口,因为将预留这些端口以进行自动分配。通常,低于 32768 的端口位于临时端口范围之外。

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

containerPort

类型:整数

必需:是,当使用 portMappings

绑定到用户指定的或自动分配的主机端口的容器上的端口号。如果指定容器端口而不是主机端口,则您的容器将自动接收临时端口范围中的主机端口(有关更多信息,请参阅 hostPort)。通过此方式自动分配的端口映射不计入容器实例的 100 个预留端口限制。

protocol

类型:字符串

必需:否

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

重要

UDP 支持仅适用于使用 Amazon ECS 容器代理的 1.2.0 版(例如 amzn-ami-2015.03.c-amazon-ecs-optimized AMI)或更高版本或者使用已更新至版本 1.3.0 或更高版本的容器代理启动的容器实例。要将您的容器代理更新至最新版本,请参阅更新 Amazon ECS 容器代理

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

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

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

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

高级容器定义参数

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

环境

cpu

类型:整数

必需:否

要为容器预留的 cpu 单元的数量。一个容器实例中,每个 CPU 核心有 1,024 个 cpu 单元。此参数指定要为一个容器预留的最小 CPU 数,并且容器会按照与其分配的量相同的比例,与实例上的其他容器共享未分配的 CPU 单元。此参数将映射到 Docker Remote API创建容器部分中的 CpuSharesdocker run--cpu-shares 选项。

注意

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

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

容器实例上的 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 传递给 Docker。

essential

类型:布尔值

必需:否

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

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

"essential": true|false
entryPoint

重要

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

类型:字符串数组

必需:否

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

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

类型:字符串数组

必需:否

传递给容器的命令。此参数将映射到 Docker Remote API创建容器部分中的 Cmddocker runCOMMAND 参数。有关 Docker CMD 参数的更多信息,请转到 https://docs.docker.com/engine/reference/builder/#cmd

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

类型:字符串

必需:否

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

"workingDirectory": "string"
environment

类型:对象数组

必需:否

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

重要

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

name

类型:字符串

必需:是,当使用 environment

环境变量的名称。

value

类型:字符串

必需:是,当使用 environment

环境变量的值。

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

网络设置

disableNetworking

类型:布尔值

必需:否

当此参数设置为 true 时,容器内禁用联网。此参数将映射到 Docker Remote API创建容器部分中的 NetworkDisabled

"disableNetworking": true|false
links

类型:字符串数组

必需:否

link 参数允许容器相互进行通信,而无需端口映射。name:internalName 构造类似于 Docker 链接中的 name:alias。最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。 有关链接 Docker 容器的更多信息,请转到 https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/。此参数将映射到 Docker Remote API创建容器部分中的 Linksdocker run--link 选项。

重要

在单个容器实例上并置的容器也许能够相互进行通信,而无需链接或主机端口映射。可使用安全组和 VPC 设置在容器实例上实现网络隔离。

"links": ["name:internalName", ...]
hostname

类型:字符串

必需:否

要对您的容器使用的主机名。此参数将映射到 Docker Remote API创建容器部分中的 Hostnamedocker run--hostname 选项。

"hostname": "string"
dnsServers

类型:字符串数组

必需:否

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

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

类型:字符串数组

必需:否

提供给容器的 DNS 搜索域的列表。此参数将映射到 Docker Remote API创建容器部分中的 DnsSearchdocker run--dns-search 选项。

"dnsSearchDomains": ["string", ...]
extraHosts

类型:对象数组

必需:否

要追加到容器上的 /etc/hosts 文件的主机名和 IP 地址映射的列表。此参数将映射到 Docker Remote API创建容器部分中的 ExtraHostsdocker run--add-host 选项。

"extraHosts": [
      {
        "hostname": "string",
        "ipAddress": "string"
      }
      ...
    ]
hostname

类型:字符串

必需:是,当使用 extraHosts

要用于 /etc/hosts 条目中的主机名。

ipAddress

类型:字符串

必需:是,当使用 extraHosts

要用于 /etc/hosts 条目中的 IP 地址。

存储和日志记录

readonlyRootFilesystem

类型:布尔值

必需:否

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

"readonlyRootFilesystem": true|false
mountPoints

类型:对象数组

必需:否

您的容器中数据卷的挂载点。此参数将映射到 Docker Remote API创建容器部分中的 Volumesdocker run--volume 选项。

sourceVolume

类型:字符串

必需:是,当使用 mountPoints

要挂载的卷的名称。

containerPath

类型:字符串

必需:是,当使用 mountPoints

要将主机卷挂载到的容器上的路径。

readOnly

类型:布尔值

必需:否

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

"mountPoints": [
                {
                  "sourceVolume": "string",
                  "containerPath": "string",
                  "readOnly": true|false
                }
              ]
volumesFrom

类型:对象数组

必需:否

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

sourceContainer

类型:字符串

必需:是,当使用 volumesFrom

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

readOnly

类型:布尔值

必需:否

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

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

类型:LogConfiguration 对象

必需:否

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

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

注意

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

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

注意

在容器实例上运行的 Amazon ECS 容器代理必须先将该实例上的可用日志记录驱动程序注册到 ECS_AVAILABLE_LOGGING_DRIVERS 环境变量,然后该实例上的容器才能使用这些日志配置选项。有关更多信息,请参阅 Amazon ECS 容器代理配置

"logConfiguration": {
      "logDriver": "json-file"|"syslog"|"journald"|"gelf"|"fluentd"|"awslogs"|"splunk",
      "options": {"string": "string"
        ...}
logDriver

类型:字符串

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

必需:是,当使用 logConfiguration

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

注意

如果您有上面未列出的要与 Amazon ECS 容器代理一起使用的自定义驱动程序,则可使 GitHub 上提供的 Amazon ECS 容器代理项目分叉,并对其进行自定义以便与该驱动程序结合使用。我们鼓励您针对要包含的更改提交提取请求。但是,Amazon Web Services 当前不支持运行此软件的修改后副本。

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.

安全性

privileged

类型:布尔值

必需:否

当此参数为 true 时,将对此容器提供对主机容器实例的提升的特权(类似于 root 用户)。此参数将映射到 Docker Remote API创建容器部分中的 Privilegeddocker run--privileged 选项。

"privileged": true|false
user

类型:字符串

必需:否

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

"user": "string"
dockerSecurityOptions

类型:字符串数组

必需:否

用于为 SELinux 和 AppArmor 多级别安全系统提供自定义标签的字符串列表。此参数将映射到 Docker Remote API创建容器部分中的 SecurityOptdocker run--security-opt 选项。

"dockerSecurityOptions": ["string", ...]

注意

在容器实例上运行的 Amazon ECS 容器代理必须先注册到 ECS_SELINUX_CAPABLE=trueECS_APPARMOR_CAPABLE=true 环境变量,然后该实例上的容器才能使用这些安全选项。有关更多信息,请参阅 Amazon ECS 容器代理配置

资源限制

ulimits

类型:对象数组

必需:否

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

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

"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创建容器部分中的 Labelsdocker run--label 选项。

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

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

任务放置约束

您在注册任务定义时,可以提供任务放置约束,自定义 Amazon ECS 如何放置任务。例如,您可以使用约束,根据可用区、实例类型或属性放置任务。有关更多信息,请参阅 Amazon ECS 任务放置约束。容器定义中允许以下参数:

expression

类型:字符串

必需:否

应用于约束的集群查询语言表达式。请注意,如果约束类型为 distinctInstance,您不能指定表达式。有关更多信息,请参阅 集群查询语言

type

类型:字符串

必需:是

约束类型。使用 memberOf 限制选择一组有效的候选类型。请注意,任务定义不支持 distinctInstance

当您注册任务定义时,可以选择指定一个卷列表,这些卷将传递到容器实例上的 Docker 守护程序并可供同一容器实例上的其他容器访问。有关更多信息,请参阅 在任务中使用数据卷。容器定义中允许以下参数:

name

类型:字符串

必需:是

卷的名称。最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。 此名称已在容器定义 mountPointssourceVolume 参数中引用。

host

类型:对象

必需:否

host 参数的内容确定您的数据卷是否一直保存在主机容器实例上以及存储它的位置上。如果 host 参数为空,则 Docker 守护程序将为您的数据卷分配一个主机路径,但不保证数据在与其关联的容器停止运行后将保留。

默认情况下,将在 /var/lib/docker/vfs/dir/ 中创建 Docker 托管的卷。您可以通过将 OPTIONS="-g=/my/path/for/docker/volumes" 写入容器实例上的 /etc/sysconfig/docker 来更改此默认位置。

sourcePath

类型:字符串

必需:否

向容器提供的主机容器实例上的路径。如果此参数为空,则 Docker 守护程序将为您分配一个主机路径。

如果 host 参数包含 sourcePath 文件位置,则数据卷将在主机容器实例上的指定位置保留,除非您手动将其删除。如果主机容器实例上不存在 sourcePath 值,则 Docker 守护程序将创建该值。如果该位置不存在,则将导出源路径文件夹的内容。

[
  {
    "name": "string",
    "host": {
      "sourcePath": "string"
    }
  }
]