任务定义参数 - Amazon Elastic Container Service
Amazon Web Services 文档中描述的 Amazon Web Services 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅 中国的 Amazon Web Services 服务入门 (PDF)

本文属于机器翻译版本。若本译文内容与英语原文存在差异,则一律以英文原文为准。

任务定义参数

任务定义分为不同的部分:任务系列、 Amazon Identity and Access Management (IAM) 任务角色、网络模式、容器定义、卷、任务放置限制和启动类型。任务定义中需要系列和容器定义。相反,任务角色、网络模式、卷、任务放置约束和启动类型是可选的。

您可以在 JSON 文件中使用这些参数来配置任务定义。有关更多信息,请参阅日志记录选项任务定义示例

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

系列

family

类型:字符串

必需:是

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

启动类型

您在注册任务定义时,可以指定 Amazon ECS 应验证任务定义的启动类型。如果任务定义未根据指定的兼容性进行验证,则返回客户端异常。有关更多信息,请参阅Amazon ECS 启动类型

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

requiresCompatibilities

类型:字符串数组

必需:否

有效值:EC2 | FARGATE | EXTERNAL

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

任务角色

taskRoleArn

类型:字符串

必需:否

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

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

任务执行角色

executionRoleArn

类型:字符串

必需:条件

任务执行角色的亚马逊资源名称 (ARN),该角色授予 Amazon ECS 容器代理代表您进行 Amazon API 调用的权限。

注意

任务执行 IAM 角色是必需的,具体取决于任务的要求。有关更多信息,请参阅Amazon ECS 任务执行 IAM 角色

网络模式

networkMode

类型:字符串

必需:否

在任务中用于容器的 Docker 联网模式。对于 Amazon EC2 Linux 实例上托管的 Amazon ECS 任务,有效值为 nonebridgeawsvpchost。如果未指定网络模式,原定设置网络模式为bridge对于在 Amazon EC2 Windows 实例上托管的 Amazon ECS 任务,有效值为 defaultawsvpc。如果未指定网络模式,则 default 使用网络模式。对于 Fargate 上托管的 Amazon ECS 任务,需要使用awsvpc网络模式。

如果网络模式设置为 none,则任务的容器没有外部连接性,且无法在容器定义中指定端口映射。

如果网络模式为 bridge,则任务在 Linux 上使用 Docker 的内置虚拟网络,该网络在托管任务的每个 Amazon EC2 实例内运行。Linux 上的内置虚拟网络使用 bridge Docker 网络驱动程序。

如果网络模式为 host,任务将通过直接映射容器端口到托管任务的 Amazon EC2 实例的 ENI,使用会绕过 Docker 内置虚拟网络的主机网络。动态端口映射不可在此网络模式中使用。使用此模式的任务定义中的容器必须指定具体的 hostPort 号。主机上的端口号不可被用于多个任务。因此,您不可以在单个 Amazon EC2 实例上运行相同任务定义的多个任务。

重要

运行使用 host 网络模式的任务时,请勿使用根用户(UID 0)运行容器,以获得更好的安全性。作为安全最佳实践,请始终使用非根用户。

对于 Amazon EC2 启动类型,如果网络模式为awsvpc,则会为任务分配一个弹性网络接口,并且您必须在创建服务或使用任务定义运行任务NetworkConfiguration时指定。有关更多信息,请参阅Amazon EC2 实例上任务的任务联网

如果网络模式为 default,则任务在 Windows 上使用 Docker 的内置虚拟网络,该网络在托管任务的每个 Amazon EC2 实例内运行。Windows 上的内置虚拟网络使用 nat Docker 网络驱动程序。

对于 Fargate 启动类型,当网络模式为时awsvpc,会为任务分配一个弹性网络接口,并且您必须在创建服务或使用任务定义运行任务NetworkConfiguration时指定。有关更多信息,请参阅 Fargate 任务联网awsvpc 网络模式可为容器提供最高联网性能,因为容器使用 Amazon EC2 网络堆栈。公开的容器端口直接映射到附加的弹性网络接口端口。因此,您不能使用动态主机端口映射。

hostawsvpc 网络模式可为容器提供最高联网性能,因为容器使用 Amazon EC2 网络堆栈。使用 hostawsvpc 网络模式,公开的容器端口将直接映射到相应的主机端口(用于 host 网络模式)或附加的弹性网络接口端口(用于 awsvpc 网络模式)。因此,您不能使用动态主机端口映射。

如果使用 Fargate 启动类型,则需要 awsvpc 网络模式。如果使用 EC2 启动类型,则允许的网络模式取决于底层 EC2 实例的操作系统。对于 Linux,可以使用任何网络模式。如果 Windows,defaultawsvpc 模式可以使用。

运行时平台

operatingSystemFamily

类型:字符串

必需:条件

原定设置:LINUX

对于在 Fargate 上托管的 Amazon ECS 任务,此参数是必需的。

当您注册任务定义时,您可以指定操作系统系列。

托管在 Fargate 上的 Amazon ECS 任务的有效值为 LINUXWINDOWS_SERVER_2019_FULLWINDOWS_SERVER_2019_COREWINDOWS_SERVER_2022_FULLWINDOWS_SERVER_2022_CORE

托管在 EC2 上的 Amazon ECS 任务的有效值为 LINUXWINDOWS_SERVER_2022_COREWINDOWS_SERVER_2022_FULLWINDOWS_SERVER_2019_FULL 以及 WINDOWS_SERVER_2019_COREWINDOWS_SERVER_2016_FULLWINDOWS_SERVER_2004_COREWINDOWS_SERVER_20H2_CORE

服务中使用的所有任务定义对于此参数都必须具有相同的值。

当任务定义是服务的一部分时,此值必须与服务 platformFamily 值匹配。

cpuArchitecture

类型:字符串

必需:条件

原定设置:X86_64

对于在 Fargate 上托管的 Amazon ECS 任务,此参数是必需的。如果将参数保留为 null,则在 Fargate 上托管的任务启动时会自动分配默认值。

当您注册任务定义时,您可以指定 CPU 架构。有效值为 X86_64ARM64

服务中使用的所有任务定义对于此参数都必须具有相同的值。

当您有 Fargate 启动类型或 EC2 启动类型的 Linux 任务时,可以将值设置为 ARM64。有关更多信息,请参阅使用 Amazon ECS 上的 64 位 ARM 工作负载

任务大小

注册任务定义时,您可以指定用于任务的总 CPU 和内存量。这独立于容器定义级别的 cpumemory 值。对于 Amazon EC2 实例上托管的任务,这些字段是可选的。对于 Fargate 上托管的任务(Linux 和 Windows),这些字段是必填字段,支持的 cpumemory 有具体值。

注意

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

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

cpu

