# Amazon EC2 的 Amazon ECS 任务定义参数
任务定义包括以下各部分：任务系列、AWS Identity and Access Management（IAM）任务角色、网络模式、容器定义、卷、任务放置约束和容量。任务定义中需要系列和容器定义。相反，任务角色、网络模式、卷、任务放置约束和启动类型是可选的。
您可以在 JSON 文件中使用这些参数来配置任务定义。
下面是 Amazon EC2 的每个任务定义参数的更详细描述
## 系列
`family`
类型：字符串
是否必需：是
当您注册任务定义时，将为其提供一个系列，与任务定义的多个版本的名称类似，它是使用修订号指定的。注册到某个特定系列的第一个任务定义将获得修订 1，而随后注册的任何任务定义将获得后续修订号。
## 容量
注册任务定义时，您可以指定 Amazon ECS 应根据哪个容量来验证任务定义。如果任务定义未根据指定的兼容性进行验证，则返回客户端异常。
任务定义中允许以下参数。
`requiresCompatibilities`
类型：字符串数组
必需：否
有效值：`EC2`
根据其验证任务定义的容量。这将启动一项检查，以确保任务定义中使用的所有参数都符合 Amazon EC2 的要求。
## 任务 角色
`taskRoleArn`
类型：字符串
必需：否
注册任务定义时，可以为 IAM 角色提供任务角色，此角色可使任务中的容器有权代表您调用其关联策略中指定的 AWS API。有关更多信息，请参阅 [Amazon ECS 任务 IAM 角色](task-iam-roles.md)。
在您启动经 Amazon ECS 优化的 Windows Server AMI 时，Windows 上任务的 IAM 角色需要设置 `-EnableTaskIAMRole` 选项。此外，您的容器必须运行一些配置代码才能利用此功能。有关更多信息，请参阅 [Amazon EC2 Windows 实例附加配置](task-iam-roles.md#windows_task_IAM_roles)。
## 任务执行 角色
`executionRoleArn`
类型：字符串
必需：条件
任务执行角色的 Amazon 资源名称（ARN），该角色授予 Amazon ECS 容器代理代表您进行 AWS API 调用的权限。
任务执行 IAM 角色是必需的，具体取决于任务的要求。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
## 网络模式
`networkMode`
类型：字符串
必需：否
在任务中用于容器的 Docker 联网模式。对于 Amazon EC2 Linux 实例上托管的 Amazon ECS 任务，有效值为 `none`、`bridge`、`awsvpc` 和 `host`。如果未指定网络模式，则默认网络模式为 `bridge`。对于在 Amazon EC2 Windows 实例上托管的 Amazon ECS 任务，有效值为 `default` 和 `awsvpc`。如果未指定网络模式，则将使用 `default` 网络模式。
如果网络模式设置为 `none`，则任务的容器没有外部连接性，且无法在容器定义中指定端口映射。
如果网络模式为 `bridge`，则任务在 Linux 上使用 Docker 的内置虚拟网络，该网络在托管任务的每个 Amazon EC2 实例内运行。Linux 上的内置虚拟网络使用 `bridge` Docker 网络驱动程序。
如果网络模式为 `host`，任务将通过直接映射容器端口到托管任务的 Amazon EC2 实例的 ENI，使用会绕过 Docker 内置虚拟网络的主机网络。动态端口映射不可在此网络模式中使用。使用此模式的任务定义中的容器必须指定具体的 `hostPort` 号。主机上的端口号不可被用于多个任务。因此，您不可以在单个 Amazon EC2 实例上运行相同任务定义的多个任务。
运行使用 `host` 网络模式的任务时，请勿使用根用户（UID 0）运行容器，以获得更好的安全性。作为安全最佳实践，请始终使用非根用户。
如果网络模式为 `awsvpc`，则将为任务分配弹性网络接口，且在创建服务或运行具有任务定义的任务时必须指定 `NetworkConfiguration`。有关更多信息，请参阅 [EC2 的 Amazon ECS 任务联网选项](task-networking.md)。
如果网络模式为 `default`，则任务在 Windows 上使用 Docker 的内置虚拟网络，该网络在托管任务的每个 Amazon EC2 实例内运行。Windows 上的内置虚拟网络使用 `nat` Docker 网络驱动程序。
`host` 和 `awsvpc` 网络模式可为容器提供最高联网性能，因为容器使用 Amazon EC2 网络堆栈。使用 `host` 和 `awsvpc` 网络模式，公开的容器端口将直接映射到相应的主机端口（用于 `host` 网络模式）或附加的弹性网络接口端口（用于 `awsvpc` 网络模式）。因此，您不能使用动态主机端口映射。
允许的网络模式取决于底层 EC2 实例的操作系统。对于 Linux，可以使用任何网络模式。如果 Windows，`default` 和 `awsvpc` 模式可以使用。
## 运行时平台
`operatingSystemFamily`
类型：字符串
必需：条件
原定设置：LINUX
当您注册任务定义时，您可以指定操作系统系列。
有效值为 `LINUX`、`WINDOWS_SERVER_2025_FULL`、`WINDOWS_SERVER_2025_CORE`、`WINDOWS_SERVER_2022_CORE`、`WINDOWS_SERVER_2022_FULL`、`WINDOWS_SERVER_2019_FULL`，以及 `WINDOWS_SERVER_2019_CORE`、`WINDOWS_SERVER_2016_FULL`、`WINDOWS_SERVER_2004_CORE` 和 `WINDOWS_SERVER_20H2_CORE`。
服务中使用的所有任务定义对于此参数都必须具有相同的值。
当任务定义是服务的一部分时，此值必须与服务 `platformFamily` 值匹配。
`cpuArchitecture`
类型：字符串
必需：条件
注册任务定义时，您可以指定 CPU 架构。有效值为 `X86_64` 和 `ARM64`。如果不指定值，Amazon ECS 会根据容量提供程序配置尝试将任务放置在可用的 CPU 架构上。要确保任务放置在特定 CPU 架构上，请在任务定义中指定 `cpuArchitecture` 的值。
服务中使用的所有任务定义对于此参数都必须具有相同的值。
当您有 Linux 任务时，可以将该值设置为 `ARM64`。有关更多信息，请参阅 [适用于 64 位 ARM 工作负载的 Amazon ECS 任务定义](ecs-arm64.md)。
## 任务大小
注册任务定义时，您可以指定用于任务的总 CPU 和内存量。这独立于容器定义级别的 `cpu` 和 `memory` 值。对于 Amazon EC2 实例上托管的任务，这些字段是可选的。
**注意**
Windows 容器将忽略任务级 CPU 和内存参数。我们建议为 Windows 容器指定容器级资源。
`cpu`
类型：字符串
必需：条件
Windows 容器不支持此参数。
要为任务提供的 CPU 单位的硬限制。您可以通过 CPU 单位数或虚拟 CPU（vCPU）数字符串的方式在 JSON 文件中将 CPU 值。例如，您可以使用 `1024`（CPU 单位数）或 `1 vCPU`（vCPU 数）来指定 CPU 值。注册任务定义时，vCPU 值将转换为指示 CPU 单元的整数。
该字段是可选的。如果您的集群没有任何带可用的已请求 CPU 单位的已注册容器实例，则该任务将失败。支持的值介于 `0.125` vCPU 和 `192` vCPU 之间。
`memory`
类型：字符串
必需：条件
Windows 容器不支持此参数。
要向任务提供的内存硬限制。您可以通过以二进制兆字节（MiB）或千兆字节（GB）字符串方式在任务定义中指定内存值。例如，您可以使用 `3072`（以 MiB 为单位）或 `3 GB`（以 GB 为单位）指定内存值。注册任务定义时，GB 值将转换为指示 MiB 的整数。
此字段是可选的，并且可使用任何值。如果指定了任务级内存值，则容器级内存值是可选的。如果您的集群没有任何带可用的已请求内存的已注册容器实例，则该任务将失败。您可以尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源。有关更多信息，请参阅 [预留 Amazon ECS Linux 容器实例内存](memory-management.md)。
## 容器定义
当您注册任务定义时，必须指定将传递给容器实例上的 Docker 进程守护程序的容器定义的列表。容器定义中允许以下参数。
**Topics**
+ [标准容器定义参数](#standard_container_definition_params_ec2)
+ [高级容器定义参数](#advanced_container_definition_params_ec2)
+ [其他容器定义参数](#other_container_definition_params_ec2)
### 标准容器定义参数
以下任务定义参数是必需的参数或在大多数容器定义中使用。
**Topics**
+ [名称](#container_definition_name_ec2)
+ [Image](#container_definition_image_ec2)
+ [内存](#container_definition_memory_ec2)
+ [端口映射](#container_definition_portmappings_ec2)
+ [私有存储库凭证](#container_definition_repositoryCredentials_ec2)
#### 名称
`name`
类型：字符串
是否必需：是
容器的名称。最多能包含 255 个字母（大写和小写字母）、数字、连字符和下划线。如果您正在任务定义中将多个容器链接在一起，则可在另一个容器的 `links` 中输入一个容器的 `name`。这样是为了连接容器。
#### Image
`image`
类型：字符串
是否必需：是
用于启动容器的映像。此字符串将直接传递给 Docker 进程守护程序。默认情况下，Docker Hub 注册表中的映像可用。您也可以使用 `repository-url/image:tag` 或 `repository-url/image@digest` 指定其他存储库。允许最多 255 个字母（大写和小写字母）、数字、连字符、下划线、冒号、句点、正斜杠和井号。此参数对应于 docker create-container 命令中的 `Image` 和 docker run 命令的 `IMAGE` 参数。
+ 在新任务启动时，Amazon ECS 容器代理会提取最新版本的指定映像和标签以供容器使用。但是，存储库映像的后续更新不会传播到已在运行的任务。
+ 如果未在任务定义的映像路径中指定某个标签或摘要，则 Amazon ECS 容器代理会使用 `latest` 标签来拉取指定的映像。
+ 存储库映像的后续更新不会传播到已在运行的任务。
+ 支持私有注册表中的映像。有关更多信息，请参阅 [在 Amazon ECS 中使用非 AWS 容器映像](private-auth.md)。
+ Amazon ECR 存储库中的映像可通过使用完整的 `registry/repository:tag` 或 `registry/repository@digest` 命名约定来指定（例如 `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app:latest` 或 `aws_account_id.dkr.ecr.region.amazonaws.com``/my-web-app@sha256:94afd1f2e64d908bc90dbca0035a5b567EXAMPLE`）。
+ Docker Hub 上的官方存储库中的映像使用一个名称（例如，`ubuntu` 或 `mongo`）。
+ Docker Hub 上其他存储库中的映像通过组织名称（例如，`amazon/amazon-ecs-agent`）进行限定。
+ 其他在线存储库中的映像由域名（例如，`quay.io/assemblyline/ubuntu`）进行进一步限定。
`versionConsistency`
类型：字符串
有效值：`enabled`\$1`disabled`
必需：否
指定 Amazon ECS 是否将容器定义中提供的容器映像标签解析为映像摘要。默认情况下，此行为`enabled`。如果您将容器的值设置为 `disabled`，Amazon ECS 不会将容器映像标签解析为摘要，而是使用容器定义中指定的原始映像 URI 进行部署。有关容器映像解析的更多信息，请参阅[容器映像解析](deployment-type-ecs.md#deployment-container-image-stability)。
#### 内存
`memory`
类型：整数
必需：否
要提供给容器的内存量（以 MiB 为单位）。如果容器尝试使用超出此处指定的内存，该容器将被终止。为任务中的所有容器预留的内存总量必须低于任务 `memory` 值（如果指定了一个）。此参数对应于 docker create-container 命令中的 `Memory` 和 docker run 命令的 `--memory` 选项。
您必须指定任务级内存值或容器级内存值。如果同时指定容器级 `memory` 和 `memoryReservation` 值，则 `memory` 值必须大于 `memoryReservation` 值。如果指定 `memoryReservation`，则将从容器所在的容器实例的可用内存资源中减去该值。否则，将使用 `memory` 的值。
Docker 20.10.0 或更高版本进程守护程序将为容器预留最少 6MiB 的内存。因此，不要为容器指定少于 6MiB 的内存。
Docker 19.03.13-ce 或更早版本的进程守护程序将为容器预留最少 4MiB 的内存。因此，不要为容器指定少于 4MiB 的内存。
如果您尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源，请参阅[预留 Amazon ECS Linux 容器实例内存](memory-management.md)。
`memoryReservation`
类型：整数
必需：否
要为容器预留的内存量的软限制（以 MiB 为单位）。当系统内存处于争用状态时，Docker 会尝试将容器内存保持在此软限制范围内。但是，您的容器在需要时可使用更多内存。容器可以用尽使用 `memory` 参数指定的硬限制（如果适用）或容器实例中的全部可用内存，以较低者为准。此参数对应于 docker create-container 命令中的 `MemoryReservation` 和 docker run 命令的 `--memory-reservation` 选项。
如果未指定任务级内存值，则必须为容器定义中的一个或两个 `memory` 或 `memoryReservation` 指定非零整数。如果指定两者，则 `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 的内存。
如果您尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源，请参阅[预留 Amazon ECS Linux 容器实例内存](memory-management.md)。
#### 端口映射
`portMappings`
类型：对象数组
必需：否
端口映射将容器的网络端口暴露给外界。这让客户端能够访问您的应用程序。它也用于同一任务内的容器间通信。
对于使用 `awsvpc` 网络模式的任务定义，只能指定 `containerPort`。`hostPort` 始终被忽略，并且容器端口会自动映射到主机上的随机高编号端口。
Windows 上的端口映射使用 `NetNAT` 网关地址而非 `localhost`。没有针对 Windows 上的端口映射的回环，因此，您无法从主机自身访问容器的映射端口。
此参数的大部分字段（包括 `containerPort`、`hostPort`、`protocol`）对应于 thedocker create-container 命令中的 `PortBindings` 和 docker run 命令的 `--publish` 选项。如果将任务定义的网络模式设置为 `host`，则主机端口必须是未定义的或者必须与端口映射中的容器端口匹配。
在任务达到 `RUNNING` 状态之后，手动和自动主机及容器端口分配在以下位置可见：
+ 控制台：所选任务的容器说明的**网络绑定**部分。
+ AWS CLI：**describe-tasks** 命令输出的 `networkBindings` 部分。
+ API：`DescribeTasks` 响应。
+ 元数据：任务元数据端点。
`appProtocol`
类型：字符串
必需：否
用于端口映射的应用程序协议。此参数仅适用于服务连接。我们建议您将此参数设置为与应用程序使用的协议一致。如果您设置此参数，Amazon ECS 会将协议特定的连接处理添加到服务连接代理。如果您设置此参数，Amazon ECS 会在 Amazon ECS 控制台和 CloudWatch 中添加协议特定的遥测。
如果您没有为此参数设置值，则使用 TCP。但是，Amazon ECS 不会为 TCP 添加协议特定的遥测。
有关更多信息，请参阅 [使用 Service Connect 连接具有短名称的 Amazon ECS 服务](service-connect.md)。
有效的协议值：`"http" | "http2" | "grpc" `
`containerPort`
类型：整数
必需：是，当使用 `portMappings` 时
绑定到用户指定的或自动分配的主机端口的容器上的端口号。
对于使用 `awsvpc` 网络模式的任务，请使用 `containerPort` 指定公开的端口。
假设您正在具有 EC2 容量提供程序的任务中使用容器，且指定了容器端口，而非主机端口。然后，您的容器将自动接收临时端口范围内的主机端口。有关更多信息，请参阅 `hostPort`。通过此方式自动分配的端口映射不计入容器实例的 100 个预留端口配额。
`containerPortRange`
类型：字符串
必需：否
容器上的端口号范围，该容器绑定到动态映射的主机端口范围。
您只能使用 `register-task-definition` API 设置此参数。该选项在 `portMappings` 参数中可用。有关更多信息，请参阅《AWS Command Line Interface 参考》**中的 [register-task-definition](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html)。
当您指定 `containerPortRange` 时，以下规则适用：
+ 必须使用 `bridge` 网络模式或 `awsvpc` 网络模式。
+ 此参数同时适用于 Linux 和 Windows 操作系统。
+ 容器实例必须拥有不低于 1.67.0 版本的容器代理和不低于 1.67.0-1 版本的 `ecs-init` 程序包。
+ 每个容器最多可指定 100 个端口范围。
+ 您不用指定 `hostPortRange`。`hostPortRange` 的值设置如下：
+ 对于使用 `awsvpc` 网络模式的任务中的容器，`hostPort` 将设置为与 `containerPort` 相同的值。这是一种静态映射策略。
+ 对于使用 `bridge` 网络模式的任务中的容器，Amazon ECS 代理会从默认临时范围内找到开放主机端口，并将其传递给 Docker 以将其绑定到容器端口。
+ `containerPortRange` 有效值为 1 到 65535。
+ 每个容器的一个端口只能包含在的一个端口映射中。
+ 您不能指定重叠的端口范围。
+ 范围中的第一个端口必须小于范围中的最后一个端口。
+ 当有大量端口时，Docker 建议您关闭 Docker 进程守护程序配置文件中的 docker-proxy。
有关更多信息，请参阅 Github 上的[问题 \$111185](https://github.com/moby/moby/issues/11185)。
有关如何关闭 Docker 进程守护程序配置文件中的 docker-proxy 的信息，请参阅《Amazon ECS 开发者指南》**中的 [Docker 进程守护程序](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/bootstrap_container_instance.html#bootstrap_docker_daemon)。
您可以调用 [DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html) 以查看 `hostPortRange`，它们是绑定到容器端口的主机端口。
该端口范围不包含在发送到 EventBridge 的 Amazon ECS 任务事件中。有关更多信息，请参阅 [使用 EventBridge 自动响应 Amazon ECS 错误](cloudwatch_event_stream.md)。
`hostPortRange`
类型：字符串
必需：否
用于网络绑定的主机上的端口号范围。它由 Docker 分配并由 Amazon ECS 代理传送。
`hostPort`
类型：整数
必需：否
要为您的容器预留的容器实例上的端口号。
您可以为容器端口映射指定非预留主机端口。此项称为*静态*主机端口映射。或者，您可以在指定 `containerPort` 时省略 `hostPort`（或将其设置为 `0`）。您的容器会自动接收容器实例操作系统和 Docker 版本的临时端口范围内的端口。这称为*动态*主机端口映射。
Docker 版本 1.6.0 及更高版本的默认临时端口范围在 `/proc/sys/net/ipv4/ip_local_port_range` 下的实例上列出。如果此内核参数不可用，则将使用来自 `49153–65535` 的原定设置临时端口范围。不要尝试指定临时端口范围内的主机端口。这是因为这些都是为自动分配预留的。通常，低于 `32768` 的端口位于临时端口范围之外。您可以使用 ECS 容器代理配置中的 `ECS_DYNAMIC_HOST_PORT_RANGE` 设置为动态分配的主机端口指定自定义范围。如果您的任务由于与容器实例上的其他进程（例如，也使用临时端口范围内的端口的出站连接）发生端口冲突而无法启动，这可能会有所帮助。有关更多信息，请参阅 [Amazon ECS 容器代理配置](ecs-agent-config.md)。
默认预留端口为适用于 SSH 的 `22`、Docker 端口 `2375` 和 `2376` 以及 Amazon ECS 容器代理端口 `51678-51680`。针对正在运行的任务的之前由用户指定的任何主机端口在任务运行时也将预留。任务停止后，系统会释放主机端口。当前预留端口将显示在 **describe-container-instances** 输出的 `remainingResources` 中。一个容器实例一次最多可拥有 100 个预留端口，包括默认预留端口。自动分配的端口不计入 100 个预留端口配额。
`name`
类型：字符串
必填项：否，在服务中配置 Service Connect 和 VPC Lattice 时需要
用于端口映射的名称。此参数仅适用于 Service Connect 和 VPC Lattice。此参数是您在服务的 Service Connect 和 VPC Lattice 配置中使用的名称。
有关更多信息，请参阅 [使用 Service Connect 连接具有短名称的 Amazon ECS 服务](service-connect.md)。
在以下示例中，使用了针对 Service Connect 和 VPC Lattice 的两个必填字段。
```
"portMappings": [
{
"name": string,
"containerPort": integer
}
]
```
`protocol`
类型：字符串
必需：否
用于端口映射的协议。有效值为 `tcp` 和 `udp`。默认值为 `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 容器代理](ecs-agent-update.md)。
如果您指定的是主机端口，请使用以下语法。
```
"portMappings": [
{
"containerPort": integer,
"hostPort": integer
}
...
]
```
如果您需要自动分配的主机端口，请使用以下语法。
```
"portMappings": [
{
"containerPort": integer
}
...
]
```
#### 私有存储库凭证
`repositoryCredentials`
类型：[RepositoryCredentials](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_RepositoryCredentials.html) 对象
必需：否
私有注册表身份验证的存储库凭证。
有关更多信息，请参阅 [在 Amazon ECS 中使用非 AWS 容器映像](private-auth.md)。
`credentialsParameter`
类型：字符串
必需：是，当使用 `repositoryCredentials` 时
包含私有存储库凭证的密钥的 Amazon 资源名称（ARN）。
有关更多信息，请参阅 [在 Amazon ECS 中使用非 AWS 容器映像](private-auth.md)。
使用 Amazon ECS API、AWS CLI 或 AWS 开发工具包时，如果密钥存在于要启动的任务所在的区域，使用密钥的完整 ARN 或名称。在您使用 AWS 管理控制台 时，必须指定密钥的完整 ARN。
下面是显示必需参数的任务定义代码段：
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### 高级容器定义参数
以下高级容器定义参数为 docker run 命令（用于在 Amazon ECS 容器实例上启动容器）提供了扩展功能。
**Topics**
+ [重启策略](#container_definition_restart_policy_ec2)
+ [运行状况检查](#container_definition_healthcheck_ec2)
+ [环境](#container_definition_environment_ec2)
+ [网络设置](#container_definition_network_ec2)
+ [存储和日志记录](#container_definition_storage_ec2)
+ [安全性](#container_definition_security_ec2)
+ [资源限制](#container_definition_limits_ec2)
+ [Docker 标签](#container_definition_labels_ec2)
#### 重启策略
`restartPolicy`
容器重启策略和相关的配置参数。为容器设置重启策略后，Amazon ECS 无需替换任务即可重启容器。有关更多信息，请参阅 [使用容器重启策略重启 Amazon ECS 任务中的单个容器](container-restart-policy.md)。
`enabled`
类型：布尔值
是否必需：是
指定是否为该容器启用重启策略。
`ignoredExitCodes`
类型：整数数组
必需：否
Amazon ECS 将会忽略并且不会尝试重启的退出代码列表。您最多可以指定 50 个容器退出代码。默认情况下，Amazon ECS 不会忽略任何退出代码。
`restartAttemptPeriod`
类型：整数
必需：否
容器在尝试重启前必须运行的时长（以秒为单位）。容器每 `restartAttemptPeriod` 秒只能重启一次。如果容器在此期间无法运行并提前退出，则不会重启。您可以将最小 `restartAttemptPeriod` 设置为 60 秒，将最大 `restartAttemptPeriod` 设置为 1800 秒。默认情况下，容器必须运行 300 秒后才能重启。
#### 运行状况检查
`healthCheck`
容器的运行状况检查命令和关联的配置参数。有关更多信息，请参阅 [使用容器运行状况检查确定 Amazon ECS 任务运行状况](healthcheck.md)。
`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" ]
```
不带有 `stderr` 输出的退出代码 0 表示成功，非零退出代码表示失败。
`interval`
每次运行状况检查间隔的时间（以秒为单位）。您可以指定 5 到 300 秒之间的值。默认值为 30 秒。
`timeout`
等待运行状况检查成功执行的时间长度（以秒为单位），超过该时间则视为失败。您可以指定 2 到 60 秒之间的值。默认值为 5 秒。
`retries`
重试失败的运行状况检查的次数，超过该次数将容器视为不正常。您可以指定 1 到 10 之间的重试次数。默认值为三次重试。
`startPeriod`
可选的宽限期，这让容器有时间来引导，不将失败的运行状况检查计数计入最大重试次数中。您可以指定 0 到 300 秒之间的值。`startPeriod` 默认已禁用。
如果 `startPeriod` 中的运行状况检查成功，则容器将被视为运行状况良好，并且任何后续失败将计入最大重试次数。
#### 环境
`cpu`
类型：整数
必需：否
Amazon ECS 容器代理为容器预留的 `cpu` 单位的数量。在 Linux 上，此参数对应于[创建容器](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate)部分中的 `CpuShares`。
您可以确定每个 Amazon EC2 实例类型可用的 CPU 单位数。为此，请将 [Amazon EC2 实例](https://aws.amazon.com/ec2/instance-types/)详细信息页面上为该实例类型列出的 vCPU 数量乘以 1024。
Linux 容器会按照与其分配的量相同的比例，与容器实例上的其他容器共享未分配的 CPU 单元。例如，假设您在单核实例类型上运行一个单容器任务，同时为该容器指定 512 个 CPU 单元。此外，在容器实例上，该任务是运行的唯一任务。在此示例中，容器可以在任何给定时间使用完整的 1024 个 CPU 单位份额。但是，假设您在该容器实例上启动了同一任务的另一个副本。在需要时，保证每个任务至少有 512 个 CPU 单位。同样，如果另一个容器没有使用剩余的 CPU，则每个容器都可以浮动到更高的 CPU 利用率。但是，如果两个任务一直都处于 100％ 活动状态，那么它们将限制为 512 个 CPU 单位。
在 Linux 容器实例上，容器实例上的 Docker 进程守护程序使用 CPU 值来计算正在运行的容器的相对 CPU 共享比例。Linux 内核允许的最小有效 CPU 共享值为 2，Linux 内核允许的最大有效 CPU 共享值为 262144。不过，CPU 参数不是必需的，您可以在容器定义中使用小于 2 和大于 262144 的 CPU 值。对于小于 2（包括 null）和大于 262144 的 CPU 值，此行为因 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。
+ **代理版本为 1.84.0 或更高：**大于 256 vCPU 的 CPU 值作为 256 传递给 Docker，等同于 262144 次 CPU 共享。
在 Windows 容器实例上，此 CPU 配额将作为绝对配额强制实施。Windows 容器只能访问任务定义中所定义的指定 CPU 量。Null 或零 CPU 值将作为 `0` 传递给 Docker。然后 Windows 将此值解释为一个 CPU 的 1%。
有关更多示例，请参阅 [Amazon ECS 如何管理 CPU 和内存资源](https://aws.amazon.com/blogs/containers/how-amazon-ecs-manages-cpu-and-memory-resources/)。
`gpu`
类型：[ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 对象
必需：否
Amazon ECS 容器代理为容器预留的物理 `GPUs` 的数量。为某个任务中的所有容器预留的 GPU 的数量不得超过该任务在其上启动的容器实例的可用 GPU 的数量。有关更多信息，请参阅 [适用于 GPU 工作负载的 Amazon ECS 任务定义](ecs-gpu.md)。
Windows 容器不支持此参数。
`Elastic Inference accelerator`
类型：[ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 对象
必需：否
对于 `InferenceAccelerator` 类型，`value` 与任务定义中指定的 `InferenceAccelerator` 的 `deviceName` 匹配。有关更多信息，请参阅 [Elastic Inference 加速器名称（已弃用）](task_definition_parameters.md#elastic-Inference-accelerator)。
Windows 容器不支持此参数。
`essential`
类型：布尔值
必需：否
假设将容器的 `essential` 参数标记为 `true`，并且该容器出于任何原因发生故障或停止。然后，将停止属于此任务的所有其他容器。如果将容器的 `essential` 参数标记为 `false`，则容器发生故障不会影响任务中的剩余容器。如果省略此参数，则假定容器是主要容器。
所有任务都必须具有至少一个主要容器。假设您有一个由多个容器组成的应用程序。然后，将用于相同目的的容器分组成各组件，并将不同的组件分成多个任务定义。有关更多信息，请参阅 [设计适用于 Amazon ECS 的应用程序架构](application_architecture.md)。
```
"essential": true|false
```
`entryPoint`
Amazon ECS 容器代理的早期版本无法正确处理 `entryPoint` 参数。如果您在使用 `entryPoint` 时遇到问题，请更新您的容器代理或改为输入命令和参数作为 `command` 数组项。
类型：字符串数组
必需：否
传递给容器的入口点。
```
"entryPoint": ["string", ...]
```
`command`
类型：字符串数组
必需：否
传递给容器的命令。此参数对应于 create-container 命令中的 `Cmd` 和 docker run 命令的 `COMMAND` 参数。如果有多个参数，则确保每个参数都是数组中的分隔字符串。
```
"command": ["string", ...]
```
`workingDirectory`
类型：字符串
必需：否
在其中运行命令的容器中的工作目录。此参数将映射到 [Docker Remote API](https://docs.docker.com/reference/api/engine/version/v1.38/) 的[创建容器](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate)部分中的 `WorkingDir` 以及 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) 的 `--workdir` 选项。
```
"workingDirectory": "string"
```
`environmentFiles`
类型：对象数组
必需：否
包含要传递到容器的环境变量的文件列表。此参数对应于 docker run 命令的 `--env-file` 选项。
启用 FIPS 时，不支持包含句点（.）的存储桶名称（例如，amzn-s3-demo-bucket1.name.example）。存储桶名称中包含句点（.）会导致任务无法启动，因为代理无法从 Amazon S3 中提取环境变量文件。
这不适用于 Windows 容器。
您最多可以指定 10 个环境文件。文件必须具有 `.env` 文件扩展名。环境文件中的每一行都包含 `VARIABLE=VALUE` 格式的环境变量。以 `#` 开头的行被视为注释并会被忽略。
如果在容器定义中指定了单个环境变量，则这些变量的优先级高于环境文件中包含的变量。如果指定了多个包含相同变量的环境文件，则会按从上到下的顺序处理这些文件。建议您使用唯一的变量名。有关更多信息，请参阅 [将单个环境变量传递给 Amazon ECS 容器](taskdef-envfiles.md)。
`value`
类型：字符串
是否必需：是
包含环境变量文件的 Amazon S3 对象的 Amazon 资源名称（ARN）。
`type`
类型：字符串
是否必需：是
要使用的文件类型 `s3` 是唯一受支持的值。
`environment`
类型：对象数组
必需：否
要传递给容器的环境变量。此参数对应于 docker create-container 命令中的 `Env` 和 docker run 命令的 `--env` 选项。
建议不要对敏感信息（如凭证数据）使用纯文本环境变量。
`name`
类型：字符串
必需：是，当使用 `environment` 时
环境变量的名称。
`value`
类型：字符串
必需：是，当使用 `environment` 时
环境变量的值。
```
"environment" : [
{ "name" : "string", "value" : "string" },
{ "name" : "string", "value" : "string" }
]
```
`secrets`
类型：对象数组
必需：否
表示用于对容器开放的密钥的对象。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
`name`
类型：字符串
是否必需：是
要在容器上设置为环境变量的值。
`valueFrom`
类型：字符串
是否必需：是
要向容器公开的密文。支持的值为 AWS Secrets Manager 密钥的完整 Amazon 资源名称（ARN）或 AWS Systems Manager Parameter Store 中的参数的完整 ARN。
如果 Systems Manager Parameter Store 参数或 Secrets Manager 书与要启动的任务位于同一 AWS 区域中，则可以使用密钥的完整 ARN 或名称。如果参数存在于不同的区域，则必须指定完整的 ARN。
```
"secrets": [
{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}
]
```
#### 网络设置
`disableNetworking`
类型：布尔值
必需：否
当此参数设置为 true 时，容器内会关闭联网。
使用 `awsvpc` 网络模式的 Windows 容器或任务不支持此参数。
默认值为 `false`。
```
"disableNetworking": true|false
```
`links`
类型：字符串数组
必需：否
`link` 参数允许容器相互进行通信，而无需端口映射。只有在任务定义的网络模式被设置为 `bridge` 时才支持此参数。`name:internalName` 构造类似于 Docker 链接中的 `name:alias`。最多可使用 255 个字母（大写和小写字母）、数字、连字符和下划线。
使用 `awsvpc` 网络模式的 Windows 容器或任务不支持此参数。
在同一容器实例上并置的容器也许能够相互进行通信，而无需链接或主机端口映射。容器实例上的网络隔离由安全组和 VPC 设置控制。
```
"links": ["name:internalName", ...]
```
`hostname`
类型：字符串
必需：否
要对您的容器使用的主机名。此参数对应于 docker create-container 命令中的 `Hostname` 和 docker run 命令的 `--hostname` 选项。
如果使用 `awsvpc` 网络模式，则不支持 `hostname` 参数。
```
"hostname": "string"
```
`dnsServers`
类型：字符串数组
必需：否
提供给容器的 DNS 服务器的列表。
使用 `awsvpc` 网络模式的 Windows 容器或任务不支持此参数。
```
"dnsServers": ["string", ...]
```
`dnsSearchDomains`
类型：字符串数组
必需：否
模式：^[a-zA-Z0-9-.]\$10,253\$1[a-zA-Z0-9]\$1
提供给容器的 DNS 搜索域的列表。此参数对应于 docker create-container 命令中的 `DnsSearch` 和 docker run 命令的 `--dns-search` 选项。
使用 `awsvpc` 网络模式的 Windows 容器或任务不支持此参数。
```
"dnsSearchDomains": ["string", ...]
```
`extraHosts`
类型：对象数组
必需：否
要追加到容器上的 `/etc/hosts` 文件的主机名和 IP 地址映射的列表。
此参数对应于 docker create-container 命令中的 `ExtraHosts` 和 docker run 命令的 `--add-host` 选项。
使用 `awsvpc` 网络模式的 Windows 容器或任务不支持此参数。
```
"extraHosts": [
{
"hostname": "string",
"ipAddress": "string"
}
...
]
```
`hostname`
类型：字符串
必需：是，当使用 `extraHosts` 时
要用于 `/etc/hosts` 条目中的主机名。
`ipAddress`
类型：字符串
必需：是，当使用 `extraHosts` 时
要用于 `/etc/hosts` 条目中的 IP 地址。
#### 存储和日志记录
`readonlyRootFilesystem`
类型：布尔值
必需：否
当此参数为 true 时，将对此容器提供对其根文件系统的只读访问权。此参数对应于 docker create-container 命令中的 `ReadonlyRootfs` 和 docker run 命令的 `--read-only` 选项。
Windows 容器不支持此参数。
默认值为 `false`。
```
"readonlyRootFilesystem": true|false
```
`mountPoints`
类型：对象数组
必需：否
容器中数据卷的挂载点。此参数对应于 create-container Docker API 中的 `Volumes` 和 docker run 命令的 `--volume` 选项。
Windows 容器可在 `$env:ProgramData` 所在的驱动器上挂载整个目录。Windows 容器无法在其他驱动器上挂载目录，并且挂载点不能跨驱动器使用。您必须指定挂载点才能将 Amazon EBS 卷直接附加到 Amazon ECS 任务。
`sourceVolume`
类型：字符串
必需：是，当使用 `mountPoints` 时
要挂载的卷的名称。
`containerPath`
类型：字符串
必需：是，当使用 `mountPoints` 时
挂载卷的容器中的路径。
`readOnly`
类型：布尔值
必需：否
如果此值为`true`，则容器具有对卷的只读访问权。如果此值为`false`，则容器可对卷进行写入。默认值为 `false`。
对于运行 Windows 操作系统的任务，请保留默认值 `false`。
`volumesFrom`
类型：对象数组
必需：否
要从其他容器挂载的数据卷。此参数对应于 docker create-container 命令中的 `VolumesFrom` 和 docker run 命令的 `--volumes-from` 选项。
`sourceContainer`
类型：字符串
必需：是，当使用 `volumesFrom` 时
要从其中挂载卷的容器的名称。
`readOnly`
类型：布尔值
必需：否
如果此值为`true`，则容器具有对卷的只读访问权。如果此值为`false`，则容器可对卷进行写入。默认值为 `false`。
```
"volumesFrom": [
{
"sourceContainer": "string",
"readOnly": true|false
}
]
```
`logConfiguration`
类型：[LogConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html) 对象
必需：否
容器的日志配置规范。
有关使用日志配置的示例任务定义，请参阅[Amazon ECS 任务定义示例](example_task_definitions.md)。
此参数对应于 docker create-container 命令中的 `LogConfig` 和 docker run 命令的 `--log-driver` 选项。默认情况下，容器使用与 Docker 进程守护程序相同的日志记录驱动程序。但容器可能通过在容器定义中使用此参数指定日志驱动程序，以此来使用不同于 Docker 进程守护程序的日志记录驱动程序。要对容器使用不同的日志记录驱动程序，必须在容器实例上正确配置日志系统（或者在不同的日志服务器上使用远程日志记录选项）。
指定容器的日志配置时，考虑以下事项：
+ Amazon ECS 支持提供给 Docker 进程守护程序的一小部分日志记录驱动程序。
+ 此参数要求您容器实例上的 Docker Remote API 版本为 1.18 或更高版本。
+ 在容器实例上运行的 Amazon ECS 容器代理必须先将该实例上的可用日志记录驱动程序注册到 `ECS_AVAILABLE_LOGGING_DRIVERS` 环境变量，然后该实例上的容器才能使用这些日志配置选项。有关更多信息，请参阅 [Amazon ECS 容器代理配置](ecs-agent-config.md)。
```
"logConfiguration": {
"logDriver": "awslogs","fluentd","gelf","json-file","journald","splunk","syslog","awsfirelens",
"options": {"string": "string"
...},
"secretOptions": [{
"name": "string",
"valueFrom": "string"
}]
}
```
`logDriver`
类型：字符串
有效值：`"awslogs","fluentd","gelf","json-file","journald","splunk","syslog","awsfirelens"`
必需：是，当使用 `logConfiguration` 时
要用于容器的日志驱动程序。默认情况下，前面列出的有效值是一些日志驱动程序，Amazon ECS 容器代理可以与它们进行通信。
支持的日志驱动程序为`awslogs`、`fluentd`、`gelf`、`json-file`、`journald`、`syslog`、`splunk`和`awsfirelens`。
有关在任务定义中如何使用 `awslogs` 日志驱动程序以将容器日志发送到 CloudWatch Logs 的更多信息，请参阅[将 Amazon ECS 日志发送到 CloudWatch](using_awslogs.md)。
有关使用 `awsfirelens` 日志驱动程序的更多信息，请参阅[自定义日志路由](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/using_firelens.html)。
如果具有未列出的自定义驱动程序，您可以复制 [GitHub 上提供的](https://github.com/aws/amazon-ecs-agent) Amazon ECS 容器代理项目，并对其进行自定义以与该驱动程序一起使用。我们鼓励您针对要包含的更改提交拉取请求。但是，当前不支持运行此软件的修改后副本。
此参数要求容器实例上的 Docker Remote API 版本为 1.18 或更高版本。
`options`
类型：字符串到字符串映射
必需：否
要发送到日志驱动程序的配置选项的键/值映射。
您可以指定的选项取决于日志驱动程序。使用 `awslogs` 路由器将日志路由到 Amazon CloudWatch 时可以指定的一些选项包括：
`awslogs-create-group`
必需：否
指定您是否希望自动创建日志组。如果未指定此选项，则默认为 `false`。
您的 IAM 策略必须包含 `logs:CreateLogGroup` 权限，然后才能尝试使用 `awslogs-create-group`。
`awslogs-region`
是否必需：是
指定 `awslogs` 日志驱动程序要将 Docker 日志发送到的 AWS 区域。您可选择将位于不同区域的集群中的所有日志发送到 CloudWatch Logs 中的单个区域。这是为了使它们都在一个位置可见。否则，您可以按区域对它们进行分隔以获得更高粒度。确保指定的日志组存在于您使用此选项指定的区域中。
`awslogs-group`
是否必需：是
确保指定 `awslogs` 日志驱动程序将其日志流发送到的日志组。
`awslogs-stream-prefix`
必需：可选
利用 `awslogs-stream-prefix` 选项，可将日志流与指定的前缀、容器名称和容器所属的 Amazon ECS 任务的 ID 关联在一起。如果您使用此选项指定前缀，则日志流将采用以下格式。
```
prefix-name/container-name/ecs-task-id
```
如果您未使用此选项指定前缀，则日志流将以 Docker 进程守护程序在容器实例上分配的容器 ID 命名。由于仅使用 Docker 容器 ID（仅在容器实例上可用）很难将日志回溯到发送它们的容器，因此，我们建议您使用此选项指定前缀。
对于 Amazon ECS 服务，您可以使用服务名称作为前缀。这样，您可以将日志流跟踪到容器所属的服务、发送它们的容器的名称以及容器所属的任务的 ID。
您必须为日志指定流前缀，才能在使用 Amazon ECS 控制台时在日志窗格中显示日志。
`awslogs-datetime-format`
必需：否
此选项以 Python `strftime` 格式定义多行开始位置模式。日志消息由与模式匹配的行以及与模式不匹配的任何以下行组成。匹配行是日志消息之间的分隔符。
使用此格式的一个使用案例示例是用于解析输出（如堆栈转储），这可能记录在多个条目中。正确模式允许它捕获在单个条目中。
有关更多信息，请参阅 [awslogs-datetime-format](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-datetime-format)。
您无法同时配置 `awslogs-datetime-format` 和 `awslogs-multiline-pattern` 选项。
多行日志记录对所有日志消息执行正则表达式解析和匹配。这可能会对日志记录性能产生负面影响。
`awslogs-multiline-pattern`
必需：否
此选项使用正则表达式定义多行开始位置模式。日志消息由与模式匹配的行以及与模式不匹配的任何以下行组成。匹配行是日志消息之间的分隔符。
有关更多信息，请参阅 [awslogs-multiline-pattern](https://docs.docker.com/engine/logging/drivers/awslogs/#awslogs-multiline-pattern)。
如果还配置了`awslogs-datetime-format`，则会忽略此选项。
您无法同时配置 `awslogs-datetime-format` 和 `awslogs-multiline-pattern` 选项。
多行日志记录对所有日志消息执行正则表达式解析和匹配。这可能会对日志记录性能产生负面影响。
以下选项适用于所有支持的日志驱动程序。
`mode`
必需：否
有效值：`non-blocking` \$1 `blocking`
此选项用于定义从容器到使用 `logDriver` 指定的日志驱动程序的日志消息交付模式。当来自容器的日志流中断时，您选择的交付模式会影响应用程序的可用性。
如果使用 `blocking` 模式并且日志流发生中断，则容器代码中写入 `stdout` 和 `stderr` 流的调用将被阻止。因此，应用程序的日志线程将阻塞。这可能会导致应用程序失去响应并导致容器运行状况检查失败。
如果您使用 `non-blocking` 模式，则容器的日志将存储在配置了 `max-buffer-size` 选项的内存中中间缓冲区。这样可以防止应用程序在无法发送日志时失去响应。如果您想确保服务可用性并且可以接受一些日志丢失，建议您使用此模式。有关更多信息，请参阅[在 `awslogs` 容器日志驱动程序中使用非阻塞模式防止日志丢失](https://aws.amazon.com/blogs/containers/preventing-log-loss-with-non-blocking-mode-in-the-awslogs-container-log-driver/)。
您可以使用 `defaultLogDriverMode` 账户设置，为特定 AWS 区域中的所有容器设置默认 `mode`。如果未在 `logConfiguration` 中指定 `mode` 选项，也未配置账户设置，则 Amazon ECS 将默认使用 `non-blocking` 模式。有关账户设置的更多信息，请参阅 [默认日志驱动程序模式](ecs-account-settings.md#default-log-driver-mode)。
使用 `non-blocking` 模式时，`max-buffer-size` 日志选项控制用于中间消息存储的缓冲区的大小。确保根据您的应用程序指定足够的缓冲区大小。除了日志驱动程序的内存缓冲区外，在任务级别分配的内存总量必须大于为所有容器分配的内存量。
2025 年 6 月 25 日，Amazon ECS 的默认日志驱动程序模式从 `blocking` 更改为 `non-blocking`，以优先考虑任务可用性而不是日志记录。要在此更改后继续使用 `blocking` 模式，请执行以下操作之一：
+ 将容器定义 `logConfiguration` 中的 `mode` 选项设置为 `blocking`。
+ 将 `defaultLogDriverMode` 账户设置设置为 `blocking`。
`max-buffer-size`
必需：否
默认值：`10 m`
使用 `non-blocking` 模式时，`max-buffer-size` 日志选项控制用于中间消息存储的缓冲区的大小。确保根据您的应用程序指定足够的缓冲区大小。当缓冲区已满时，将无法存储更多日志。无法存储的日志会丢失。
要使用 `splunk` 日志路由器路由日志，需要指定 `splunk-token` 和 `splunk-url`。
当使用 `awsfirelens` 日志路由器将日志路由到 AWS Partner Network 或 AWS 服务 目的地以进行日志存储和分析时，可以将 `log-driver-buffer-limit` 选项设置为限制内存中缓冲的日志行数量，然后再发送到日志路由器容器。它可以帮助解决潜在的日志丢失问题，因为高吞吐量可能会导致 Docker 内部缓冲区的内存耗尽。有关更多信息，请参阅 [配置 Amazon ECS 日志，以实现高吞吐量](firelens-docker-buffer-limit.md)。
使用 `awsfirelens` 路由日志时可以指定的其他选项取决于目的地。将日志导出到 Amazon Data Firehose 时，可以使用 `region` 指定 AWS 区域，并使用 `delivery_stream` 指定日志流的名称。
将日志导出到 Amazon Kinesis Data Streams 时，可以使用 `region` 指定 AWS 区域，并使用 `stream` 指定数据流名称。
将日志导出到 Amazon OpenSearch Service 时，可以指定 `Name`、`Host`（没有协议的 OpenSearch Service 端点）、`Port`、`Index`、`Type`、`Aws_auth`、`Aws_region`、`Suppress_Type_Name` 和 `tls` 等选项。
将日志导出到 Amazon S3 时，可以使用 `bucket` 选项指定存储桶。您还可以指定 `region`、`total_file_size`、`upload_timeout` 和 `use_put_object` 选项。
此参数要求容器实例上的 Docker Remote API 版本为 1.19 或更高版本。
`secretOptions`
类型：对象数组
必需：否
表示要传递到日志配置的密文的对象。日志配置中使用的密钥可能包括身份验证令牌、证书或加密密钥。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
`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](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FirelensConfiguration.html) 对象
必需：否
容器的 FireLens 配置。这用于为容器日志指定和配置日志路由器。有关更多信息，请参阅 [将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner](using_firelens.md)。
```
{
"firelensConfiguration": {
"type": "fluentd",
"options": {
"KeyName": ""
}
}
}
```
`options`
类型：字符串到字符串映射
必需：否
在配置日志路由器时使用的选项的键/值映射。此字段是可选的，可用于指定自定义配置文件或向日志事件添加其他元数据，如任务、任务定义、集群和容器实例详细信息。如果指定，则使用的语法为 `"options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf|filepath"}`。有关更多信息，请参阅 [Amazon ECS 任务定义示例：将日志路由到 FireLens](firelens-taskdef.md)。
`type`
类型：字符串
是否必需：是
要使用的日志路由器。有效值为 `fluentd` 或 `fluentbit`。
#### 安全性
有关容器安全的更多信息，请参阅 [Amazon ECS 任务和容器安全性最佳实践](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/security-tasks-containers.html)。
`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 容器](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/windows-gmsa.html)和[将 gMSA 用于 Linux 容器](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/linux-gmsa.html)。
`privileged`
类型：布尔值
必需：否
当该参数为 true 时，将对此容器提供对主机容器实例的提升的特权（类似于 `root` 用户）。我们建议不要使用 `privileged` 运行容器。在大多数情况下，您可以使用特定参数来指定所需的确切权限，而不是使用 `privileged`。
此参数对应于 docker create-container 命令中的 `Privileged` 和 docker run 命令的 `--privileged` 选项。
使用 Fargate 启动类型的 Windows 容器或任务不支持此参数。
默认值为 `false`。
```
"privileged": true|false
```
`user`
类型：字符串
必需：否
要在容器内使用的用户。此参数对应于 docker create-container 命令中的 `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" \$1 "apparmor:PROFILE" \$1 "label:*value*" \$1 "credentialspec:*CredentialSpecFilePath*"
必需：否
用于为多个安全系统提供自定义配置的字符串列表。
对于 Linux 任务，此参数可用于引用 SELinux 和 AppArmor 多级安全系统的自定义标签。
此参数可用于在为 Active Directory 身份验证配置容器时引用凭证规范文件。有关更多信息，请参阅[了解了解如何将 gMSA 用于适用于 Amazon ECS 的 EC2 Windows 容器](windows-gmsa.md)和[将 gMSA 用于 Amazon ECS 上的 EC2 Linux 容器](linux-gmsa.md)。
此参数对应于 docker create-container 命令中的 `SecurityOpt` 和 docker run 命令的 `--security-opt` 选项。
```
"dockerSecurityOptions": ["string", ...]
```
在容器实例上运行的 Amazon ECS 容器代理必须先注册到 `ECS_SELINUX_CAPABLE=true` 或 `ECS_APPARMOR_CAPABLE=true` 环境变量，然后该实例上的容器才能使用这些安全选项。有关更多信息，请参阅 [Amazon ECS 容器代理配置](ecs-agent-config.md)。
#### 资源限制
`ulimits`
类型：对象数组
必需：否
列表 `ulimit` 值为容器定义。此值将覆盖操作系统的默认资源配额设置。此参数对应于 docker create-container 命令中的 `Ulimits` 和 docker run 命令的 `--ulimit` 选项。
此参数要求容器实例上的 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` 时
`ulimit`的`type`。
`hardLimit`
类型：整数
必需：是，当使用 `ulimits` 时
`ulimit`类型的硬限制。该值可以用字节、秒或计数为单位指定，具体取决于 `ulimit` 的 `type`。
`softLimit`
类型：整数
必需：是，当使用 `ulimits` 时
`ulimit`类型的软限制。该值可以用字节、秒或计数为单位指定，具体取决于 `ulimit` 的 `type`。
#### Docker 标签
`dockerLabels`
类型：字符串到字符串映射
必需：否
要添加到容器的标签的键值映射。此参数对应于 docker create-container 命令中的 `Labels` 和 docker run 命令的 `--label` 选项。
此参数要求容器实例上的 Docker Remote API 版本为 1.18 或更高版本。
```
"dockerLabels": {"string": "string"
...}
```
### 其他容器定义参数
以下容器定义参数可在 Amazon ECS 控制台中注册任务定义时使用，方法是使用 **Configure via JSON**（通过 JSON 配置）选项。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
**Topics**
+ [Linux 参数](#container_definition_linuxparameters_ec2)
+ [容器依赖项](#container_definition_dependson_ec2)
+ [容器超时](#container_definition_timeout_ec2)
+ [系统控制](#container_definition_systemcontrols_ec2)
+ [交互式](#container_definition_interactive_ec2)
+ [伪终端](#container_definition_pseudoterminal_ec2)
#### Linux 参数
`linuxParameters`
类型：[LinuxParameters](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LinuxParameters.html) 对象
必需：否
应用于容器的特定于 Linux 的选项，如 [KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html)。
Windows 容器不支持此参数。
```
"linuxParameters": {
"capabilities": {
"add": ["string", ...],
"drop": ["string", ...]
}
}
```
`capabilities`
类型：[KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities_ec2.html) 对象
必需：否
容器的 Linux 功能，这些功能已在 Docker 提供的默认配置中添加或删除。有关这些 Linux 功能的更多信息，请参阅 [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) 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 create-container 命令中的 `CapAdd` 和 docker run 命令的 `--cap-add` 选项。
`add`
类型：字符串数组
有效值：`"SYS_PTRACE"`
必需：否
容器的 Linux 功能，这些功能将添加到 Docker 提供的默认配置。此参数对应于 docker create-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 create-container 命令中的 `CapDrop` 和 docker run 命令的 `--cap-drop` 选项。
`devices`
对容器公开的任何主机设备。此参数对应于 docker create-container 命令中的 `Devices` 和 docker run 命令的 `--device` 选项。
类型：[设备](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Device.html)对象数组
必需：否
`hostPath`
主机容器实例上的设备路径。
类型：字符串
是否必需：是
`containerPath`
要将主机设备公开到的容器中的路径。
类型：字符串
必需：否
`permissions`
提供给设备的容器的显式权限。默认情况下，容器对设备上的 `read`、`write` 和 `mknod` 具有权限。
类型：字符串数组
有效值：`read` \$1 `write` \$1 `mknod`
`initProcessEnabled`
在容器内运行 `init` 进程，转发信号和获得进程。此参数对应于 docker run 命令的 `--init` 选项。
此参数要求容器实例上的 Docker Remote API 版本为 1.25 或更高版本。
`maxSwap`
容器可以使用的交换内存总量（以 MiB 为单位）。此参数会转换为 docker run 命令的 `--memory-swap` 选项，值为容器内存与 `maxSwap` 值之和。
如果指定`maxSwap`值为`0`，则该容器不使用交换。接受的值为`0`或任何正整数。如果省略 `maxSwap` 参数，该容器将为其运行所在的容器实例使用交换配置。必须为要使用的`swappiness`参数设置`maxSwap`值。
`sharedMemorySize`
`/dev/shm` 卷的大小值（以 MiB 为单位）。此参数对应于 docker run 命令的 `--shm-size` 选项。
类型：整数
`swappiness`
您可以使用此参数调整容器的内存 swappiness 行为。`swappiness` 的值 `0` 防止交换发生，除非有要求。`swappiness` 的值 `100` 导致页面被频繁交换。接受的值为`0`到`100`之间的整数。如果您未指定值，则将使用默认值 `60`。此外，如果未指定 `maxSwap` 的值，则此参数将被忽略。此参数对应于 docker run 命令的 `--memory-swappiness` 选项。
如果您在 Amazon Linux 2023 上使用任务，则不支持 `swappiness` 参数。
`tmpfs`
tmpfs 挂载的容器路径、挂载选项和最大大小（以 MiB 为单位）。此参数对应于 docker run 命令的 `--tmpfs` 选项。
类型：[Tmpfs](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Tmpfs.html) 对象数组
必需：否
`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](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html) 对象的数组
必需：否
针对容器启动和关闭定义的依赖项。一个容器可以包含多个依赖项。当针对容器启动定义依赖项时，对于容器关闭，将反转此项。有关示例，请参阅[容器依赖项](example_task_definitions.md#example_task_definition-containerdependency)。
如果容器不满足依赖性约束或在满足约束之前超时，Amazon ECS 不会将依赖性容器推进到其下一个状态。
实例需要至少 `1.26.0` 版的容器代理才能启用容器依赖项。但是，我们建议使用最新的容器代理版本。有关检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。如果您正在使用 Amazon ECS 优化型 Amazon Linux AMI，您的实例将需要不低于 `1.26.0-1` 版本的 `ecs-init` 程序包。如果您的容器实例是从版本 `20190301` 或更高版本启动的，那么这些实例将包含所需版本的容器代理和 `ecs-init`。有关更多信息，请参阅 [经 Amazon ECS 优化的 Linux AMI](ecs-optimized_AMI.md)。
```
"dependsOn": [
{
"containerName": "string",
"condition": "string"
}
]
```
`containerName`
类型：字符串
是否必需：是
必须符合指定条件的容器名称。
`condition`
类型：字符串
是否必需：是
容器的依赖项条件。以下是可用的条件及其行为：
+ `START`：此条件将立即模拟链接和卷的行为。此条件将验证从属容器是否是在允许其他容器启动前启动的。
+ `COMPLETE`：此条件将验证从属容器是否在允许其他容器启动前运行完成（退出）。这对于运行脚本然后退出的非主要容器非常有用。无法在基本容器上设置此条件。
+ `SUCCESS`：此条件与 `COMPLETE` 相同，但它还要求容器退出并具有 `zero` 状态。无法在基本容器上设置此条件。
+ `HEALTHY`：此条件将验证从属容器是否在允许其他容器启动前传递其容器运行状况检查。这要求从属容器已在任务定义中配置运行状况检查。仅在任务启动时确认此条件。
#### 容器超时
`startTimeout`
类型：整数
必需：否
示例值：`120`
在放弃解析容器的依赖项之前要等待的持续时间（以秒为单位）。
例如，在任务定义中指定两个容器，`containerA` 需要依赖 `containerB` 达到 `COMPLETE`、`SUCCESS` 或 `HEALTHY` 状态。如果为 `containerB` 指定了一个 `startTimeout` 值并且它未在该时间内达到所需状态，则 `containerA` 将不会启动。
如果容器不满足依赖性约束或在满足约束之前超时，Amazon ECS 不会将依赖性容器推进到其下一个状态。
最大值为 120 秒。
`stopTimeout`
类型：整数
必需：否
示例值：`120`
容器由于未自行正常退出而被强制终止前要等待的持续时间（以秒为单位）。
如果未指定 `stopTimeout` 参数，则使用为 Amazon ECS 容器代理配置变量 `ECS_CONTAINER_STOP_TIMEOUT` 设置的值。如果既没有设置 `stopTimeout` 参数，也没有设置 `ECS_CONTAINER_STOP_TIMEOUT` 代理配置变量，那么，对于 Linux 容器，使用默认值 30 秒；对于 Windows 容器，使用默认值 30 秒。容器实例需要至少 1.26.0 版的容器代理才能启用容器停止超时值。但是，我们建议使用最新的容器代理版本。有关如何检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。如果您正在使用经 Amazon ECS 优化的 Amazon Linux AMI，您的实例将需要不低于 1.26.0-1 版本的 `ecs-init` 程序包。如果您的容器实例是从版本 `20190301` 或更高版本启动的，那么这些实例将包含所需版本的容器代理和 `ecs-init`。有关更多信息，请参阅 [经 Amazon ECS 优化的 Linux AMI](ecs-optimized_AMI.md)。
#### 系统控制
`systemControls`
类型：[SystemControl](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_SystemControl.html) 对象
必需：否
要在容器中设置的命名空间内核参数的列表。此参数对应于 docker create-container 命令中的 `Sysctls` 和 docker run 命令的 `--sysctl` 选项。例如，您可以配置 `net.ipv4.tcp_keepalive_time` 设置以保持更长期的连接。
不建议在使用了 `awsvpc` 或 `host` 网络模式的单个任务中为多个容器指定与网络相关的 `systemControls` 参数。执行此操作具有以下缺点：
+ 对于使用 `awsvpc` 网络模式的任务，如果为任何容器设置了 `systemControls`，则它将应用于该任务中的所有容器。如果您为单个任务中的多个容器设置了不同的 `systemControls`，最后启动的容器将确定哪个 `systemControls` 生效。
+ 对于使用 `host` 网络模式的任务，不支持网络命名空间 `systemControls`。
如果您要设置 IPC 资源命名空间以用于任务中的容器，则以下条件将适用于您的系统控制。有关更多信息，请参阅 [IPC 模式](task_definition_parameters.md#task_definition_ipcmode)。
+ 对于使用 `host` IPC 模式的任务，不支持 IPC 命名空间 `systemControls`。
+ 对于使用 `task` IPC 模式的任务，IPC 命名空间 `systemControls` 值适用于任务中的所有容器。
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` 时，您可以部署需要分配 `stdin` 或 `tty` 的容器化应用程序。此参数对应于 docker create-container 命令中的 `OpenStdin` 和 docker run 命令的 `--interactive` 选项。
默认值为 `false`。
#### 伪终端
`pseudoTerminal`
类型：布尔值
必需：否
当此参数为 `true` 时，则分配 TTY。此参数对应于 docker create-container 命令中的 `Tty` 和 docker run 命令的 `--tty` 选项。
默认值为 `false`。
## Elastic Inference 加速器名称（已弃用）
您的任务定义的 Elastic Inference 加速器资源要求。
**注意**
Amazon Elastic Inference（EI）功能不再向客户开放。
任务定义中允许以下参数：
`deviceName`
类型：字符串
是否必需：是
Elastic Inference 加速器设备名称。还必须在容器定义中引用 `deviceName`，请参阅 [Elastic Inference accelerator](task_definition_parameters.md#ContainerDefinition-elastic-inference)。
`deviceType`
类型：字符串
是否必需：是
要使用的 Elastic Inference 加速器。
## 任务放置约束
您在注册任务定义时，可以提供任务放置约束，自定义 Amazon ECS 如何放置任务。
您可以使用约束来根据可用区、实例类型或自定义属性来放置任务。有关更多信息，请参阅 [定义 Amazon ECS 将哪些容器实例用于任务](task-placement-constraints.md)。
容器定义中允许以下参数：
`expression`
类型：字符串
必需：否
应用于约束的集群查询语言表达式。有关更多信息，请参阅 [创建表达式，以为 Amazon ECS 任务定义容器实例](cluster-query-language.md)。
`type`
类型：字符串
是否必需：是
约束类型。使用 `memberOf` 将选择限制为一组有效的候选。
## 代理配置
`proxyConfiguration`
类型：[ProxyConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ProxyConfiguration.html) 对象
必需：否
App Mesh 代理的配置详细信息。
对于使用 EC2 的任务，容器实例需要至少 1.26.0 版的容器代理和至少 1.26.0-1 版的 `ecs-init` 包才能启用代理配置。如果您的容器实例是从经 Amazon ECS 优化的 AMI 版本 `20190301` 或更高版本启动的，则这些实例将包含所需版本的容器代理和 `ecs-init`。有关更多信息，请参阅 [经 Amazon ECS 优化的 Linux AMI](ecs-optimized_AMI.md)。
Windows 容器不支持此参数。
```
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "string",
"properties": [
{
"name": "string",
"value": "string"
}
]
}
```
`type`
类型：字符串
有效值：`APPMESH`
必需：否
代理类型。`APPMESH` 是唯一受支持的值。
`containerName`
类型：字符串
是否必需：是
将作为 App Mesh 代理的容器的名称。
`properties`
类型：[KeyValuePair](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KeyValuePair.html) 对象的数组
必需：否
提供容器网络接口（CNI）插件的网络配置参数集，以键值对形式指定。
+ `IgnoredUID`：（必填）代理容器的用户 ID（UID），由容器定义中的 `user` 参数定义。此字段用于确保代理会忽略自己的流量。如果指定了 `IgnoredGID`，此字段可为空。
+ `IgnoredGID`：（必填）代理容器的组 ID（GID），由容器定义中的 `user` 参数定义。此字段用于确保代理会忽略自己的流量。如果指定了 `IgnoredUID`，此字段可为空。
+ `AppPorts` -（必填）应用程序使用的端口的列表。发送到这些端口的网络流量将转发到 `ProxyIngressPort` 和 `ProxyEgressPort`。
+ `ProxyIngressPort` -（必填）指定传入到 `AppPorts` 的流量将定向到的端口。
+ `ProxyEgressPort` -（必填）指定从 `AppPorts` 传出的流量将定向到的端口。
+ `EgressIgnoredPorts` –（必填）进入这些指定端口的出站流量将被忽略但不会重定向到 `ProxyEgressPort`。它可以是空列表。
+ `EgressIgnoredIPs` –（必填）进入这些指定 IP 地址的出站流量将被忽略但不会重定向到 `ProxyEgressPort`。它可以是空列表。
`name`
类型：字符串
必需：否
键值对的名称。
`value`
类型：字符串
必需：否
键值对的值。
## 卷
当您注册任务定义时，可以选择指定一个卷列表，这些卷将传递到容器实例上的 Docker 进程守护程序，然后它们将变得可供同一容器实例上的其他容器访问。
下面是可使用的数据卷的类型：
+ Amazon EBS 卷 – 为数据密集型容器化工作负载提供经济实惠、持久、高性能的块存储。在运行独立任务，或者创建或更新服务时，您可以为每个 Amazon ECS 任务附加 1 个 Amazon EBS 卷。Linux 任务支持 Amazon EBS 卷。有关更多信息，请参阅 [将 Amazon EBS 卷与 Amazon ECS 结合使用](ebs-volumes.md)。
+ Amazon EFS 卷——提供简单的可扩展和持久的文件存储以供您的 Amazon ECS 任务使用。使用 Amazon EFS 时，存储容量是弹性的。它会随着您添加和删除文件而自动增加和缩减。您的应用程序可以在需要时获得所需存储。支持 Amazon EFS 卷。有关更多信息，请参阅 [将 Amazon EFS 卷与 Amazon ECS 结合使用](efs-volumes.md)。
+ 适用于 Windows File Server 的 FSx 卷 — 提供完全托管的 Microsoft Windows 文件服务器。这些文件服务器由 Windows 文件系统提供支持。使用适用于 Windows File Server 的 FSx 和 Amazon ECS 时，您可以使用永久、分布式、共享的静态文件存储来配置 Windows 任务。有关更多信息，请参阅 [将适用于 Windows File Server 的 FSx 卷与 Amazon ECS 结合使用](wfsx-volumes.md)。
Fargate 上的 Windows 容器不支持此选项。
+ Docker 卷 – 在主机 Amazon EC2 实例上的 `/var/lib/docker/volumes` 下创建的 Docker 托管卷。Docker 卷驱动程序（也称为插件）用于将卷与外部存储系统（如 Amazon EBS）集成。可使用内置 `local` 卷驱动程序或第三方卷驱动程序。只有在 Amazon EC2 实例上运行任务时，才支持 Docker 卷。Windows 容器仅支持使用 `local` 驱动程序。要使用 Docker 卷，请在任务定义中指定 `dockerVolumeConfiguration`。
+ 绑定挂载 – 挂载到容器中的主机上的文件或目录。支持绑定挂载主机卷。要使用绑定挂载主机卷，请在任务定义中指定 `host` 和可选的 `sourcePath` 值。
有关更多信息，请参阅 [Amazon ECS 任务的存储选项](using_data_volumes.md)。
容器定义中允许以下参数。
`name`
类型：字符串
必需：否
卷的名称。最多允许 255 个字母（大写和小写字母）、数字、连字符（`-`）和下划线（`_`）。此名称已在容器定义 `mountPoints` 对象的 `sourceVolume` 参数中引用。
`host`
必需：否
`host` 参数用于将绑定挂载的生命周期绑定到主机 Amazon EC2 实例（而不是任务）及其存储位置。如果 `host` 参数为空，则 Docker 进程守护程序将为您的数据卷分配一个主机路径，但不保证数据在与其关联的容器停止运行后将保留。
Windows 容器可在 `$env:ProgramData` 所在的驱动器上挂载整个目录。
只有在使用 Amazon EC2 实例或 Amazon ECS 托管实例上托管的任务时，才支持 `sourcePath` 参数。
`sourcePath`
类型：字符串
必需：否
在使用 `host` 参数时，指定 `sourcePath` 可声明提供给容器的主机 Amazon EC2 容器实例上的路径。如果此参数为空，则 Docker 进程守护程序将为您分配一个主机路径。如果 `host` 参数包含 `sourcePath` 文件位置，则数据卷将在主机 Amazon EC2 容器实例上的指定位置保留，除非您手动将其删除。如果主机 Amazon EC2 容器实例上不存在 `sourcePath` 值，则 Docker 进程守护程序将创建该值。如果该位置不存在，则将导出源路径文件夹的内容。
`configuredAtLaunch`
类型：布尔值
必需：否
指定卷在启动时是否可配置。如果设置为 `true`，则可以在运行独立任务或者创建或更新服务时配置卷。如果设置为 `true`，则无法在任务定义中提供其他卷配置。必须将此参数设置为 `true` 才能将 Amazon EBS 卷配置为附加到一个任务中。将 `configuredAtLaunch` 设置为 `true` 并将卷配置延迟到启动阶段使您可以创建不受卷类型或特定卷设置限制的任务定义。这样做可以让您的任务定义在不同的执行环境中重复使用。有关更多信息，请参阅 [Amazon EBS 卷](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ebs-volumes.html)。
`dockerVolumeConfiguration`
类型：[DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) 对象
必需：否
使用 Docker 卷时将指定此参数。只有在 EC2 实例上运行任务时，才支持 Docker 卷。Windows 容器仅支持使用 `local` 驱动程序。要使用绑定挂载，请改为指定 `host`。
`scope`
类型：字符串
有效值：`task` \$1 `shared`
必需：否
Docker 卷的范围，可确定其生命周期。当任务开始时，将自动预配置范围限定为 `task` 的 Docker 卷；而当任务停止时销毁此卷。任务停止后，范围限定为 `shared` 的 Docker 卷将持续存在。
`autoprovision`
类型：布尔值
默认值：`false`
必需：否
如果此值为 `true`，则将创建 Docker 卷（如果此卷不存在）。仅在 `scope` 为 `shared` 时使用此字段。如果 `scope` 为 `task`，则必须省略此参数。
`driver`
类型：字符串
必需：否
要使用的 Docker 卷驱动程序。由于驱动程序值用于任务放置，因此，该名称必须与 Docker 提供的驱动程序名称匹配。如果已使用 Docker 插件 CLI 创建驱动程序，则使用 `docker plugin ls` 可从容器实例中检索驱动程序名称。如果已使用其他方法安装驱动程序，则使用 Docker 插件发现功能可检索驱动程序名称。
`driverOpts`
类型：字符串
必需：否
要传递的 Docker 驱动程序特定的选项的映射。此参数将映射到 Docker 中“创建卷”部分中的 `DriverOpts`。
`labels`
类型：字符串
必需：否
要添加到 Docker 卷的自定义元数据。
`efsVolumeConfiguration`
类型：[EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 对象
必需：否
使用 Amazon EFS 卷时将指定此参数。
`fileSystemId`
类型：字符串
是否必需：是
要使用的 Amazon EFS 文件系统 ID。
`rootDirectory`
类型：字符串
必需：否
Amazon EFS 文件系统中要作为主机内的根目录挂载的目录。如果忽略此参数，将使用 Amazon EFS 卷的根目录。指定 `/` 与忽略此参数效果相同。
如果在 `authorizationConfig` 中指定了 EFS 接入点，则必须省略根目录值，或者将其设置为 `/`，以便在 EFS 接入点上强制执行设置的路径。
`transitEncryption`
类型：字符串
有效值：`ENABLED` \$1 `DISABLED`
必需：否
指定是否对 Amazon ECS 主机和 Amazon EFS 服务器之间的 Amazon EFS 传输中数据启用加密。如果使用 Amazon EFS IAM 授权，则必须启用传输加密。如果忽略此参数，将使用默认值`DISABLED`。有关更多信息，请参阅*《Amazon Elastic File System 用户指南》*中的[加密传输中数据](https://docs.aws.amazon.com/efs/latest/ug/encryption-in-transit.html)。
`transitEncryptionPort`
类型：整数
必需：否
在 Amazon ECS 主机和 Amazon EFS 服务器之间发送加密数据时要使用的端口。如果未指定传输加密端口，任务将使用 Amazon EFS 挂载帮助程序使用的端口选择策略。有关更多信息，请参阅[《Amazon Elastic File System 用户指南》](https://docs.aws.amazon.com/efs/latest/ug/efs-mount-helper.html)中的 *EFS 挂载帮助程序*。
`authorizationConfig`
类型：[EFSAuthorizationConfig](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSAuthorizationConfig.html) 对象
必需：否
Amazon EFS 文件系统的授权配置详细信息。
`accessPointId`
类型：字符串
必需：否
要使用的接入点 ID。如果指定了接入点，则必须省略 `efsVolumeConfiguration` 中的根目录值，或者将其设置为 `/`，以便在 EFS 接入点上强制执行设置的路径。如果使用接入点，则必须在`EFSVolumeConfiguration`中启用传输加密。有关更多信息，请参阅《Amazon Elastic File System 用户指南》**中的[使用 Amazon EFS 接入点工作](https://docs.aws.amazon.com/efs/latest/ug/efs-access-points.html)。
`iam`
类型：字符串
有效值：`ENABLED` \$1 `DISABLED`
必需：否
指定在挂载 Amazon EFS 文件系统时是否使用在任务定义中定义的 Amazon ECS 任务 IAM 角色。如果启用，则必须在`EFSVolumeConfiguration`中启用传输加密。如果忽略此参数，将使用默认值`DISABLED`。有关更多信息，请参阅[适用于任务的 IAM 角色](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html)。
`FSxWindowsFileServerVolumeConfiguration`
类型：[FSxWindowsFileServerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FSxWindowsFileServerVolumeConfiguration.html) 对象
是否必需：是
当您使用[适用于 Windows File Server 的 Amazon FSx](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 文件系统进行任务存储时，指定此参数。
`fileSystemId`
类型：字符串
是否必需：是
要使用的适用于 Windows File Server 的 FSx 文件系统 ID。
`rootDirectory`
类型：字符串
是否必需：是
适用于 Windows File Server 的 FSx 文件系统中要作为主机内的根目录挂载的目录。
`authorizationConfig`
`credentialsParameter`
类型：字符串
是否必需：是
授权凭证选项。
**选项**
+ [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 密钥的 Amazon 资源名称（ARN）。
+ [AWS Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) 参数的 ARN。
`domain`
类型：字符串
是否必需：是
由 [AWS Directory Service for Microsoft Active Directory](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/directory_microsoft_ad.html)（AWS Managed Microsoft AD）目录托管的完全限定域名或自托管 EC2 Active Directory。
## 标签
在注册任务定义时，可以选择指定应用于任务定义的元数据标签。标签可帮助您对任务定义进行分类和组织。每个标签都由一个键和一个可选值组成。您可以同时定义它们。有关更多信息，请参阅 [为 Amazon ECS 资源添加标签](ecs-using-tags.md)。
**重要**
请勿在标签中添加个人身份信息或其他机密或敏感信息。标签可供许多 AWS 服务访问，包括计费。标签不适合用于私有或敏感数据。
标签对象中允许以下参数。
`key`
类型：字符串
必需：否
构成标签的键-值对的一个部分。键是一种常见的标签，行为类似于更具体的标签值的类别。
`value`
类型：字符串
必需：否
构成标签的键-值对的可选部分。值充当标签类别（键）中的描述符。
## 其他任务定义参数
以下任务定义参数可在 Amazon ECS 控制台中注册任务定义时使用，方法是使用 **Configure via JSON**（通过 JSON 配置）选项。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
**Topics**
+ [IPC 模式](#task_definition_ipcmode_ec2)
+ [PID 模式](#task_definition_pidmode_ec2)
+ [故障注入](#task_definition_faultInjection_ec2)
### IPC 模式
`ipcMode`
类型：字符串
必需：否
用于任务中的容器的 IPC 资源命名空间。有效值为 `host`、`task` 或 `none`。如果指定了 `host`，则在同一容器实例上指定了 `host` IPC 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的 IPC 资源。如果指定了 `task`，则指定任务中的所有容器将共享相同的 IPC 资源。如果指定了 `none`，则任务的容器中的 IPC 资源是私有的，不与任务中或容器实例上的其他容器共享。如果未指定任何值，则 IPC 资源命名空间共享取决于容器实例上的 Docker 进程守护程序设置。
如果使用了 `host` IPC 模式，发生非预期的 IPC 命名空间公开的风险会提高。
如果您设置了为任务中的容器使用 `systemControls` 的带有命名空间的内核参数，则以下内容适用于您的 IPC 资源命名空间。
+ 对于使用 `host` IPC 模式的任务，不支持与 IPC 命名空间相关的 `systemControls`。
+ 对于使用 `task` IPC 模式的任务，与 IPC 命名空间相关的 `systemControls` 将适用于任务中的所有容器。
### PID 模式
`pidMode`
类型：字符串
有效值：`host` \$1 `task`
必需：否
用于任务中的容器的过程命名空间。有效值为 `host` 或 `task`。例如，监控 sidecar 可能需要 `pidMode` 访问有关在同一任务中运行的其他容器的信息。
如果指定了 `host`，则在同一容器实例上指定了 `host` PID 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的进程命名空间。
如果指定了 `task`，则指定任务中的所有容器将共享相同的过程命名空间。
如果未指定任何值，则默认值为每个容器的私有命名空间。
如果使用了 `host` PID 模式，发生非预期的过程命名空间公开的风险会提高。
**注意**
Windows 容器不支持此参数。
### 故障注入
`enableFaultInjection`
类型：布尔值
有效值：`true` \$1 `false`
必需：否
如果在任务的有效载荷中将此参数设置为 `true`，则 Amazon ECS 将接受来自该任务的容器的故障注入请求。默认情况下，此参数设置为 `false`。