类型:字符串

必需:条件

注意

Windows 容器不支持此参数。

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

对于 EC2 实例或外部实例上运行的任务,此字段是可选字段。如果您的集群没有任何带可用的已请求 CPU 单位的已注册容器实例,则该任务将失败。在 EC2 或外部实例上运行的任务支持的值介于 0.125 个 vCPU 与 10 个 vCPU 之间。

对于 Fargate 上托管的任务(Linux 和 Windows 容器),此字段为必填字段,并且必须使用以下值之一,这决定了 memory 参数支持的值范围。下表显示了任务级 CPU 和内存的有效组合。

CPU 值

内存值

Amazon Fargate 支持的操作系统

256 (.25 vCPU)

512MiB、1GB、2GB

Linux

512 (.5 vCPU)

1GB、2GB、3GB、4GB

Linux

1024 (1 vCPU)

2GB、3GB、4GB、5GB、6GB、7GB、8GB

Linux、Windows

2048 (2 vCPU)

4GB 到 16GB 之间 (以 1GB 为增量)

Linux、Windows

4096 (4 vCPU)

8GB 到 30GB 之间 (以 1GB 为增量)

Linux、Windows

8192 (8 vCPU)

注意

此选项需要 Linux 平台 1.4.0 或更高版本。

16 GB 到 60 GB 之间(以 4 GB 为增量)

Linux

16384 (16vCPU)

注意

此选项需要 Linux 平台 1.4.0 或更高版本。

32 GB 到 120 GB 之间(以 8 GB 为增量)

Linux

memory

类型:字符串

必需:条件

注意

Windows 容器不支持此参数。

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

对于 Amazon EC2 实例上托管的任务,此字段是可选的,可使用任何值。如果指定了任务级内存值,则容器级内存值是可选的。如果您的集群没有任何带可用的已请求内存的已注册容器实例,则该任务将失败。您可以尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源。有关更多信息,请参阅容器实例内存管理

对于 Fargate 上托管的任务(Linux 和 Windows 容器),此字段为必填字段,并且必须使用以下值之一,这决定了 cpu 参数支持的值范围:

内存值(以 MiB 为单位,近似等效值以 GB 为单位)

CPU 值

Fargate 支持的操作系统

512 (0.5GB)、1024 (1GB)、2048 (2GB)

256 (.25 vCPU)

Linux

1024 (1GB)、2048 (2GB)、3072 (3GB)、4096 (4GB)

512 (.5 vCPU)

Linux

2048 (2GB)、3072 (3GB)、4096 (4GB)、5120 (5GB)、6144 (6GB)、7168 (7GB)、8192 (8GB)

1024 (1 vCPU)

Linux、Windows

4096 (4GB) 到 16384 (16GB) 之间(以 1024 (1GB) 为增量)

2048 (2 vCPU)

Linux、Windows

8192 (8GB) 到 30720 (30GB) 之间(以 1024 (1GB) 为增量)

4096 (4 vCPU)

Linux、Windows

16 GB 到 60 GB 之间(以 4 GB 为增量)

注意

此选项需要 Linux 平台 1.4.0 或更高版本。

8192 (8 vCPU)

Linux

32 GB 到 120 GB 之间(以 8 GB 为增量)

注意

此选项需要 Linux 平台 1.4.0 或更高版本。

16384 (16vCPU)

Linux

容器定义

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

标准容器定义参数

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

名称

name

类型:字符串

必需:否

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

图像

image

类型:字符串

必需:否

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

如果您使用的是 EC2 启动类型,则必须指定任务级内存值或容器级内存值。如果同时指定容器级 memorymemoryReservation 值,则 memory 值必须大于 memoryReservation 值。如果指定 memoryReservation,则将从容器所在的容器实例的可用内存资源中减去该值。否则,将使用 memory 的值。

Docker 20.10.0 或更高版本进程守护程序将为容器预留最少 6MiB 的内存。因此,不要为容器指定少于 6MiB 的内存。

Docker 19.03.13-ce 或更早版本的进程守护程序将为容器预留最少 4MiB 的内存。因此,不要为容器指定少于 4MiB 的内存。

注意

如果您尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源,请参阅容器实例内存管理

memoryReservation

类型:整数

必需:否

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

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

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

注意

Windows 容器不支持此参数。

Docker 20.10.0 或更高版本进程守护程序将为容器预留最少 6MiB 的内存。因此,不要为容器指定少于 6MiB 的内存。

Docker 19.03.13-ce 或更早版本的进程守护程序将为容器预留最少 4MiB 的内存。因此,不要为容器指定少于 4MiB 的内存。

注意

如果您尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源,请参阅容器实例内存管理

端口映射

portMappings

类型:对象数组

必需:否

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

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

Windows 上的端口映射使用 NetNAT 网关地址而非 localhost。没有针对 Windows 上的端口映射的回环,因此,您无法从主机自身访问容器的映射端口。

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

注意

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

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

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

  • API:DescribeTasks 响应。

  • 元数据:任务元数据端点。

appProtocol

类型:字符串

必需:否

用于端口映射的应用程序协议。此参数仅适用于服务连接。我们建议您将此参数设置为与应用程序使用的协议一致。如果您设置此参数,Amazon ECS 会将协议特定的连接处理添加到服务连接代理。如果您设置了此参数,Amazon ECS 将在 Amazon ECS 控制台中添加特定于协议的遥测功能,然后。 CloudWatch

如果您没有为此参数设置值,则使用 TCP。但是,Amazon ECS 不会为 TCP 添加协议特定的遥测。

有关更多信息,请参阅Service Connect

有效的协议值:"HTTP" | "HTTP2" | "GRPC"

containerPort

类型:整数

必需:是,当使用 portMappings

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

如果在具有 Fargate 启动类型的任务中使用容器,公开的端口必须使用 containerPort 指定。

对于 Fargate 上的 Windows 容器,不能将端口 3150 用于 containerPort。这是因为它是预留的。

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

containerPortRange

类型:字符串

必需:否

容器上的端口号范围,该容器绑定到动态映射的主机端口范围。

您只能使用 register-task-definition API 设置此参数。该选项在 portMappings 参数中可用。有关更多信息,请参阅 Amazon Command Line Interface 参考中的 register-task-definition

当您指定 containerPortRange 时,以下规则适用:

  • 必须使用 bridge 网络模式或 awsvpc 网络模式。

  • 此参数同时适用于 EC2 和 Amazon Fargate 启动类型。

  • 此参数同时适用于 Linux 和 Windows 操作系统。

  • 容器实例必须拥有不低于 1.67.0 版本的容器代理和不低于 1.67.0-1 版本的 ecs-init 程序包。

  • 每个容器最多可指定 100 个端口范围。

  • 您不用指定 hostPortRangehostPortRange 的值设置如下:

    • 对于使用 awsvpc 网络模式的任务中的容器,hostPort 将设置为与 containerPort 相同的值。这是一种静态映射策略。

    • 对于使用 bridge 网络模式的任务中的容器,Amazon ECS 代理会从默认临时范围内找到开放主机端口,并将其传递给 Docker 以将其绑定到容器端口。

  • containerPortRange 有效值为 1 到 65535。

  • 每个容器的一个端口只能包含在的一个端口映射中。

  • 您不能指定重叠的端口范围。

  • 范围中的第一个端口必须小于范围中的最后一个端口。

  • 当有大量端口时,Docker 建议您关闭 Docker 进程守护程序配置文件中的 docker-proxy。

    有关更多信息,请参阅上的 #11185 问题 GitHub。

    有关如何关闭 Docker 进程守护程序配置文件中的 docker-proxy 的信息,请参阅《Amazon ECS 开发者指南》中的 Docker 进程守护程序

您可以调用 DescribeTasks 以查看 hostPortRange,它们是绑定到容器端口的主机端口。

端口范围不包含在发送到的 Amazon ECS 任务事件中 EventBridge。有关更多信息,请参阅Amazon ECS 事件和 EventBridge

hostPortRange

类型:字符串

必需:否

用于网络绑定的主机上的端口号范围。它由 Docker 分配并由 Amazon ECS 代理传送。

hostPort

类型:整数

必需:否

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

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

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

Docker 版本 1.6.0 及更高版本的默认临时端口范围在 /proc/sys/net/ipv4/ip_local_port_range 下的实例上列出。如果此内核参数不可用,则将使用来自 49153–65535 的原定设置临时端口范围。不要尝试指定临时端口范围内的主机端口。这是因为这些都是为自动分配预留的。通常,低于 32768 的端口位于临时端口范围之外。

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

name

类型:字符串

必填项:否,在服务中配置 Service Connect 时需要

用于端口映射的名称。此参数仅适用于服务连接。此参数是您在服务的 Service Connect 配置中使用的名称。

有关更多信息,请参阅Service Connect

在以下示例中,使用了针对 Service Connect 的两个必填字段。

"portMappings": [ { "name": string, "containerPort": integer } ]
protocol

类型:字符串

必需:否

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

重要

Service Connect 仅支持 tcp。请记住,如果未设置此字段,则表示 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 } ... ]

私有存储库凭证

repositoryCredentials

类型:RepositoryCredentials 对象

必需:否

私有注册表身份验证的存储库凭证。

有关更多信息,请参阅任务的私有注册表身份验证

credentialsParameter

类型:字符串

必需:是,当使用 repositoryCredentials

包含私有存储库凭证的密钥的 Amazon 资源名称 (ARN)。

有关更多信息,请参阅任务的私有注册表身份验证

注意

当您使用 Amazon ECS API 或 Amazon 软件开发工具包时,如果密钥与您启动的任务位于同一区域,则可以使用完整的 ARN 或密钥的名称。 Amazon CLI使用时 Amazon Web Services Management Console,必须指定密钥的完整 ARN。

下面是显示必需参数的任务定义代码段:

"containerDefinitions": [ { "image": "private-repo/private-image", "repositoryCredentials": { "credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name" } } ]

高级容器定义参数

以下高级容器定义参数为 docker run 命令,该命令用于在 Amazon ECS 容器实例上启动容器。

运行状况检查

healthCheck

容器的运行状况检查命令和关联的配置参数。此参数将映射到 Docker Remote APICreate a container(创建容器)部分中的 HealthCheck 以及 docker runHEALTHCHECK 参数。

注意

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

通过两种方法中的任何一种,您可以查看单个容器和任务的运行状况。您可以调用 DescribeTasks API 或在控制台中查看任务详细信息。

运行状况检查旨在确保您的容器在代理重启、升级或暂时不可用后仍能保留。

下面介绍了容器的 healthStatus 可能值:

  • HEALTHY – 容器运行状况检查已成功通过。

  • UNHEALTHY – 容器运行状况检查失败。

  • UNKNOWN – 正在评估容器运行状况检查,没有定义容器运行状况检查,或者 Amazon ECS 没有容器的运行状况。

以下内容根据任务中基本容器的容器运行状况检查器状态描述了可能的 healthStatus 值,其优先级顺序如下(从高到低):

  • UNHEALTHY – 一个或多个基本容器未通过运行状况检查。

  • UNKNOWN – 任务中运行的任何基本容器都处于 UNKNOWN 状态,且其他基本容器都没有 UNHEALTHY 状态。

  • HEALTHY – 任务中的所有基本容器都通过了其运行状况检查。

如果任务是手动运行的,而不是作为服务的一部分运行,则该任务将继续其生命周期,而无论其运行状况如何。对于属于服务的任务,如果任务报告为运行状况不佳,则服务计划程序会首先启动一个替换任务。一旦替换任务的 healthStatus 值为 HEALTHYUNHEALTHY,服务计划程序就可以停止运行状况不佳的任务。有关更多信息,请参阅服务计划程序概念

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

  • 当 Amazon ECS 代理无法连接到 Amazon ECS 服务时,该服务会将容器报告为 UNHEALTHY

  • 运行状况检查状态是 Amazon ECS 代理发出的“最后一次收到”响应。对容器运行状况检查的状态未做出任何假设。

  • 容器运行状况检查需要 Amazon ECS 容器代理版本 1.17.0 或更高版本。有关更多信息,请参阅更新 Amazon ECS 容器代理

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

command

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

在中注册任务定义时 Amazon Web Services Management Console,请使用逗号分隔的命令列表。在创建任务定义后,这些命令将转换为字符串。以下是运行状况检查的输入示例。

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

使用 Amazon Web Services Management Console JSON 面板 Amazon CLI、或 API 注册任务定义时,请将命令列表放在方括号中。以下是运行状况检查的输入示例。

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

不带有 stderr 输出的退出代码 0 表示成功,非零退出代码表示失败。有关更多信息,请参阅 Docker Remote APICreate a container(创建容器)部分中的 HealthCheck

interval

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

timeout

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

retries

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

startPeriod

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

环境

cpu

类型:整数

必需:否

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

对于使用 Fargate 启动类型的任务,此字段为可选字段。为任务中的所有容器预留的 CPU 总量必须低于任务级的 cpu 值。

注意

您可以确定每个 Amazon EC2 实例类型可用的 CPU 单位数。为此,请将 Amazon EC2 实例详细信息页面上为该实例类型列出的 vCPU 数量乘以 1024。

Linux 容器会按照与其分配的量相同的比例,与容器实例上的其他容器共享未分配的 CPU 单元。例如,假设您在单核实例类型上运行一个单容器任务,同时为该容器指定 512 个 CPU 单元。此外,在容器实例上,该任务是运行的唯一任务。在此示例中,容器可以在任何给定时间使用完整的 1024 个 CPU 单位份额。但是,假设您在该容器实例上启动了同一任务的另一个副本。在需要时,保证每个任务至少有 512 个 CPU 单位。同样,如果另一个容器没有使用剩余的 CPU,则每个容器都可以浮动到更高的 CPU 利用率。但是,如果两个任务一直都处于 100% 活动状态,那么它们将限制为 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 将其转换为 1024 个 CPU 份额。CPU 值 1 将作为 1 传递给 Docker,然后 Linux 内核将其转换为 2 个 CPU 份额。

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

在 Windows 容器实例上,此 CPU 配额将作为绝对配额强制实施。Windows 容器只能访问任务定义中所定义的指定 CPU 量。Null 或零 CPU 值将作为 0 传递给 Docker。然后 Windows 将此值解释为一个 CPU 的 1%。

有关更多示例,请参阅 Amazon ECS 如何管理 CPU 和内存资源

gpu

类型:ResourceRequirement 对象

必需:否

Amazon ECS 容器代理为容器预留的物理 GPUs 的数量。为某个任务中的所有容器预留的 GPU 的数量不得超过该任务在其上启动的容器实例的可用 GPU 的数量。有关更多信息,请参阅在 Amazon ECS 上使用 GPU

注意

在 Fargate 上托管的 Windows 容器不支持此参数。

Elastic Inference accelerator

类型:ResourceRequirement 对象

必需:否

对于 InferenceAccelerator 类型,value 与任务定义中指定的 InferenceAcceleratordeviceName 匹配。有关更多信息,请参阅Elastic Inference 加速器名称

注意

从 2023 年 4 月 15 日起, Amazon 将不会让新客户加入 Amazon Elastic Inference (EI),并将帮助现有客户将其工作负载迁移到价格和性能更高的选项。2023 年 4 月 15 日之后,新客户将无法在亚马逊、亚马逊 ECS 或亚马逊 EC2 中使用亚马逊 SageMaker EI 加速器启动实例。但是,在过去 30 天内至少使用过一次 Amazon EI 的客户将视为当前客户,可继续使用该服务。

注意

在 Fargate 上托管的 Windows 容器不支持此参数。

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"
environmentFiles

类型:对象数组

必需:否

包含要传递到容器的环境变量的文件列表。此参数可将 --env-file 选项映射到 docker run

这不适用于 Windows 容器。

您最多可以指定 10 个环境文件。文件必须具有 .env 文件扩展名。环境文件中的每一行都包含 VARIABLE=VALUE 格式的环境变量。以 # 开头的行被视为注释并会被忽略。有关适当的环境变量文件语法的更多信息,请参阅在文件中声明默认环境变量

如果在容器定义中指定了单个环境变量,则这些变量的优先级高于环境文件中包含的变量。如果指定了多个包含相同变量的环境文件,则会按从上到下的顺序处理这些文件。建议您使用唯一的变量名。有关更多信息,请参阅使用任务定义参数将环境变量传递到容器

value

类型:字符串

必需:是

包含环境变量文件的 Amazon S3 对象的 Amazon Resource Name (ARN)。

type

类型:字符串

必需:是

要使用的文件类型 s3 是唯一受支持的值。

environment

类型:对象数组

必需:否

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

重要

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

name

类型:字符串

必需:是,当使用 environment

环境变量的名称。

value

类型:字符串

必需:是,当使用 environment

环境变量的值。

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

类型:对象数组

必需:否

表示用于对容器开放的密钥的对象。有关更多信息,请参阅将敏感数据传递给容器

name

类型:字符串

必需:是

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

valueFrom

类型:字符串

必需:是

要向容器公开的密文。支持的值要么是 Amazon Secrets Manager 密钥的完整亚马逊资源名称 (ARN),要么是参数存储中参数的完整 ARN。 Amazon Systems Manager

注意

如果 Systems Manager 参数存储参数与您启动的任务相同 Amazon Web Services 区域 ,则可以使用密钥的完整 ARN 或名称。如果参数存在于不同的区域,则必须指定完整的 ARN。

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

Network settings (网络设置)

disableNetworking

类型:布尔值

必需:否

当此参数设置为 true 时,容器内会关闭联网。此参数将映射到 Docker Remote APICreate a container(创建容器)部分中的 NetworkDisabled

注意

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

默认值为 false

"disableNetworking": true|false

类型:字符串数组

必需:否

link 参数允许容器相互进行通信,而无需端口映射。只有在任务定义的网络模式被设置为 bridge 时才支持此参数。name:internalName 构造类似于 Docker 链接中的 name:alias。最多能包含 255 个字母 (大写和小写字母)、数字、连字符和下划线。有关链接 Docker 容器的更多信息,请参阅 https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/。此参数将映射到 Docker Remote API创建容器部分中的Links以及docker run--link选项。

注意

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

重要

在同一容器实例上并置的容器也许能够相互进行通信,而无需链接或主机端口映射。容器实例上的网络隔离由安全组和 VPC 设置控制。

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

类型:字符串

必需:否

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

注意

如果使用 awsvpc 网络模式,则不支持 hostname 参数。

"hostname": "string"
dnsServers

类型:字符串数组

必需:否

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

注意

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

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

类型:字符串数组

必需:否

模式:^[a-zA-Z0-9-.]{0,253}[a-zA-Z0-9]$

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

注意

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

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

类型:对象数组

必需:否

要追加到容器上的 /etc/hosts 文件的主机名和 IP 地址映射的列表。

此参数将映射到 Docker Remote API创建容器部分中的 ExtraHosts 以及 docker run--add-host 选项。

注意

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

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

类型:字符串

必需:是,当使用 extraHosts

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

ipAddress

类型:字符串

必需:是,当使用 extraHosts

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

存储和日志记录

readonlyRootFilesystem

类型:布尔值

必需:否

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

注意

Windows 容器不支持此参数。

默认值为 false

"readonlyRootFilesystem": true|false
mountPoints

类型:对象数组

必需:否

容器中数据卷的挂载点。

此参数将映射到 Docker Remote API创建容器部分中的 Volumes 以及 docker run--volume 选项。

Windows 容器可在 $env:ProgramData 所在的驱动器上挂载整个目录。Windows 容器无法在其他驱动器上挂载目录,并且挂载点不能跨驱动器。

sourceVolume

类型:字符串

必需:是,当使用 mountPoints

要挂载的卷的名称。

containerPath

类型:字符串

必需:是,当使用 mountPoints

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

readOnly

类型:布尔值

必需:否

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

volumesFrom

类型:对象数组

必需:否

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

sourceContainer

类型:字符串

必需:是,当使用 volumesFrom

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

readOnly

类型:布尔值

必需:否

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

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

类型:LogConfiguration对象

必需:否

容器的日志配置规范。

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

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

指定容器的日志配置时,考虑以下事项:

  • Amazon ECS 支持提供给 Docker 进程守护程序的一小部分日志记录驱动程序。可能会在 Amazon ECS 容器代理的未来版本中提供其他日志驱动程序。

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

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

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

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

类型:字符串

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

必需:是,当使用 logConfiguration

要用于容器的日志驱动程序。默认情况下,前面列出的有效值是一些日志驱动程序,Amazon ECS 容器代理可以与它们进行通信。

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

对于使用 EC2 启动类型的任务,支持的日志驱动程序为 awslogsfluentdgelfjson-filejournaldlogentriessyslogsplunkawsfirelens

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

有关使用 awsfirelens 日志驱动程序的更多信息,请参阅自定义日志路由

注意

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

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

options

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

必需:否

要发送到日志驱动程序的配置选项的键/值映射。

当您使用 FireLens 将日志路由到 Amazon Web Service 或 Amazon Partner Network 目标以进行日志存储和分析时,可以设置该log-driver-buffer-limit选项,以限制在发送到日志路由器容器之前在内存中缓冲的事件数量。它可以帮助解决潜在的日志丢失问题,因为高吞吐量可能会导致 Docker 内部缓冲区的内存耗尽。有关更多信息,请参阅Fluentd 缓冲区限制

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

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" }] }
firelensConfiguration

类型:FirelensConfiguration对象

必需:否

容器的 FireLens 配置。这用于为容器日志指定和配置日志路由器。有关更多信息,请参阅使用自定义日志路由

{ "firelensConfiguration": { "type": "fluentd", "options": { "KeyName": "" } } }
options

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

必需:否

在配置日志路由器时使用的选项的键/值映射。此字段是可选的,可用于指定自定义配置文件或向日志事件添加其他元数据,如任务、任务定义、群集和容器实例详细信息。如果指定,则使用的语法为 "options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::mybucket/fluent.conf|filepath"}。有关更多信息,请参阅在任务定义中指定FireLens配置

type

类型:字符串

必需:是

要使用的日志路由器。有效值为 fluentdfluentbit

安全性

有关容器安全的更多信息,请参阅 Amazon ECS Best Practices Guide(《Amazon ECS 最佳实践指南》)中的 Task and container security(任务与容器安全)。

credentialSpecs

类型:字符串数组

必需:否

SSM 或 Amazon S3 中的 ARN 列表,指向配置容器进行 Active Directory 身份验证的凭证规范(CredSpec)文件。建议您使用此参数,而不是 dockerSecurityOptions。ARN 的最大数量为 1。

每个 ARN 有两种格式。

credentialspecdomainless:MyARN

您可以使用 credentialspecdomainless:MyARN 在 Secrets Manager 中为 CredSpec 提供一个密钥的额外部分。您在密钥中提供域的登录凭证。

在任何容器实例上运行的每个任务均可以加入不同的域。

您无需将容器实例加入域,即可使用此格式。

credentialspec:MyARN

您使用 credentialspec:MyARN 为单个域提供 CredSpec

在开始使用此任务定义的任何任务之前,您必须将容器实例加入域。

在这两种格式中,将 MyARN 替换为 SSM 或 Amazon S3 中的 ARN。

credspec 必须在 Secrets Manager 中为包含用户名、密码和要连接的域的密钥提供 ARN。为了提高安全性,该实例未加入域进行无域身份验证。实例上的其他应用程序无法使用无域凭证。您可以使用此参数在同一个实例上运行任务,即使这些任务需要加入不同的域。有关更多信息,请参阅将 gMSA 用于 Windows 容器将 gMSA 用于 Linux 容器

privileged

类型:布尔值

必需:否

当该参数为 true 时,将对此容器提供对主机容器实例的提升的特权(类似于 root 用户)。我们建议不要使用 privileged 运行容器。在大多数情况下,您可以使用特定参数来指定所需的确切权限,而不是使用 privileged

此参数将映射到 Docker Remote API创建容器部分中的 Privileged 以及 docker run--privileged 选项。

注意

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

默认值为 false

"privileged": true|false
user

类型:字符串

必需:否

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

重要

运行使用 host 网络模式的任务时,请勿使用根用户(UID 0)运行容器。作为安全最佳实践,请始终使用非根用户。

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

  • user

  • user:group

  • uid

  • uid:gid

  • user:gid

  • uid:group

注意

Windows 容器不支持此参数。

"user": "string"
dockerSecurityOptions

类型:字符串数组

有效值:“no-new-privileges” | “apparmor: Profile” | “标签:value” | “credenti al spec:” CredentialSpecFilePath

必需:否

用于为多个安全系统提供自定义配置的字符串列表。有关有效值的更多信息,请参阅 Docker 运行安全配置。此字段对使用 Fargate 启动类型的任务中的容器无效。

对于 EC2 上的 Linux 任务,此参数可用于引用 SELinux 和 AppArmor 多级安全系统的自定义标签。

对于 EC2 上的任何任务,此参数可用于在为 Active Directory 身份验证配置容器时引用凭证规范文件。有关更多信息,请参阅 为 Windows 容器使用 gMSA将 gMSAs 用于 Linux 容器

此参数将映射到 Docker Remote API创建容器部分中的SecurityOpt以及docker--security-opt选项。

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

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

资源限制

ulimits

类型:对象数组

必需:否

列表 ulimit 值为容器定义。此值将覆盖操作系统的默认资源配额设置。此参数将映射到 Docker Remote API创建容器部分中的Ulimits以及docker run--ulimit选项。

Fargate 上托管的 Amazon ECS 任务使用操作系统设置的默认资源限制值,nofile 资源限制参数除外。nofile 资源限制对容器可以使用的打开文件数量设置限制。在 Fargate 上,默认的 nofile 软限制为 1024,硬限制为 65535。您可以将两个限制的值最高设置为 1048576有关更多信息,请参阅任务资源限制

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

注意

Windows 容器不支持此参数。

"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 选项。

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

"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 手册页面。

add

类型:字符串数组

有效值:"ALL" | "AUDIT_CONTROL" | "AUDIT_READ" | "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创建容器部分中的CapAdd以及 Docker 运行--cap-add选项。

注意

在 Fargate 上启动的任务仅支持添加 SYS_PTRACE 内核功能。

add

类型:字符串数组

有效值:"SYS_PTRACE"

必需:否

容器的 Linux 功能,这些功能将添加到 Docker 提供的默认配置。此参数将映射到 Docker Remote APICreate a container(创建容器)部分中的 CapAdd 以及 docker run--cap-add 选项。

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 APICreate a container(创建容器)部分中的 CapDrop 以及 docker run--cap-drop 选项。

devices

对容器公开的任何主机设备。此参数将映射到 Docker Remote APICreate a container(创建容器)部分中的 Devices 以及 docker run--device 选项。

注意

当您使用 Fargate 启动类型或 Windows 容器时,不支持 devices 参数。

类型:设备对象数组

必需:否

hostPath

主机容器实例上的设备路径。

类型:字符串

必需:是

containerPath

要将主机设备公开到的容器中的路径。

类型:字符串

必需:否

permissions

提供给设备的容器的显式权限。默认情况下,容器对设备上的 readwritemknod 具有权限。

类型:字符串数组

有效值:read | write | mknod

initProcessEnabled

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

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

maxSwap

容器可以使用的交换内存总量(以 MiB 为单位)。该参数会转换为 Docker 运行--memory-swap选项,其中,该值为容器内存和maxSwap值之和。

如果指定maxSwap值为0,则该容器不使用交换。接受的值为0或任何正整数。如果省略 maxSwap 参数,该容器将为其运行所在的容器实例使用交换配置。必须为要使用的swappiness参数设置maxSwap值。

注意

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

sharedMemorySize

/dev/shm卷的大小值 (以 MiB 为单位)。此参数会将--shm-size选项映射到 Docker 运行

注意

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

类型:整数

swappiness

您可以使用此参数调整容器的内存 swappiness 行为。swappiness 的值 0 防止交换发生,除非有要求。swappiness 的值 100 导致页面被频繁交换。接受的值为0100之间的整数。如果您未指定值,则将使用默认值 60。此外,如果未指定 maxSwap 的值,则此参数将被忽略。此参数会将--memory-swappiness选项映射到 Docker 运行

注意

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

如果您在 Amazon Linux 2023 上使用任务,则不支持 swappiness 参数。

tmpfs

tmpfs 挂载的容器路径、挂载选项和最大大小(以 MiB 为单位)。此参数会将--tmpfs选项映射到 Docker 运行

注意

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

类型:Tmpfs 对象数组

必需:否

containerPath

要挂载 tmpfs 卷的绝对文件路径。

类型:字符串

必需:是

mountOptions

tmpfs卷挂载选项列表。

类型:字符串数组

必需:否

有效值:"defaults" | "ro" | "rw" | "suid" | "nosuid" | "dev" | "nodev" | "exec" | "noexec" | "sync" | "async" | "dirsync" | "remount" | "mand" | "nomand" | "atime" | "noatime" | "diratime" | "nodiratime" | "bind" | "rbind" | "unbindable" | "runbindable" | "private" | "rprivate" | "shared" | "rshared" | "slave" | "rslave" | "relatime" | "norelatime" | "strictatime" | "nostrictatime" | "mode" | "uid" | "gid" | "nr_inodes" | "nr_blocks" | "mpol"

size

tmpfs 卷的最大大小(以 MiB 为单位)。

类型:整数

必需:是

容器依赖项

dependsOn

类型:ContainerDependency 对象数组

必需:否

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

注意

如果容器不满足依赖性约束或在满足约束之前超时,Amazon ECS 不会将依赖性容器推进到其下一个状态。

对于 Amazon EC2 实例上托管的 Amazon ECS 任务,实例至少需要版本 1.26.0 的容器代理以启用容器依赖关系。但是,我们建议使用最新的容器代理版本。有关检查您的代理版本并更新到最新版本的信息,请参阅更新 Amazon ECS 容器代理。如果您正在使用 Amazon ECS 优化型 Amazon Linux AMI,您的实例将需要不低于 1.26.0-1 版本的 ecs-init 程序包。如果您的容器实例是从版本 20190301 或更高版本启动的,那么这些实例将包含所需版本的容器代理和 ecs-init。有关更多信息,请参阅经 Amazon ECS 优化的 AMI

对于 Fargate 上托管的 Amazon ECS 任务,此参数需要任务或服务使用平台版本 1.3.0 或更高版本(Linux)或 1.0.0(Windows)。

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

类型:字符串

必需:是

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

condition

类型:字符串

必需:是

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

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

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

  • SUCCESS - 此条件与 COMPLETE 相同,但它还要求容器退出并具有 zero 状态。无法在基本容器上设置此条件。

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

容器超时

startTimeout

类型:整数

必需:否

示例值:120

在放弃解析容器的依赖项之前要等待的持续时间(以秒为单位)。

例如,在任务定义中指定两个容器,containerA 需要依赖 containerB 达到 COMPLETESUCCESSHEALTHY 状态。如果为 containerB 指定了一个 startTimeout 值并且它未在该时间内达到所需状态,则 containerA 将不会启动。

注意

如果容器不满足依赖性约束或在满足约束之前超时,Amazon ECS 不会将依赖性容器推进到其下一个状态。

对于 Fargate 上托管的 Amazon ECS 任务,此参数需要任务或服务使用平台版本 1.3.0 或更高版本(Linux)。

stopTimeout

类型:整数

必需:否

示例值:120

容器由于未自行正常退出而被强制终止前要等待的持续时间(以秒为单位)。

对于 Fargate 上托管的 Amazon ECS 任务,此参数需要任务或服务使用平台版本 1.3.0 或更高版本(Linux)。如果未指定该参数,则使用默认值 30 秒。最大值为 120 秒。

对于使用 EC2 启动类型的任务,如果未指定 stopTimeout 参数,则使用为 Amazon ECS 容器代理配置变量 ECS_CONTAINER_STOP_TIMEOUT 设置的值。如果既没有设置 stopTimeout 参数,也没有设置 ECS_CONTAINER_STOP_TIMEOUT 代理配置变量,那么,对于 Linux 容器,使用默认值 30 秒;对于 Windows 容器,使用默认值 30 秒。容器实例需要至少 1.26.0 版的容器代理才能启用容器停止超时值。但是,我们建议使用最新的容器代理版本。有关如何检查您的代理版本并更新到最新版本的信息,请参阅更新 Amazon ECS 容器代理。如果您正在使用经 Amazon ECS 优化的 Amazon Linux AMI,您的实例将需要不低于 1.26.0-1 版本的 ecs-init 程序包。如果您的容器实例是从版本 20190301 或更高版本启动的,那么这些实例将包含所需版本的容器代理和 ecs-init。有关更多信息,请参阅经 Amazon ECS 优化的 AMI

系统控制

systemControls

类型:SystemControl 对象

必需:否

要在容器中设置的命名空间内核参数列表。此参数将映射到 Docker Remote API创建容器部分中的Sysctls以及docker run--sysctl选项。例如,您可以配置 net.ipv4.tcp_keepalive_time 设置以保持更长期的连接。

不建议在使用了 awsvpchost 网络模式的单个任务中为多个容器指定与网络相关的 systemControls 参数。执行此操作具有以下缺点:

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

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

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

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

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

注意

Windows 容器不支持此参数。

注意

如果任务使用平台版本 1.4.0 或更高版本(Linux),则在 Amazon Fargate 上托管的任务仅支持此参数。Fargate 上的 Windows 容器不支持此参数。

"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 时,您可以部署需要分配 stdintty 的容器化应用程序。此参数将映射到 Docker Remote API创建容器部分中的OpenStdin以及docker run--interactive选项。

默认值为 false

伪终端

pseudoTerminal

类型:布尔值

必需:否

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

默认值为 false

Elastic Inference 加速器名称

注意

从 2023 年 4 月 15 日起, Amazon 将不会让新客户加入 Amazon Elastic Inference (EI),并将帮助现有客户将其工作负载迁移到价格和性能更高的选项。2023 年 4 月 15 日之后,新客户将无法在亚马逊、亚马逊 ECS 或亚马逊 EC2 中使用亚马逊 SageMaker EI 加速器启动实例。但是,在过去 30 天内至少使用过一次 Amazon EI 的客户将视为当前客户,可继续使用该服务。

您的任务定义的 Elastic Inference 加速器资源要求。有关更多信息,请参阅什么是 Amazon Elastic Inferenc e? 在《亚马逊 Elastic Inference 开发者指南》中。

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

deviceName

类型:字符串

必需:是

Elastic Inference 加速器设备名称。还必须在容器定义中引用 deviceName,请参阅 Elastic Inference accelerator

deviceType

类型:字符串

必需:是

要使用的 Elastic Inference 加速器。

任务放置约束

您在注册任务定义时,可以提供任务放置约束,自定义 Amazon ECS 如何放置任务。

如果您使用的是 Fargate 启动类型,则不支持任务放置约束。预设情况下,Fargate 任务分布在可用区中。

对于使用 EC2 启动类型的任务,则可以使用约束来根据可用区、实例类型或自定义属性来放置任务。有关更多信息,请参阅Amazon ECS 任务放置约束

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

expression

类型:字符串

必需:否

应用于约束的集群查询语言表达式。有关更多信息,请参阅集群查询语言

type

类型:字符串

必需:是

约束类型。使用 memberOf 将选择限制为一组有效的候选。

代理配置

proxyConfiguration

类型:ProxyConfiguration 对象

必需:否

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

对于使用 EC2 启动类型的任务,容器实例需要至少 1.26.0 版的容器代理和至少 1.26.0-1 版的 ecs-init 程序包才能启用代理配置。如果您的容器实例是从经 Amazon ECS 优化的 AMI 版本 20190301 或更高版本启动的,则这些实例将包含所需版本的容器代理和 ecs-init。有关更多信息,请参阅经 Amazon ECS 优化的 AMI

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

注意

Windows 容器不支持此参数。

"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

类型:字符串

必需:否

键值对的值。

注册任务定义时,您可以选择指定要传递给容器实例Docker上的守护程序的卷列表,然后该列表可供同一容器实例上的其他容器访问。

下面是可使用的数据卷的类型:

  • Amazon EFS 卷——提供简单的可扩展和持久的文件存储以供您的 Amazon ECS 任务使用。使用 Amazon EFS 时,存储容量是弹性的。它会随着您添加和删除文件而自动增加和缩减。您的应用程序可在需要时获得所需存储。Fargate 或 Amazon EC2 实例上托管的任务支持 Amazon EFS 卷。有关更多信息,请参阅Amazon EFS 卷

  • FSx for Windows File Server 卷 — 提供完全托管的 Microsoft Windows 文件服务器。这些文件服务器由 Windows 文件系统提供支持。使用 FSx for Windows File Server 和 Amazon ECS 时,您可以使用永久、分布式、共享的静态文件存储来配置 Windows 任务。有关更多信息,请参阅FSx for Windows File Server 卷

    Fargate 上的 Windows 容器不支持此选项。

  • Docker 卷 — 在主机 Amazon EC2 实例/var/lib/docker/volumes上创建的由 Docker 管理的卷。Docker 卷驱动程序(也称为插件)用于将卷与外部存储系统(如 Amazon EBS)集成。可使用内置 local 卷驱动程序或第三方卷驱动程序。只有在 Amazon EC2 实例上运行任务时才支持 Docker 卷。Windows 容器仅支持使用local驱动程序。要使用 Docker 卷,请在任务定义中指定 dockerVolumeConfiguration。有关更多信息,请参阅使用卷

  • Bind mounts — 主机上挂载到容器中的文件或目录。在 Amazon Fargate 或 Amazon EC2 实例上运行任务时,支持绑定挂载主机卷。要使用绑定挂载主机卷,请在任务定义中指定 host 和可选的 sourcePath 值。有关详细信息,请参阅使用绑定挂载

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

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

name

类型:字符串

必需:否

卷的名称。最多允许 255 个字母(大写和小写)、数字、连字符 (-) 和下划线 (_)。此名称在容器定义mountPoints对象的sourceVolume参数中引用。

host

必需:否

host 参数用于将绑定挂载的生命周期绑定到主机 Amazon EC2 实例(而不是任务)及其存储位置。如果 host 参数为空,则 Docker 进程守护程序将为您的数据卷分配一个主机路径,但不保证数据在与其关联的容器停止运行后将保留。

Windows 容器可在 $env:ProgramData 所在的驱动器上挂载整个目录。

注意

仅当使用托管在 Amazon EC2 实例上的任务时,才支持该sourcePath参数。

sourcePath

类型:字符串

必需:否

在使用 host 参数时,指定 sourcePath 可声明提供给容器的主机 Amazon EC2 容器实例上的路径。如果此参数为空,则 Docker 进程守护程序将为您分配一个主机路径。如果 host 参数包含 sourcePath 文件位置,则数据卷将在主机 Amazon EC2 容器实例上的指定位置保留,除非您手动将其删除。如果主机 Amazon EC2 容器实例上不存在 sourcePath 值,则 Docker 进程守护程序将创建该值。如果该位置不存在,则将导出源路径文件夹的内容。

dockerVolumeConfiguration

类型:DockerVolumeConfiguration对象

必需:否

使用 Docker 卷时将指定此参数。只有在 EC2 实例上运行任务时才支持 Docker 卷。Windows 容器仅支持使用local驱动程序。要使用绑定挂载,请改为指定 host

scope

类型:字符串

有效值:task | shared

必需:否

Docker 卷的范围,可确定其生命周期。当任务开始时,将自动预配置范围限定为 task 的 Docker 卷;而当任务停止时销毁此卷。任务停止后,范围限定为 shared 的 Docker 卷将持续存在。

autoprovision

类型:布尔值

默认值:false

必需:否

如果此值为 true,则将创建 Docker 卷(如果此卷不存在)。仅当为时才使用此字段sharedscope如果scopetask,则必须省略此参数或将其设置为false

driver

类型:字符串

必需:否

要使用的 Docker 卷驱动程序。驱动程序值必须与 Docker 提供的驱动程序名称相匹配,因为此名称用于任务放置。如果驱动程序是使用 Docker 插件 CLI 安装的,docker plugin ls请使用从容器实例中检索驱动程序名称。如果驱动程序是通过其他方法安装的,请使用 Docker 插件发现来检索驱动程序名称。有关更多信息,请参阅 Docker 插件发现。此参数映射到 Docker Remote API创建卷部分中的 Driver 以及 docker volume create--driver 选项。

driverOpts

类型:字符串

必需:否

要通过的 Docker 驱动程序特定选项的地图。此参数映射到 Docker Remote API创建卷部分中的 DriverOpts 以及 docker volume create--opt 选项。

labels

类型:字符串

必需:否

要添加到 Docker 卷的自定义元数据。此参数映射到 Docker Remote API创建卷部分中的 Labels 以及 docker volume create--label 选项。

efsVolumeConfiguration

类型:EFS VolumeConfiguration 对象

必需:否

使用 Amazon EFS 卷时将指定此参数。

fileSystemId

类型:字符串

必需:是

要使用的 Amazon EFS 文件系统 ID。

rootDirectory

类型:字符串

必需:否

Amazon EFS 文件系统中要作为主机内的根目录挂载的目录。如果忽略此参数,将使用 Amazon EFS 卷的根目录。指定 / 与忽略此参数效果相同。

重要

如果在中指定了 EFS 接入点authorizationConfig,则必须省略根目录参数或将其设置为/,这将强制执行 EFS 接入点上设置的路径。

transitEncryption

类型:字符串

有效值:ENABLED | DISABLED

必需:否

指定是否对 Amazon ECS 主机和 Amazon EFS 服务器之间传输的 Amazon EFS 数据启用加密。如果使用 Amazon EFS IAM 授权,则必须启用传输加密。如果忽略此参数,将使用默认值DISABLED。有关更多信息,请参阅《Amazon Elastic File System 用户指南》中的加密传输中的数据

transitEncryptionPort

类型:整数

必需:否

在 Amazon ECS 主机和 Amazon EFS 服务器之间发送加密数据时要使用的端口。如果您未指定传输加密端口,则该任务将使用 Amazon EFS 挂载帮助程序使用的端口选择策略。有关更多信息,请参阅《Amazon Elastic File System 用户指南》中的 EFS 挂载帮助程序

authorizationConfig

类型:EFS AuthorizationConfiguration 对象

必需:否

Amazon EFS 文件系统的授权配置详细信息。

accessPointId

类型:字符串

必需:否

要使用的接入点 ID。如果指定了接入点,则efsVolumeConfiguration必须省略或将中的根目录值设置为/,这将强制执行 EFS 接入点上设置的路径。如果使用接入点,则必须在EFSVolumeConfiguration中启用传输加密。有关更多信息,请参阅《Amazon Elastic File System 用户指南》中的使用 Amazon EFS 接入点

iam

类型:字符串

有效值:ENABLED | DISABLED

必需:否

指定在安装 Amazon EFS 文件系统时是否使用在任务定义中定义的 Amazon ECS 任务 IAM 角色。如果启用,则必须在EFSVolumeConfiguration中启用传输加密。如果忽略此参数,将使用默认值DISABLED。有关更多信息,请参阅适用于任务的 IAM 角色

FSxWindowsFileServerVolumeConfiguration

类型:F SxWindowsFileServerVolumeConfiguration 对象

必需:是

此参数是在您使用适用于 Windows 文件服务器的 Amazon FSx 文件系统进行任务存储时指定的。

fileSystemId

类型:字符串

必需:是

要使用的 FSx for Windows File Server 文件系统 ID。

rootDirectory

类型:字符串

必需:是

FSx for Windows File Server 文件系统中要作为主机内的根目录挂载的目录。

authorizationConfig
credentialsParameter

类型:字符串

必需:是

授权凭据选项。

选项
domain

类型:字符串

必需:是

Amazon Directory Service for Microsoft Active Directory(Amazon Managed Microsoft AD) 目录或自托管的 EC2 Active Directory 托管的完全限定域名。

标签

在注册任务定义时,可以选择指定应用于任务定义的元数据标签。标签可帮助您对任务定义进行分类和组织。每个标签都由一个键和一个可选值组成。您可以同时定义它们。有关更多信息,请参阅 亚马逊 ECS 资源标记

重要

请勿在标签中添加个人身份信息或其他机密或敏感信息。许多 Amazon 服务都可以访问标签,包括账单。标签不适合用于私有或敏感数据。

标签对象中允许以下参数。

key

类型:字符串

必需:否

构成标签的键-值对的一个部分。键是一种常见的标签,行为类似于更具体的标签值的类别。

value

类型:字符串

必需:否

构成标签的键-值对的可选部分。值充当标签类别(键)中的描述符。

其他任务定义参数

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

临时存储

ephemeralStorage

类型:EphemeralStorage 对象

必需:否

要为任务分配的临时存储量(以 GB 为单位)。此参数用于扩展可用的临时存储总量,超出原定设置数量,可用于在 Amazon Fargate 上托管的任务。有关更多信息,请参阅绑定挂载

注意

使用平台版本 1.4.0 或更高版本(Linux)或者 1.0.0 或更高版本(Windows)在 Amazon Fargate 上托管的任务仅支持此参数。

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 将适用于任务中的所有容器。

注意

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

PID 模式

pidMode

类型:字符串

有效值:host | task

必需:否

用于任务中的容器的过程命名空间。有效值为 hosttask。在适用于 Linux 的 Fargate 容器上,唯一的有效值为 task。例如,监控 sidecar 可能需要 pidMode 访问有关在同一任务中运行的其他容器的信息。

如果指定了 host,则在同一容器实例上指定了 host PID 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的进程命名空间。

如果指定了 task,则指定任务中的所有容器将共享相同的过程命名空间。

如果未指定任何值,则默认值为每个容器的私有命名空间。有关更多信息,请参阅 Docker 运行参考中的 PID 设置

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

注意

Windows 容器不支持此参数。

注意

如果任务使用平台版本 1.4.0 或更高版本(Linux),则在 Amazon Fargate 上托管的任务仅支持此参数。Fargate 上的 Windows 容器不支持此参数。