You are using Amazon FSx for Windows File Server file system for persistent container storage.
' -Force"],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": false,
"name": "container1",
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
]
},
{
"entryPoint": [
"powershell",
"-Command"
],
"portMappings": [
{
"hostPort": 443,
"protocol": "tcp",
"containerPort": 80
}
],
"command": ["Remove-Item -Recurse C:\\inetpub\\wwwroot\\* -Force; Start-Sleep -Seconds 120; Move-Item -Path C:\\fsx-windows-dir\\index.html -Destination C:\\inetpub\\wwwroot\\index.html -Force; C:\\ServiceMonitor.exe w3svc"],
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": true,
"name": "container2"
}
],
"family": "fsx-windows",
"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
"volumes": [
{
"name": "fsx-windows-dir",
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "fs-0eeb5730b2EXAMPLE",
"authorizationConfig": {
"domain": "example.com",
"credentialsParameter": "arn:arn-1234"
},
"rootDirectory": "share"
}
}
]
}
```
`FSxWindowsFileServerVolumeConfiguration`
类型：对象
必需：否
当您使用适用于 Windows File Server 的 FSx [https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html)文件系统进行任务存储时，指定此参数。
`fileSystemId`
类型：字符串
是否必需：是
要使用的适用于 Windows File Server 的 FSx 文件系统 ID。
`rootDirectory`
类型：字符串
是否必需：是
适用于 Windows File Server 的 FSx 文件系统中要作为主机内的根目录挂载的目录。
`authorizationConfig`
`credentialsParameter`
类型：字符串
是否必需：是
授权凭证选项：
+ [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 密钥的 Amazon 资源名称（ARN）。
+ [Secrets Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) 参数的 Amazon 资源名称（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。
## 存储适用于 Windows File Server 的 FSx 卷凭证的方法
存储凭证的凭证有两种不同的方法，以便与凭证参数一起使用。
+ **AWS Secrets Manager 密钥**
此凭证可以在 AWS Secrets Manager 控制台中使用*其他密钥类型*类别。您可以为每个键/值对、用户名/管理员和密码/*password* 添加一行。
+ **Systems Manager 参数**
通过以下示例代码片段中的形式输入文本，可以在 Systems Manager 参数控制台中创建此凭证。
```
{
"username": "admin",
"password": "password"
}
```
任务定义 `FSxWindowsFileServerVolumeConfiguration` 参数中的 `credentialsParameter` 将保存密钥 ARN 或 Systems Manager 参数 ARN。有关更多信息，请参阅 *Secrets Manager用户指南*中的[什么是 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)以及 *Systems Manager 用户指南*中的 [Systems Manager 参数存储](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html)。
# 了解为 Amazon ECS 配置适用于 Windows File Server 的 FSx 文件系统
了解如何启动经 Amazon ECS 优化的 Windows 实例，该实例托管适用于 Windows File Server 的 FSx 文件系统和可访问该文件系统的容器。要执行此操作，您首先创建一个Directory Service AWS托管 Microsoft Active Directory。然后，您可以创建适用于 Windows File Server 的 FSx 文件系统和带有 Amazon EC2 实例和任务定义的集群。您可以配置容器的任务定义使用适用于 Windows File Server 的 FSx 文件系统。最后，您测试文件系统。
每次启动或删除 Active Directory 或适用于 Windows File Server 的 FSx 文件系统时都需要 20 到 45 分钟。准备至少保留 90 分钟以完成本教程或通过几个课程完成本教程。
## 教程的先决条件
+ 管理用户。请参阅[设置以使用 Amazon ECS](get-set-up-for-amazon-ecs.md)。
+ （可选）一个 `PEM` 密钥对，用于通过 RDP 访问连接到您的 EC2 Windows 实例。有关如何创建密钥对的信息，请参阅《Amazon EC2 用户指南》中的 [Amazon EC2 密钥对和 Amazon EC2 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)**。
+ 至少有一个公有子网和一个私有子网以及一个安全组的 VPC。您可以使用您的原定设置 VPC。您不需要 NAT 网关或设备。Directory Service 不支持 Active Directory 的网络地址转换（NATI）。为了实现这一点，您的 VPC 中必须有 Active Directory、适用于 Windows File Server 的 FSx 文件系统、ECS 集群和 EC2 实例。有关 VPC 和 Active Directory 的更多信息，请参阅[创建 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) 和 [Prerequisites for creating an AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_prereqs)。
+ IAM ecsInstanceRole 和 ecsTaskExecutionRole 权限与您的账户关联。这些服务链接角色允许服务代表您进行 API 调用并访问容器、密钥、目录和文件服务器。
## 步骤 1：创建 IAM 访问角色
**使用 AWS 管理控制台 创建集群**
1. 请参阅 [Amazon ECS 容器实例 IAM 角色](instance_IAM_role.md) 来检查你是否有ecsInstanceRole，如果没有，查看你如何创建。
1. 我们建议为实际生产环境中的最低权限自定义角色策略。为了完成本教程，请验证以下 AWS 托管策略附加到您的 ecsInstanceRole 上。如果尚未附加策略，则附加策略。
+ AmazonEC2ContainerServiceforEC2Role
+ AmazonSSMManagedInstanceCore
+ AmazonSSMDirectoryServiceAccess
要附加 AWS 托管策略
1. 打开 [IAM 控制台](https://console.aws.amazon.com//iam/)。
1. 在导航窗格中，选择**角色**。
1. 选择 **AWS 托管角色**。
1. 依次选择**权限、附加策略**。
1. 要缩小要附加的可用策略范围，请使用**筛选条件**。
1. 选择适当的策略，然后选择**附加策略**。
1. 请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md) 来检查你是否有ecsTaskExecutionRole，如果没有，查看你如何创建。
我们建议为实际生产环境中的最低权限自定义角色策略。为了完成本教程，请验证以下 AWS 托管策略附加到您的 ecsTaskExecutionRole上。如果尚未附加策略，则附加策略。使用上一节中给出的过程附加 AWS 托管策略。
+ SecretsManagerReadWrite
+ AmazonFSxReadOnlyAccess
+ AmazonSSMReadOnlyAccess
+ AmazonECSTaskExecutionRolePolicy
## 步骤 2：创建 Windows Active Directory（AD）
1. 按照《AWS Directory Service 管理指南》**中 [Creating your AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_create_directory) 部分描述的步骤进行操作。使用您为本教程指定的 VPC。在 *Creating your AWS Managed Microsoft AD* 的第 3 步中，保存用户名和管理员密码，以便在后续步骤中使用。另外，记下完全限定域名，以备后续步骤使用。在创建 Active Directory 时，您可以完成以下步骤。
1. 创建要在以下步骤中使用的 AWS Secrets Manager 密码。有关更多信息，请参阅《AWS Secrets Manager 用户指南》中的 [Get started with Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html#get-started)**。
1. 打开 [Secrets Manager 控制台](https://console.aws.amazon.com//secretsmanager/)。
1. 单击**存储新密钥**。
1. 选择**其他密钥类型**。
1. 对于**私有密钥/值**，在第一行创建值为 **admin** 的密钥 **username**。点击**\$1 添加行**。
1. 在新行中，创建密钥 **password**。对于值，键入在*创建 AWS 托管 AD 目录*的步骤 3 中输入的密码。
1. 点击**下一步**按钮。
1. 提供密钥名称和说明。单击**下一步**。
1. 单击**下一步**。单击**存储**。
1. 在**密钥**列表页面上，单击您刚刚创建的密钥。
1. 保存新密钥的 ARN，以便在以下步骤中使用。
1. 您的 Active Directory 正在创建时，您可以继续执行下一步。
## 步骤 3：确认并更新安全组规则
在此步骤中，您将验证并更新您正在使用的安全组的规则。对此，您可以使用为 VPC 创建的原定设置安全组。
**验证并更新安全组。**
您需要创建或编辑安全组以从端口发送数据和向端口发送数据，在适用于 Windows File Server 的 FSx *用户指南*中的 [Amazon VPC 安全组](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/limit-access-security-groups.html#fsx-vpc-security-groups)中描述这些端口。您可以通过创建下表入站规则的第一行中显示的安全组入站规则来执行此操作。规则允许来自分配给相同安全组的网络接口（及其关联实例）的入站流量。您创建的所有云资源都位于同一 VPC 中，并连接到同一安全组。因此，此规则允许根据需要向适用于 Windows File Server 的 FSx 系统、Active Directory 和 ECS 实例发送流量。其他入站规则允许流量为网站提供服务，并允许 RDP 访问连接到 ECS 实例。
下表显示了本教程需要哪些安全组入站规则。
| Type | 协议 | 端口范围 | 来源 |
| --- | --- | --- | --- |
| 所有流量 | All | 全部 | *sg-securitygroup* |
| HTTPS | TCP | 443 | 0.0.0.0/0 |
| RDP | TCP | 3389 | 您的笔记本电脑 IP 地址 |
下表显示了本教程所需的安全组出站规则。
| Type | 协议 | 端口范围 | 目标 |
| --- | --- | --- | --- |
| 所有流量 | All | 全部 | 0.0.0.0/0 |
1. 打开[EC2 控制台](https://console.aws.amazon.com//ec2/)并从左侧菜单中选择**安全组**。
1. 从现在显示的安全组列表中，选中用于本教程的安全组左侧的复选框。
显示您的安全组详细信息。
1. 通过选择**入站规则**或**出站规则**选项卡并选择**编辑入站规则**或**编辑出站规则**按钮来编辑入站和出站规则。编辑规则以匹配前表中显示的规则。在本教程的稍后阶段创建 EC2 实例后，按照《Amazon EC2 用户指南》中的[使用 RDP 连接到 Windows 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html)**部分所述，使用 EC2 实例的公有 IP 地址编辑入站规则 RDP 源。
## 步骤 4：创建适用于 Windows File Server 的 FSx 文件系统
验证并更新安全组，创建 Active Directory 并处于活动状态后，在与 Active Directory 相同的 VPC 中创建适用于 Windows File Server 的 FSx 文件系统。使用以下步骤创建适用于 Windows File Server 的 FSx 文件系统供 Windows 任务使用。
**创建您的第一个文件系统。**
1. 打开 [Amazon FSx 控制台](https://console.aws.amazon.com//fsx/)。
1. 在控制面板上，选择**创建文件系统**以启动文件系统创建向导。
1. 在**选择文件系统类型**页面上，选择**适用于 Windows File Server 的 FSx**，然后选择**下一步**。显示**创建文件系统**页面。
1. 在**文件系统详细信息**部分中，为您的文件系统提供一个名称。命名您的文件系统可以更轻松地查找和管理它们。最多可以使用 256 个 Unicode 字符。允许的字符包括字母、数字、空格和特殊字符加号（\$1）。减号（-）、等号（=）、句点（.）、下划线（\$1）、冒号（:）和正斜杠（/）。
1. 对于**部署类型**，选择**单可用区**部署部署在单个可用区中的文件系统。*单可用区 2*是最新一代的单可用区文件系统，支持 SSD 和 HDD 存储。
1. 对于**存储类型**，选择 **HDD**。
1. 对于**存储容量**，输入最小存储容量。
1. 保持**吞吐能力**设置为默认设置。
1. 在**网络和安全**部分，选择您为 Directory Service 目录选择的同一个 Amazon VPC。
1. 对于**VPC 安全组**，选择选择在*步骤3：验证和更新安全组中验证的安全组*。
1. 对于**Windows 身份验证**，选择 **AWS托管 Microsoft Active Directory**，然后选择您的 Directory Service 目录。
1. 对于**加密**，请保留 **aws/fsx（默认）**的默认**加密密钥**设置。
1. 保留**维护首选项**的原定设置。
1. 点击**下一步**按钮。
1. 检查**创建文件系统**页面上显示的文件系统配置。请注意创建文件系统后可以修改的文件系统设置（供您参考）。选择**创建文件系统**。
1. 请记下文件系统 ID 值。您将在后面的步骤中用到它。
在创建适用于 Windows File Server 的 FSx 文件系统时，您可以继续执行后续步骤以创建集群和 EC2 实例。
## 步骤 5：创建 Amazon ECS 集群
**使用 Amazon ECS 控制台创建集群**
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 从导航栏中，选择要使用的区域。
1. 在导航窗格中，选择**集群**。
1. 在 **Clusters**（集群）页面上，选择 **Create cluster**（创建集群）。
1. 在**集群配置**下方的**集群名称**中，输入 **windows-fsx-cluster**。
1. 展开**基础设施**，清除 AWS Fargate（无服务器），然后选择 **Amazon EC2 实例**。
1. 要创建 自动扩缩组，请从 **自动扩缩组（ASG）**（自动扩缩组（ASG））中，选择 **Create new group**（创建新组），然后提供有关组的以下详细信息：
+ 对于**操作系统/架构**，请选择 **Windows Server 2019 Core**。
+ 对于 **EC2 实例类型**，选择 t2.medium 或 t2.micro。
1. 选择**创建**。
## 步骤 6：创建经 Amazon ECS 优化的 Amazon EC2 实例
创建 Amazon ECS Windows 容器实例。
**创建 Amazon ECS 实例**
1. 使用 `aws ssm get-parameters` 命令检索托管您 VPC 的区域的 AMI 名称。有关更多信息，请参阅[检索经 Amazon ECS 优化的 AMI 元数据](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/retrieve-ecs-optimized_windows_AMI.html)。
1. 用来创建启动实例的 Amazon EC2 控制台。
1. 通过以下网址打开 Amazon EC2 控制台：[https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/)。
1. 从导航栏中，选择要使用的区域。
1. 从 **EC2 控制面板**中，选择 **Launch Instance**（启动实例）。
1. 对于**名称**，输入唯一的名称。
1. 对于**应用程序和操作系统映像（亚马逊机器映像）**，在**搜索**字段中，输入您检索的 AMI 名称。
1. 对于**实例类型**，选择 t2.medium 或 t2.micro。
1. 对于**密钥对（登录）**，选择一个密钥对。如果您未指定密钥对，则您
1. 在**网络设置**下，对于 **VPC** 和**子网**，选择您的 VPC 和公有子网。
1. 在 **Network settings**（网络设置）下，对于 **Security group**（安全组），可以选择现有安全组或创建新安全组。确保您选择的安全组在 [教程的先决条件](#wfsx-prerequisites) 中定义了入站和出站规则
1. 在 **Network settings**（网络设置）下，对于 **Auto-assign Public IP**（自动分配公有 IP），选择 **Enable**（启用）。
1. 展开**高级详细信息**，然后对于**域加入目录**，选择您创建的 Active Directory 的 ID。此选项域在 EC2 实例启动时加入您的 AD。
1. 在 **Advanced details**（高级详细信息）下，对于 **IAM instance profile**（IAM 实例配置文件），选择 **ecsInstanceRole**。
1. 使用以下用户数据配置您的 Amazon ECS 容器实例。在 **Advanced Details**（高级详细信息）下，将以下脚本粘贴到 **User data**（用户数据）字段中，将 *cluster\$1name* 替换为您的集群的名称。
```
```
1. 准备好后，选中确认字段，然后选择 **Launch Instances**。
1. 确认页面会让您知道自己的实例已启动。选择 **View Instances** 以关闭确认页面并返回控制台。
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择**集群**，然后选择 **windows-fsx-cluster**。
1. 选择**基础设施**选项卡，验证您的实例是否已在 **windows-fsx-cluster** 集群中注册。
## 步骤 7：注册 Windows 任务定义
您必须先注册任务定义，然后才能在 Amazon ECS 集群中运行 Windows 容器。以下任务定义示例显示一个简单网页。此任务将启动两个具有 FSX 文件系统访问权限的容器。第一个容器将 HTML 文件写入文件系统。第二个容器从文件系统下载 HTML 文件并提供网页。
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 选择 **Create new task definition**（创建新的任务定义）、**Create new task definition with JSON**（使用 JSON 创建新的任务定义）。
1. 在 JSON 编辑器框中，替换任务执行角色的值以及有关 FSx 文件系统的详细信息，然后选择**保存**。
```
{
"containerDefinitions": [
{
"entryPoint": [
"powershell",
"-Command"
],
"portMappings": [],
"command": ["New-Item -Path C:\\fsx-windows-dir\\index.html -ItemType file -Value '
Amazon ECS Sample App
It Works!
You are using Amazon FSx for Windows File Server file system for persistent container storage.
' -Force"],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": false,
"name": "container1",
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
]
},
{
"entryPoint": [
"powershell",
"-Command"
],
"portMappings": [
{
"hostPort": 443,
"protocol": "tcp",
"containerPort": 80
}
],
"command": ["Remove-Item -Recurse C:\\inetpub\\wwwroot\\* -Force; Start-Sleep -Seconds 120; Move-Item -Path C:\\fsx-windows-dir\\index.html -Destination C:\\inetpub\\wwwroot\\index.html -Force; C:\\ServiceMonitor.exe w3svc"],
"mountPoints": [
{
"sourceVolume": "fsx-windows-dir",
"containerPath": "C:\\fsx-windows-dir",
"readOnly": false
}
],
"cpu": 512,
"memory": 256,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"essential": true,
"name": "container2"
}
],
"family": "fsx-windows",
"executionRoleArn": "arn:aws:iam::111122223333:role/ecsTaskExecutionRole",
"volumes": [
{
"name": "fsx-windows-dir",
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "fs-0eeb5730b2EXAMPLE",
"authorizationConfig": {
"domain": "example.com",
"credentialsParameter": "arn:arn-1234"
},
"rootDirectory": "share"
}
}
]
}
```
## 步骤 8：运行任务并查看结果
在运行任务之前，请验证适用于 Windows File Server 的 FSx 文件系统的状态是**Available**。可用后，您可以使用创建的任务定义运行任务。任务首先是创建容器，使用文件系统在它们之间随机打开 HTML 文件。随机打开后，Web 服务器提供简单的 HTML 页面。
**注意**
您可能无法从 VPN 内连接到网站。
**使用 Amazon ECS 控制台运行任务并查看结果。**
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择**集群**，然后选择 **windows-fsx-cluster**。
1. 选择**任务**选项卡，然后选择**运行新任务**。
1. 对于**启动类型**，选择 **EC2**。
1. 在部署配置下的**任务定义**中，选择 **fsx-windows**，然后选择**创建**。
1. 当您的任务状态为 **RUNNING** 时，选择任务 ID。
1. 在**容器**下，当 container1 状态为 **STOPPED** 时，选择 container2 以查看容器的详细信息。
1. 在 **container2 的容器详细信息**下，选择**网络绑定**，然后单击与容器关联的外部 IP 地址。您的浏览器将打开并显示以下消息。
```
Amazon ECS Sample App
It Works!
You are using Amazon FSx for Windows File Server file system for persistent container storage.
```
**注意**
显示消息可能需要几分钟时间。如果您在几分钟后未看到此消息，请检查是否未在 VPN 中运行，并确保容器实例的安全组允许端口 443 上的入站网络 HTTP 通信。
## 步骤 9：清除
**注意**
要花费 20 到45 分钟删除适用于 Windows File Server 的 FSx 文件系统或 AD。您必须等待，直到适用于 Windows File Server 的 FSx 文件系统删除操作完成，然后再开始 AD 删除操作。
**删除适用于 Windows File Server 的 FSx 文件系统。**
1. 打开 [Amazon FSx 控制台](https://console.aws.amazon.com//fsx/)。
1. 选择刚刚创建的适用于 Windows File Server 的 FSx 文件系统左侧的单选按钮。
1. 选择**操作**。
1. 选择**删除文件系统**。
**删除 AD。**
1. 打开 [Directory Service 控制台](https://console.aws.amazon.com//directoryservicev2/)。
1. 选择刚刚创建的 AD 左侧的单选按钮。
1. 选择**操作**。
1. 选择**删除目录**。
**请删除集群。**
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择**集群**，然后选择 **windows-fsx-cluster**。
1. 选择**删除集群**。
1. 输入短语，然后选择**删除**。
**终止 EC2 实例。**
1. 打开 [Amazon EC2 控制台](https://console.aws.amazon.com//ec2/)。
1. 从左侧菜单中，选择**实例**。
1. 选中您创建的 EC2 实例左侧的框。
1. 单击**实例状态**、**终止实例**。
**删除密钥。**
1. 打开 [Secrets Manager 控制台](https://console.aws.amazon.com//secretsmanager/)。
1. 选择您为本演练创建的密钥。
1. 点击**操作**。
1. 选择**删除密钥**。
# 将 Docker 卷与 Amazon ECS 结合使用
当使用 Docker 卷时，可以使用内置的 `local` 驱动程序或第三方卷驱动程序。Docker 卷由 Docker 管理，而目录在包含卷数据的容器实例上的 `/var/lib/docker/volumes` 中创建。
要使用 Docker 卷，请在任务定义中指定 `dockerVolumeConfiguration`。有关更多信息，请参阅 Docker 文档中的 [Volumes](https://docs.docker.com/engine/storage/volumes/)。
Docker 卷的一些常见使用案例如下：
+ 提供持久性数据卷以用于容器
+ 在同一个容器实例上不同容器中的不同位置共享一个定义的数据卷
+ 定义空的非持久性数据卷，并将其挂载到同一任务内的多个容器上
+ 向由第三方驱动程序管理的任务提供数据卷
## 使用 Docker 卷的注意事项
使用 Docker 卷时考虑以下事项：
+ 只有在使用 EC2 启动类型或外部实例时，才支持 Docker 卷。
+ Windows 容器仅支持使用 `local` 驱动程序。
+ 如果使用第三方驱动程序，确保在容器代理启动之前在容器实例上安装并激活该驱动程序。如果在代理启动之前第三方驱动程序未处于活动状态，则可以使用下列命令之一重新启动容器代理：
+ 对于经 Amazon ECS 优化的 Amazon Linux 2 AMI：
```
sudo systemctl restart ecs
```
+ 对于经 Amazon ECS 优化的 Amazon Linux AMI：
```
sudo stop ecs && sudo start ecs
```
有关如何在任务定义中指定 Docker 卷的信息，请参阅[在 Amazon ECS 任务定义中指定 Docker 卷](specify-volume-config.md)。
# 在 Amazon ECS 任务定义中指定 Docker 卷
在您的容器可以使用数据卷之前，您必须在任务定义中指定卷和挂载点配置。此部分描述容器的卷配置。对于使用 Docker 卷的任务，请指定 `dockerVolumeConfiguration`。对于使用绑定挂载主机卷的任务，请指定 `host` 和可选的 `sourcePath`。
以下任务定义 JSON 显示容器的 `volumes` 和 `mountPoints` 对象的语法。
```
{
"containerDefinitions": [
{
"mountPoints": [
{
"sourceVolume": "string",
"containerPath": "/path/to/mount_volume",
"readOnly": boolean
}
]
}
],
"volumes": [
{
"name": "string",
"dockerVolumeConfiguration": {
"scope": "string",
"autoprovision": boolean,
"driver": "string",
"driverOpts": {
"key": "value"
},
"labels": {
"key": "value"
}
}
}
]
}
```
`name`
类型：字符串
必需：否
卷的名称。最多允许 255 个字母（大写和小写字母）、数字、连字符（`-`）和下划线（`_`）。此名称已在容器定义 `mountPoints` 对象的 `sourceVolume` 参数中引用。
`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 卷的自定义元数据。
`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 操作系统的 EC2 实例上运行的任务，请保留默认值 `false`。
# 适用于 Amazon ECS 的 Docker 卷示例
以下示例说明如何为容器提供临时存储、如何为多个容器提供共享卷，以及如何为容器提供 NFS 持久性存储。
**要使用 Docker 卷为容器提供临时存储**
在此示例中，容器使用在任务完成后处置的空数据卷。一个示例使用案例为，您可能具有一个需要在任务期间访问某个临时文件存储位置的容器。可以使用 Docker 卷实现此任务。
1. 在任务定义 `volumes` 部分中，使用 `name` 和 `DockerVolumeConfiguration` 值定义数据卷。在此示例中，我们将范围指定为 `task`，以便在任务停止后删除此卷并使用内置的 `local` 驱动程序。
```
"volumes": [
{
"name": "scratch",
"dockerVolumeConfiguration" : {
"scope": "task",
"driver": "local",
"labels": {
"scratch": "space"
}
}
}
]
```
1. 在 `containerDefinitions` 部分中，使用引用已定义卷的名称的 `mountPoints` 值和将卷挂载到容器上所在的 `containerPath` 值定义容器。
```
"containerDefinitions": [
{
"name": "container-1",
"mountPoints": [
{
"sourceVolume": "scratch",
"containerPath": "/var/scratch"
}
]
}
]
```
**使用 Docker 卷为多个容器提供持久性存储**
在本示例中，您希望多个容器使用一个共享卷，并希望在使用此卷的任何单个任务停止后该卷持续存在。正在使用的是内置的 `local` 驱动程序。以便该卷仍绑定到容器实例的生命周期。
1. 在任务定义 `volumes` 部分中，使用 `name` 和 `DockerVolumeConfiguration` 值定义数据卷。在此示例中，指定 `shared` 范围以便卷持续存在，将自动预置设置为 `true`。这样就可以创建卷以供使用。然后，还可使用内置的 `local` 驱动程序。
```
"volumes": [
{
"name": "database",
"dockerVolumeConfiguration" : {
"scope": "shared",
"autoprovision": true,
"driver": "local",
"labels": {
"database": "database_name"
}
}
}
]
```
1. 在 `containerDefinitions` 部分中，使用引用已定义卷的名称的 `mountPoints` 值和将卷挂载到容器上所在的 `containerPath` 值定义容器。
```
"containerDefinitions": [
{
"name": "container-1",
"mountPoints": [
{
"sourceVolume": "database",
"containerPath": "/var/database"
}
]
},
{
"name": "container-2",
"mountPoints": [
{
"sourceVolume": "database",
"containerPath": "/var/database"
}
]
}
]
```
**使用 Docker 卷为容器提供 NFS 持久性存储**
在此示例中，容器使用 NFS 数据卷，该数据卷在任务启动时自动挂载，在任务停止时自动卸载。这使用了 Docker 内置 `local` 驱动程序。一个示例使用案例为，您可能具有本地 NFS 存储，并且需要从 ECS Anywhere 任务访问该存储。可以通过带有 NFS 驱动程序选项的 Docker 卷实现此目标。
1. 在任务定义 `volumes` 部分中，使用 `name` 和 `DockerVolumeConfiguration` 值定义数据卷。在此示例中，指定 `task` 范围以便在任务停止后卸载卷。使用 `local` 驱动程序并使用 `type`、`device` 和 `o` 选项相应地配置 `driverOpts`。`NFS_SERVER` 替换为 NFS 服务器端点。
```
"volumes": [
{
"name": "NFS",
"dockerVolumeConfiguration" : {
"scope": "task",
"driver": "local",
"driverOpts": {
"type": "nfs",
"device": "$NFS_SERVER:/mnt/nfs",
"o": "addr=$NFS_SERVER"
}
}
}
]
```
1. 在 `containerDefinitions` 部分中，使用引用已定义卷的名称的 `mountPoints` 值和将卷挂载到容器上所在的 `containerPath` 值定义容器。
```
"containerDefinitions": [
{
"name": "container-1",
"mountPoints": [
{
"sourceVolume": "NFS",
"containerPath": "/var/nfsmount"
}
]
}
]
```
# 将绑定挂载与 Amazon ECS 结合使用
使用绑定挂载，主机上的文件或目录（如 Amazon EC2 实例）被挂载到容器中。Fargate 和 Amazon EC2 实例上托管的任务都支持绑定挂载。绑定挂载与使用它们的容器的生命周期相关。停止使用绑定挂载的所有容器后（例如，停止任务时），数据将被删除。对于托管在 Amazon EC2 实例上的任务，可以通过在任务定义中指定 `host` 和可选值 `sourcePath`，将数据绑定到主机 Amazon EC2 实例的生命周期。有关更多信息，请参阅 Docker 文档中的 [Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)。
以下是绑定挂载的常见使用案例。
+ 提供空数据卷以挂载在一个或多个容器中。
+ 在一个或多个容器中挂载主机数据卷。
+ 与相同任务中的其他容器共享来自源容器的数据卷。
+ 将 Dockerfile 路径及其内容公开到一个或多个容器。
## 使用绑定挂载时的注意事项
使用绑定挂载时应考虑以下事项。
+ 默认情况下，使用平台版本 `1.4.0` 或更高版本（Linux）或者 `1.0.0` 或更高版本（Windows）在 AWS Fargate 上托管的任务会收到至少 20GiB 的临时存储以用于绑定挂载。您可以增加临时存储总量，最多可达 200GiB，方法是在您的任务定义中指定 `ephemeralStorage` 参数。
+ 要在任务运行时将 Dockerfile 中的文件公开到数据卷，Amazon ECS 数据面板将查找 `VOLUME` 指令。如果 `VOLUME` 指令中指定的绝对路径与任务定义中指定的 `containerPath` 绝对路径相同，则指令路径 `VOLUME` 中的数据将复制到数据卷。在下面的 Dockerfile 示例中，`/var/log/exported` 目录中名为 `examplefile` 的文件将写入主机，然后挂载到容器中。
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN mkdir -p /var/log/exported
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]
```
预设情况下，卷权限设置为 `0755` 和所有者设置为 `root`。您可以在 Dockerfile 中自定义这些权限。以下示例将目录的所有者定义为 `node`。
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install -y shadow-utils && yum clean all
RUN useradd node
RUN mkdir -p /var/log/exported && chown node:node /var/log/exported
RUN touch /var/log/exported/examplefile
USER node
VOLUME ["/var/log/exported"]
```
+ 对于 Amazon EC2 实例上托管的任务，如果未指定 `host` 和 `sourcePath` 值，则 Docker 进程守护程序将为您管理绑定挂载。如果没有容器引用此绑定挂载，则 Amazon ECS 容器代理任务清理服务最终会将其删除。默认情况下，这发生在容器退出三个小时后。但是，您可以使用 `ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION` 代理变量配置此持续时间。有关更多信息，请参阅 [Amazon ECS 容器代理配置](ecs-agent-config.md)。如果需要在容器的生命周期内保持此数据，请为绑定挂载指定一个 `sourcePath` 值。
+ 对于托管在 Amazon ECS 托管实例上的任务，其根文件系统部分为只读。读/写绑定挂载必须使用可写目录，例如 `/var` 用于存储永久数据或 `/tmp` 用于存储临时数据。尝试在其他目录创建读/写绑定挂载将导致任务启动失败，并返回类似如下错误：
```
error creating empty volume: error while creating volume path '/path': mkdir /path: read-only file system
```
只读绑定挂载（在 `mountPoints` 参数中配置 `"readOnly": true`）可以指向主机上任何可访问的目录。
要查看完整的可写路径列表，您可以在 Amazon ECS 托管实例上运行一个任务，并使用相关命令检查实例的挂载表。创建一个任务定义，并进行如下设置以访问主机文件系统：
```
{
"pidMode": "host",
"containerDefinitions": [{
"privileged": true,
...
}]
}
```
然后在容器内执行以下命令：
```
# List writable mounts
cat /proc/1/root/proc/1/mounts | awk '$4 ~ /^rw,/ || $4 == "rw" {print $2}' | sort
# List read-only mounts
cat /proc/1/root/proc/1/mounts | awk '$4 ~ /^ro,/ || $4 == "ro" {print $2}' | sort
```
**重要**
`privileged` 设置在主机上授予容器扩展功能，相当于 root 权限。在本例中，此项设置用于检查主机的挂载表以进行诊断。有关更多信息，请参阅 [避免以特权身份运行容器（Amazon EC2）](security-tasks-containers.md#security-tasks-containers-recommendations-avoid-privileged-containers)。
有关在容器中运行交互式命令的更多信息，请参阅 [使用 ECS Exec 监控 Amazon ECS 容器](ecs-exec.md)。
# 在 Amazon ECS 任务定义中指定绑定挂载
对于在 Fargate 或 Amazon EC2 实例上托管的 Amazon ECS 任务，以下任务定义 JSON 代码段显示任务定义的 `volumes`、`mountPoints` 和 `ephemeralStorage` 对象的语法。
```
{
"family": "",
...
"containerDefinitions" : [
{
"mountPoints" : [
{
"containerPath" : "/path/to/mount_volume",
"sourceVolume" : "string"
}
],
"name" : "string"
}
],
...
"volumes" : [
{
"name" : "string"
}
],
"ephemeralStorage": {
"sizeInGiB": integer
}
}
```
对于 Amazon EC2 实例上托管的 Amazon ECS 任务，您可以在指定任务卷详细信息时使用可选的 `host` 参数和 `sourcePath`。指定后，它将绑定挂载与任务的生命周期而不是容器关联起来。
```
"volumes" : [
{
"host" : {
"sourcePath" : "string"
},
"name" : "string"
}
]
```
下面将更详细地描述每个任务定义参数。
`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 进程守护程序将创建该值。如果该位置不存在，则将导出源路径文件夹的内容。
`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 操作系统的 EC2 实例上运行的任务，请保留默认值 `false`。
`ephemeralStorage`
类型：对象
必需：否
要为任务分配的临时存储容量。对于使用平台版本 `1.4.0` 或更高版本（Linux）或者 `1.0.0` 或更高版本（Windows）的 AWS Fargate 上托管的任务，此参数用于将短暂可用存储的总量扩展到默认数量之外。
您可以使用 Copilot CLI、CloudFormation、AWS SDK 或 CLI 为绑定挂载指定临时存储容量。
# Amazon ECS 绑定挂载示例
以下示例介绍了为容器使用绑定挂载的常见使用案例。
**为 Fargate 任务分配更多的临时存储空间**
对于在使用平台版本 `1.4.0` 或更高版本（Linux）或 `1.0.0`（Windows）的 Fargate 上托管的 Amazon ECS 任务，您可以为任务中要使用的容器分配超过原定设置数量的短暂存储。此示例可以合并到其他示例中，以便为 Fargate 任务分配更多的临时存储空间。
+ 在任务定义中，定义 `ephemeralStorage` 对象。`sizeInGiB` 必须是介于 `21` 和 `200` 之间的整数，单位是 GiB。
```
"ephemeralStorage": {
"sizeInGiB": integer
}
```
**为一个或多个容器提供空数据卷**
在某些使用案例中，您希望为任务中的容器提供一些临时空间。例如，您可能在任务期间具有需要访问同一临时文件存储位置的两个数据库容器。可以通过绑定挂载实现此目标。
1. 在任务定义 `volumes` 部分中，使用名称 `database_scratch` 定义绑定挂载。
```
"volumes": [
{
"name": "database_scratch"
}
]
```
1. 在 `containerDefinitions` 部分中，创建数据库容器定义。以便它们挂载卷。
```
"containerDefinitions": [
{
"name": "database1",
"image": "my-repo/database",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "database_scratch",
"containerPath": "/var/scratch"
}
]
},
{
"name": "database2",
"image": "my-repo/database",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "database_scratch",
"containerPath": "/var/scratch"
}
]
}
]
```
**将 Dockerfile 中的路径及其内容公开给容器**
在本例中，您有一个 Dockerfile，用于写入要挂载到容器中的数据。此示例适用于 Fargate 或 Amazon EC2 实例上托管的任务。
1. 创建 Dockerfile。下面的示例使用公共 Amazon Linux2 容器映像，并在我们希望挂载容器的 `/var/log/exported` 目录中创建一个名为 `examplefile` 的文件。`VOLUME` 指令应该指定绝对路径。
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN mkdir -p /var/log/exported
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]
```
预设情况下，卷权限设置为 `0755` 和所有者设置为 `root`。可以在 Dockerfile 中变更这些权限。在下面的示例中，`/var/log/exported` 目录的所有者设置为 `node`。
```
FROM public.ecr.aws/amazonlinux/amazonlinux:latest
RUN yum install -y shadow-utils && yum clean all
RUN useradd node
RUN mkdir -p /var/log/exported && chown node:node /var/log/exported
USER node
RUN touch /var/log/exported/examplefile
VOLUME ["/var/log/exported"]
```
1. 在任务定义 `volumes` 部分中，使用名称 `application_logs` 定义卷。
```
"volumes": [
{
"name": "application_logs"
}
]
```
1. 在 `containerDefinitions` 部分中，创建应用程序容器定义。以便它们挂载存储。`containerPath` 值必须与 Dockerfile 的 `VOLUME` 指令中指定的绝对路径匹配。
```
"containerDefinitions": [
{
"name": "application1",
"image": "my-repo/application",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "application_logs",
"containerPath": "/var/log/exported"
}
]
},
{
"name": "application2",
"image": "my-repo/application",
"cpu": 100,
"memory": 100,
"essential": true,
"mountPoints": [
{
"sourceVolume": "application_logs",
"containerPath": "/var/log/exported"
}
]
}
]
```
**为与主机 Amazon EC2 实例生命周期相关的容器提供空数据卷**
对于在 Amazon EC2 实例上托管的任务，可以使用绑定挂载，并将数据绑定到主机 Amazon EC2 实例的生命周期。您可以通过使用 `host` 参数并指定 `sourcePath` 值进行此操作。存在于 `sourcePath` 的任何文件将提交至值为 `containerPath` 的容器。写入 `containerPath` 值的任何文件将会写入主机 Amazon EC2 实例上的 `sourcePath` 值。
**重要**
Amazon ECS 不会跨 Amazon EC2 实例同步您的存储。使用持久性存储的任务可置于您的集群中具有可用容量的任何 Amazon EC2 实例上。如果任务在停止和重新启动后需要持久存储，应始终在任务启动时使用 AWS CLI [start-task](https://docs.aws.amazon.com/cli/latest/reference/ecs/start-task.html) 命令指定相同的 Amazon EC2 实例。您也可以将 Amazon EFS 卷用于持久性存储。有关更多信息，请参阅 [将 Amazon EFS 卷与 Amazon ECS 结合使用](efs-volumes.md)。
1. 在任务定义 `volumes` 部分中，使用 `name` 和 `sourcePath` 值定义绑定挂载。在下面的示例中，主机 Amazon EC2 实例包含 `/ecs/webdata` 您希望挂载容器中的数据。
```
"volumes": [
{
"name": "webdata",
"host": {
"sourcePath": "/ecs/webdata"
}
}
]
```
1. 在 `containerDefinitions` 部分中，使用引用绑定挂载的名称的 `mountPoints` 值和要在容器上挂载绑定挂载的 `containerPath` 值定义容器。
```
"containerDefinitions": [
{
"name": "web",
"image": "public.ecr.aws/docker/library/nginx:latest",
"cpu": 99,
"memory": 100,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"essential": true,
"mountPoints": [
{
"sourceVolume": "webdata",
"containerPath": "/usr/share/nginx/html"
}
]
}
]
```
**在不同位置多个容器上挂载定义的卷**
您可以在任务定义中定义数据卷并在其他容器上的不同位置挂载该卷。例如，您的主机容器在 `/data/webroot` 有一个网站数据文件夹。您可能想在具有不同文档根目录的两个不同 Web 服务器上以只读方式挂载该数据卷。
1. 在任务定义 `volumes` 部分中，使用名称 `webroot` 和源路径 `/data/webroot` 定义数据卷。
```
"volumes": [
{
"name": "webroot",
"host": {
"sourcePath": "/data/webroot"
}
}
]
```
1. 在 `containerDefinitions` 部分中，使用将 `mountPoints` 卷与指向容器的文档根目录的 `webroot` 值关联的 `containerPath` 值为每个 Web 服务器定义容器。
```
"containerDefinitions": [
{
"name": "web-server-1",
"image": "my-repo/ubuntu-apache",
"cpu": 100,
"memory": 100,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"essential": true,
"mountPoints": [
{
"sourceVolume": "webroot",
"containerPath": "/var/www/html",
"readOnly": true
}
]
},
{
"name": "web-server-2",
"image": "my-repo/sles11-apache",
"cpu": 100,
"memory": 100,
"portMappings": [
{
"containerPort": 8080,
"hostPort": 8080
}
],
"essential": true,
"mountPoints": [
{
"sourceVolume": "webroot",
"containerPath": "/srv/www/htdocs",
"readOnly": true
}
]
}
]
```
**使用 `volumesFrom` 从其他容器挂载卷**
对于托管在 Amazon EC2 实例上的任务，您可以在一个容器上定义一个或多个卷，然后在相同任务内的不同容器定义中使用 `volumesFrom` 参数从其初始定义的挂载点的 `sourceContainer` 中挂载所有卷。`volumesFrom` 参数适用于任务定义中定义的卷以及使用 Dockerfile 内置到映像中的卷。
1. （可选）要共享映像中内置的卷，请使用 Dockerfile 中的 `VOLUME` 指令。以下示例 Dockerfile 使用了 `httpd` 映像，然后添加卷并在 Apache 文档根目录中的 `dockerfile_volume` 处挂载卷。这是 `httpd` Web 服务器使用的文件夹。
```
FROM httpd
VOLUME ["/usr/local/apache2/htdocs/dockerfile_volume"]
```
您可以使用此 Dockerfile 生成映像并将其推送至存储库（如 Docker Hub），然后在任务定义中使用它。以下步骤中使用的示例 `my-repo/httpd_dockerfile_volume` 映像是通过上述 Dockerfile 构建的。
1. 创建一个为您的容器定义其他卷和挂载点的任务定义。在此示例 `volumes` 部分中，您将创建一个名为 `empty` 的空卷，此卷由 Docker 进程守护程序管理。还有一个定义的主机卷，被称为 `host_etc`。它在主机容器实例上导出 `/etc` 文件夹。
```
{
"family": "test-volumes-from",
"volumes": [
{
"name": "empty",
"host": {}
},
{
"name": "host_etc",
"host": {
"sourcePath": "/etc"
}
}
],
```
在容器定义部分中，创建一个挂载之前定义的卷的容器。在此示例中，`web` 容器会挂载 `empty` 和 `host_etc` 卷。该容器使用通过 Dockerfile 中的卷构建的映像。
```
"containerDefinitions": [
{
"name": "web",
"image": "my-repo/httpd_dockerfile_volume",
"cpu": 100,
"memory": 500,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"mountPoints": [
{
"sourceVolume": "empty",
"containerPath": "/usr/local/apache2/htdocs/empty_volume"
},
{
"sourceVolume": "host_etc",
"containerPath": "/usr/local/apache2/htdocs/host_etc"
}
],
"essential": true
},
```
创建另一个容器，该容器使用 `volumesFrom` 挂载与 `web` 容器关联的所有卷。`web` 容器上的所有卷以同样方式挂载在 `busybox` 容器上。这包括在 Dockerfile 中指定的用于构建 `my-repo/httpd_dockerfile_volume` 映像的卷。
```
{
"name": "busybox",
"image": "busybox",
"volumesFrom": [
{
"sourceContainer": "web"
}
],
"cpu": 100,
"memory": 500,
"entryPoint": [
"sh",
"-c"
],
"command": [
"echo $(date) > /usr/local/apache2/htdocs/empty_volume/date && echo $(date) > /usr/local/apache2/htdocs/host_etc/date && echo $(date) > /usr/local/apache2/htdocs/dockerfile_volume/date"
],
"essential": false
}
]
}
```
当此任务运行时，这两个容器将挂载卷，并且 `busybox` 容器中的 `command` 会将日期和时间写入文件。此文件在每个卷文件夹中被称为 `date`。这些文件夹随后将显示在由 `web` 容器显示的网站上。
**注意**
由于 `busybox` 容器运行快速命令然后退出，它必须在容器定义中设置为 `"essential": false`。否则，它在退出时会停止整个任务。
# 管理 Amazon ECS 上的容器交换内存空间
使用 Amazon ECS，您可以在容器级别控制基于 Linux 的 Amazon EC2 实例上的交换内存空间使用量。使用每个容器的交换配置，任务定义中的每个容器都可以启用或禁用交换。对于启用此功能的用户，可以对所用的最大交换空间量进行限制。例如，延迟关键型容器可以禁用交换。相比之下，具有高暂时内存需求的容器可以打开交换，以减少容器负载时出现内存不足错误的机率。
容器的交换配置由以下容器定义参数管理。
`maxSwap`
容器可以使用的交换内存总量（以 MiB 为单位）。此参数会转换为 docker run 命令的 `--memory-swap` 选项，值为容器内存与 `maxSwap` 值之和。
如果指定`maxSwap`值为`0`，则该容器不使用交换。接受的值为`0`或任何正整数。如果省略 `maxSwap` 参数，该容器将为其运行所在的容器实例使用交换配置。必须为要使用的`swappiness`参数设置`maxSwap`值。
`swappiness`
您可以使用此功能调整容器的内存 swappiness 行为。`swappiness` 值为 `0` 不会导致交换，除非有需要。`swappiness` 值为 `100` 将导致页面被积极地交换。接受的值为`0`到`100`之间的整数。如果未指定`swappiness`参数，则使用默认值`60`。如果未指定 `maxSwap` 的值，则此参数将被忽略。此参数对应于 docker run 命令的 `--memory-swappiness` 选项。
在以下示例中，提供了 JSON 语法。
```
"containerDefinitions": [{
...
"linuxParameters": {
"maxSwap": integer,
"swappiness": integer
},
...
}]
```
## 注意事项
在使用每个容器交换配置时，请考虑以下事项。
+ 必须在托管任务的 Amazon EC2 实例上启用和分配交换空间，以供容器使用。预设情况下，经 Amazon ECS 优化的 AMI 没有启用交换功能。必须在实例上启用交换才能使用此功能。有关更多信息，请参阅《Amazon EC2 用户指南》的中的[实例存储交换卷](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-store-swap-volumes.html)**或[如何分配内存以便在 Amazon EC2 实例中用作交换空间？](https://repost.aws/knowledge-center/ec2-memory-swap-file)。
+ 仅指定 EC2 的任务定义支持交换空间容器定义参数。仅供 Fargate 上的 Amazon ECS 使用的任务定义不支持这些参数。
+ 仅 Linux 容器支持此功能。目前不支持 Windows 容器。
+ 如果任务定义中忽略了 `maxSwap` 和 `swappiness` 任务定义参数，每个容器都有默认的 `swappiness` 值 `60`。此外，总交换使用量限制为容器内存的两倍。
+ 如果您在 Amazon Linux 2023 上使用任务，则不支持 `swappiness` 参数。
# Amazon ECS 托管实例的 Amazon ECS 任务定义差异
要使用 Amazon ECS 托管实例，您必须将任务定义配置为使用 Amazon ECS 托管实例启动类型。使用 Amazon ECS 托管实例还需注意其他事项。
## 任务定义参数
使用 Amazon ECS 托管实例的任务支持大多数可用的 Amazon ECS 任务定义参数。然而，在与 Amazon ECS 托管实例任务一起使用时，某些参数具有特定行为或限制。
以下任务定义参数在 Amazon ECS 托管实例任务中无效：
+ `disableNetworking`
+ `dnsSearchDomains`
+ `dnsServers`
+ `dockerLabels`
+ `dockerSecurityOptions`
+ `dockerVolumeConfiguration`
+ `ephemeralStorage`
+ `extraHosts`
+ `fsxWindowsFileServerVolumeConfiguration`
+ `hostname`
+ `inferenceAccelerator`
+ `ipcMode`
+ `links`
+ `maxSwap`
+ `proxyConfiguration`
+ `sharedMemorySize`
+ `sourcepath` 卷
+ `swappiness`
+ `tmpfs`
以下任务定义参数在 Amazon ECS 托管实例任务中有效，但应注意以下限制：
+ `networkConfiguration`：Amazon ECS 托管实例任务使用 `awsvpc` 或 `host` 网络模式。
+ `placementConstraints`：支持以下约束属性。
+ `ecs.subnet-id`
+ `ecs.availability-zone`
+ `ecs.instance-type`
+ `ecs.cpu-architecture`
+ `requiresCompatibilities`：必须包含 `MANAGED_INSTANCES`，以确保任务定义与 Amazon ECS 托管实例兼容。
+ `resourceRequirement`：不支持 `InferenceAccelerator`。
+ `operatingSystemFamily`：Amazon ECS 托管实例使用 `LINUX`。
+ `volumes`-当将绑定挂载与 `sourcePath` 搭配使用时，其路径必须指向主机上的可写目录。Amazon ECS 托管实例文件系统的部分内容为只读。可写目录包括 `/var` 和 `/tmp`。有关更多信息，请参阅 [将绑定挂载与 Amazon ECS 结合使用](bind-mounts.md)。
为确保您的任务定义验证能否用于 Amazon ECS 托管实例，可在注册任务定义时指定以下内容：
+ 在 AWS 管理控制台中，为**需要兼容性**字段指定 `MANAGED_INSTANCES`。
+ 在 AWS CLI 中指定 `--requires-compatibilities` 选项。
+ 在 Amazon ECS API 中指定 `requiresCompatibilities` 标记。
# Fargate 的 Amazon ECS 任务定义差异
要使用 Fargate，您必须将任务定义配置为使用 Fargate 启动类型。使用 Fargate 时还有其他注意事项。
## 任务定义参数
使用 Fargate 的任务并非支持所有可用的 Amazon ECS 任务定义参数。某些参数完全不受支持，而其他参数对于 Fargate 任务的行为则不同。
以下任务定义参数在 Fargate 任务中无效：
+ `disableNetworking`
+ `dnsSearchDomains`
+ `dnsServers`
+ `dockerSecurityOptions`
+ `extraHosts`
+ `gpu`
+ `ipcMode`
+ `links`
+ `placementConstraints`
+ `privileged`
+ `maxSwap`
+ `swappiness`
以下任务定义参数在 Fargate 任务中有效，但应注意以下限制：
+ `linuxParameters` – 当指定适用于容器的 Linux 特定选项时，对于 `capabilities`，您可以添加的唯一功能是 `CAP_SYS_PTRACE`。`devices`、`sharedMemorySize` 和 `tmpfs` 参数不受支持。有关更多信息，请参阅 [Linux 参数](task_definition_parameters.md#container_definition_linuxparameters)。
+ `volumes` – Fargate 任务仅支持绑定挂载主机卷，因此， `dockerVolumeConfiguration` 参数不受支持。有关更多信息，请参阅 [卷](task_definition_parameters.md#volumes)。
+ `cpu`：对于 AWS Fargate 上的 Windows 容器，该值不能小于 1 vCPU。
+ `networkConfiguration`：Fargate 任务始终使用 `awsvpc` 网络模式。
为确保您的任务定义可验证用于 Fargate，可在注册任务定义时指定以下内容：
+ 在 AWS 管理控制台中，为**需要兼容性**字段指定 `FARGATE`。
+ 在 AWS CLI 中指定 `--requires-compatibilities` 选项。
+ 在 Amazon ECS API 中指定 `requiresCompatibilities` 标记。
## 操作系统和架构
为 AWS Fargate 配置任务和容器定义时，您必须指定容器运行的操作系统。AWS Fargate 支持以下操作系统：
+ Amazon Linux 2
**注意**
Linux 容器仅使用主机操作系统中的内核和内核配置。例如，内核配置包括 `sysctl` 系统控件。Linux 容器映像可以由包含任何 Linux 发行版中的文件和程序的基本映像创建。如果 CPU 架构匹配，则可以在任何操作系统上通过任何 Linux 容器映像运行容器。
+ Windows Server 2019 Full
+ Windows Server 2019 Core
+ Windows Server 2022 Full
+ Windows Server 2022 Core
当您在 AWS Fargate 上运行 Windows 容器时，您必须具有 X86\$164 CPU 架构。
当您在 AWS Fargate 上运行 Linux 容器时，您可以使用 X86\$164 CPU 架构，也可以使用 ARM64 架构用于基于 ARM 的应用程序。有关更多信息，请参阅 [适用于 64 位 ARM 工作负载的 Amazon ECS 任务定义](ecs-arm64.md)。
## 任务 CPU 和内存
AWS Fargate 的 Amazon ECS 任务定义需要您在任务级别指定 CPU 和内存。只需在任务级别指定这些资源便可满足大多数使用案例。下表显示了任务级 CPU 和内存的有效组合。您可以通过以 MiB 或 GB 字符串方式在任务定义中指定内存值。例如，您可以使用 `3072`（以 MiB 为单位）或 `3 GB`（以 GB 为单位）指定内存值。您可以通过 CPU 单位数或虚拟 CPU（vCPU）数字符串的方式在 JSON 文件中将 CPU 值。例如，您可以使用 `1024`（CPU 单位数）或 `1 vCPU`（vCPU 数）来指定 CPU 值。
| CPU 值 | 内存值 | AWS 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) | 4 GB 到 16 GB 之间（以 1 GB 为增量） | Linux、Windows |
| 4096 (4 vCPU) | 8 GB 到 30 GB 之间（以 1 GB 为增量） | 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 |
## 任务联网
AWS Fargate 的 Amazon ECS 任务要求使用 `awsvpc` 网络模式，该模式可为每个任务提供一个弹性网络接口。在使用此网络模式运行任务或创建服务时，必须指定一个或多个要附加网络接口的子网以及一个或多个要应用于该网络接口的安全组。
如果您使用的是公有子网，请决定是否为网络接口提供公有 IP 地址。对于公有子网中拉取容器映像的 Fargate 任务，需要向该任务的弹性网络接口分配一个公有 IP 地址，还需要一个到互联网的路由，或一个可以将请求路由到互联网的 NAT 网关。对于私有子网中拉取容器映像的 Fargate 任务，您需要私有子网中的 NAT 网关以将请求路由到互联网。在 Amazon ECR 中托管容器映像时，您可以将 Amazon ECR 配置为使用接口 VPC 端点。在这种情况下，任务的专用 IPv4 地址将用于图像提取。有关 Amazon ECR 接口端点的更多信息，请参阅《Amazon Elastic Container Registry 用户指南》**中的 [Amazon ECR 接口 VPC 端点（AWS PrivateLink）](https://docs.aws.amazon.com/AmazonECR/latest/userguide/vpc-endpoints.html)。
以下是 Fargate 服务的 `networkConfiguration` 部分的示例：
```
"networkConfiguration": {
"awsvpcConfiguration": {
"assignPublicIp": "ENABLED",
"securityGroups": [ "sg-12345678" ],
"subnets": [ "subnet-12345678" ]
}
}
```
## 任务资源限制
AWS Fargate 上的 Linux 容器的 Amazon ECS 任务定义支持使用 `ulimits` 参数来定义要为容器设置的资源限制。
AWS Fargate 上的 Windows 的 Amazon ECS 任务定义支持使用 `ulimits` 参数来定义要为容器设置的资源限制。
Fargate 上托管的 Amazon ECS 任务使用操作系统设置的默认资源限制值，`nofile` 资源限制参数除外。`nofile` 资源限制对容器可以使用的打开文件数量设置限制。在 Fargate 上，默认的 `nofile` 软限制为 ` 65535`，硬限制为 `65535`。您可以将两个限制的值最高设置为 `1048576`。
下面是一个示例任务定义代码段，介绍如何定义 `nofile` 限制已经增加了一倍：
```
"ulimits": [
{
"name": "nofile",
"softLimit": 2048,
"hardLimit": 8192
}
]
```
有关可以调整的其他资源限制的更多信息，请参阅[资源限制](task_definition_parameters.md#container_definition_limits)。
## 日志记录
### 事件日志记录
Amazon ECS 将其采取的操作记录到 EventBridge 中。您可以使用 EventBridge 的 Amazon ECS 事件来接收有关 Amazon ECS 集群、服务和任务当前状态的近实时通知。此外，您还可以自动执行操作以响应这些事件。有关更多信息，请参阅 [使用 EventBridge 自动响应 Amazon ECS 错误](cloudwatch_event_stream.md)。
### 任务生命周期日志记录
在 Fargate 上运行的任务会发布时间戳，以便在任务生命周期的各个状态中跟踪任务。通过描述 AWS CLI 和开发工具包中的任务，可以在 AWS 管理控制台 中的任务详细信息中查看时间戳。例如，您可以使用时间戳来评估任务下载容器映像所花费的时间，并决定是应优化容器映像大小，还是使用 Seekable OCI 索引。有关容器映像实践的更多信息，请参阅 [Amazon ECS 容器映像的最佳实践](container-considerations.md)。
### 应用程序日志记录
AWS Fargate 的 Amazon ECS 任务定义支持用于日志配置的 `awslogs`、`splunk` 和 `awsfirelens` 日志驱动程序。
`awslogs` 日志驱动程序会将您的 Fargate 任务配置为向 Amazon CloudWatch Logs 信息。下面显示了任务定义中配置 `awslogs` 日志驱动程序的代码段：
```
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group" : "/ecs/fargate-task-definition",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
}
```
有关在任务定义中使用 `awslogs` 日志驱动程序以将容器日志发送到 CloudWatch Logs 的更多信息，请参阅 [将 Amazon ECS 日志发送到 CloudWatch](using_awslogs.md)。
有关任务定义中的 `awsfirelens` 日志驱动程序的更多信息，请参阅[将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner](using_firelens.md)。
有关在任务定义中使用 `splunk` 日志驱动程序的更多信息，请参阅[`splunk` 日志驱动程序](example_task_definitions.md#example_task_definition-splunk)。
## 任务存储
对于 Fargate 上托管的 Amazon ECS 任务，支持以下存储类型：
+ Amazon EBS 卷为数据密集型容器化工作负载提供经济高效、持久、高性能的块存储。有关更多信息，请参阅 [将 Amazon EBS 卷与 Amazon ECS 结合使用](ebs-volumes.md)。
+ Amazon EFS 卷（用于持久性存储）。有关更多信息，请参阅 [将 Amazon EFS 卷与 Amazon ECS 结合使用](efs-volumes.md)。
+ 绑定挂载以实现临时存储。有关更多信息，请参阅 [将绑定挂载与 Amazon ECS 结合使用](bind-mounts.md)。
## 使用 Seekable OCI（SOCI）延迟加载容器映像
Fargate 上使用 Linux 平台版本 `1.4.0` 的 Amazon ECS 任务可以使用 Seekable OCI（SOCI）来帮助更快地启动任务。借助 SOCI，容器只需花几秒钟的时间进行映像拉取即可启动，从而在后台下载映像时为环境设置和应用程序实例化提供了时间。这称为*延迟加载*。当 Fargate 启动 Amazon ECS 任务时，Fargate 会自动检测任务中是否存在映像的 SOCI 索引，并在不等待下载整个映像的情况下启动容器。
对于在没有 SOCI 索引的情况下运行的容器，容器映像将在容器启动之前完全下载。此行为在 Fargate 的所有其他平台版本上以及 Amazon EC2 实例上经 Amazon ECS 优化的 AMI 上均相同。
Seekable OCI（SOCI）是 AWS 开发的一种开源技术，它可以通过延迟加载容器映像来更快地启动容器。SOCI 的工作原理是为现有容器映像中的文件创建索引（SOCI 索引）。此索引有助于更快地启动容器，从而提供在下载整个映像之前从容器映像中提取单个文件的功能。SOCI 索引必须作为构件存储在与容器注册表中的映像相同的存储库中。您只能使用来自可信来源的 SOCI 索引，因为该索引是映像内容的权威来源。有关更多信息，请参阅[介绍用于延迟加载容器映像的 Seekable OCI](https://aws.amazon.com/about-aws/whats-new/2022/09/introducing-seekable-oci-lazy-loading-container-images/)。
需要使用 SOCI 的客户将只能使用 SOCI 索引清单 v2。之前已在 Fargate 上使用 SOCI 的现有客户可以继续使用 SOCI 索引清单 v1，但是我们强烈建议这些客户迁移到 SOCI 索引清单 v2。SOCI 索引清单 v2 会在容器映像与其 SOCI 索引之间建立显式关系，从而确保部署的一致性。
**注意事项**
如果您希望 Fargate 使用 SOCI 索引在任务中延迟加载容器映像，请考虑以下几点：
+ 只有在 Linux 平台版本 `1.4.0` 上运行的任务才能使用 SOCI 索引。不支持在 Fargate 上运行 Windows 容器的任务。
+ 支持在 X86\$164 或 ARM64 CPU 架构上运行的任务。
+ 任务定义中的容器映像必须存储在兼容的映像注册表中。以下列出了兼容的注册表：
+ Amazon ECR 私有注册表。
+ 仅支持使用 gzip 压缩或未压缩的容器映像。不支持使用 zstd 压缩的容器映像。
+ 对于 SOCI 索引清单 v2，生成 SOCI 索引清单会修改容器映像清单，因为我们为 SOCI 索引添加了注释。这将导致新的容器映像摘要。容器映像文件系统层的内容并无变化。
+ 对于 SOCI 索引清单 v2，如果容器映像已经存储在容器映像存储库中，则在生成 SOCI 索引后，您需要重新推送容器映像。重新推送容器映像不会因重复的文件系统层而增加存储成本，因为仅会上传新的清单文件。
+ 建议您尝试使用大于 250 MiB 压缩后的容器映像进行延迟加载。您不太可能看到加载较小映像的时间缩短。
+ 由于延迟加载可能会改变任务启动所需的时间，因此您可能需要对各种超时时间进行更改，例如 Elastic Load Balancing 的运行状况检查宽限期。
+ 要防止容器映像延迟加载，您需要在不附加 SOCI 索引的情况下重新推送容器映像。
**创建 Seekable OCI 索引**
对于要延迟加载的容器映像，需要创建 SOCI 索引（元数据文件），并将其与容器映像一起存储在容器映像存储库中。要创建和推送 SOCI 索引，您可以使用 GitHub 上的开源 [soci-snapshotter CLI 工具](https://github.com/awslabs/soci-snapshotter)。或者，您可以部署 CloudFormation AWS SOCI 索引构建器。这是一种无服务器解决方案，可以在将容器映像推送到 Amazon ECR 时自动创建和推送 SOCI 索引。有关解决方案和安装步骤的更多信息，请参阅 GitHub 上的 [CloudFormation AWS SOCI 索引构建器](https://awslabs.github.io/cfn-ecr-aws-soci-index-builder/)。CloudFormation AWS SOCI 索引构建器是自动开始使用 SOCI 的一种方法，而开源 SOCI 工具在索引生成方面具有更大的灵活性，并且能够将索引生成集成到持续集成和持续交付（CI/CD）管道中。
**注意**
要为映像创建 SOCI 索引，该映像必须存在于正在运行 `soci-snapshotter` 的计算机上的 containerd 映像存储中。如果映像在 Docker 映像存储中，则无法找到该映像。
**验证任务是否使用延迟加载**
要验证任务是否使用 SOCI 延迟加载，请从任务内部检查任务元数据端点。在您查询任务元数据端点版本 4 时，在您要查询的容器的默认路径中有一个 `Snapshotter` 字段。此外，`/task` 路径中每个容器都有 `Snapshotter` 字段。此字段的默认值为 `overlayfs`，如果使用 SOCI，则此字段设置为 `soci`。要验证容器映像是否附加了 SOCI 索引清单 v2，您可以使用 AWS CLI 从 Amazon ECR 检索映像索引。
```
IMAGE_REPOSITORY=r
IMAGE_TAG=latest
aws ecr batch-get-image \
--repository-name=$IMAGE_REPOSITORY \
--image-ids imageTag=$IMAGE_TAG \
--query 'images[0].imageManifest' --output text | jq -r '.manifests[] | select(.artifactType=="application/vnd.amazon.soci.index.v2+json")'
```
要验证容器映像是否附加了 SOCI 索引清单 v1，您可以使用 OCI Referrers API。
```
ACCOUNT_ID=111222333444
AWS_REGION=us-east-1
IMAGE_REPOSITORY=nginx-demo
IMAGE_TAG=latest
IMAGE_DIGEST=$(aws ecr describe-images --repository-name $IMAGE_REPOSITORY --image-ids imageTag=$IMAGE_TAG --query 'imageDetails[0].imageDigest' --output text)
ECR_PASSWORD=$(aws ecr get-login-password)
curl \
--silent \
--user AWS:$ECR_PASSWORD \
https://$ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/v2/$IMAGE_REPOSITORY/referrers/$IMAGE_DIGEST?artifactType=application%2Fvnd.amazon.soci.index.v1%2Bjson | jq -r '.'
```
# 运行 Windows 的 EC2 实例的 Amazon ECS 任务定义差异
在 EC2 Windows 实例上运行的任务并不支持所有可用的 Amazon ECS 任务定义参数。某些参数完全不受支持，而其他参数的行为则不同。
Amazon EC2 Windows 任务定义不支持以下任务定义参数：
+ `containerDefinitions`
+ `disableNetworking`
+ `dnsServers`
+ `dnsSearchDomains`
+ `extraHosts`
+ `links`
+ `linuxParameters`
+ `privileged`
+ `readonlyRootFilesystem`
+ `user`
+ `ulimits`
+ `volumes`
+ `dockerVolumeConfiguration`
+ `cpu`
我们建议为 Windows 容器指定容器级 CPU。
+ `memory`
我们建议为 Windows 容器指定容器级内存。
+ `proxyConfiguration`
+ `ipcMode`
+ `pidMode`
+ `taskRoleArn`
EC2 Windows 实例上的任务的 IAM 角色需要额外配置，但此配置很大程度上类似于在 Linux 容器实例上配置任务的 IAM 角色。有关更多信息，请参阅 [Amazon EC2 Windows 实例附加配置](task-iam-roles.md#windows_task_IAM_roles)。
# 使用控制台创建 Amazon ECS 任务定义
您可以创建任务定义，以便可以定义作为任务或服务运行的应用程序。
为外部启动类型创建任务定义时，需要使用 JSON 编辑器创建任务定义并将 `requireCapabilities` 参数设置为 `EXTERNAL`。
您可以通过使用控制台体验或指定 JSON 文件来创建任务定义。使用 JSON 编辑器时，您可以让 Amazon Q 提供建议。有关更多信息，请参阅 [使用 Amazon Q 开发者版在 Amazon ECS 控制台中提供任务定义建议](using-amazon-q.md)。
## JSON 验证
Amazon ECS 控制台 JSON 编辑器会在 JSON 文件中验证以下各项：
+ 该文件是有效的 JSON 文件。
+ 该文件不包含任何无关的键。
+ 该文件包含 `familyName` 参数。
+ `containerDefinitions` 下方至少有一个条目。
## CloudFormation 堆栈
以下行为适用于 2023 年 1 月 12 日之前在新的 Amazon ECS 控制台中创建的任务定义。
当您创建任务定义时，Amazon ECS 控制台会自动创建一个名称以 `ECS-Console-V2-TaskDefinition-` 开头的 CloudFormation 堆栈。如果您使用 AWS CLI 或 AWS SDK 取消注册任务定义，则必须手动删除任务定义堆栈。有关更多信息，请参阅《CloudFormation 用户指南》**中的[删除堆栈](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html)。
2023 年 1 月 12 日之后创建的任务定义不会为其自动创建 CloudFormation 堆栈。
## 过程
------
#### [ Amazon ECS console ]
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 在**创建新任务定义**菜单上，选择**创建新任务定义**。
1. 对于**Task definition family**（任务定义系列）中，为任务定义指定唯一名称。
1. 对于**启动类型**，选择应用程序环境。控制台默认值为 **AWS Fargate**（无服务器）。Amazon ECS 使用此值执行验证，以确保任务定义参数对基础设施类型有效。
1. 对于**操作系统/架构**，为任务选择操作系统和 CPU 架构。
要在 64 位 ARM 架构上运行任务，请选择 **Linux/ARM64**。有关更多信息，请参阅 [运行时平台](task_definition_parameters.md#runtime-platform)。
要在 Windows 容器上运行您的 **AWS Fargate** 任务，请选择受支持的 Windows 操作系统。有关更多信息，请参阅 [操作系统和架构](fargate-tasks-services.md#fargate-task-os)。
1. 对于 **Task size**（任务大小），选择要为任务预留的 CPU 和内存值。CPU 值指定为 vCPU，内存指定为 GB。
对于 Fargate 上托管的任务，下表显示了有效的 CPU 和内存组合。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/create-task-definition.html)
对于使用 EC2 实例或外部实例的任务，支持的任务 CPU 值介于 128 个 CPU 单位（0.125 vCPU）和 196608 个 CPU 单位（192 vCPU）之间。
要以 GB 为单位指定内存值，请在值的后面输入 **GB**。例如，要将**内存值**设置为 3GB，请输入 **3GB**。
**注意**
Windows 容器将忽略任务级 CPU 和内存参数。
1. 对于 **Network mode**（网络模式），选择要使用的网络模式。默认值为 **awsvpc** 模式。有关更多信息，请参阅 [Amazon ECS 任务联网](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-networking.html)。
如果您为**主机端口**在**端口映射**下选择**桥接**，请输入要为容器预留的容器实例上的端口号。
1. （可选）展开**任务角色**部分以配置任务的 AWS Identity and Access Management（IAM）角色：
1. 对于 **Task role**（任务角色），选择要分配到任务的 IAM 角色。任务 IAM 角色为要调用 AWS API 操作的任务中的容器提供权限。
1. 对于**任务执行角色**，请选择角色。
有关何时使用任务执行角色的信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。如果您不需要该角色，请选择**无**。
1. （可选）展开**任务放置**部分可添加放置约束。借助任务放置约束，您可以使用内置或自定义属性来筛选用于任务放置的容器实例。
1. （可选）展开**故障注入**部分可启用故障注入。借助故障注入功能，您可以测试应用程序对某些受损场景的响应。
1. 对于在您的任务定义中定义的每个容器，请完成以下步骤。
1. 对于 **Name**（名称），输入容器的名称。
1. 对于 **Image URI**（映像 URI），输入用于启动容器的映像。Amazon ECR 公开映像浏览馆注册表中的映像只能使用 Amazon ECR 公开注册表名称来指定。例如，如果 `public.ecr.aws/ecs/amazon-ecs-agent:latest` 已指定，则使用 Amazon ECR 公开映像浏览馆上托管的 Amazon Linux 容器。对于所有其他存储库，请使用 `repository-url/image:tag` 或 `repository-url/image@digest` 格式指定存储库。
1. 如果您的映像位于 Amazon ECR 之外的私有注册表中，请在**私有注册表**下开启**私有注册表身份验证**。然后，在 **Secrets Manager ARN 或名称**中，输入密钥的 Amazon 资源名称（ARN）。
1. 对于**必需容器**，如果您的任务定义中定义了两个或更多容器，则可以指定是否应将该容器视为必需容器。当一个容器被标记为**必需**时，则在该容器停止时任务将停止。每个任务定义都必须至少包含一个关键容器。
1. 端口映射可让容器访问主机容器上的端口以发送或接收流量。在 **Port mappings**（端口映射）下，请执行以下操作之一：
+ 当您使用 **awsvpc** 网络模式时，对于 **Container port**（容器端口）和 **Protocol**（协议），选择要用于容器的端口映射。
+ 当您使用 **bridge** 网络模式时，对于 **Container port**（容器端口）和 **Protocol**（协议），选择要用于容器的端口映射。
选择 **Add more port mappings**（添加更多端口映射）以指定其他容器端口映射。
1. 要为容器提供对其根文件系统的只读访问权，对于**只读根文件系统**，选择**只读**。
1. （可选）要在**资源分配限制**下定义与任务级值不同的容器级 CPU、GPU 和内存限制，请执行以下操作：
+ 对于 **CPU**，输入 Amazon ECS 容器代理为容器预留的 CPU 单元数。
+ 对于 **GPU**，输入容器实例的 GPU 单元数。
支持 GPU 的 Amazon EC2 实例为每个 GPU 配备 1 个 GPU 单元。有关更多信息，请参阅 [适用于 GPU 工作负载的 Amazon ECS 任务定义](ecs-gpu.md)。
+ 对于**内存硬限制**，输入要提供给容器的内存量（以 GB 为单位）。如果容器试图超出硬限制，则容器将停止。
+ Docker 20.10.0 或更高版本进程守护程序将为容器预留最少 6 兆字节（MiB）的内存，因此，请不要为容器指定 6MiB 以下的内存。
Docker 19.03.13-ce 或较早版本进程守护程序将为容器预留最少 4MiB 的内存，因此，请不要为容器指定 4MiB 以下的内存。
+ 对于**内存软限制**，输入要为容器预留的内存软限制（以 GB 为单位）。
当系统内存处于争用状态时，Docker 会尝试将容器内存保持在此软限制范围内。如果您未指定任务级内存，则必须为**内存硬限制**和**内存软限制**中的一个或两个指定非零整数。如果同时指定两者，则**内存硬限制**必须大于**内存软限制**。
Windows 容器不支持此功能。
1. （可选）展开**环境变量**部分来指定要注入到容器中的环境变量。您可以使用键值对单独指定环境变量，也可以通过指定 Amazon S3 存储桶中托管的环境变量文件来批量指定环境变量。有关如何设置环境变量文件的格式的信息，请参阅[将单个环境变量传递给 Amazon ECS 容器](taskdef-envfiles.md)。
当您为密钥存储指定环境变量时，请在**密钥**中输入密钥名称。然后，在 **ValueFrom** 中，输入 Systems Manager Parameter Store 密钥或 Secrets Manager 密钥的完整 ARN
1. （可选）选择 **Use log collection**（使用日志收集）选项来指定日志配置。对于每个可用的日志驱动程序，都有日志驱动程序选项要指定。默认选项将容器日志发送到 Amazon CloudWatch Logs。其他日志驱动程序选项都使用 AWS FireLens 进行配置。有关更多信息，请参阅 [将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner](using_firelens.md)。
下面更详细地介绍了每个容器日志目标。
+ **Amazon CloudWatch** – 将任务配置为将容器日志发送到 CloudWatch Logs。提供了默认的日志驱动程序选项，用于代表您创建 CloudWatch 日志组。要指定其他日志组名称，请更改驱动程序选项值。
+ **将日志导出到 Splunk** – 将任务配置为将容器日志发送到将日志发送到远程服务的 Splunk 驱动程序。您必须输入 Splunk Web 服务的 URL。Splunk 令牌指定为密钥选项，因为它可能被视为敏感数据。
+ **将日志导出到 Amazon Data Firehose** – 将任务配置为将容器日志发送到 Firehose。提供了默认的日志驱动程序选项，该选项将日志发送到 Firehose 传输流。要指定其他传输流名称，请更改驱动程序选项值。
+ **将日志导出到 Amazon Kinesis Data Streams** – 将任务配置为将容器日志发送到 Kinesis Data Streams。提供了默认的日志驱动程序选项，该选项将日志发送到 Kinesis Data Streams 流。要指定其他传输流名称，请更改驱动程序选项值。
+ **将日志导出到 Amazon OpenSearch Service** – 将任务配置为将容器日志发送到 OpenSearch Service 域。必须提供日志驱动程序选项。
+ **将日志导出到 Amazon S3** – 将任务配置为将容器日志发送到 Amazon S3 存储桶。提供了默认的日志驱动程序选项，但您必须指定有效的 Amazon S3 存储桶名称。
1. （可选）配置其他容器参数。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/create-task-definition.html)
1. （可选）选择 **Add more containers**（添加更多容器）将其他容器添加到任务定义。
1. （可选）**存储**部分用于扩展 Fargate 上托管的任务的短暂存储量。您还可以使用此部分为任务添加数据卷配置。
1. 要将可用的短暂存储扩展到超出您的 Fargate 任务的默认值 20 gibibytes (GiB)，请在 **Amount**（量）中输入一个最高为 200 GiB 的值。
1. （可选）要为任务定义添加数据卷配置，选择**添加卷**，然后按照以下步骤操作。
1. 对于 **Volume name**（卷名称），输入数据卷的名称。创建容器挂载点时，将使用数据卷名称。
1. 对于**卷配置**，请选择是要在创建任务定义时还是在部署期间配置卷。
**注意**
可以在创建任务定义时配置的卷包括绑定挂载、Docker、Amazon EFS 和适用于 Windows File Server 的 Amazon FSx。运行任务或创建或更新服务时可以在部署时配置的卷包括 Amazon EBS。
1. 对于**卷类型**，选择与所选配置类型兼容的卷类型，然后再配置该卷类型。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/create-task-definition.html)
1. 要从另一个容器中添加卷，请选择**从中添加卷**，然后配置以下内容：
+ 对于**容器**，选择容器。
+ 对于**来源**，选择包含要装载的卷的容器。
+ 对于**只读**，选择容器是否具有对卷的只读访问权。
1. （可选）要使用 AWS Distro for OpenTelemetry 集成配置应用程序跟踪和指标收集设置，请展开**监控**，然后选择**使用指标收集**来收集任务的指标并将其发送到或 Amazon CloudWatch 或 Amazon Managed Service for Prometheus。选择此选项后，Amazon ECS 会创建 AWS Distro for OpenTelemetry 容器附加，该附加已预先配置为发送应用程序指标。有关更多信息，请参阅 [使用应用程序指标关联 Amazon ECS 应用程序性能](metrics-data.md)。
1. 选中 **Amazon CloudWatch** 后，您的自定义应用程序指标将作为自定义指标路由到 CloudWatch。有关更多信息，请参阅 [将应用程序指标导出到 Amazon CloudWatch](application-metrics-cloudwatch.md)。
**重要**
将应用程序指标导出到 Amazon CloudWatch 时，您的任务定义需要具有所需权限的任务 IAM 角色。有关更多信息，请参阅 [AWS Distro for OpenTelemetry 与 Amazon CloudWatch 集成所需的 IAM 权限](application-metrics-cloudwatch.md#application-metrics-cloudwatch-iam)。
1. 当您选择 **Amazon Managed Service for Prometheus（Prometheus 库埋点）**时，您的任务级 CPU、内存、网络和存储指标以及自定义应用程序指标都将路由到 Amazon Managed Service for Prometheus。对于**工作空间远程写入端点**，为 Prometheus 工作空间输入远程写入端点 URL。对于**抓取目标**，输入 AWS Distro for OpenTelemetry 收集器可用来抓取指标数据的主机和端口。有关更多信息，请参阅 [将应用程序指标导出到 Amazon Managed Service for Prometheus](application-metrics-prometheus.md)。
**重要**
将应用程序指标导出到 Amazon Managed Service for Prometheus 时，您的任务定义需要具有所需权限的任务 IAM 角色。有关更多信息，请参阅 [AWS Distro for OpenTelemetry 与 Amazon Managed Service for Prometheus 集成所需的 IAM 权限](application-metrics-prometheus.md#application-metrics-prometheus-iam)。
1. 当您选择 **Amazon Managed Service for Prometheus（OpenTelemetry 分析）**时，您的任务级 CPU、内存、网络和存储指标以及自定义应用程序指标都将路由到 Amazon Managed Service for Prometheus。对于**工作空间远程写入端点**，为 Prometheus 工作空间输入远程写入端点 URL。有关更多信息，请参阅 [将应用程序指标导出到 Amazon Managed Service for Prometheus](application-metrics-prometheus.md)。
**重要**
将应用程序指标导出到 Amazon Managed Service for Prometheus 时，您的任务定义需要具有所需权限的任务 IAM 角色。有关更多信息，请参阅 [AWS Distro for OpenTelemetry 与 Amazon Managed Service for Prometheus 集成所需的 IAM 权限](application-metrics-prometheus.md#application-metrics-prometheus-iam)。
1. （可选）展开**标签**部分将标签（作为键值对）添加到任务定义中。
+ [添加标签] 选择 **Add tag**（添加标签），然后执行以下操作：
+ 对于 **Key（键）**，输入键名称。
+ 对于**值**，输入键值。
+ [删除标签] 在标签旁，选择**删除标签**。
1. 选择**创建**以注册任务定义。
------
#### [ Amazon ECS console JSON editor ]
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 在**创建新的任务定义**菜单上，选择**使用 JSON 创建新的任务定义**。
1. 在 JSON 编辑器框中，编辑您的 JSON 文件，
JSON 必须通过 [JSON 验证](#json-validate-for-create) 中指定的验证检查。
1. 选择**创建**。
------
# 使用 Amazon Q 开发者版在 Amazon ECS 控制台中提供任务定义建议
当您在 Amazon ECS 控制台中使用 JSON 编辑器创建任务定义时，您可以使用 Amazon Q 开发者版为您的任务定义提供人工智能生成的代码建议。
您可以使用内联聊天功能让 Amazon Q 开发者版使用对话界面生成、解释或重构任务定义 JSON。您可以在任务定义的任何位置插入生成的建议，并接受或拒绝提出的更改。Amazon ECS 还增强了现有的内联建议功能，使其能够利用 Amazon Q 开发者版。
当您使用 JSON 编辑器创建任务定义时，可以让 Amazon Q 开发者版提供建议，帮助您更快地创建任务定义。您可以获得基于属性的内联建议，也可以使用 Amazon Q 开发者版建议自动完成整个示例代码块。
您可以在支持 Amazon Q 开发者版的区域使用此功能。有关更多信息，请参阅[按区域划分的 AWS 服务](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。
## 先决条件
以下是先决条件：
+ 除了控制台权限之外，在控制台中创建任务定义的用户还必须拥有 `codewhisperer:GenerateRecommendations` 权限才能获得建议，拥有 `q:SendMessage` 权限才能使用内联聊天。有关更多信息，请参阅 [使用 Amazon Q 开发者版在控制台中提供建议所需的权限](console-permissions.md#amazon-q-permission)。
## 过程
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 在**创建新的任务定义**菜单上，选择**使用 JSON 创建新的任务定义**。
此时将打开**创建任务定义**页面。
控制台提供以下默认模板。
```
{
"requiresCompatibilities": [
"FARGATE"
],
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
"essential": true
}
],
"volumes": [],
"networkMode": "awsvpc",
"memory": "3 GB",
"cpu": "1 vCPU",
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```
1. 在 Amazon Q 内联建议弹出窗口中，选择**允许**。
如果您关闭弹出窗口，则可以在齿轮图标下启用 Amazon Q。
1. 在 JSON 编辑器框中，编辑 JSON 文档。
要让 Amazon Q 创建并填充参数，请输入一条注释说明要添加的内容。在下面的示例中，注释会让 Amazon Q 生成粗体行。
```
{
"requiresCompatibilities": [
"FARGATE"
],
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
"essential": true
},
// add an nginx container using an image from Public ECR, with port 80 open, and send logs to CloudWatch log group "myproxy"
{
"name": "nginx",
"image": "public.ecr.aws/nginx/nginx:latest",
"essential": true,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "myproxy",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "nginx"
}
}
}
],
"volumes": [],
"networkMode": "awsvpc",
"memory": "3 GB",
"cpu": "1 vCPU",
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```
1. 要使用内联聊天功能，您可以突出显示这些行，然后选择星形图标。
此时将显示 Amazon Q 开发者版聊天框。
输入您的请求。
Amazon Q 开发者版会生成 JSON 文件，然后对其进行更新。
要接受更改，请选择**全部接受**
1. 选择**创建**。
# 使用控制台更新 Amazon ECS 任务定义
一个*任务定义修订*是当前任务定义的副本，新的参数值将替换现有参数值。您未修改的所有参数都在新修订版中。
要更新任务定义，请创建任务定义修订。如果任务定义用于服务中，则您必须更新该服务才能使用更新的任务定义。
创建修订版时，可以修改以下容器属性和环境属性。
+ 容器映像 URI
+ 端口映射
+ 环境变量
+ 基础设施要求
+ 任务大小
+ 容器大小
+ 任务 角色
+ 任务执行 角色
+ 卷和容器挂载点
+ 私有注册表
使用 JSON 编辑器时，您可以让 Amazon Q 提供建议。有关更多信息，请参阅 [使用 Amazon Q 开发者版在 Amazon ECS 控制台中提供任务定义建议](using-amazon-q.md)。
## JSON 验证
Amazon ECS 控制台 JSON 编辑器会在 JSON 文件中验证以下各项：
+ 该文件是有效的 JSON 文件
+ 该文件不包含任何无关的键
+ 该文件包含 `familyName` 参数
+ `containerDefinitions` 下方至少有一个条目
## 过程
------
#### [ Amazon ECS console ]
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 从导航栏中，选择包含您的任务定义的地区。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 选择任务定义。
1. 选择任务定义修订版，然后选择**创建新的修订**、**创建新的修订**。
1. 在 **Create new task definition revision**（创建新任务定义修订版）页面上，进行更改。例如，要更改现有的容器定义（如容器映像、内存限制或端口映射），请选择容器，进行更改，然后进行更改。您可以将任务定义兼容性更新为 **AWS Fargate**、**托管实例**或 **Amazon EC2 实例**。
1. 验证信息，然后选择**更新**。
1. 如果您的任务定义已用于某个服务，请使用更新后的任务定义来更新该服务。有关更多信息，请参阅 [更新 Amazon ECS 服务](update-service-console-v2.md)。
------
#### [ Amazon ECS console JSON editor ]
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 选择 **Create new revision**（创建新的修订）、**Create new revision with JSON**（使用 JSON 创建新的修订）。
1. 在 JSON 编辑器框中，编辑您的 JSON 文件，
JSON 必须通过 [JSON 验证](#json-validate-for-update) 中指定的验证检查。
1. 选择**创建**。
------
# 使用控制台注销 Amazon ECS 任务定义修订
您可以注销任务定义修订，这样一来，当您想运行任务或更新服务时，任务定义修订将不再显示在 `ListTaskDefinition` API 调用或控制台中。
在注销任务定义修订后，它将立即被标记为 `INACTIVE`。现有任务和服务引用 `INACTIVE` 任务定义修订版将继续运行，而不会中断。引用 `INACTIVE` 任务定义修订仍可通过修改服务的预期数目来纵向扩展或缩减。
您不能使用 `INACTIVE` 任务定义修订版以运行新任务或创建新服务。您也无法更新现有服务以引用 `INACTIVE` 任务定义修订版（即使在取消注册后，这些限制尚未生效的情况下，可能会有长达10分钟的窗口）。
**注意**
注销任务系列中的所有修订后，任务定义系列将移至 `INACTIVE` 列表。添加 `INACTIVE` 任务定义的新修订会将任务定义系列移回 `ACTIVE` 列表。
在这个时候,`INACTIVE` 任务定义修订版本仍然可以无限期地在您的账户中发现。但是，此行为可能会在将来发生变化。因此，您不应该依赖 `INACTIVE` 任务定义修订版，这些修订版将持续存在于任何相关任务和服务的生命周期之外。
## CloudFormation 堆栈
以下行为适用于 2023 年 1 月 12 日之前在新的 Amazon ECS 控制台中创建的任务定义。
当您创建任务定义时，Amazon ECS 控制台会自动创建一个名称以 `ECS-Console-V2-TaskDefinition-` 开头的 CloudFormation 堆栈。如果您使用 AWS CLI 或 AWS SDK 取消注册任务定义，则必须手动删除任务定义堆栈。有关更多信息，请参阅《CloudFormation 用户指南》**中的[删除堆栈](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-console-delete-stack.html)。
2023 年 1 月 12 日之后创建的任务定义不会为其自动创建 CloudFormation 堆栈。
## 过程
**取消注册新的任务定义（Amazon ECS 控制台）**
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 从导航栏中，选择包含您的任务定义的区域。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 在 **Task definitions**（任务定义）页面上，选择包含要取消注册的一个或多个修订的任务定义系列。
1. 在**任务定义名称**页面上，选择要删除的修订，然后依次选择**操作**、**取消注册**。
1. 验证 **Deregister**（注销）窗口中的信息，然后选择 **Deregister**（注销）以完成操作。
# 使用控制台删除 Amazon ECS 任务定义修订
当 Amazon ECS 中不再需要特定的任务定义修订时，您可以删除该任务定义修订。
删除任务定义修订时，它将立即从 `INACTIVE` 转换为 `DELETE_IN_PROGRESS`。引用 `DELETE_IN_PROGRESS` 任务定义修订的现有任务和服务将继续运行，而不会中断。
您不能使用 `DELETE_IN_PROGRESS` 任务定义修订来运行新任务或创建新服务。您也无法更新现有服务以引用 `DELETE_IN_PROGRESS` 任务定义修订。
删除所有 `INACTIVE` 任务定义修订版时，任务定义名称不会显示在控制台中，也不会在 API 中返回。如果任务定义修订版处于 `DELETE_IN_PROGRESS` 状态，任务定义名称会显示在控制台中，并且在 API 中返回。任务定义名称由 Amazon ECS 保留，并且在下次使用该名称创建任务定义时，修订版本会增加。
## 可以阻止删除的 Amazon ECS 资源
当有任何依赖于任务定义修订的 Amazon ECS 资源时，将无法完成任务定义删除请求。以下资源可能会阻止任务定义被删除：
+ Amazon ECS 独立任务 – 需要任务定义才能使任务保持正常运行状态。
+ Amazon ECS 服务任务 – 需要任务定义才能使任务保持正常运行状态。
+ Amazon ECS 服务部署和任务集 – 在 Amazon ECS 部署或任务集启动扩展事件时，需要任务定义。
如果您的任务定义仍处于 `DELETE_IN_PROGRESS` 状态，则可以使用控制台或 AWS CLI 来识别，然后停止阻止删除任务定义的资源。
### 移除被阻止的资源后删除任务定义
在您移除阻止删除任务定义的资源后，将适用以下规则：
+ Amazon ECS 任务：任务停止后，删除任务定义最多可能需要 1 小时才能完成。
+ Amazon ECS 服务部署和任务集 – 删除部署或任务集后，任务定义的删除最长可能需要 24 小时才能完成。
## 过程
**删除任务定义（Amazon ECS 控制台）**
在删除任务定义修订之前，您必须将其取消注册。有关更多信息，请参阅 [使用控制台注销 Amazon ECS 任务定义修订](deregister-task-definition-v2.md)。
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 从导航栏中，选择包含您的任务定义的区域。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 在**任务定义**页面上，选择包含要删除的一个或多个修订的任务定义系列。
1. 在**任务定义名称**页面上，选择要删除的修订，然后依次选择**操作**、**删除**。
如果**删除**不可用，您必须注销任务定义。
1. 验证**删除**确认框中的信息，然后选择**删除**以完成操作。
# Amazon ECS 任务定义应用场景
了解如何为各种 AWS 服务和功能编写任务定义的更多信息。
根据您的工作负载，需要设置某些任务定义参数。另外，对于 EC2，必须选择专为工作负载设计的特定实例。
**Topics**
+ [
# 适用于 GPU 工作负载的 Amazon ECS 任务定义
](ecs-gpu.md)
+ [
# 适用于视频转码工作负载的 Amazon ECS 任务定义
](ecs-vt1.md)
+ [
# 适用于 AWS 神经元机器学习工作负载的 Amazon ECS 任务定义
](ecs-inference.md)
+ [
# 适用于深度学习实例的 Amazon ECS 任务定义
](ecs-dl1.md)
+ [
# 适用于 64 位 ARM 工作负载的 Amazon ECS 任务定义
](ecs-arm64.md)
+ [
# 将 Amazon ECS 日志发送到 CloudWatch
](using_awslogs.md)
+ [
# 将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner
](using_firelens.md)
+ [
# 在 Amazon ECS 中使用非 AWS 容器映像
](private-auth.md)
+ [
# 使用容器重启策略重启 Amazon ECS 任务中的单个容器
](container-restart-policy.md)
+ [
# 将敏感数据传递给 Amazon ECS 容器
](specifying-sensitive-data.md)
# 适用于 GPU 工作负载的 Amazon ECS 任务定义
当您使用支持 GPU 的容器实例创建集群时，Amazon ECS 支持使用 GPU 的工作负载。使用 p2、p3、p5、g3、g4 和 g5 实例类型的基于 GPU 的 Amazon EC2 容器实例提供对 NVIDIA GPU 的访问权限。有关更多信息，请参阅《Amazon EC2 示例类型指南》中的 [Linux 加速型计算实例](https://docs.aws.amazon.com/ec2/latest/instancetypes/ac.html)**。
Amazon ECS 提供了经 GPU 优化的 AMI，后者附带了预配置的 NVIDIA 内核驱动程序和 Docker GPU 运行时。有关更多信息，请参阅 [经 Amazon ECS 优化的 Linux AMI](ecs-optimized_AMI.md)。
您可以在任务定义中指定多个 GPU，以便在容器级别考虑任务放置。Amazon ECS 将安排支持 GPU 的可用容器实例，并将物理 GPU 固定到正确的容器以获得最佳性能。
支持以下基于 GPU 的 Amazon EC2 实例类型。有关更多信息，请参阅 [Amazon EC2 P2 实例](https://aws.amazon.com/ec2/instance-types/p2/)、[Amazon EC2 P3 实例](https://aws.amazon.com/ec2/instance-types/p3/)、[Amazon EC2 P4d 实例](https://aws.amazon.com/ec2/instance-types/p4/)、[Amazon EC2 P5 实例](https://aws.amazon.com/ec2/instance-types/p5/)、[Amazon EC2 G3 实例](https://aws.amazon.com/ec2/instance-types/g3/)、[Amazon EC2 G4 实例](https://aws.amazon.com/ec2/instance-types/g4/)、[Amazon EC2 G5 实例](https://aws.amazon.com/ec2/instance-types/g5/)、[Amazon EC2 G6 实例](https://aws.amazon.com/ec2/instance-types/g6/)和[Amazon EC2 G6e 实例](https://aws.amazon.com/ec2/instance-types/g6e/)。
| 实例类型 | GPU | GPU 内存（GiB） | vCPU | 内存（GiB） |
| --- | --- | --- | --- | --- |
| p3.2xlarge | 1 | 16 | 8 | 61 |
| p3.8xlarge | 4 | 64 | 32 | 244 |
| p3.16xlarge | 8 | 128 | 64 | 488 |
| p3dn.24xlarge | 8 | 256 | 96 | 768 |
| p4d.24xlarge | 8 | 320 | 96 | 1152 |
| p5.48xlarge | 8 | 640 | 192 | 2048 |
| g3s.xlarge | 1 | 8 | 4 | 30.5 |
| g3.4xlarge | 1 | 8 | 16 | 122 |
| g3.8xlarge | 2 | 16 | 32 | 244 |
| g3.16xlarge | 4 | 32 | 64 | 488 |
| g4dn.xlarge | 1 | 16 | 4 | 16 |
| g4dn.2xlarge | 1 | 16 | 8 | 32 |
| g4dn.4xlarge | 1 | 16 | 16 | 64 |
| g4dn.8xlarge | 1 | 16 | 32 | 128 |
| g4dn.12xlarge | 4 | 64 | 48 | 192 |
| g4dn.16xlarge | 1 | 16 | 64 | 256 |
| g5.xlarge | 1 | 24 | 4 | 16 |
| g5.2xlarge | 1 | 24 | 8 | 32 |
| g5.4xlarge | 1 | 24 | 16 | 64 |
| g5.8xlarge | 1 | 24 | 32 | 128 |
| g5.16xlarge | 1 | 24 | 64 | 256 |
| g5.12xlarge | 4 | 96 | 48 | 192 |
| g5.24xlarge | 4 | 96 | 96 | 384 |
| g5.48xlarge | 8 | 192 | 192 | 768 |
| g6.xlarge | 1 | 24 | 4 | 16 |
| g6.2xlarge | 1 | 24 | 8 | 32 |
| g6.4xlarge | 1 | 24 | 16 | 64 |
| g6.8xlarge | 1 | 24 | 32 | 128 |
| g6.16.xlarge | 1 | 24 | 64 | 256 |
| g6.12xlarge | 4 | 96 | 48 | 192 |
| g6.24xlarge | 4 | 96 | 96 | 384 |
| g6.48xlarge | 8 | 192 | 192 | 768 |
| g6.metal | 8 | 192 | 192 | 768 |
| gr6.4xlarge | 1 | 24 | 16 | 128 |
| g6e.xlarge | 1 | 48 | 4 | 32 |
| g6e.2xlarge | 1 | 48 | 8 | 64 |
| g6e.4xlarge | 1 | 48 | 16 | 128 |
| g6e.8xlarge | 1 | 48 | 32 | 256 |
| g6e16.xlarge | 1 | 48 | 64 | 512 |
| g6e12.xlarge | 4 | 192 | 48 | 384 |
| g6e24.xlarge | 4 | 192 | 96 | 768 |
| g6e48.xlarge | 8 | 384 | 192 | 1536 |
| gr6.8xlarge | 1 | 24 | 32 | 256 |
您可以通过查询 AWS Systems Manager Parameter Store API 来检索经 Amazon EKS 优化的 AMI 的亚马逊机器映像（AMI）ID。使用此参数，您无需手动查找经 Amazon ECS 优化的 AMI ID。有关 Systems Manager Parameter Store API 的更多信息，请参阅 [GetParameter](https://docs.aws.amazon.com/systems-manager/latest/APIReference/API_GetParameter.html)。您使用的用户必须具有 `ssm:GetParameter` IAM 权限才能检索经 Amazon ECS 优化的 AMI 元数据。
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
```
# 将 GPU 与 Amazon ECS 托管实例结合使用
Amazon ECS 托管实例通过以下 Amazon EC2 实例类型对机器学习、高性能计算和视频处理等工作负载支持 GPU 加速计算。有关 Amazon ECS 托管实例支持的实例类型的更多信息，请参阅[Amazon ECS 托管实例实例类型](managed-instances-instance-types.md)。
下面是 Amazon ECS 托管实例上支持的部分基于 GPU 的实例类型：
+ `g4dn`：由 NVIDIA T4 GPUs 提供支持，适用于机器学习推理、计算机视觉和图形密集型应用程序。
+ `g5`：由 NVIDIA A10G GPUs 提供支持，为图形密集型应用程序和机器学习工作负载提供更高性能。
+ `p3`：由 NVIDIA V100 GPUs 提供支持，专为高性能计算和深度学习训练而设计。
+ `p4d`：由 NVIDIA A100 GPUs 提供支持，为机器学习训练和高性能计算提供最高性能。
当您将支持 GPU 的实例类型与 Amazon ECS 托管实例一起使用时，NVIDIA 驱动程序和 CUDA 工具包已预先安装在实例上，从而更轻松地运行 GPU 加速的工作负载。
## 选择支持 GPU 的实例
要为您的 Amazon ECS 托管实例工作负载选择选择 GPU 的实例类型，请使用容量提供程序的启动模板中的 `instanceRequirements` 对象。以下代码段展示了可用于选择支持 GPU 的实例的属性。
```
{
"instanceRequirements": {
"acceleratorTypes": "gpu",
"acceleratorCount": 1,
"acceleratorManufacturers": ["nvidia"]
}
}
```
以下代码段展示了可用于在启动模板中指定支持 GPU 的实例类型的属性。
```
{
"instanceRequirements": {
"allowedInstanceTypes": ["g4dn.xlarge", "p4de.24xlarge"]
}
}
```
## 支持 GPU 的容器映像
要在容器中使用 GPU，您需要使用包含必要 GPU 库和工具的容器映像。NVIDIA 提供了一些预构建的容器映像，您可以将其用作 GPU 工作负载的基础，包括：
+ `nvidia:cuda`：包含用于 GPU 计算的 CUDA 工具包的基础映像。
+ `tensorflow/tensorflow:latest-gpu`：支持 GPU 的 TensorFlow。
+ `pytorch/pytorch:latest-cuda`：支持 GPU 的 PyTorch。
有关涉及使用 GPU 的 Amazon ECS 托管实例的 Amazon ECS 任务定义示例，请参阅[在 Amazon ECS 任务定义中指定 GPU 数](ecs-gpu-specifying.md)。
## 注意事项
**注意**
已弃用对 g2 实例系列类型的支持。
Amazon ECS 经 GPU 优化的 AMI 的 `20230912` 版本之前的版本仅支持 p2 实例系列类型。如果您需要继续使用 p2 实例，请参阅 [如果您需要 P2 实例该怎么办](#p2-instance)。
这两种实例系列类型上的 NVIDIA/CUDA 驱动程序的就地更新将导致 GPU 工作负载出现潜在故障。
开始在 Amazon ECS 上使用 GPU 之前，我们建议您考虑以下事项。
+ 您的集群可以包含 GPU 和非 GPU 容器实例的组合。
+ 您可以在外部实例上运行 GPU 工作负载。当向集群注册外部实例时，请确保安装脚本中包含 `--enable-gpu` 标记。有关更多信息，请参阅 [将外部实例注册到 Amazon ECS 集群](ecs-anywhere-registration.md)。
+ 您必须在代理配置文件中将 `ECS_ENABLE_GPU_SUPPORT` 设置为 `true`。有关更多信息，请参阅 [Amazon ECS 容器代理配置](ecs-agent-config.md)。
+ 在运行任务或创建服务时，您可以在配置任务放置约束时使用实例类型属性，以确定要在其上启动任务的容器实例。通过这样做，您可以更有效地使用您的资源。有关更多信息，请参阅 [Amazon ECS 如何将任务放置在容器实例上](task-placement.md)。
以下示例在您的默认集群中的 `g4dn.xlarge` 容器实例上启动一个任务。
```
aws ecs run-task --cluster default --task-definition ecs-gpu-task-def \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == g4dn.xlarge" --region us-east-2
```
+ 对于在容器定义中指定了 GPU 资源要求的每个容器，Amazon ECS 将容器运行时设置为 NVIDIA 容器运行时。
+ NVIDIA 容器运行时需要在容器中设置一些环境变量才能工作。有关这些环境变量的列表，请参阅[使用 Docker 的专用配置](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html?highlight=environment%20variable)。Amazon ECS 设置 `NVIDIA_VISIBLE_DEVICES` 环境变量值设置为 Amazon ECS 分配给容器的 GPU 设备 ID 列表。对于其他必需的环境变量，Amazon ECS 不会对其进行设置。因此，请确保容器映像对其进行设置，或者在容器定义中对其进行设置。
+ `20230929` 版本和更高版本的 Amazon ECS 经 GPU 优化的 AMI 支持 p5 实例类型系列。
+ `20230913` 版本和更高版本的 Amazon ECS 经 GPU 优化的 AMI 支持 g4 实例类型系列。有关更多信息，请参阅 [经 Amazon ECS 优化的 Linux AMI](ecs-optimized_AMI.md)。它在 Amazon ECS 控制台的“创建集群”工作流中不受支持。要使用这些实例类型，您必须使用 Amazon EC2 控制台、AWS CLI 或 API 并手动将实例注册到您的集群。
+ p4d.24xlarge 实例类型仅适用于 CUDA 11 或更高版本。
+ Amazon ECS 经 GPU 优化的 AMI 启用了 IPv6，这会导致使用 `yum` 时出现问题。可以通过配置 `yum` 将 IPv4 与以下命令结合使用。
```
echo "ip_resolve=4" >> /etc/yum.conf
```
+ 当您构建不使用 NVIDIA/CUDA 基础映像的容器映像时，必须设置 `NVIDIA_DRIVER_CAPABILITIES` 容器运行时变量设置为以下值之一：
+ `utility,compute`
+ `all`
有关如何设置变量的信息，请参阅 NVIDIA 网站上的[控制 NVIDIA 容器运行时](https://sarus.readthedocs.io/en/stable/user/custom-cuda-images.html#controlling-the-nvidia-container-runtime)
+ Windows 容器不支持 GPU。
# 启动适用于 Amazon ECS 的 GPU 容器实例
要在 Amazon EC2 上的 Amazon ECS 上使用 GPU 实例，您需要创建启动模板、用户数据文件，然后启动实例。
然后，您可以运行使用为 GPU 配置的任务定义的任务。
## 使用启动模板
您可以创建启动模板。
+ 创建将经 Amazon ECS 优化的 GPU AMI ID 用于 AMI 的启动模板。有关如何创建启动模板的信息，请参阅《Amazon EC2 用户指南》中的[使用您定义的参数创建新启动模板](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#create-launch-template-define-parameters)**。
将上一步中的 AMI ID 用于**亚马逊机器映像**。有关如何使用 Systems Manager 参数指定 AMI ID 的信息，请参阅《Amazon EC2 用户指南》中的[在启动模板中指定 Systems Manager 参数](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#use-an-ssm-parameter-instead-of-an-ami-id)**。
将以下各项添加到启动模板中的**用户数据**中。将 *cluster-name* 替换为您集群的名称。
```
#!/bin/bash
echo ECS_CLUSTER=cluster-name >> /etc/ecs/ecs.config;
echo ECS_ENABLE_GPU_SUPPORT=true >> /etc/ecs/ecs.config
```
## 使用 AWS CLI
您可以使用 AWS CLI 启动容器实例。
1. 创建名为 `userdata.toml` 的文件。此文件会用于实例用户数据。将 *cluster-name* 替换为您集群的名称。
```
#!/bin/bash
echo ECS_CLUSTER=cluster-name >> /etc/ecs/ecs.config;
echo ECS_ENABLE_GPU_SUPPORT=true >> /etc/ecs/ecs.config
```
1. 运行以下命令以获取 GPU AMI ID。您将在以下步骤中使用此 ID。
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2/gpu/recommended --region us-east-1
```
1. 运行以下命令来启动 GPU 实例。请记得替换以下参数：
+ 用您的实例将在其中启动的私有或公有子网的 ID 替换*子网*。
+ 将 *gpu\$1ami* 替换为上一步中的 AMI ID。
+ 将 *t3.large* 替换为您要使用的实例类型。
+ 将 *region* 替换为区域代码。
```
aws ec2 run-instances --key-name ecs-gpu-example \
--subnet-id subnet \
--image-id gpu_ami \
--instance-type t3.large \
--region region \
--tag-specifications 'ResourceType=instance,Tags=[{Key=GPU,Value=example}]' \
--user-data file://userdata.toml \
--iam-instance-profile Name=ecsInstanceRole
```
1. 运行以下命令，以验证容器实例是否注册到集群。在运行此命令时，请记得替换以下参数：
+ 将 *cluster* 替换为您的集群名称。
+ 将 *region* 替换为区域代码。
```
aws ecs list-container-instances --cluster cluster-name --region region
```
# 在 Amazon ECS 任务定义中指定 GPU 数
要在容器实例和 Docker GPU 运行时上使用 GPU，请确保在任务定义中指定容器所需的 GPU 数量。由于已放置支持 GPU 的容器，Amazon ECS 容器代理会将所需数量的物理 GPU 固定到相应的容器中。为某个任务中的所有容器预留的 GPU 的数量不能超过该任务在其上启动的容器实例的可用 GPU 的数量。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
**重要**
如果任务定义中未指定 GPU 要求，则任务将使用原定设置 Docker 运行时。
下面显示了任务定义中的 GPU 要求的 JSON 格式：
```
{
"containerDefinitions": [
{
...
"resourceRequirements" : [
{
"type" : "GPU",
"value" : "2"
}
],
},
...
}
```
以下示例演示了指定 GPU 要求的 Docker 容器的语法。此容器使用两个 GPU，运行 `nvidia-smi` 实用程序，然后退出。
```
{
"containerDefinitions": [
{
"memory": 80,
"essential": true,
"name": "gpu",
"image": "nvidia/cuda:11.0.3-base",
"resourceRequirements": [
{
"type":"GPU",
"value": "2"
}
],
"command": [
"sh",
"-c",
"nvidia-smi"
],
"cpu": 100
}
],
"family": "example-ecs-gpu"
}
```
以下示例任务定义展示了一个打印可用 GPU 数量的 TensorFlow 容器。该任务在 Amazon ECS 托管实例上运行，需要一个 GPU，并使用 `g4dn.xlarge` 实例。
```
{
"family": "tensorflow-gpu",
"networkMode": "awsvpc",
"executionRoleArn": "arn:aws:iam::account-id:role/ecsTaskExecutionRole",
"containerDefinitions": [
{
"name": "tensorflow",
"image": "tensorflow/tensorflow:latest-gpu",
"essential": true,
"command": [
"python",
"-c",
"import tensorflow as tf; print('Num GPUs Available: ', len(tf.config.list_physical_devices('GPU')))"
],
"resourceRequirements": [
{
"type": "GPU",
"value": "1"
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/tensorflow-gpu",
"awslogs-region": "region",
"awslogs-stream-prefix": "ecs"
}
}
}
],
"requiresCompatibilities": [
"MANAGED_INSTANCES"
],
"cpu": "4096",
"memory": "8192",
}
```
## 共享 GPU
当想要共享 GPU 时，需要进行以下配置。
1. 从任务定义中移除 GPU 资源要求，以便 Amazon ECS 不会预留任何应共享的 GPU。
1. 当想要共享 GPU 时，请将以下用户数据添加到您的实例。这将使 nvidia 成为容器实例上的默认 Docker 容器运行时，以便所有 Amazon ECS 容器都可以使用 GPU。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[在启动包含用户数据输入的 EC2 实例时运行命令](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)。
```
const userData = ec2.UserData.forLinux();
userData.addCommands(
'sudo rm /etc/sysconfig/docker',
'echo DAEMON_MAXFILES=1048576 | sudo tee -a /etc/sysconfig/docker',
'echo OPTIONS="--default-ulimit nofile=32768:65536 --default-runtime nvidia" | sudo tee -a /etc/sysconfig/docker',
'echo DAEMON_PIDFILE_TIMEOUT=10 | sudo tee -a /etc/sysconfig/docker',
'sudo systemctl restart docker',
);
```
1. 在容器上设置 `NVIDIA_VISIBLE_DEVICES` 环境变量。您可以通过在任务定义中指定环境变量来执行此操作。有关有效值的信息，请参阅 NVIDIA 文档网站上的 [GPU Enumeration](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration)。
## 如果您需要 P2 实例该怎么办
如果您需要使用 P2 实例，可以使用以下选项之一继续使用实例。
您必须修改这两个选项的实例用户数据。有关更多信息，请参阅《Amazon EC2 用户指南》**中的[在启动包含用户数据输入的 EC2 实例时运行命令](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html)。
**使用最新支持的经 GPU 优化的 AMI**
您可以使用经 GPU 优化的 AMI 的 `20230906` 版本，并将以下内容添加到实例用户数据中。
将 cluster-name 替换为您集群的名称。
```
#!/bin/bash
echo "exclude=*nvidia* *cuda*" >> /etc/yum.conf
echo "ECS_CLUSTER=cluster-name" >> /etc/ecs/ecs.config
```
**使用最新的经 GPU 优化的 AMI，并更新用户数据**
您可在实例用户数据中添加以下内容。这将卸载 Nvidia 535/Cuda12.2 驱动程序，然后安装 Nvidia 470/Cuda11.4 驱动程序并修复该版本。
```
#!/bin/bash
yum remove -y cuda-toolkit* nvidia-driver-latest-dkms*
tmpfile=$(mktemp)
cat >$tmpfile <
> /etc/yum.conf
nvidia-smi
```
**创建您自己的兼容 P2 且经过 GPU 优化的 AMI**
您可以创建与 P2 实例兼容的自定义 Amazon ECS GPU 优化型 AMI，然后使用 AMI 启动 P2 实例。
1. 运行以下命令以克隆 `amazon-ecs-ami repo`。
```
git clone https://github.com/aws/amazon-ecs-ami
```
1. 在 `release.auto.pkrvars.hcl` 或 `overrides.auto.pkrvars.hcl` 中设置所需的 Amazon ECS 代理和源 Amazon Linux AMI 版本。
1. 运行以下命令来构建兼容 P2 的私有 EC2 AMI。
将“区域”替换为“区域”和“实例区域”。
```
REGION=region make al2keplergpu
```
1. 使用包含以下实例用户数据的 AMI 连接到 Amazon ECS 集群。
将 cluster-name 替换为您集群的名称。
```
#!/bin/bash
echo "ECS_CLUSTER=cluster-name" >> /etc/ecs/ecs.config
```
# 适用于视频转码工作负载的 Amazon ECS 任务定义
要在 Amazon ECS 上使用视频转码工作负载，请注册 [Amazon EC2 VT1](https://aws.amazon.com/ec2/instance-types/vt1/) 实例。注册这些实例后，您可以将实时和预渲染的视频转码工作负载作为 Amazon ECS 上的任务运行。Amazon EC2 VT1 实例使用 Xilinx U30 媒体转码卡来加速实时和预渲染的视频转码工作负载。
**注意**
有关如何在 Amazon ECS 以外的容器中运行视频转码工作负载的说明，请参阅 [Xilinx 文档](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#working-with-docker-vt1)。
## 注意事项
在 Amazon ECS 上开始部署 VT1 之前，请注意以下事项：
+ 您的集群可以包含 VT1 和非 VT1 实例的组合。
+ 您需要一个 Linux 应用程序，该应用程序使用具有加速 AVC（H.264）和 HEVC（H.265）编解码器的 Xilinx U30 媒体转码卡。
**重要**
使用其他编解码器的应用程序可能不会在 VT1 实例上获得性能提升。
+ U30 卡上只能运行一个转码任务。每张卡都有两个与之关联的设备。您可以运行的转码任务数量与每个 VT1 实例的卡的数量一样。
+ 在创建服务或运行独立任务时，您可以在配置任务放置约束时使用实例类型属性。这样可以确保在您指定的容器实例上启动任务。这样做有助于确保您有效地使用资源，并确保视频转码工作负载任务在 VT1 实例上。有关更多信息，请参阅 [Amazon ECS 如何将任务放置在容器实例上](task-placement.md)。
在以下示例中，任务在您的 `default` 集群上的 `vt1.3xlarge` 实例上运行。
```
aws ecs run-task \
--cluster default \
--task-definition vt1-3xlarge-xffmpeg-processor \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == vt1.3xlarge"
```
+ 您可以将容器配置为使用主机容器实例上可用的特定 U30 卡。您可以通过使用 `linuxParameters` 参数并指定设备详细信息来执行此操作。有关更多信息，请参阅 [任务定义要求](#ecs-vt1-requirements)。
## 使用 VT1 AMI
您有两种选择可以在 Amazon EC2 上运行适用于 Amazon ECS 容器实例的 AMI。第一个选项是在 AWS Marketplace 上使用 Xilinx 官方 AMI。第二种选择是从示例存储库构建自己的 AMI。
+ [Xilinx 在 AWS Marketplace 上提供 AMI](https://aws.amazon.com/marketplace/pp/prodview-phvk6d4mq3hh6)。
+ Amazon ECS 提供了一个示例存储库，您可以使用该存储库为视频转码工作负载构建 AMI。该 AMI 随附 Xilinx U30 驱动程序。您可以在 [Github](https://github.com/aws-samples/aws-vt-baseami-pipeline) 上找到包含 Packer 脚本的存储库。有关 Packer 的更多信息，请参阅 [Packer 文档](https://developer.hashicorp.com/packer/docs)。
## 任务定义要求
要在 Amazon ECS 上运行视频转码容器，您的任务定义必须包含使用加速 H.264/AVC 和 H.265/HEVC 编解码器的视频转码应用程序。您可以按照 [Xilinx Github](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#creating-a-docker-image-for-vt1-usage) 上的步骤来构建容器映像。
任务定义必须特定于实例类型。实例类型为 3xlarge、6xlarge 和 24xlarge。您必须将容器配置为使用主机容器实例上可用的特定 Xilinx U30 设备。您还可以使用 `linuxParameters` 参数执行此操作。下表详细介绍了特定于每种实例类型的卡和设备 SoC。
| 实例类型 | vCPU | RAM (GiB) | U30 加速器卡 | 可寻址的 XCU30 SoC 设备 | 设备路径 |
| --- | --- | --- | --- | --- | --- |
| vt1.3xlarge | 12 | 24 | 1 | 2 | /dev/dri/renderD128,/dev/dri/renderD129 |
| vt1.6xlarge | 24 | 48 | 2 | 4 | /dev/dri/renderD128,/dev/dri/renderD129,/dev/dri/renderD130,/dev/dri/renderD131 |
| vt1.24xlarge | 96 | 182 | 8 | 16 | /dev/dri/renderD128,/dev/dri/renderD129,/dev/dri/renderD130,/dev/dri/renderD131,/dev/dri/renderD132,/dev/dri/renderD133,/dev/dri/renderD134,/dev/dri/renderD135,/dev/dri/renderD136,/dev/dri/renderD137,/dev/dri/renderD138,/dev/dri/renderD139,/dev/dri/renderD140,/dev/dri/renderD141,/dev/dri/renderD142,/dev/dri/renderD143 |
**重要**
如果任务定义列出了 EC2 实例没有的设备，则任务将无法运行。当任务失败时，`stoppedReason` 中将出现以下错误消息：`CannotStartContainerError: Error response from daemon: error gathering device information while adding custom device "/dev/dri/renderD130": no such file or directory`。
# 在 Amazon ECS 任务定义中指定视频转码
以下示例中，提供了用于 Amazon EC2 上 Linux 容器的任务定义的语法。此任务定义适用于按照 [Xilinx 文档](https://xilinx.github.io/video-sdk/v1.5/container_setup.html#creating-a-docker-image-for-vt1-usage)中提供的过程构建的容器映像。如果使用此示例，请将 `image` 替换为您自己的映像，然后将视频文件复制到 `/home/ec2-user` 目录中的实例。
------
#### [ vt1.3xlarge ]
1. 使用以下内容创建名为 `vt1-3xlarge-ffmpeg-linux.json` 的文本文件。
```
{
"family": "vt1-3xlarge-xffmpeg-processor",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == vt1.3xlarge"
}
],
"containerDefinitions": [
{
"entryPoint": [
"/bin/bash",
"-c"
],
"command": ["/video/ecs_ffmpeg_wrapper.sh"],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/dri/renderD128",
"hostPath": "/dev/dri/renderD128",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD129",
"hostPath": "/dev/dri/renderD129",
"permissions": [
"read",
"write"
]
}
]
},
"mountPoints": [
{
"containerPath": "/video",
"sourceVolume": "video_file"
}
],
"cpu": 0,
"memory": 12000,
"image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
"essential": true,
"name": "xilinix-xffmpeg"
}
],
"volumes": [
{
"name": "video_file",
"host": {"sourcePath": "/home/ec2-user"}
}
]
}
```
1. 注册任务定义。
```
aws ecs register-task-definition --family vt1-3xlarge-xffmpeg-processor --cli-input-json file://vt1-3xlarge-xffmpeg-linux.json --region us-east-1
```
------
#### [ vt1.6xlarge ]
1. 使用以下内容创建名为 `vt1-6xlarge-ffmpeg-linux.json` 的文本文件。
```
{
"family": "vt1-6xlarge-xffmpeg-processor",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == vt1.6xlarge"
}
],
"containerDefinitions": [
{
"entryPoint": [
"/bin/bash",
"-c"
],
"command": ["/video/ecs_ffmpeg_wrapper.sh"],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/dri/renderD128",
"hostPath": "/dev/dri/renderD128",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD129",
"hostPath": "/dev/dri/renderD129",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD130",
"hostPath": "/dev/dri/renderD130",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD131",
"hostPath": "/dev/dri/renderD131",
"permissions": [
"read",
"write"
]
}
]
},
"mountPoints": [
{
"containerPath": "/video",
"sourceVolume": "video_file"
}
],
"cpu": 0,
"memory": 12000,
"image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
"essential": true,
"name": "xilinix-xffmpeg"
}
],
"volumes": [
{
"name": "video_file",
"host": {"sourcePath": "/home/ec2-user"}
}
]
}
```
1. 注册任务定义。
```
aws ecs register-task-definition --family vt1-6xlarge-xffmpeg-processor --cli-input-json file://vt1-6xlarge-xffmpeg-linux.json --region us-east-1
```
------
#### [ vt1.24xlarge ]
1. 使用以下内容创建名为 `vt1-24xlarge-ffmpeg-linux.json` 的文本文件。
```
{
"family": "vt1-24xlarge-xffmpeg-processor",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == vt1.24xlarge"
}
],
"containerDefinitions": [
{
"entryPoint": [
"/bin/bash",
"-c"
],
"command": ["/video/ecs_ffmpeg_wrapper.sh"],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/dri/renderD128",
"hostPath": "/dev/dri/renderD128",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD129",
"hostPath": "/dev/dri/renderD129",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD130",
"hostPath": "/dev/dri/renderD130",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD131",
"hostPath": "/dev/dri/renderD131",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD132",
"hostPath": "/dev/dri/renderD132",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD133",
"hostPath": "/dev/dri/renderD133",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD134",
"hostPath": "/dev/dri/renderD134",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD135",
"hostPath": "/dev/dri/renderD135",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD136",
"hostPath": "/dev/dri/renderD136",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD137",
"hostPath": "/dev/dri/renderD137",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD138",
"hostPath": "/dev/dri/renderD138",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD139",
"hostPath": "/dev/dri/renderD139",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD140",
"hostPath": "/dev/dri/renderD140",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD141",
"hostPath": "/dev/dri/renderD141",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD142",
"hostPath": "/dev/dri/renderD142",
"permissions": [
"read",
"write"
]
},
{
"containerPath": "/dev/dri/renderD143",
"hostPath": "/dev/dri/renderD143",
"permissions": [
"read",
"write"
]
}
]
},
"mountPoints": [
{
"containerPath": "/video",
"sourceVolume": "video_file"
}
],
"cpu": 0,
"memory": 12000,
"image": "0123456789012.dkr.ecr.us-west-2.amazonaws.com/aws/xilinx-xffmpeg",
"essential": true,
"name": "xilinix-xffmpeg"
}
],
"volumes": [
{
"name": "video_file",
"host": {"sourcePath": "/home/ec2-user"}
}
]
}
```
1. 注册任务定义。
```
aws ecs register-task-definition --family vt1-24xlarge-xffmpeg-processor --cli-input-json file://vt1-24xlarge-xffmpeg-linux.json --region us-east-1
```
------
# 适用于 AWS 神经元机器学习工作负载的 Amazon ECS 任务定义
您可以将 [Amazon EC2 Trn1](https://aws.amazon.com/ec2/instance-types/trn1/)、[Amazon EC2 Trn2](https://aws.amazon.com/ec2/instance-types/trn2/)、[Amazon EC2 Inf1](https://aws.amazon.com/ec2/instance-types/inf1/) 和 [Amazon EC2 Inf2](https://aws.amazon.com/ec2/instance-types/inf2/) 实例注册到您的集群，以执行机器学习工作负载。
Amazon EC2 Trn1 和 Trn2 实例由 [AWS Trainium](https://aws.amazon.com/ai/machine-learning/trainium/) 芯片提供技术支持。这些实例在云中为机器学习提供高性能的低成本训练。您可以在 Trn1 或 Trn2 实例上使用具有 AWS Neuron 的机器学习框架训练机器学习推理模型。然后，您可以在 Inf1 实例或 Inf2 实例上运行模型来利用 AWS Inferentia 芯片的加速。
Amazon EC2 Inf1 实例和 Inf2 实例由 [AWS Inferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) 芯片提供支持，，它们可在云中提供高性能和最低成本的推理。
机器学习模型使用 [AWS Neuron](https://aws.amazon.com/ai/machine-learning/neuron/) 部署到容器中，它是专门的软件开发工具包（SDK）。SDL 由编译器、运行时和分析工具组成，可用于优化 AWS 机器学习芯片的机器学习性能。AWSNeuron 支持常用的机器学习框架，例如 TensorFlow、PyTorch 和 Apache MXNet。
## 注意事项
在 Amazon ECS 上开始部署 Neuron 之前，请注意以下事项：
+ 您的集群可以包含 Trn1、Trn2、Inf1、Inf2 和其他实例的组合。
+ 在容器中，您需要一个采用支持 AWS Neuron 的机器学习框架的 Linux 应用程序。
**重要**
使用其他框架的应用程序可能不会在 Trn1、Trn2、Inf1 和 Inf2 实例上获得性能提升。
+ 每个 [AWS Trainium](https://aws.amazon.com/ai/machine-learning/trainium/) 或 [AWS Inferentia](https://aws.amazon.com/ai/machine-learning/inferentia/) 芯片上只能运行一个推理或推理训练任务。对于 Inf1，每个芯片有 4 个 NeuronCore。对于 Trn1、Trn2 和 Inf2，每个芯片有 2 个 NeuronCore。每个 Trn1、Trn2、Inf1 和 Inf2 实例都有芯片，您可以运行与之一样多的任务。
+ 在创建服务或运行独立任务时，您可以在配置任务放置约束时使用实例类型属性。这样可以确保在您指定的容器实例上启动任务。这样做可以帮助您优化总体资源利用率，并确保推理工作负载的任务位于 Trn1、Trn2、Inf1 和 Inf2 实例上。有关更多信息，请参阅 [Amazon ECS 如何将任务放置在容器实例上](task-placement.md)。
在以下示例中，任务在您的 `default` 集群上的 `Inf1.xlarge` 实例上运行。
```
aws ecs run-task \
--cluster default \
--task-definition ecs-inference-task-def \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == Inf1.xlarge"
```
+ 无法在任务定义中定义 Neuron 资源需求。但您要将容器配置为使用主机容器实例上可用的特定 AWS Trainium 或 AWSInferentia 芯片。通过使用 `linuxParameters` 参数并指定设备详细信息来执行此操作。有关更多信息，请参阅 [任务定义要求](#ecs-inference-requirements)。
## 使用经 Amazon ECS 优化的 Amazon Linux 2023（Neuron）AMI
Amazon ECS 为 AWS Trainium 和 AWS Inferentia 工作负载提供了一个基于 Amazon Linux 2023 的经 Amazon ECS 优化的 AMI。它附带适用于 Docker 的 AWS Neuron 驱动程序和运行时。此 AMI 使得在 Amazon ECS 上运行机器学习 inference 工作负载变得更加轻松。
我们建议您在启动 Amazon EC2 Trn1、Inf1 和 Inf2 实例时使用经 Amazon ECS 优化的 Amazon Linux 2023（Neuron）AMI。
您可以使用 AWS CLI 和以下命令检索当前经 Amazon ECS 优化的 Amazon Linux 2023（Neuron）AMI。
```
aws ssm get-parameters --names /aws/service/ecs/optimized-ami/amazon-linux-2023/neuron/recommended
```
## 任务定义要求
要在 Amazon ECS 上部署 Neuron，您的任务定义必须包含预构建容器的容器定义，该容器服务于 TensorFlow 的 推理模型。它是由 AWS Deep Learning Containers 提供的。此容器包含 AWS Neuron 运行时和 TensorFlow 服务应用程序。在启动时，此容器将从 Amazon S3 获取您的模型，用保存的模型启动 Neuron TensorFlow 服务，并等待预测请求。在以下示例中，容器映像具有 TensorFlow 1.15 和 Ubuntu 18.04。GitHub 上维护了针对 Neuron 优化的预构建 Deep Learning Containers 的完整列表。有关更多信息，请参阅[使用 AWS Neuron TensorFlow Serving](https://docs.aws.amazon.com/dlami/latest/devguide/tutorial-inferentia-tf-neuron-serving.html)。
```
763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-inference-neuron:1.15.4-neuron-py37-ubuntu18.04
```
或者，您也可以构建自己的 Neuron 边车容器映像。有关更多信息，请参阅《AWS Deep Learning AMIs 开发人员指南》**中的[教程：Neuron TensorFlow Serving](https://github.com/aws-neuron/aws-neuron-sdk/blob/master/frameworks/tensorflow/tensorflow-neuron/tutorials/tutorials-tensorflow-utilizing-neuron-capabilities.rst)。
任务定义必须特定于一种实例类型。您必须将容器配置为使用主机容器实例上可用的特定 AWS Trainium 或 AWS Inferentia 设备。您还可以使用 `linuxParameters` 参数执行此操作。对于示例任务定义，请参阅 [在 Amazon ECS 任务定义中指定 AWS Neuron 机器学习](ecs-inference-task-def.md)。下表详细介绍了特定于每种实例类型的芯片。
| 实例类型 | vCPU | RAM (GiB) | AWS ML 加速器芯片 | 设备路径 |
| --- | --- | --- | --- | --- |
| trn1.2xlarge | 8 | 32 | 1 | /dev/neuron0 |
| trn1.32xlarge | 128 | 512 | 16 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15 |
| trn2.48xlarge | 192 | 1536 | 16 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15 |
| inf1.xlarge | 4 | 8 | 1 | /dev/neuron0 |
| inf1.2xlarge | 8 | 16 | 1 | /dev/neuron0 |
| inf1.6xlarge | 24 | 48 | 4 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3 |
| inf1.24xlarge | 96 | 192 | 16 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11, /dev/neuron12, /dev/neuron13, /dev/neuron14, /dev/neuron15 |
| inf2.xlarge | 8 | 16 | 1 | /dev/neuron0 |
| inf2.8xlarge | 32 | 64 | 1 | /dev/neuron0 |
| inf2.24xlarge | 96 | 384 | 6 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, |
| inf2.48xlarge | 192 | 768 | 12 | /dev/neuron0, /dev/neuron1, /dev/neuron2, /dev/neuron3, /dev/neuron4, /dev/neuron5, /dev/neuron6, /dev/neuron7, /dev/neuron8, /dev/neuron9, /dev/neuron10, /dev/neuron11 |
# 在 Amazon ECS 任务定义中指定 AWS Neuron 机器学习
以下是 `inf1.xlarge` 的示例 Linux 任务定义，显示要使用的语法。
```
{
"family": "ecs-neuron",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == inf1.xlarge"
}
],
"executionRoleArn": "${YOUR_EXECUTION_ROLE}",
"containerDefinitions": [
{
"entryPoint": [
"/usr/local/bin/entrypoint.sh",
"--port=8500",
"--rest_api_port=9000",
"--model_name=resnet50_neuron",
"--model_base_path=s3://amzn-s3-demo-bucket/resnet50_neuron/"
],
"portMappings": [
{
"hostPort": 8500,
"protocol": "tcp",
"containerPort": 8500
},
{
"hostPort": 8501,
"protocol": "tcp",
"containerPort": 8501
},
{
"hostPort": 0,
"protocol": "tcp",
"containerPort": 80
}
],
"linuxParameters": {
"devices": [
{
"containerPath": "/dev/neuron0",
"hostPath": "/dev/neuron0",
"permissions": [
"read",
"write"
]
}
],
"capabilities": {
"add": [
"IPC_LOCK"
]
}
},
"cpu": 0,
"memoryReservation": 1000,
"image": "763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-inference-neuron:1.15.4-neuron-py37-ubuntu18.04",
"essential": true,
"name": "resnet50"
}
]
}
```
# 适用于深度学习实例的 Amazon ECS 任务定义
要在 Amazon ECS 上使用深度学习工作负载，请将 [Amazon EC2 DL1](https://aws.amazon.com/ec2/instance-types/dl1/) 实例注册到您的集群。Amazon EC2 DL1 实例由英特尔旗下公司 Habana Labs 的 Gaudi 加速器提供支持。使用 Habana SynapseAI SDK 连接 Habana Gaudi 加速器。SDK 支持常用的机器学习框架 TensorFlow 和 PyTorch。
## 注意事项
在 Amazon ECS 上开始部署 DL1 之前，请注意以下事项：
+ 您的集群可以包含 DL1 和非 DL1 实例的组合。
+ 在创建服务或运行独立任务时，您可以在配置任务放置约束时使用实例类型属性，以确保在您指定的容器实例上启动任务。这样做可以确保您有效地使用资源，并确保深度学习工作负载任务在 DL1 实例上。有关更多信息，请参阅 [Amazon ECS 如何将任务放置在容器实例上](task-placement.md)。
以下示例运行 `default` 集群上的 `dl1.24xlarge` 实例任务。
```
aws ecs run-task \
--cluster default \
--task-definition ecs-dl1-task-def \
--placement-constraints type=memberOf,expression="attribute:ecs.instance-type == dl1.24xlarge"
```
## 使用 DL1 AMI
您有三种选择可以在 Amazon EC2 DL1 实例上运行适用于 Amazon ECS 的 AMI：
+ Habana [在此处](https://aws.amazon.com/marketplace/pp/prodview-h24gzbgqu75zq)提供的 AWS Marketplace AMI。
+ Amazon Web Services 提供的 Habana 深度学习 AMI。因为它不包括在内，因此您需要单独安装 Amazon ECS 容器代理。
+ 使用 Packer 构建由 [GitHub 存储库](https://github.com/aws-samples/aws-habana-baseami-pipeline)提供的自定义 AMI。有关更多信息，请参阅 [Packer 文档](https://developer.hashicorp.com/packer/docs)。
# 在 Amazon ECS 任务定义中指定深度学习
要在 Amazon ECS 上运行 Habana Gaudi 加速深度学习容器，您的任务定义必须包含预构建容器的容器定义，该容器使用 AWS 深度学习容器提供的 Habana SynapseAI 服务于 TensorFlow 或 PyTorch 的深度学习模型。
以下容器映像具有 TensorFlow 2.7.0 和 Ubuntu 20.04。GitHub 上维护了针对 Habana Gaudi 加速器优化的预构建深度学习容器的完整列表。有关更多信息，请参阅 [Habana Training Containers](https://github.com/aws/deep-learning-containers/blob/master/available_images.md#habana-training-containers)（Habana 训练容器）。
```
763104351884.dkr.ecr.us-east-1.amazonaws.com/tensorflow-training-habana:2.7.0-hpu-py38-synapseai1.2.0-ubuntu20.04
```
以下是 Amazon EC2 上的 Linux 容器的示例任务定义，显示要使用的语法。此示例使用包含 Habana Labs 实验室系统管理界面工具（HL-SMI）的图像，可参见此处：`vault.habana.ai/gaudi-docker/1.1.0/ubuntu20.04/habanalabs/tensorflow-installer-tf-cpu-2.6.0:1.1.0-614`
```
{
"family": "dl-test",
"requiresCompatibilities": ["EC2"],
"placementConstraints": [
{
"type": "memberOf",
"expression": "attribute:ecs.os-type == linux"
},
{
"type": "memberOf",
"expression": "attribute:ecs.instance-type == dl1.24xlarge"
}
],
"networkMode": "host",
"cpu": "10240",
"memory": "1024",
"containerDefinitions": [
{
"entryPoint": [
"sh",
"-c"
],
"command": ["hl-smi"],
"cpu": 8192,
"environment": [
{
"name": "HABANA_VISIBLE_DEVICES",
"value": "all"
}
],
"image": "vault.habana.ai/gaudi-docker/1.1.0/ubuntu20.04/habanalabs/tensorflow-installer-tf-cpu-2.6.0:1.1.0-614",
"essential": true,
"name": "tensorflow-installer-tf-hpu"
}
]
}
```
# 适用于 64 位 ARM 工作负载的 Amazon ECS 任务定义
Amazon ECS 支持使用 64 位 ARM 应用程序。您可以在 [AWS Graviton 处理器](https://aws.amazon.com/ec2/graviton/)支持的平台上运行您的应用程序。它适用于各类工作负载。这包括应用程序服务器、微服务、高性能计算、基于 CPU 的机器学习推断、视频编码、电子设计自动化、游戏、开源数据库和内存缓存等工作负载。
## 注意事项
在开始部署使用 64 位 ARM 架构的任务定义之前，请考虑以下事项：
+ 应用程序可以使用 Fargate 或 EC2。
+ 这些应用程序只能使用 Linux 操作系统。
+ 对于 Fargate 类型，应用程序必须使用 Fargate 平台版本 `1.4.0` 或更高版本。
+ 应用程序可以使用 Fluent Bit 或 CloudWatch 进行监控。
+ 对于 Fargate，以下 AWS 区域不支持 64 位 ARM 工作负载：
+ 美国东部（弗吉尼亚州北部），`use1-az3` 可用区
+ 对于 EC2，请参阅以下内容以验证您的区域是否支持要使用的实例类型：
+ [Amazon EC2 M6g 实例](https://aws.amazon.com/ec2/instance-types/m6)
+ [Amazon EC2 T4g 实例](https://aws.amazon.com/ec2/instance-types/t4/)
+ [Amazon EC2 C6g 实例](https://aws.amazon.com/ec2/instance-types/c6g/)
+ [Amazon EC2 R6gd 实例](https://aws.amazon.com/ec2/instance-types/r6/)
+ [Amazon EC2 X2gd 实例](https://aws.amazon.com/ec2/instance-types/x2/)
您还可以使用带筛选器的 Amazon EC2 `describe-instance-type-offerings` 命令来查看您所在区域的实例产品。
```
aws ec2 describe-instance-type-offerings --filters Name=instance-type,Values=instance-type --region region
```
以下示例检查美国东部（弗吉尼亚州北部）（us-east-1）区域中的 M6 实例类型可用性。
```
aws ec2 describe-instance-type-offerings --filters "Name=instance-type,Values=m6*" --region us-east-1
```
有关更多信息，请参阅 *Amazon EC2 命令行参考*中的 [describe-instance-type-offerings](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instance-type-offerings.html)。
# 在 Amazon ECS 任务定义中指定 ARM 架构
要使用 ARM 架构，请为 `cpuArchitecture` 任务定义参数指定 `ARM64`。
在以下示例中，ARM 架构是在任务定义中指定的。该文件以 JSON 格式。
```
{
"runtimePlatform": {
"operatingSystemFamily": "LINUX",
"cpuArchitecture": "ARM64"
},
...
}
```
在以下示例中，ARM 架构的任务定义显示“hello world”。
```
{
"family": "arm64-testapp",
"networkMode": "awsvpc",
"containerDefinitions": [
{
"name": "arm-container",
"image": "public.ecr.aws/docker/library/busybox:latest",
"cpu": 100,
"memory": 100,
"essential": true,
"command": [ "echo hello world" ],
"entryPoint": [ "sh", "-c" ]
}
],
"requiresCompatibilities": [ "EC2" ],
"cpu": "256",
"memory": "512",
"runtimePlatform": {
"operatingSystemFamily": "LINUX",
"cpuArchitecture": "ARM64"
},
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole"
}
```
# 将 Amazon ECS 日志发送到 CloudWatch
您可在任务中配置容器以将日志信息发送到 CloudWatch Logs。如果您对任务使用 Fargate，则可以查看容器中的日志。如果您使用 EC2，则可以在一个方便的位置查看容器中的不同日志，并防止您的容器日志占用您容器实例上的磁盘空间。
**注意**
任务中的容器所记录的信息类型主要取决于其 `ENTRYPOINT` 命令。默认情况下，捕获的日志显示命令输出是您在本地运行容器时在交互式终端上通常看到的内容，即 `STDOUT` 和 `STDERR` I/O 流。`awslogs`日志驱动程序只是将 Docker 中的这些日志传递到 CloudWatch Logs。有关如何处理 Docker 日志的更多信息，包括捕获不同文件数据或流的替代方法，请参阅 Docker 文档中的[查看容器或服务的日志](https://docs.docker.com/engine/logging/)。
要将系统日志从 Amazon ECS 容器实例发送到 CloudWatch Logs，请参阅《Amazon CloudWatch Logs 用户指南》**中的[监控日志文件](https://docs.aws.amazon.com/AmazonCloudWatch/latest/DeveloperGuide/WhatIsCloudWatchLogs.html)和 [CloudWatch Logs 配额](https://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/cloudwatch_limits_cwl.html)。
## Fargate
如果您对任务使用 Fargate，您需要将所需的 `logConfiguration` 参数添加到您的任务定义才能打开 `awslogs` 日志驱动程序。有关更多信息，请参阅 [Amazon ECS 任务定义示例：将日志路由到 CloudWatch](specify-log-config.md)。
对于 Fargate 上的 Windows 容器，当您的任何任务定义参数包含特殊字符（例如 `& \ < > ^ |`）时，请执行以下选项之一：
+ 在整个参数字符串周围添加一个带有双引号的 escape（`\`）字符
示例
```
"awslogs-multiline-pattern": "\"^[|DEBUG|INFO|WARNING|ERROR\"",
```
+ 在每个特殊字符周围添加一个 escape（`^`）字符
示例
```
"awslogs-multiline-pattern": "^^[^|DEBUG^|INFO^|WARNING^|ERROR",
```
## EC2
如果您对任务使用 EC2，并且想要打开 `awslogs` 日志驱动程序，您的 Amazon ECS 容器实例至少需要容器代理的 1.9.0 版本。有关如何检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。
**注意**
您必须使用经 Amazon ECS 优化的 AMI 或至少包含 `ecs-init` 软件包版本 `1.9.0-1` 的自定义 AMI。使用自定义 AMI 时，如果在 **docker run** 语句或环境变量文件中使用以下环境变量启动代理，您必须指定 `awslogs` 日志驱动程序在 Amazon EC2 实例上可用。
```
ECS_AVAILABLE_LOGGING_DRIVERS=["json-file","awslogs"]
```
Amazon ECS 容器实例还需要针对您用于启动容器实例的 IAM 角色的 `logs:CreateLogStream` 和 `logs:PutLogEvents` 权限。如果在 Amazon ECS 中启用 `awslogs` 日志驱动程序支持之前创建了 Amazon ECS 容器实例，可能需要添加此权限。`ecsTaskExecutionRole` 在将其分配给任务时使用，并且可能包含正确的权限。有关任务执行角色的信息，请参阅[Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。如果您的容器实例使用容器实例的托管 IAM 策略，您的容器实例可能具有正确的权限。有关容器实例的托管 IAM 策略的信息，请参阅[Amazon ECS 容器实例 IAM 角色](instance_IAM_role.md)。
# Amazon ECS 任务定义示例：将日志路由到 CloudWatch
必须先在任务定义中为容器指定 `awslogs` 日志驱动程序，容器才能将日志发送到 CloudWatch。有关日志参数的更多信息，请参阅 [存储和日志记录](task_definition_parameters.md#container_definition_storage)
下面的任务定义 JSON 有一个为每个容器指定的 `logConfiguration` 对象。一个是用于将日志发送到名为 `awslogs-wordpress` 的日志组的 WordPress 容器。另一个是用于将日志发送到名为 `awslogs-mysql` 的日志组的 MySQL 容器。两个容器都使用`awslogs-example`日志流前缀。
```
{
"containerDefinitions": [
{
"name": "wordpress",
"links": [
"mysql"
],
"image": "public.ecr.aws/docker/library/wordpress:latest",
"essential": true,
"portMappings": [
{
"containerPort": 80,
"hostPort": 80
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "awslogs-wordpress",
"awslogs-region": "us-west-2",
"awslogs-stream-prefix": "awslogs-example"
}
},
"memory": 500,
"cpu": 10
},
{
"environment": [
{
"name": "MYSQL_ROOT_PASSWORD",
"value": "password"
}
],
"name": "mysql",
"image": "public.ecr.aws/docker/library/mysql:latest",
"cpu": 10,
"memory": 500,
"essential": true,
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-create-group": "true",
"awslogs-group": "awslogs-mysql",
"awslogs-region": "us-west-2",
"awslogs-stream-prefix": "awslogs-example",
"mode": "non-blocking",
"max-buffer-size": "25m"
}
}
}
],
"family": "awslogs-example"
}
```
## 后续步骤
+ 您可以选择使用 CloudWatch AWS CLI 或 API 为日志组设置保留策略。有关更多信息，请参阅《AWS Command Line Interface 命令参考》中的 [put-retention-policy](https://docs.aws.amazon.com/cli/latest/reference/logs/put-retention-policy.html)**。
+ 在容器定义日志配置中向 `awslogs` 日志驱动程序注册任务定义之后，可运行任务或使用此任务定义创建服务以开始将日志发送到 CloudWatch Logs。有关更多信息，请参阅[将应用程序作为 Amazon ECS 任务运行](standalone-task-create.md)和[创建 Amazon ECS 滚动更新部署](create-service-console-v2.md)。
# 将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner
您可以使用适用于 Amazon ECS 的 FireLens 来使用任务定义参数将日志路由到 AWS 服务或 AWS Partner Network（APN）目标来进行日志存储和分析。AWS Partner Network 是一个由合作伙伴组成的全球社区，它利用计划、专业知识和资源来构建、营销和销售客户产品。有关更多信息，请参阅 [AWS Partner](https://aws.amazon.com/partners/work-with-partners/)。FireLens 与 [Fluentd](https://www.fluentd.org/) 和 [Fluent Bit](https://fluentbit.io/) 结合使用。我们提供 AWS for Fluent Bit 映像，您也可以使用自己的 Fluentd 或 Fluent Bit 映像。
默认情况下，Amazon ECS 会配置容器依赖关系，以便 Firelens 容器先启动，任何使用它的容器随后启动。Firelens 容器也会在所有使用它的容器停止后才停止。
要使用此功能，您必须为您的任务创建一个 IAM 角色，该角色提供使用任务需要的任何 AWS 服务所需的权限。例如，如果容器将日志路由到 Firehose，则任务需要调用 `firehose:PutRecordBatch` API 的权限。有关更多信息，请参阅 *IAM用户指南*中的[添加和删除 IAM 标识权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)。
在以下条件下，您的任务也可能需要 Amazon ECS 任务执行角色。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
+ 如果在 Fargate 上托管您的任务，并且您正在从 Amazon ECR 提取容器映像或 AWS Secrets Manager 在日志配置中引用敏感数据，那么您必须包含任务执行 IAM 角色。
+ 当您使用托管于 Amazon S3 中的自定义配置文件时，任务执行 IAM 角色必须包含 `s3:GetObject` 权限。
使用 FireLens for Amazon ECS 时考虑以下事项：
+ 建议您在日志容器名称中添加 `my_service_`，以便可以在控制台中轻松区分容器名称。
+ 默认情况下，Amazon ECS 在应用程序容器和 FireLens 容器之间添加启动容器顺序依赖关系。当您在应用程序容器和 FireLens 容器之间指定容器顺序时，默认的启动容器顺序将被覆盖。
+ 支持将适用于 Amazon ECS 的 FireLens 用于托管在 Linux 上的 AWS Fargate 和 Amazon EC2 的任务。Windows 容器不支持 FireLens。
有关如何为 Windows 容器配置集中日志记录的信息，请参阅[使用 Fluent Bit 在 Amazon ECS 上对 Windows 容器进行集中日志记录](https://aws.amazon.com/blogs/containers/centralized-logging-for-windows-containers-on-amazon-ecs-using-fluent-bit/)。
+ 您可以使用 CloudFormation 模板为 Amazon ECS 配置 FireLens。有关更多信息，请参阅《AWS CloudFormation 用户指南》**中的 [AWS::ECS::TaskDefinition FirelensConfiguration](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-firelensconfiguration.html)
+ FireLens 在端口 `24224` 上侦听，因此为了确保从任务外部无法访问 FireLens 日志路由器，不得允许任务使用的安全组中端口 `24224` 上的入站流量。对于使用 `awsvpc` 网络模式的任务，这是与任务关联的安全组。对于使用 `host` 网络模式的任务，它是与托管任务的 Amazon EC2 实例关联的安全组。对于使用 `bridge` 网络模式的任务，请勿创建任何使用端口 `24224` 的端口映射。
+ 对于使用 `bridge` 网络模式的任务，具有 FirelLens 配置的容器必须在依赖它的任何应用程序容器启动之前启动。要控制容器的启动顺序，请在任务定义中使用依赖条件。有关更多信息，请参阅 [容器依赖项](task_definition_parameters.md#container_definition_dependson)。
**注意**
如果您将容器定义中的依赖条件参数与 FirelLens 配置结合使用，请确保每个容器均具有 `START` 或 `HEALTHY` 条件要求。
+ 默认情况下，FireLens 将集群和任务定义名称以及集群的 Amazon 资源名称（ARN）作为元数据键添加到您的 stdout/stderr 容器日志中。以下为元数据格式的示例。
```
"ecs_cluster": "cluster-name",
"ecs_task_arn": "arn:aws:ecs:region:111122223333:task/cluster-name/f2ad7dba413f45ddb4EXAMPLE",
"ecs_task_definition": "task-def-name:revision",
```
如果您不希望日志中出现元数据，请在任务定义的 `firelensConfiguration` 部分中将 `enable-ecs-log-metadata` 设置为 `false`。
```
"firelensConfiguration":{
"type":"fluentbit",
"options":{
"enable-ecs-log-metadata":"false",
"config-file-type":"file",
"config-file-value":"/extra.conf"
}
```
您可以将 FireLens 容器配置为以非根用户身份运行。请考虑以下事项：
+ 要将 FireLens 容器配置为以非根用户身份运行，您必须使用以下其中一种格式指定用户：
+ `uid`
+ `uid:gid`
+ `uid:group`
有关在容器定义中指定用户的更多信息，请参阅《Amazon Elastic Container Service API 参考》**中的 [ContainerDefinition](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDefinition.html)。
FireLens 容器通过 UNIX 套接字接收应用程序日志。Amazon ECS 代理使用 `uid` 将套接字目录的所有权分配给 FireLens 容器。
+ 在 Amazon ECS 代理版本 `1.96.0` 及更高版本以及经 Amazon ECS 优化的 AMI 版本 `v20250716` 及更高版本上，支持将 FireLens 容器配置为以非根用户身份运行。
+ 当您为 FireLens 容器指定用户时，`uid` 必须是唯一的，并且不得用于属于任务中其他容器或容器实例的其他进程。
有关如何将多个配置文件用于 Amazon ECS 的信息（包括您托管的文件或 Amazon S3 中的文件），请参阅 [Init process for Fluent Bit on ECS, multi-config support](https://github.com/aws/aws-for-fluent-bit/tree/mainline/use_cases/init-process-for-fluent-bit)。
有关示例配置的信息，请参阅[Amazon ECS 任务定义示例：将日志路由到 FireLens](firelens-taskdef.md)。
有关配置日志以实现高吞吐量的更多信息，请参阅[配置 Amazon ECS 日志，以实现高吞吐量](firelens-docker-buffer-limit.md)。
# 配置 Amazon ECS 日志，以实现高吞吐量
对于高日志吞吐量场景，我们建议将 `awsfirelens` 日志驱动程序与 FireLens 和 Fluent Bit 一起使用。Fluent Bit 是一款轻量级日志处理器，资源利用效率高，可以处理数百万条日志记录。但是，要大规模实现最佳性能，需要调整其配置。
本部分介绍高级 Fluent Bit 优化技术，用于处理高日志吞吐量，同时保持系统稳定性并确保不丢失数据。
有关如何使用 FireLens 自定义配置文件的信息，请参阅 [使用自定义配置文件](firelens-taskdef.md#firelens-taskdef-customconfig)。有关其他示例，请参阅 GitHub 上的 [Amazon ECS FireLens 示例](https://github.com/aws-samples/amazon-ecs-firelens-examples)。
**注意**
本部分中的某些配置选项（例如 `workers` 和 `threaded`）需要适用于 Fluent Bit 版本 3 或更高版本的 AWS。有关可用版本的信息，请参阅[适用于 Fluent Bit 的 AWS 版本](https://github.com/aws/aws-for-fluent-bit/releases)。
## 使用文件系统缓冲
默认情况下，Fluent Bit 将所有数据缓冲到内存中。当数据摄取的速度超过其刷新到输出的速度时，缓冲区就会被填满。填满后，输入插件会暂停直到缓冲空间变为可用，这可能会导致背压并减慢应用程序的速度。
对于高吞吐量场景，我们建议使用文件系统缓冲。有关 Fluent Bit 如何管理缓冲和存储的更多信息，请参阅 Fluent Bit 文档中的[缓冲和存储](https://docs.fluentbit.io/manual/administration/buffering-and-storage)。
文件系统缓冲提供以下优势：
+ **更大的缓冲容量** – 磁盘空间通常比内存更充足。
+ **持久性** – 缓冲的数据在 Fluent Bit 重新启动后仍能存活下来。
+ **正常降级** – 在输出失败期间，数据会积聚在磁盘上，而不是导致内存耗尽。
要启用文件系统缓冲，请提供自定义 Fluent Bit 配置文件。以下示例展示了建议的配置：
```
[SERVICE]
# Flush logs every 1 second
Flush 1
# Wait 120 seconds during shutdown to flush remaining logs
Grace 120
# Directory for filesystem buffering
storage.path /var/log/flb-storage/
# Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
storage.max_chunks_up 32
# Flush backlog chunks to destinations during shutdown (prevents log loss)
storage.backlog.flush_on_shutdown On
[INPUT]
Name forward
unix_path /var/run/fluent.sock
# Run input in separate thread to prevent blocking
threaded true
# Enable filesystem buffering for persistence
storage.type filesystem
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
# Use multiple workers for parallel processing
workers 2
# Retry failed flushes up to 15 times
retry_limit 15
# Maximum disk space for buffered data for this output
storage.total_limit_size 10G
```
关键配置参数：
`storage.path`
Fluent Bit 在磁盘上存储缓冲块的目录。
`storage.backlog.flush_on_shutdown`
启用后，Fluent Bit 会尝试在停机期间将所有积压文件系统块刷新到目标。这有助于确保在 Fluent Bit 停止之前传输数据，但可能会增加停机时间。
`storage.max_chunks_up`
保留在内存中的块的数量。默认值为 128 个块，这会消耗 500 MB 以上的内存，因为每个块最多可以使用 4-5 MB 的内存。在内存受限的环境中，请降低此值。例如，如果您有 50 MB 可于缓冲，请将其设置为 8-10 个块。
`storage.type filesystem`
为输入插件启用文件系统存储。尽管名称如此，但 Fluent Bit 会使用 `mmap` 将块映射到内存和磁盘，从而在不牺牲性能的情况下提供持久性。
`threaded true`
在自己的线程中运行输入，与 Fluent Bit 的主事件循环分开。这样可以防止慢速输入阻塞整个管道。
## 优化输出配置
网络问题、服务中断和目标节流可能会导致无法传送日志。正确的输出配置可确保韧性而不会丢失数据。
当输出刷新失败时，Fluent Bit 可以重试该操作。以下参数控制重试行为：
`retry_limit`
删除记录之前的最大重试尝试次数。默认 为 1。对于生产环境，我们建议设置为 15 或更高，这可以通过指数回退覆盖几分钟的中断时间。
`scheduler.base`
两次重试之间的最短秒数。我们建议 10 秒。
`scheduler.cap`
使用指数回退时两次重试之间的最长秒数。我们建议 60 秒。
`workers`
并行输出处理的线程数。多个 Worker 允许并发刷新，从而提高处理多个块时的吞吐量。
`[SERVICE]` 部分中的 `Grace` 参数设置 Fluent Bit 在停机期间等待刷新缓冲数据的时间。`Grace` 期限必须与容器的 `stopTimeout` 相协调。确保 `stopTimeout` 超过 `Grace` 期限，进而允许 Fluent Bit 在接收 `SIGKILL` 之前完成刷新。例如，如果 `Grace` 为 120 秒，则将 `stopTimeout` 设置为 150 秒。
以下示例展示了针对高吞吐量场景的完整 Fluent Bit 配置，其中包含所有推荐设置：
```
[SERVICE]
# Flush logs every 1 second
Flush 1
# Wait 120 seconds during shutdown to flush remaining logs
Grace 120
# Directory for filesystem buffering
storage.path /var/log/flb-storage/
# Limit chunks stored 'up' in memory (reduce for memory-constrained environments)
storage.max_chunks_up 32
# Flush backlog chunks to destinations during shutdown (prevents log loss)
storage.backlog.flush_on_shutdown On
# Minimum seconds between retries
scheduler.base 10
# Maximum seconds between retries (exponential backoff cap)
scheduler.cap 60
[INPUT]
Name forward
unix_path /var/run/fluent.sock
# Run input in separate thread to prevent blocking
threaded true
# Enable filesystem buffering for persistence
storage.type filesystem
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
# Use multiple workers for parallel processing
workers 2
# Retry failed flushes up to 15 times
retry_limit 15
# Maximum disk space for buffered data for this output
storage.total_limit_size 10G
```
## 使用多目标日志记录实现可靠性
将日志发送到多个目标可以消除单点故障。例如，如果 CloudWatch Logs 出现中断，日志仍会到达 Amazon S3。
多目标日志记录提供以下优势：Amazon S3 输出插件还支持 gzip 和 Parquet 格式等压缩选项，这可以降低存储成本。有关更多信息，请参阅 Fluent Bit 文档中的 [S3 压缩](https://docs.fluentbit.io/manual/pipeline/outputs/s3#compression)。
多目标日志记录可以提供以下优势：
+ **冗余** – 如果一个目标出现故障，日志仍会到达另一个目标。
+ **恢复** – 重建一个系统与另一个系统之间的差距。
+ **持久性** – 将日志归档到 Amazon S3 实现长期保留。
+ **成本优化** – 将最近的日志保存在诸如 CloudWatch Logs 之类的快速查询服务中，保留时间较短，而将所有日志归档到成本较低的 Amazon S3 存储可以实现长期保留。
以下 Fluent Bit 配置将日志发送到 CloudWatch Logs 和 Amazon S3：
```
[OUTPUT]
Name cloudwatch_logs
Match *
region us-west-2
log_group_name /aws/ecs/my-app
log_stream_name $(ecs_task_id)
workers 2
retry_limit 15
[OUTPUT]
Name s3
Match *
bucket my-logs-bucket
region us-west-2
total_file_size 100M
s3_key_format /fluent-bit-logs/$(ecs_task_id)/%Y%m%d/%H/%M/$UUID
upload_timeout 10m
# Maximum disk space for buffered data for this output
storage.total_limit_size 5G
```
两个输出都使用相同的 `Match *` 模式，因此所有记录都独立发送到两个目标。在一个目标中断期间，日志继续流向另一个目标，而失败的刷新会积聚在文件系统缓冲区中供以后重试。
## 通过 tail 输入插件使用基于文件的日志记录
对于日志丢失是一个关键问题的高吞吐量场景，可以使用另一种方法：让应用程序将日志写入磁盘上的文件，然后使用 `tail` 输入插件将 Fluent Bit 配置为读取日志。这种方法完全绕过了 Docker 日志记录驱动程序层。
通过 tail 插件进行基于文件的日志记录提供以下优势：
+ **偏移跟踪** – Tail 插件可以将文件偏移存储在数据库文件中（使用 `DB` 选项），从而在 Fluent Bit 重新启动后提供持久性。这有助于防止在容器重新启动期间丢失日志。
+ **输入级缓冲** – 可以使用 `Mem_Buf_Limit` 直接在输入插件上配置内存缓冲区限制，从而更精细地控制内存使用情况。
+ **避免 Docker 开销** – 日志直接从文件转到 Fluent Bit，无需通过 Docker 的日志缓冲区。
要使用这种方法，您的应用程序必须将日志写入文件中，而不是 `stdout`。应用程序容器和 Fluent Bit 容器都挂载一个存储日志文件的共享卷。
以下示例展示了具有最佳实践的 tail 输入配置：
```
[INPUT]
Name tail
# File path or glob pattern to tail
Path /var/log/app.log
# Database file for storing file offsets (enables resuming after restart)
DB /var/log/flb_tail.db
# when true, controls that only fluent-bit will access the database (improves performance)
DB.locking true
# Skip long lines instead of skipping the entire file
Skip_Long_Lines On
# How often (in seconds) to check for new files matching the glob pattern
Refresh_Interval 10
# Extra seconds to monitor a file after rotation to account for pending flush
Rotate_Wait 30
# Maximum size of the buffer for a single line
Buffer_Max_Size 10MB
# Initial allocation size for reading file data
Buffer_Chunk_Size 1MB
# Maximum memory buffer size (tail pauses when full)
Mem_Buf_Limit 75MB
```
使用 tail 输入插件时，请考虑以下几点：
+ 对应用程序日志实施日志轮换，以防止磁盘耗尽。监控基础卷指标以衡量性能。
+ 根据您的日志格式考虑诸如 `Ignore_Older`、`Read_from_Head` 和多行解析器之类的设置。
有关更多信息，请参阅 Fluent Bit 文档中的 [Tail](https://docs.fluentbit.io/manual/pipeline/inputs/tail)。有关最佳实践，请参阅适用于 Fluent Bit 的 AWS 故障排除指南中的 [Tail 配置和最佳实践](https://github.com/aws/aws-for-fluent-bit/blob/mainline/troubleshooting/debugging.md#tail-config-with-best-practices)。
## 直接记录到 FireLens
在任务定义中指定 `awsfirelens` 日志驱动程序时，Amazon ECS 容器 代理会将以下环境变量注入容器中：
`FLUENT_HOST`
分配给 FirelLens 容器的 IP 地址。
如果在 `bridge` 网络模式下使用 EC2，则在重启 FireLens 日志路由器容器（容器定义中包含 `firelensConfiguration` 对象的容器）后，应用程序容器中的 `FLUENT_HOST` 环境变量可能会变得不准确。这是因为 `FLUENT_HOST` 是一个动态 IP 地址，重启后就会改变。地址改变后，直接从应用程序容器登录到 `FLUENT_HOST` IP 地址可能会失败。有关重启单个容器的更多信息，请参阅 [使用容器重启策略重启 Amazon ECS 任务中的单个容器](container-restart-policy.md)。
`FLUENT_PORT`
Fluent Forward 协议正在侦听的端口。
您可以使用这些环境变量，使用 Fluent Forward 协议从应用程序代码直接记录到 Fluent Bit 日志路由器，而不是写入 `stdout`。这种方法绕过了 Docker 日志记录驱动程序层，提供以下优势：
+ **更低的延迟** – 日志无需通过 Docker 的日志记录基础设施即可直接转到 Fluent Bit。
+ **结构化日志记录** – 以原生方式发送结构化日志数据，无需 JSON 编码开销。
+ **更好的控制** – 您的应用程序可以实现自己的缓冲和错误处理逻辑。
以下 Fluent 记录器库支持 Fluent Forward 协议，可用于将日志直接发送到 Fluent Bit：
+ **Go** – [fluent-logger-golang](https://github.com/fluent/fluent-logger-golang)
+ **Python** – [fluent-logger-python](https://github.com/fluent/fluent-logger-python)
+ **Java** – [fluent-logger-java](https://github.com/fluent/fluent-logger-java)
+ **Node.js** – [fluent-logger-node](https://github.com/fluent/fluent-logger-node)
+ **Ruby** – [fluent-logger-ruby](https://github.com/fluent/fluent-logger-ruby)
## 配置 Docker 缓冲区限制
创建任务定义时，您可以通过在 `log-driver-buffer-limit` 中指定值来指定将在内存中缓冲的日志行数。这会控制 Docker 和 Fluent Bit 之间的缓冲区。有关更多信息，请参阅 Docker 文档中的 [Fluentd 日志记录驱动程序](https://docs.docker.com/engine/logging/drivers/fluentd/)。
当吞吐量高时使用此选项，因为 Docker 可能会耗尽缓冲区内存并丢弃缓冲区消息，以便添加新消息。
使用此选项时，请考虑以下几点：
+ 平台版本为 `1.4.0` 或更高版本的 EC2 和 Fargate 类型支持此选项。
+ 该选项仅在 `logDriver` 设置为 `awsfirelens` 时有效。
+ 默认缓冲区限制为 `1048576` 个日志行。
+ 缓冲区限制必须大于或等于 `0` 且小于 `536870912` 个日志行。
+ 用于此缓冲区的最大内存量是每个日志行的大小与缓冲区大小的乘积。例如，假设应用程序的日志行大小平均为 `2` KiB，则缓冲区限制为 4096 时最多只能使用 `8` MiB。除了日志驱动程序的内存缓冲区外，在任务级别分配的内存总量必须大于为所有容器分配的内存量。
以下任务定义展示了如何配置 `log-driver-buffer-limit`：
```
{
"containerDefinitions": [
{
"name": "my_service_log_router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
"cpu": 0,
"memoryReservation": 51,
"essential": true,
"firelensConfiguration": {
"type": "fluentbit"
}
},
{
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:latest",
"name": "app",
"logConfiguration": {
"logDriver": "awsfirelens",
"options": {
"Name": "firehose",
"region": "us-west-2",
"delivery_stream": "my-stream",
"log-driver-buffer-limit": "52428800"
}
},
"dependsOn": [
{
"containerName": "my_service_log_router",
"condition": "START"
}
],
"memoryReservation": 100
}
]
}
```
# Amazon ECS 的 AWS for Fluent Bit 映像存储库
AWS 提供了 Fluent Bit 映像以及 CloudWatch Logs 和 Firehose 的插件。我们建议使用 Fluent Bit 作为日志路由器，因为其资源利用率低于 Fluentd。有关更多信息，请参阅 [CloudWatch Logs for Fluent Bit](https://github.com/aws/amazon-cloudwatch-logs-for-fluent-bit) 和 [Amazon Kinesis Firehose for Fluent Bit](https://github.com/aws/amazon-kinesis-firehose-for-fluent-bit)。
为了获得高可用性，Amazon ECR 公开映像浏览馆和 Amazon ECR 存储库上的 Amazon ECR 都提供了 **AWS for Fluent Bit** 映像。
## Amazon ECR 公开映像浏览馆
Amazon ECR 公开映像浏览馆提供了 AWS for Fluent Bit 映像。这是下载 AWS for Fluent Bit 映像的推荐位置，因为它是一个公共存储库，可从所有AWS 区域区域使用。有关更多信息，请参阅 Amazon ECR 公开映像浏览馆上的 [aws-for-fluent-bit](https://gallery.ecr.aws/aws-observability/aws-for-fluent-bit)。
### Linux
Amazon ECR 公开映像浏览馆中的 AWS for Fluent Bit 映像支持带有 `ARM64` 或 `x86-64` 架构的 Amazon Linux 操作系统。
通过使用所需的映像标记指定存储库 URL，可以从 Amazon ECR 公开映像浏览馆中提取 AWS for Fluent Bit 映像。可在 Amazon ECR 公开映像浏览馆上的**映像标签**选项卡上找到映像标签。
下面说明 Docker CLI 使用的语法。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
例如，您可以使用此 Docker CLI 命令拉取适用于 Fluent Bit 的 AWS 版本的“3.x”系列中的最新映像。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
**注意**
可以进行未经身份验证的拉取，但速率限制低于经过身份验证的拉取。拉取前如果要使用 AWS 账户验证身份，请使用以下命令。
```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
#### AWS for Fluent Bit 3.0.0
除了现有的 AWS for Fluent Bit 版本 `2.x` 外，AWS for Fluent Bit 还支持新的主要版本 `3.x`。新的主要版本包括将映像从 Amazon Linux 2 升级到 Amazon Linux 2023 以及将 Fluent Bit 版本 `1.9.10` 升级到 `4.1.1`。有关更多信息，请参阅 GitHub 上的 [AWS for Fluent Bit 存储库](https://github.com/aws/aws-for-fluent-bit/blob/mainline/VERSIONS.md)。
以下示例展示了 AWS for Fluent Bit `3.x` 映像更新后的标签：
您可以对 AWS for Fluent Bit 映像使用多架构标签。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
### Windows
Amazon ECR 公开映像浏览馆中 Fluent Bit 映像的 AWS 支持带有以下操作系统的 `AMD64` 架构：
+ Windows Server 2022 Full
+ Windows Server 2022 Core
+ Windows Server 2019 Full
+ Windows Server 2019 Core
AWS Fargate 上的 Windows 容器不支持 FireLens。
通过使用所需的映像标记指定存储库 URL，可以从 Amazon ECR 公开映像浏览馆中提取 AWS for Fluent Bit 映像。可在 Amazon ECR 公开映像浏览馆上的**映像标签**选项卡上找到映像标签。
下面说明 Docker CLI 使用的语法。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
例如，您可以使用此 Docker CLI 命令拉取最新的稳定 AWS for Fluent Bit 映像。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:windowsservercore-stable
```
**注意**
可以进行未经身份验证的拉取，但速率限制低于经过身份验证的拉取。拉取前如果要使用 AWS 账户验证身份，请使用以下命令。
```
aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
```
## Amazon ECR
AWS for Fluent Bit 映像可在 Amazon ECR 上获得高可用性。可以使用以下命令来检索映像 URI 并确定映像在给定 AWS 区域 区域的可用性。
### Linux
可以使用以下命令检索最新的稳定 AWS for Fluent Bit 映像 URI。
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/stable \
--region us-east-1
```
使用以下命令来查询 Systems Manager Parameter Store 参数可以列出 AWS for Fluent Bit 映像的所有版本。
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit \
--region us-east-1
```
可以通过引用 Systems Manager 参数存储名称在 CloudFormation 模板中引用最新的稳定 AWS for Fluent Bit 映像。以下是示例：
```
Parameters:
FireLensImage:
Description: Fluent Bit image for the FireLens Container
Type: AWS::SSM::Parameter::Value
Default: /aws/service/aws-for-fluent-bit/stable
```
**注意**
如果命令失败或没有输出，则映像在调用该命令的 AWS 区域不可用。
### Windows
可以使用以下命令检索最新的稳定 AWS for Fluent Bit 映像 URI。
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/windowsservercore-stable \
--region us-east-1
```
使用以下命令来查询 Systems Manager Parameter Store 参数可以列出 AWS for Fluent Bit 映像的所有版本。
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit/windowsservercore \
--region us-east-1
```
可以通过引用 Systems Manager 参数存储名称在 CloudFormation 模板中引用最新的稳定 AWS for Fluent Bit 映像。以下是示例：
```
Parameters:
FireLensImage:
Description: Fluent Bit image for the FireLens Container
Type: AWS::SSM::Parameter::Value
Default: /aws/service/aws-for-fluent-bit/windowsservercore-stable
```
# Amazon ECS 任务定义示例：将日志路由到 FireLens
要将自定义日志路由与 FireLens 结合使用，您必须在任务定义中指定以下内容：
+ 包含 FireLens 配置的日志路由器容器。我们建议将容器标记为 `essential`。
+ 一个或多个包含指定 `awsfirelens` 日志驱动程序的日志配置的应用程序容器。
+ 一个任务 IAM 角色 Amazon 资源名称（ARN），其中包含任务路由日志所需的权限。
使用 AWS 管理控制台创建新的任务定义时，通过 Firelens 集成部分可以轻松添加日志路由器容器。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
Amazon ECS 将转换日志配置并生成 Fluentd 或 Fluent Bit 输出配置。输出配置挂载在 `/fluent-bit/etc/fluent-bit.conf`（对于 Fluent Bit）和 `/fluentd/etc/fluent.conf`（对于 Fluentd）处的日志路由容器中。
**重要**
FireLens 在端口 `24224` 上侦听。因此，为了确保从任务外部无法访问 FireLens 日志路由器，不得允许任务使用的安全组中端口 `24224` 上的入口流量。对于使用 `awsvpc` 网络模式的任务，这是与任务关联的安全组。对于使用 `host` 网络模式的任务，它是与托管任务的 Amazon EC2 实例关联的安全组。对于使用 `bridge` 网络模式的任务，请勿创建任何使用端口 `24224` 的端口映射。
默认情况下，Amazon ECS 会在日志条目中添加其他字段来帮助标识日志源。
+ `ecs_cluster`：任务所属的集群的名称。
+ `ecs_task_arn` – 容器所属的任务的完整 Amazon 资源名称（ARN）。
+ `ecs_task_definition`：任务正在使用的任务定义名称和修订。
+ `ec2_instance_id` – 容器托管于的 Amazon EC2 实例 ID。此字段仅对使用 EC2 启动类型的任务有效。
如果您不想要元数据，可以将 `enable-ecs-log-metadata` 设置为 `false`。
下面的任务定义示例定义了一个日志路由器容器，它使用 Fluent Bit 将日志路由到 CloudWatch Logs。该示例还定义了一个应用程序容器，它使用日志配置将日志路由到 Amazon Data Firehose 并将用于缓冲事件的内存设置为 2MiB。
**注意**
有关更多示例任务定义，请参阅 GitHub 上的 [Amazon ECS FireLens 示例](https://github.com/aws-samples/amazon-ecs-firelens-examples)。
```
{
"family": "firelens-example-firehose",
"taskRoleArn": "arn:aws:iam::123456789012:role/ecs_task_iam_role",
"containerDefinitions": [
{
"name": "log_router",
"image": "public.ecr.aws/aws-observability/aws-for-fluent-bit:3",
"cpu": 0,
"memoryReservation": 51,
"portMappings": [],
"essential": true,
"environment": [],
"mountPoints": [],
"volumesFrom": [],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/ecs-aws-firelens-sidecar-container",
"mode": "non-blocking",
"awslogs-create-group": "true",
"max-buffer-size": "25m",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "firelens"
},
"secretOptions": []
},
"systemControls": [],
"firelensConfiguration": {
"type": "fluentbit"
}
},
{
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:latest",
"name": "app",
"logConfiguration": {
"logDriver": "awsfirelens",
"options": {
"Name": "firehose",
"region": "us-west-2",
"delivery_stream": "my-stream",
"log-driver-buffer-limit": "1048576"
}
},
"memoryReservation": 100
}
]
}
```
在 `logConfiguration` 对象中指定为选项的键值对用于生成 Fluentd 或 Fluent Bit 输出配置。以下是来自 Fluent Bit 输出定义的代码示例。
```
[OUTPUT]
Name firehose
Match app-firelens*
region us-west-2
delivery_stream my-stream
```
**注意**
FirelLens 可管理 `match` 配置。您没有在任务定义中指定 `match` 配置。
## 使用自定义配置文件
您可以指定自定义配置文件。配置文件格式是您所使用的日志路由器的本机格式。有关更多信息，请参阅 [Fluentd Config 文件语法](https://docs.fluentd.org/configuration/config-file)和 [YAML 配置](https://docs.fluentbit.io/manual/administration/configuring-fluent-bit/yaml)。
在您的自定义配置文件中，对于使用 `bridge` 或 `awsvpc` 网络模式的任务，请勿通过 TCP 设置 Fluentd 或 Fluent Bit 转发输入，因为 FireLens 会将它添加到输入配置中。
您的 FireLens 配置必须包含以下选项才能指定自定义配置文件：
`config-file-type`
自定义配置文件的源位置。可用选项为 `s3` 或 `file`。
托管在 AWS Fargate 上的任务仅支持 `file` 配置文件类型。但是，您可以使用适用于 Fluent Bit 的 AWS 初始化容器在 AWS Fargate 上使用 Amazon S3 中托管的配置文件。有关更多信息，请参阅 GitHub 上的 [ECS 上的 Fluent Bit 的初始化进程，多配置支持](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)。
`config-file-value`
自定义配置文件的源。如果使用 `s3` 配置文件类型，则配置文件值是 Amazon S3 存储桶和文件的完整 ARN。如果使用 `file` 配置文件类型，则配置文件值是容器映像中或挂载到容器中的卷上存在的配置文件的完整路径。
在使用自定义配置文件时，必须指定一个与 FireLens 所用路径不同的路径。Amazon ECS 保留对于 Fluent Bit 和 `/fluentd/etc/fluent.conf` 对于 Fluentd 的文件路径 `/fluent-bit/etc/fluent-bit.conf`。
以下示例显示了指定自定义配置时所需的语法。
**重要**
要指定托管于 Amazon S3 中的自定义配置文件，请确保已创建具有适当权限的任务执行 IAM 角色。
下面显示了在指定自定义配置时所需的语法。
```
{
"containerDefinitions": [
{
"essential": true,
"image": "906394416424.dkr.ecr.us-west-2.amazonaws.com/aws-for-fluent-bit:3",
"name": "log_router",
"firelensConfiguration": {
"type": "fluentbit",
"options": {
"config-file-type": "s3 | file",
"config-file-value": "arn:aws:s3:::amzn-s3-demo-bucket/fluent.conf | filepath"
}
}
}
]
}
```
**注意**
托管在 AWS Fargate 上的任务仅支持 `file` 配置文件类型。但是，您可以使用适用于 Fluent Bit 的 AWS 初始化容器在 AWS Fargate 上使用 Amazon S3 中托管的配置文件。有关更多信息，请参阅 GitHub 上的 [ECS 上的 Fluent Bit 的初始化进程，多配置支持](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)。
# 在 Amazon ECS 中使用非 AWS 容器映像
使用私有注册表在 AWS Secrets Manager 中存储您的凭证，然后在任务定义中引用它们。这提供了一种方法来引用存在于 AWS 以外的私有注册表中的容器映像，这需要在任务定义中进行身份验证。在 Fargate 上托管的任务、Amazon EC2 实例以及使用 Amazon ECS Anywhere 的外部实例都支持此功能。
**重要**
如果您的任务定义引用了存储在 Amazon ECR 中的映像，则此主题不适用。有关更多信息，请参阅 *Amazon Elastic Container Registry 用户指南*中的[使用 Amazon ECR 和 Amazon ECS](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html)。
对于 Amazon EC2 实例上托管的任务，此功能要求您具有版本 `1.19.0` 或更高版本的容器代理。但是，我们建议使用最新的容器代理版本。有关如何检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。
对于 Fargate 上托管的任务，此功能需要平台版本 `1.2.0` 或更高版本。有关信息，请参阅[适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
在容器定义中，使用您创建的密钥的详细信息指定 `repositoryCredentials` 对象。引用的密钥可以来自与使用此密钥的任务不同的 AWS 区域 或不同的账户。
**注意**
使用 Amazon ECS API、AWS CLI 或 AWS SDK 时，如果密钥存在于要启动的任务所在的AWS 区域，可以使用密钥的完整 ARN 或名称。如果密钥存在于另一个账户中，则必须指定密钥的完整 ARN。使用 AWS 管理控制台 时，必须始终指定密钥的完整 ARN。
下面是显示必需参数的任务定义代码段：
替换以下参数：
+ 将 *private-repo* 替换为私有存储库主机名称
+ 将 *private-image* 替换为映像名称
+ 将 *arn:aws:secretsmanager:region:aws\$1account\$1id:secret:secret\$1name* 替换为密钥 Amazon 资源名称（ARN）
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
**注意**
启用私有注册表身份验证的另一种方法使用 Amazon ECS 容器代理环境变量向私有注册表进行身份验证。此方法仅支持 Amazon EC2 实例上托管的任务。有关更多信息，请参阅 [为私有 Docker 映像配置 Amazon ECS 容器实例](private-auth-container-instances.md)。
**要使用私有注册表**
1. 任务定义必须具有任务执行角色。这允许容器代理拉取容器映像。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
借助私有注册表身份验证，您的 Amazon ECS 任务将可以从位于 AWS 之外且需要身份验证凭证的私有注册表（例如 Docker Hub、Quay.io 或您自己的私有注册表）拉取容器映像。此功能使用 Secrets Manager 来安全地存储注册表凭证，然后使用 `repositoryCredentials` 参数在任务定义中引用这些凭证。
有关配置私有注册表身份验证的更多信息，请参阅[在 Amazon ECS 中使用非 AWS 容器映像](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)。
要允许访问包含您的私有注册表凭证的密钥，请将以下权限作为内联策略添加到任务执行角色中。有关更多信息，请参阅[添加和删除 IAM 策略。](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)
+ `secretsmanager:GetSecretValue`：从 Secrets Manager 检索私有注册表凭证时为必需。
+ `kms:Decrypt`：仅当您的密钥使用自定义 KMS 密钥而不是默认密钥时才需要。您的自定义密钥的 Amazon 资源名称（ARN）必须添加为资源。
下面是添加所需权限的示例内联策略。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"kms:Decrypt",
"secretsmanager:GetSecretValue"
],
"Resource": [
"arn:aws:secretsmanager:us-east-1:111122223333:secret:secret_name",
"arn:aws:kms:us-east-1:111122223333:key/key_id"
]
}
]
}
```
------
1. 使用 AWS Secrets Manager 为您的私有注册表凭证创建密钥。有关如何创建密钥的信息，请参阅《AWS Secrets Manager 用户指南》**中的[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
使用以下格式输入您的私有注册表凭证：
```
{
"username" : "privateRegistryUsername",
"password" : "privateRegistryPassword"
}
```
1. 注册任务定义。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
# 使用容器重启策略重启 Amazon ECS 任务中的单个容器
您可以为任务定义中定义的每个基本容器和非基本容器启用重启策略，以更快地克服暂时性失败并保持任务可用性。为容器启用重启策略后，Amazon ECS 可以在容器退出时重启该容器，而无需替换任务。
默认情况下，容器不会启用重启策略。为容器启用重启策略时，可以指定容器不会重启的退出代码。这些可能是表示成功的退出代码，例如退出代码 `0`，此类退出代码表示不需要重启。您还可以指定容器必须成功运行多长时间后才能尝试重启。有关这些参数的更多信息，请参阅 [重启策略](task_definition_parameters.md#container_definition_restart_policy)。有关指定这些值的任务定义示例，请参阅[在 Amazon ECS 任务定义中指定容器重启策略](container-restart-policy-example.md)。
您可以使用 Amazon ECS 任务元数据端点或 CloudWatch Container Insights 来监控容器重启的次数。有关任务元数据端点的更多信息，请参阅 [Amazon ECS 任务元数据端点版本 4](task-metadata-endpoint-v4.md) 和 [Fargate 上任务的 Amazon ECS 任务元数据端点版本 4](task-metadata-endpoint-v4-fargate.md)。有关适用于 Amazon ECS 的 Container Insights 指标的更多信息，请参阅《Amazon CloudWatch 用户指南》中的 [Amazon ECS Container Insights metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/Container-Insights-metrics-ECS.html)**。
在 Fargate、Amazon EC2 实例以及使用 Amazon ECS Anywhere 的外部实例上托管的任务都支持容器重启策略。
## 注意事项
为容器启用重启策略时应注意以下几个方面：
+ Fargate 上的 Windows 容器不支持重启策略。
+ 对于 Amazon EC2 实例上托管的任务，此功能要求您具有版本 `1.86.0` 或更高版本的容器代理。但是，我们建议使用最新的容器代理版本。有关如何检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。
+ 如果在 `bridge` 网络模式下使用 EC2，则在重启 FireLens 日志路由器容器（容器定义中包含 `firelensConfiguration` 对象的容器）后，应用程序容器中的 `FLUENT_HOST` 环境变量可能会变得不准确。这是因为 `FLUENT_HOST` 是一个动态 IP 地址，重启后就会改变。地址改变后，直接从应用程序容器登录到 `FLUENT_HOST` IP 地址可能会失败。有关 `FLUENT_HOST`的更多信息，请参阅[配置 Amazon ECS 日志，以实现高吞吐量](firelens-docker-buffer-limit.md)。
+ Amazon ECS 代理处理容器重启策略。如果由于某些意外原因导致 Amazon ECS 代理失败或不再运行，则容器将不会重启。
+ 策略中定义的重启尝试期决定了在 Amazon ECS 重启容器之前容器必须运行的时间段（以秒为单位）。
# 在 Amazon ECS 任务定义中指定容器重启策略
要在任务定义中为容器指定重启策略，请在容器定义中指定 `restartPolicy` 对象。有关 `restartPolicy` 对象的更多信息，请参阅[重启策略](task_definition_parameters.md#container_definition_restart_policy)。
下面的任务定义使用 Fargate 上的 Linux 容器来设置 Web 服务器。该容器定义包括 `restartPolicy` 对象，并将 `enabled` 设置为 true 以为该容器启用重启策略。容器必须运行 180 秒后才能重启，并且如果容器以退出代码 `0` 退出，则表示成功，也不会重启容器。
```
{
"containerDefinitions": [
{
"command": [
"/bin/sh -c \"echo ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
' > /usr/local/apache2/htdocs/index.html && httpd-foreground\""
],
"entryPoint": ["sh", "-c"],
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:2.4",
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/fargate-task-definition",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
},
"name": "sample-fargate-app",
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
],
"restartPolicy": {
"enabled": true,
"ignoredExitCodes": [0],
"restartAttemptPeriod": 180
}
}
],
"cpu": "256",
"executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
"family": "fargate-task-definition",
"memory": "512",
"networkMode": "awsvpc",
"runtimePlatform": {
"operatingSystemFamily": "LINUX"
},
"requiresCompatibilities": ["FARGATE"]
}
```
将任务定义注册到容器定义中的 `restartPolicy` 对象后，您可以使用该任务定义运行任务或创建服务。有关更多信息，请参阅[将应用程序作为 Amazon ECS 任务运行](standalone-task-create.md)和[创建 Amazon ECS 滚动更新部署](create-service-console-v2.md)。
# 将敏感数据传递给 Amazon ECS 容器
您可以将敏感数据（例如数据库凭证）安全地传递到容器中。
应用程序经常使用诸如 API 密钥和数据库凭证之类的密钥来访问其他系统。它们通常由用户名和密码、证书或 API 密钥组成。对这些密钥的访问应仅限于使用 IAM 并在运行时注入到容器中的特定 IAM 主体。
密钥可以从 AWS Secrets Manager 和 Amazon EC2 Systems Manager Parameter Store 无缝注入容器中。这些密钥可以在您的任务中作为以下任何内容引用。
1. 它们被引用为使用 `secrets` 容器定义参数的环境变量。
1. 如果您的日志记录平台需要身份验证，它们被引用为 `secretOptions`。有关更多信息，请参阅[日志记录配置选项](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html#API_LogConfiguration_Contents)。
1. 如果从中提取容器的注册表需要身份验证，则使用 `repositoryCredentials` 容器定义参数的映像将它们作为密钥引用。从 Amazon ECR 公开映像浏览馆中提取映像时使用此方法。有关更多信息，请参阅[任务的私有注册表身份验证](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)。
在设置密钥管理时，建议您执行以下操作。
## 使用 AWS Secrets Manager 或 AWS Systems Manager Parameter Store 来存储密钥材料
您应该将 API 密钥、数据库凭证和其他密钥材料安全地存储在 Secrets Manager 中，或者将其作为加密参数存储在 Systems Manager Parameter Store 中。这些服务之所以相似，是因为它们都是使用 AWS KMS 加密敏感数据的托管键值存储。但是 Secrets Manager 还包括自动轮换密钥、生成随机密钥和在账户之间共享密钥的功能。要利用这些功能，请使用 Secrets Manager。否则，请使用 Systems Manager Parameter Store 中的加密参数。
**重要**
如果您的密钥发生更改，则必须强制进行新的部署或启动新任务以检索最新的密钥值。有关更多信息，请参阅以下主题：
任务 – 停止任务，然后启动它。有关更多信息，请参阅[停止 Amazon ECS 任务](standalone-task-stop.md)和[将应用程序作为 Amazon ECS 任务运行](standalone-task-create.md)。
服务 – 更新服务并使用强制新部署选项。有关更多信息，请参阅 [更新 Amazon ECS 服务](update-service-console-v2.md)。
## 从加密的 Amazon S3 存储桶中检索数据
您应将密钥存储在加密的 Amazon S3 存储桶中，并使用任务角色来限制对这些密钥的访问权限。这样可以防止环境变量的值无意中泄漏到日志中，以及在运行 `docker inspect` 时被泄露。执行此操作时，必须编写应用程序以从 Amazon S3 存储桶中读取密钥。有关说明，请参阅[为 Amazon S3 存储桶设置默认服务器端加密行为](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-encryption.html)。
## 使用 sidecar 容器将密钥挂载到卷上
由于环境变量会增加数据泄露的风险，因此您应该运行一个 sidecar 容器，以从 AWS Secrets Manager 中读取密钥并将其写入共享卷中。通过使用 [Amazon ECS 容器排序](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html)，此容器可以在应用程序容器之前运行和退出。当您执行此操作时，应用程序容器随后会挂载写入密钥的卷。与 Amazon S3 存储桶方法类似，必须编写您的应用程序以从共享卷中读取密钥。由于该卷的作用域仅限于任务，因此该卷将在任务停止后自动删除。有关示例，请参阅 [task-def.json](https://github.com/aws-samples/aws-secret-sidecar-injector/blob/master/ecs-task-def/task-def.json) 项目。
在 Amazon EC2 上，可使用 AWS KMS 客户托管密钥对写入密钥的卷进行加密。在 AWS Fargate 上，使用服务托管密钥自动加密卷存储。
# 将单个环境变量传递给 Amazon ECS 容器
**重要**
我们建议将您的敏感数据存储在 AWS Secrets Manager 密钥或 AWS Systems Manager Parameter Store 参数中。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
任务定义中指定的环境变量可由允许执行任务定义 `DescribeTaskDefinition` 操作的所有用户和角色读取。
您可以通过以下方式将环境变量传递到容器：
+ 单独，使用 `environment` 容器定义参数。这会将 `--env` 选项映射到 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)。
+ 批量，使用 `environmentFiles` 容器定义参数列出包含环境变量的一个或多个文件。该文件必须托管在 Amazon S3 中。这会将 `--env-file` 选项映射到 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/)。
以下是演示如何指定单个环境变量的任务定义的代码段。
```
{
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
...
"environment": [
{
"name": "variable",
"value": "value"
}
],
...
}
],
...
}
```
# 将环境变量传递给 Amazon ECS 容器
**重要**
我们建议将您的敏感数据存储在 AWS Secrets Manager 密钥或 AWS Systems Manager Parameter Store 参数中。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
环境变量文件是 Amazon S3 中的对象，所有 Amazon S3 安全注意事项都适用。
您不能在 Windows 容器和 Fargate 上的 Windows 容器上使用 `environmentFiles` 参数。
您可以创建环境变量文件，并将其存储在 Amazon S3 中，以便将环境变量传递给您的容器。
通过在文件中指定环境变量，您可以批量注入环境变量。在容器定义中，使用包含环境变量文件的 Amazon S3 存储桶列表指定 `environmentFiles` 对象。
Amazon ECS 不对环境变量强制实施大小限制，但大型环境变量文件可能会填满磁盘空间。使用环境变量文件的每个任务都会导致文件的副本下载到磁盘。作为任务清理的一部分，Amazon ECS 会删除文件。
有关支持的环境变量的信息，请参阅[高级容器定义参数：环境](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definition_environment)。
在容器定义中指定环境变量文件时，请考虑以下因素。
+ 对于 Amazon EC2 上的 Amazon ECS 任务，您的容器实例需要版本 `1.39.0` 或更高版本的容器代理才能使用此功能。有关如何检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。
+ 对于 AWS Fargate 上的 Amazon ECS 任务，您的任务必须使用平台版本 `1.4.0` 或更高版本（Linux）来使用此功能。有关更多信息，请参阅 [适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
验证操作系统平台是否支持该变量。有关更多信息，请参阅 [容器定义](task_definition_parameters.md#container_definitions) 和 [其他任务定义参数](task_definition_parameters.md#other_task_definition_params)。
+ 该文件必须使用 `.env` 文件扩展名和 UTF-8 编码。
+ 该任务执行角色需要使用此功能和 Amazon S3 的额外权限。这允许容器代理从 Amazon S3 中提取环境变量文件。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
+ 每个任务定义最多只能有 10 个文件。
+ 环境文件中的每一行都必须包含 `VARIABLE=VALUE` 格式的环境变量。空格或引号作为 Amazon ECS 文件的值的一部分**包含**。以开头的行 `#` 被视为注释并会被忽略。有关环境变量文件语法的更多信息，请参阅 Docker 文档中的 [Set environment variables (-e, --env, --env-file)](https://docs.docker.com/reference/cli/docker/container/run/#env)。
以下是合适的语法。
```
#This is a comment and will be ignored
VARIABLE=VALUE
ENVIRONMENT=PRODUCTION
```
+ 如果在容器定义中存在使用 `environment` 参数指定的环境变量，则这些变量的优先级高于环境文件中包含的变量。
+ 如果指定了多个环境文件并且其中包含相同变量，则会按输入顺序处理这些文件。这意味着将使用变量的第一个值，并忽略重复变量的后续值。建议您使用唯一的变量名。
+ 如果将环境文件指定为容器覆盖，则将使用它。此外，容器定义中指定的任何其他环境文件都将被忽略。
+ 以下规则适用于 Fargate：
+ 该文件的处理方式与原生 Docker env-file 类似。
+ 容器中不会出现引用了空白且存储在 Amazon S3 中的环境变量的容器定义。
+ 不支持 shell 转义处理。
+ 容器入口点解释 `VARIABLE` 值。
## 示例
以下是演示如何指定环境变量文件的任务定义的代码段。
```
{
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
...
"environmentFiles": [
{
"value": "arn:aws:s3:::amzn-s3-demo-bucket/envfile_object_name.env",
"type": "s3"
}
],
...
}
],
...
}
```
# 在 Amazon ECS 中以编程方式传递 Secrets Manager 密钥
您可以使用 Secrets Manager 来存储敏感数据，而不是在应用程序中以纯文本形式对敏感信息进行硬编码。
我们建议使用这种方法来检索敏感数据，因为如果随后更新 Secrets Manager 密钥，应用程序会自动检索该密钥的最新版本。
可以在 Secrets Manager 中创建秘密。创建 Secrets Manager 密钥后，更新应用程序代码以检索该密钥。
在 Secrets Manager 中保护敏感数据之前，请查看以下注意事项。
+ 仅存储文本数据的机密，这些机密是使用 `SecretString` 参数 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) 支持 API。不支持存储二进制数据的密钥，这些密钥是使用 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API 的 `SecretBinary` 参数创建的。
+ 使用接口 VPC 端点增强安全控制。您必须为 Secrets Manager 创建接口 VPC 端点。有关 VPC 端点的信息，请参阅《AWS Secrets Manager 用户指南》**中的[创建 VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)。
+ 您的任务使用的 VPC 必须使用 DNS 解析。
+ 任务定义必须使用具有额外 Secrets Manager 权限的任务角色。有关更多信息，请参阅 [Amazon ECS 任务 IAM 角色](task-iam-roles.md)。
## 创建 Secrets Manager 密钥
您可以使用 Secrets Manager 控制台为您的敏感数据创建密钥。有关如何创建密钥的信息，请参阅**《AWS Secrets Manager 用户指南》中的[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
## 更新应用程序以通过编程方式检索 Secrets Manager 密钥
您可以直接从应用程序调用 Secrets Manager API 来检索密钥。有关信息，请参阅《AWS Secrets Manager 用户指南》**中的[从 AWS Secrets Manager 中检索密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。
要检索存储在 AWS Secrets Manager 中的敏感数据，请参阅 *AWS SDK 代码示例代码库*中的[使用 AWS SDK 的 AWS Secrets Manager 的代码示例](https://docs.aws.amazon.com/code-library/latest/ug/secrets-manager_code_examples.html)。
# 在 Amazon ECS 中以编程方式传递 Systems Manager Parameter Store 密钥
Systems Manager Parameter Store 提供了密钥的安全存储和管理。您可以将密码、数据库字符串、EC2 实例 ID 和 AMI ID 以及许可证代码等数据存储为参数值，而不是在应用程序中将这些信息硬编码。可以将值存储为纯文本或加密数据。
建议使用这种方法来检索敏感数据，因为如果随后更新 Systems Manager Parameter Store 参数，应用程序会自动检索最新版本。
在 Systems Manager Parameter Store 中保护敏感数据之前，请查看以下注意事项。
+ 仅支持存储文本数据的密钥。不支持存储二进制数据的密钥。
+ 使用接口 VPC 端点增强安全控制。
+ 您的任务使用的 VPC 必须使用 DNS 解析。
+ 对于使用 EC2 的任务，必须使用 Amazon ECS 代理配置变量 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE=true` 才能使用此功能。您可以在创建容器实例的过程中将其添加到 `/etc/ecs/ecs.config` 文件中，也可以将其添加到现有实例中，然后重新启动 ECS 代理。有关更多信息，请参阅 [Amazon ECS 容器代理配置](ecs-agent-config.md)。
+ 任务定义必须使用具有额外 Systems Manager Parameter Store 权限的任务角色。有关更多信息，请参阅 [Amazon ECS 任务 IAM 角色](task-iam-roles.md)。
## 创建 参数
您可以使用 Systems Manager 控制台为您的敏感数据创建 Systems Manager Parameter Store 参数。有关更多信息，请参阅**《AWS Systems Manager 用户指南》中的[创建 Systems Manager 参数（控制台）](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html)或[创建 Systems Manager 参数（AWS CLI）](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)。
## 更新应用程序以通过编程方式检索 Systems Manager Parameter Store 密钥
要检索存储在 Systems Manager Parameter Store 参数中存储的敏感数据，请参阅 *AWS SDK 代码示例代码库*中的[使用 AWS SDK 的 Systems Manager 的代码示例](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html)。
# 通过 Amazon ECS 环境变量传递 Secrets Manager 密钥
当您将密钥作为环境变量注入时，可以指定密钥的完整内容、密钥内的特定 JSON 键。这将帮助您控制提供给容器的敏感数据。有关密钥版本控制的更多信息，请参阅《AWS Secrets Manager 用户指南》**中的 [What's in a Secrets Manager secret?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/whats-in-a-secret.html#term_version)。
在使用环境变量将 Secrets Manager 密钥注入容器时，应考虑以下事项。
+ 最初启动容器时，会将敏感数据注入容器中。如果随后更新或轮换密钥，则容器将不会自动接收更新后的值。您必须启动新任务，或者如果您的任务是服务的一部分，则可以更新服务并使用**强制新部署**选项来强制服务启动新任务。
+ 在容器上运行的应用程序以及容器日志和调试工具可以访问环境变量。
+ 对于 AWS Fargate 上的 Amazon ECS 任务，请考虑以下事项：
+ 要将密钥的完整内容注入为环境变量或注入到日志配置中，您必须使用平台版本 `1.3.0` 或更高版本的平台。有关信息，请参阅[适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
+ 要将特定 JSON 密钥或密钥版本注入为环境变量或注入到日志配置中，您必须使用平台版本 `1.4.0` 或更高版本（Linux）或者 `1.0.0`（Windows）。有关信息，请参阅[适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
+ 对于 EC2 上的 Amazon ECS 任务，应注意以下事项：
+ 要使用特定的 JSON 密钥或密钥版本注入密钥，容器实例必须具有版本 `1.37.0` 或更高版本的容器代理。但是，我们建议使用最新的容器代理版本。有关检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。
要将密钥的完整内容注入为环境变量或将密钥注入日志配置中，您的容器实例必须具有版本 `1.22.0` 或更高版本的容器代理。
+ 使用接口 VPC 端点增强安全控制措施，并通过私有子网连接到 Secrets Manager。您必须为 Secrets Manager 创建接口 VPC 端点。有关 VPC 端点的信息，请参阅《AWS Secrets Manager 用户指南》**中的[创建 VPC 端点](https://docs.aws.amazon.com/secretsmanager/latest/userguide/setup-create-vpc.html)。有关使用 Secrets Manager 和 Amazon VPC 的更多信息，请参阅[如何在 Amazon VPC 内连接到 Secrets Manager 服务](https://aws.amazon.com/blogs//security/how-to-connect-to-aws-secrets-manager-service-within-a-virtual-private-cloud/)。
+ 对于配置为使用 `awslogs` 日志记录驱动程序的 Windows 任务，您还必须在容器实例上设置 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 环境变量。使用以下语法：
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
```
+ 任务定义必须使用具有 Secrets Manager 额外权限的任务执行角色。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
## 创建 AWS Secrets Manager 密钥
您可以使用 Secrets Manager 控制台为您的敏感数据创建密钥。有关更多信息，请参阅**《AWS Secrets Manager 用户指南》中的[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
## 将环境变量添加到容器定义中
在容器定义中，可以指定以下内容：
+ `secrets` 对象，该对象包含要在容器中设置的环境变量名称
+ Secrets Manager 密钥的 Amazon 资源名称（ARN）。
+ 其他参数，这些参数包含要提供给容器的敏感数据
以下示例显示必须为 Secrets Manager 密钥指定的完整语法。
```
arn:aws:secretsmanager:region:aws_account_id:secret:secret-name:json-key:version-stage:version-id
```
下一部分介绍了其他参数。这些参数是可选的，但如果不使用它们，则必须包含冒号 `:` 以使用默认值。下面提供了示例，以便您了解更多上下文。
`json-key`
使用要设置为环境变量值的值指定密钥-值对中密钥的名称。仅支持 JSON 格式的值。如果未指定 JSON 密钥，则使用密钥的完整内容。
`version-stage`
指定要使用的密钥版本的暂存标签。如果指定了版本的暂存标签，则无法指定版本 ID。如果未指定版本阶段，则默认行为是使用 `AWSCURRENT` 暂存标签检索密钥。
暂存标签用于在更新或轮换密钥的各个版本时对其进行跟踪。密钥的每个版本均有一个或多个暂存标签和一个 ID。
`version-id`
指定要使用的密钥版本的唯一标识符。如果指定了版本 ID，则无法指定版本暂存标签。如果未指定版本 ID，则默认行为是使用 `AWSCURRENT` 暂存标签检索密钥。
版本 ID 用于在更新或轮换密钥的各个版本时对其进行跟踪。密码的每个版本均有一个 ID。有关更多信息，请参阅 *AWS Secrets Manager 用户指南*中的 [AWS Secrets Manager 主要术语和概念。](https://docs.aws.amazon.com/secretsmanager/latest/userguide/terms-concepts.html#term_secret)
### 示例容器定义
以下示例说明了可用于在容器定义中引用 Secrets Manager 密钥的方法。
**Example 引用完整密钥**
以下是任务定义的片段，其中显示引用 Secrets Manager 密钥的完全文本时的格式。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
}]
}]
}
```
要从容器中访问此密钥的值，需要调用 `$environment_variable_name`。
**Example 引用完整密钥**
以下是任务定义的片段，其中显示引用多个 Secrets Manager 密钥的完全文本时的格式。
```
{
"containerDefinitions": [{
"secrets": [
{
"name": "environment_variable_name1",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
},
{
"name": "environment_variable_name2",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-abcdef"
},
{
"name": "environment_variable_name3",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-ABCDEF"
}
]
}]
}
```
要从容器中访问此密钥的值，需要调用 `$environment_variable_name1`、`$environment_variable_name2` 和 `$environment_variable_name3`。
**Example 引用密钥中的特定密钥**
下面显示了 [get-secret-value](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/get-secret-value.html) 命令中的示例输出，其中显示了密钥的内容以及与之关联的版本暂存标签和版本 ID。
```
{
"ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
"Name": "appauthexample",
"VersionId": "871d9eca-18aa-46a9-8785-981ddEXAMPLE",
"SecretString": "{\"username1\":\"password1\",\"username2\":\"password2\",\"username3\":\"password3\"}",
"VersionStages": [
"AWSCURRENT"
],
"CreatedDate": 1581968848.921
}
```
通过在 ARN 的末尾指定密钥名称，引用容器定义中的上一个输出中的特定密钥。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::"
}]
}]
}
```
**Example 引用特定的密钥版本**
下面显示了 [describe-secret](https://docs.aws.amazon.com/cli/latest/reference/secretsmanager/describe-secret.html) 命令中的示例输出，其中显示了密钥的未加密内容以及密钥的所有版本的元数据。
```
{
"ARN": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf",
"Name": "appauthexample",
"Description": "Example of a secret containing application authorization data.",
"RotationEnabled": false,
"LastChangedDate": 1581968848.926,
"LastAccessedDate": 1581897600.0,
"Tags": [],
"VersionIdsToStages": {
"871d9eca-18aa-46a9-8785-981ddEXAMPLE": [
"AWSCURRENT"
],
"9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE": [
"AWSPREVIOUS"
]
}
}
```
通过在 ARN 的末尾指定密钥名称，引用容器定义中的上一个输出中的特定版本暂存标签。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf::AWSPREVIOUS:"
}]
}]
}
```
通过在 ARN 的末尾指定密钥名称，引用容器定义中的上一个输出中的特定版本 ID。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
}]
}]
}
```
**Example 引用密钥的特定密钥和版本暂存标签**
以下内容说明如何同时引用密钥中的特定密钥和特定版本暂存标签。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1:AWSPREVIOUS:"
}]
}]
}
```
要指定特定密钥和版本 ID，请使用以下语法。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:appauthexample-AbCdEf:username1::9d4cb84b-ad69-40c0-a0ab-cead3EXAMPLE"
}]
}]
}
```
有关如何使用环境变量中指定的密钥创建任务定义的信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
# 通过 Amazon ECS 环境变量传递 Systems Manager 参数
您可以使用 Amazon ECS 向容器中注入敏感数据，方法是将您的敏感数据存储在 AWS Systems Manager Parameter Store 参数中，然后在容器定义中引用它们。
在使用环境变量将 Systems Manager 密钥注入容器时，应注意以下事项。
+ 最初启动容器时，会将敏感数据注入容器中。如果随后更新或轮换密钥，则容器将不会自动接收更新后的值。您必须启动新任务，或者如果您的任务是服务的一部分，则可以更新服务并使用**强制新部署**选项来强制服务启动新任务。
+ 对于 AWS Fargate 上的 Amazon ECS 任务，应注意以下事项：
+ 要将密钥的完整内容注入为环境变量或注入到日志配置中，您必须使用平台版本 `1.3.0` 或更高版本的平台。有关信息，请参阅[适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
+ 要将特定 JSON 密钥或密钥版本注入为环境变量或注入到日志配置中，您必须使用平台版本 `1.4.0` 或更高版本（Linux）或者 `1.0.0`（Windows）。有关信息，请参阅[适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。
+ 对于 EC2 上的 Amazon ECS 任务，应注意以下事项：
+ 要使用特定的 JSON 密钥或密钥版本注入密钥，容器实例必须具有版本 `1.37.0` 或更高版本的容器代理。但是，我们建议使用最新的容器代理版本。有关检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。
要将密钥的完整内容注入为环境变量或将密钥注入日志配置中，您的容器实例必须具有版本 `1.22.0` 或更高版本的容器代理。
+ 使用接口 VPC 端点增强安全控制。您必须为 Systems Manager 创建接口 VPC 端点。有关 VPC 端点的信息，请参阅《AWS Systems Manager 用户指南》**中的[使用适用于 Systems Manager 的 VPC 端点提高 EC2 实例的安全性](https://docs.aws.amazon.com/systems-manager/latest/userguide/setup-create-vpc.html)。
+ 任务定义必须使用具有额外 Systems Manager Parameter Store 权限的任务执行角色。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
+ 对于配置为使用 `awslogs` 日志记录驱动程序的 Windows 任务，您还必须在容器实例上设置 `ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE` 环境变量。使用以下语法：
```
[Environment]::SetEnvironmentVariable("ECS_ENABLE_AWSLOGS_EXECUTIONROLE_OVERRIDE", $TRUE, "Machine")
Initialize-ECSAgent -Cluster -EnableTaskIAMRole -LoggingDrivers '["json-file","awslogs"]'
```
## 创建 Systems Manager 参数
您可以使用 Systems Manager 控制台为您的敏感数据创建 Systems Manager Parameter Store 参数。有关更多信息，请参阅**《AWS Systems Manager 用户指南》中的[创建 Systems Manager 参数（控制台）](https://docs.aws.amazon.com/systems-manager/latest/userguide/parameter-create-console.html)或[创建 Systems Manager 参数（AWS CLI）](https://docs.aws.amazon.com/systems-manager/latest/userguide/param-create-cli.html)。
## 将环境变量添加到容器定义中
在任务定义中的容器定义中，使用要在容器中设置的环境变量的名称以及包含要提供给容器的敏感数据的 Systems Manager Parameter Store 参数完整 ARN 指定 `secrets`。有关更多信息，请参阅 [secrets](task_definition_parameters.md#ContainerDefinition-secrets)。
以下是任务定义的片段，其中显示引用 Systems Manager Parameter Store 参数时的格式。如果 Systems Manager Parameter Store 参数存在于要启动的任务所在的区域，则可以使用参数的完整 ARN 或名称。如果参数存在于不同的区域，则指定完整的 ARN。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}]
}]
}
```
有关如何使用环境变量中指定的密钥创建任务定义的信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
## 更新应用程序以通过编程方式检索 Systems Manager Parameter Store 密钥
要检索存储在 Systems Manager Parameter Store 参数中存储的敏感数据，请参阅 *AWS SDK 代码示例代码库*中的[使用 AWS SDK 的 Systems Manager 的代码示例](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html)。
# 传递用于 Amazon ECS 日志记录配置的密钥
您可以使用 `logConfiguration` 中的 `secretOptions` 参数来传递用于日志记录的敏感数据。
您可以将密钥存储在 Secrets Manager 或 Systems Manager 中。
## 使用 Secrets Manager
在容器定义中，当指定 `logConfiguration` 时，您可以同时指定 `secretOptions`，方法是使用要在容器中设置的日志驱动程序选项的名称，以及包含要提供给容器的敏感数据的 Secrets Manager 密钥的完整 ARN。有关创建密钥的更多信息，请参阅[创建 AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
以下是任务定义的片段，其中显示引用 Secrets Manager 密钥时的格式。
```
{
"containerDefinitions": [{
"logConfiguration": [{
"logDriver": "splunk",
"options": {
"splunk-url": "https://your_splunk_instance:8088"
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name-AbCdEf"
}]
}]
}]
}
```
## 将环境变量添加到容器定义中
在容器定义中，使用要在容器中设置的环境变量的名称和包含要提供给容器的敏感数据的 Systems Manager Parameter Store 参数的完整 ARN 指定 `secrets`。有关更多信息，请参阅 [secrets](task_definition_parameters.md#ContainerDefinition-secrets)。
以下是任务定义的片段，其中显示引用 Systems Manager Parameter Store 参数时的格式。如果 Systems Manager Parameter Store 参数存在于要启动的任务所在的区域，则可以使用参数的完整 ARN 或名称。如果参数存在于不同的区域，则指定完整的 ARN。
```
{
"containerDefinitions": [{
"secrets": [{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}]
}]
}
```
有关如何使用环境变量中指定的密钥创建任务定义的信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
## 使用 Systems Manager
您可以在日志配置中注入敏感数据。在容器定义中，当指定 `logConfiguration` 时，您可以使用要在容器中设置的日志驱动程序选项的名称以及包含要提供给容器的敏感数据的 Systems Manager Parameter Store 参数的完整 ARN 指定 `secretOptions`。
**重要**
如果 Systems Manager Parameter Store 参数存在于要启动的任务所在的区域，则可以使用参数的完整 ARN 或名称。如果参数存在于不同的区域，则指定完整的 ARN。
以下是任务定义的片段，其中显示引用 Systems Manager Parameter Store 参数时的格式。
```
{
"containerDefinitions": [{
"logConfiguration": [{
"logDriver": "fluentd",
"options": {
"tag": "fluentd demo"
},
"secretOptions": [{
"name": "fluentd-address",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter:/parameter_name"
}]
}]
}]
}
```
# 在 Amazon ECS 中指定使用 Secrets Manager 密钥的敏感数据
使用 Amazon ECS 时，您可以将敏感数据存储在 AWS Secrets Manager 密钥中，然后在容器定义中引用这些密钥，从而将敏感数据注入容器。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
了解如何创建 Secrets Manager 密钥，在 Amazon ECS 任务定义中引用该密钥，然后通过查询显示密钥内容的容器内的环境变量来验证它是否有效。
## 先决条件
本教程假设以下先决条件已完成：
+ [设置以使用 Amazon ECS](get-set-up-for-amazon-ecs.md) 中的步骤已完成。
+ 您的用户具有创建 Secrets Manager 和 Amazon ECS 资源所需的 IAM 权限。
## 步骤 1：创建 Secrets Manager 密钥
您可以使用 Secrets Manager 控制台为您的敏感数据创建密钥。在本教程中，我们将创建一个基本密钥来存储用户名和密码以便稍后在容器中引用。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
**key/value pairs to be stored in this secret**（要存储在此密钥中的键/值对）是教程末尾处容器中的环境变量值。
保存**密钥 ARN** 以便在后续步骤中在任务执行 IAM 策略和任务定义中引用。
## 步骤 2：向任务执行角色添加密钥权限
为了让 Amazon ECS 检索 Secrets Manager 密钥中的敏感数据，您必须具有任务执行角色的密钥权限。有关更多信息，请参阅 [Secrets Manager 或 Systems Manager 权限](task_execution_IAM_role.md#task-execution-secrets)。
## 步骤 3：创建任务定义
可以使用 Amazon ECS 控制台创建引用了 Secrets Manager 密钥的任务定义。
**创建指定密钥的任务定义**
使用 IAM 控制台更新具有所需权限的任务执行角色。
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择 **Task definitions**（任务定义）。
1. 选择 **Create new task definition**（创建新的任务定义）、**Create new task definition with JSON**（使用 JSON 创建新的任务定义）。
1. 在 JSON 编辑器框中，输入以下任务定义 JSON 文本，确保已指定在步骤 1 中创建的 Secrets Manager 密钥的完整 ARN，以及在步骤 2 中更新的任务执行角色。选择**保存**。
1.
```
{
"executionRoleArn": "arn:aws:iam::aws_account_id:role/ecsTaskExecutionRole",
"containerDefinitions": [
{
"entryPoint": [
"sh",
"-c"
],
"portMappings": [
{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
}
],
"command": [
"/bin/sh -c \"echo ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
' > /usr/local/apache2/htdocs/index.html && httpd-foreground\""
],
"cpu": 10,
"secrets": [
{
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:username_value",
"name": "username_value"
}
],
"memory": 300,
"image": "public.ecr.aws/docker/library/httpd:2.4",
"essential": true,
"name": "ecs-secrets-container"
}
],
"family": "ecs-secrets-tutorial"
}
```
1. 选择**创建**。
## 步骤 4：创建集群
您可以使用 Amazon ECS 控制台创建一个包含要运行任务的容器实例的集群。如果现有集群中至少注册了一个容器实例，并且具有可用资源来运行为本教程创建的任务定义的一个实例，则可跳到下一步。
在本教程中，我们将使用经 Amazon ECS 优化的 Amazon Linux 2 AMI 创建具有一个 `t2.micro` 容器实例的集群。
有关如何为 EC2 创建集群的信息，请参阅 [为 Amazon EC2 工作负载创建 Amazon ECS 集群](create-ec2-cluster-console-v2.md)。
## 步骤 5：运行任务
您可以使用 Amazon ECS 控制台通过创建的任务定义运行任务。在本教程中，我们将使用上一步中创建的集群来运行使用 EC2 的任务。
有关如何运行任务的信息，请参阅 [将应用程序作为 Amazon ECS 任务运行](standalone-task-create.md)。
## 步骤 6：验证
您可以使用以下步骤验证是否已成功完成所有步骤并在容器中正确创建了环境变量。
**验证是否已创建环境变量**
1. 查找您的容器实例的公共 IP 或 DNS 地址。
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择**集群**，然后选择您创建的集群。
1. 选择**基础设施**，然后选择容器实例。
1. 记录您的实例的**公有 IP** 或**公有 DNS**。
1. 如果您使用的是 macOS 或 Linux 计算机，请使用以下命令连接到您的实例，并替换您的私有密钥的路径和实例的公共地址：
```
$ ssh -i /path/to/my-key-pair.pem ec2-user@ec2-198-51-100-1.compute-1.amazonaws.com
```
有关使用 Windows 计算机的更多信息，请参阅《Amazon EC2 用户指南》**中的[使用 PuTTY 连接到 Linux 实例](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-from-windows.html)。
**重要**
要详细了解您在连接到实例时遇到的任何问题，请参阅《Amazon EC2 用户指南》中的[排查实例的连接问题](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/TroubleshootingInstancesConnecting.html)**。
1. 列出正在实例上运行的容器。记下 `ecs-secrets-tutorial` 容器的容器 ID。
```
docker ps
```
1. 使用上一步的输出中的容器 ID 连接到 `ecs-secrets-tutorial` 容器。
```
docker exec -it container_ID /bin/bash
```
1. 使用 `echo` 命令打印环境变量的值。
```
echo $username_value
```
如果教程成功完成，您应看到以下输出：
```
password_value
```
**注意**
或者，您可以使用 `env`（或 `printenv`）命令列出容器中的所有环境变量。
## 步骤 7：清除
完成本教程后，您应清除相关资源，以避免产生与未使用的资源相关的费用。
**清除资源**
1. 在 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2) 打开控制台。
1. 在导航窗格中，选择**集群**。
1. 在 **Clusters**（集群）页面上，选择集群。
1. 选择**删除集群**。
1. 在确认框中，输入 **delete *cluster name***，然后选择**删除**。
1. 通过以下网址打开 IAM 控制台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在导航窗格中，选择**角色**。
1. 在角色列表中搜索 `ecsTaskExecutionRole` 并将其选定。
1. 选择**权限**，然后选择 **ECSSecretsTutorial** 旁边的 **X**。选择**移除 **。
1. 通过 [https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/) 打开 Secrets Manager 控制台。
1. 选择您之前创建的 **username\$1value** 密钥，然后选择**操作**、**删除密钥**。
# Amazon ECS 托管实例的 Amazon ECS 任务定义参数
任务定义包括以下各部分：任务系列、AWS Identity and Access Management（IAM）任务角色、网络模式、容器定义、卷和容量。任务定义中需要系列和容器定义。相反，任务角色、网络模式、卷和容量是可选的。
您可以在 JSON 文件中使用这些参数来配置任务定义。
以下是 Amazon ECS 托管实例的每个任务定义参数的更详细描述。
## 系列
`family`
类型：字符串
是否必需：是
当您注册任务定义时，将为其提供一个系列，与任务定义的多个版本的名称类似，它是使用修订号指定的。注册到某个特定系列的第一个任务定义将获得修订 1，而随后注册的任何任务定义将获得后续修订号。
## 容量
注册任务定义时，您可以指定 Amazon ECS 应根据哪个容量来验证任务定义。如果任务定义未根据指定的兼容性进行验证，则返回客户端异常。有关更多信息，请参阅 [Amazon ECS 启动类型](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/launch_types.html)。
任务定义中允许以下参数。
`requiresCompatibilities`
类型：字符串数组
必需：否
有效值：`MANAGED_INSTANCES`
根据其验证任务定义的容量。这将启动一项检查，以确保任务定义中使用的所有参数都符合 Amazon ECS 托管实例的要求。
## 任务 角色
`taskRoleArn`
类型：字符串
必需：否
注册任务定义时，可以为 IAM 角色提供任务角色，此角色可使任务中的容器有权代表您调用其关联策略中指定的 AWS API。有关更多信息，请参阅 [Amazon ECS 任务 IAM 角色](task-iam-roles.md)。
## 任务执行 角色
`executionRoleArn`
类型：字符串
必需：条件
任务执行角色的 Amazon 资源名称（ARN），该角色授予 Amazon ECS 容器代理代表您进行 AWS API 调用的权限。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
任务执行 IAM 角色是必需的，具体取决于任务的要求。该角色是拉取私有 ECR 映像和使用 `awslogs` 日志驱动程序所必需的。
## 网络模式
`networkMode`
类型：字符串
必需：否
默认值：`awsvpc`
在任务中用于容器的联网模式。对于托管在 Amazon ECS 托管实例上的 Amazon ECS 任务，有效值是 `awsvpc` 和 `host`。如果未指定网络模式，则默认网络模式为 `awsvpc`。
如果网络模式为 `host`，则任务会绕过网络隔离，并且容器直接使用主机的网络堆栈。
运行使用 `host` 网络模式的任务时，请勿使用根用户（UID 0）运行容器，以获得更好的安全性。作为安全最佳实践，请始终使用非根用户。
如果网络模式为 `awsvpc`，则将为任务分配弹性网络接口，且在创建服务或运行具有任务定义的任务时必须指定 `NetworkConfiguration`。有关更多信息，请参阅 [Amazon ECS 托管实例的 Amazon ECS 任务联网](managed-instance-networking.md)。
`host` 和 `awsvpc` 网络模式可为容器提供最高联网性能，因为容器使用 Amazon EC2 网络堆栈。使用 `host` 和 `awsvpc` 网络模式，公开的容器端口将直接映射到相应的主机端口（用于 `host` 网络模式）或附加的弹性网络接口端口（用于 `awsvpc` 网络模式）。因此，您不能使用动态主机端口映射。
## 运行时平台
`operatingSystemFamily`
类型：字符串
必需：否
原定设置：LINUX
当您注册任务定义时，您可以指定操作系统系列。
此字段的有效值是 `LINUX`。
服务中使用的所有任务定义对于此参数都必须具有相同的值。
当任务定义是服务的一部分时，此值必须与服务 `platformFamily` 值匹配。
`cpuArchitecture`
类型：字符串
必需：条件
当您注册任务定义时，您可以指定 CPU 架构。有效值为 `X86_64` 和 `ARM64`。
如果不指定值，Amazon ECS 会根据容量提供程序配置尝试将任务放置在可用的 CPU 架构上。要确保任务放置在特定 CPU 架构上，请在任务定义中指定 `cpuArchitecture` 的值。
服务中使用的所有任务定义对于此参数都必须具有相同的值。
有关 `ARM64`的更多信息，请参阅[适用于 64 位 ARM 工作负载的 Amazon ECS 任务定义](ecs-arm64.md)。
## 任务大小
注册任务定义时，您可以指定用于任务的总 CPU 和内存量。这独立于容器定义级别的 `cpu` 和 `memory` 值。对于 Amazon EC2 实例上托管的任务，这些字段是可选的。
**注意**
Windows 容器将忽略任务级 CPU 和内存参数。我们建议为 Windows 容器指定容器级资源。
`cpu`
类型：字符串
必需：条件
要为任务提供的 CPU 单位的硬限制。您可以通过 CPU 单位数或虚拟 CPU（vCPU）数字符串的方式在 JSON 文件中将 CPU 值。例如，您可以使用 `1024`（CPU 单位数）或 `1 vCPU`（vCPU 数）来指定 CPU 值。注册任务定义时，vCPU 值将转换为指示 CPU 单元的整数。
该字段是可选的。如果您的集群没有任何带可用的已请求 CPU 单位的已注册容器实例，则该任务将失败。支持的值介于 `0.125` vCPU 和 `10` vCPU 之间。
`memory`
类型：字符串
必需：条件
要向任务提供的内存硬限制。您可以通过以二进制兆字节（MiB）或千兆字节（GB）字符串方式在任务定义中指定内存值。例如，您可以使用 `3072`（以 MiB 为单位）或 `3 GB`（以 GB 为单位）指定内存值。注册任务定义时，GB 值将转换为指示 MiB 的整数。
此字段是可选的，并且可使用任何值。如果指定了任务级内存值，则容器级内存值是可选的。如果您的集群没有任何带可用的已请求内存的已注册容器实例，则该任务将失败。您可以尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源。有关更多信息，请参阅 [预留 Amazon ECS Linux 容器实例内存](memory-management.md)。
## 其他任务定义参数
以下任务定义参数可在 Amazon ECS 控制台中注册任务定义时使用，方法是使用 **Configure via JSON**（通过 JSON 配置）选项。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
**Topics**
+ [
### 临时存储
](#task_definition_ephemeralStorage-managed-instances)
+ [
### IPC 模式
](#task_definition_ipcmode-managed-instances)
+ [
### PID 模式
](#task_definition_pidmode-managed-instances)
+ [
### 代理配置
](#proxyConfiguration-managed-instances)
+ [
### 标签
](#tags-managed-instances)
+ [
### Elastic Inference 加速器（已弃用）
](#elastic-Inference-accelerator-managed-instances)
+ [
### 置放约束
](#constraints-managed-instances)
+ [
### 卷
](#volumes-managed-instances)
### 临时存储
`ephemeralStorage`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：[EphemeralStorage](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EphemeralStorage.html) 对象
必需：否
要为任务分配的临时存储量（以 GB 为单位）。此参数用于扩展可用的临时存储总量，超出原定设置数量，可用于在 AWS Fargate 上托管的任务。有关更多信息，请参阅 [将绑定挂载与 Amazon ECS 结合使用](bind-mounts.md)。
### IPC 模式
`ipcMode`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：字符串
必需：否
用于任务中的容器的 IPC 资源命名空间。有效值为 `host`、`task` 或 `none`。如果指定了 `host`，则在同一容器实例上指定了 `host` IPC 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的 IPC 资源。如果指定了 `task`，则指定任务中的所有容器将共享相同的 IPC 资源。如果指定了 `none`，则任务的容器中的 IPC 资源是私有的，不与任务中或容器实例上的其他容器共享。如果未指定任何值，则 IPC 资源命名空间共享取决于容器运行时配置。
### PID 模式
`pidMode`
类型：字符串
必需：否
用于任务中的容器的过程命名空间。有效值为 `host` 或 `task`。如果指定了 `host`，则在同一容器实例上指定了 `host` PID 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的进程命名空间。如果指定了 `task`，则指定任务中的所有容器将共享相同的进程命名空间。如果未指定任何值，则默认值为私有命名空间。
如果使用了 `host` PID 模式，发生非预期的过程命名空间公开的风险会提高。
### 代理配置
`proxyConfiguration`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：[ProxyConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ProxyConfiguration.html) 对象
必需：否
App Mesh 代理的配置详细信息。
### 标签
您应用于任务定义以帮助您对其进行分类和组织的元数据。每个标签都由一个键和一个可选值组成。您可以同时定义它们。
下面是适用于标签的基本限制：
+ 每个资源的最大标签数：50
+ 对于每个资源，每个标签键都必须是唯一的，每个标签键只能有一个值。
+ 最大键长度：128 个 Unicode 字符（采用 UTF-8 格式）
+ 最大值长度：256 个 Unicode 字符（采用 UTF-8 格式）
+ 如果您的标记模式针对多个服务和资源使用，请记得其它服务可能对允许使用的字符有限制。通常允许使用的字符包括：可用 UTF-8 格式表示的字母、数字和空格，以及以下字符：\$1：= . \$1 : / @。
+ 标签键和值区分大小写。
+ 请不要使用 `aws:`、`AWS:` 或任何大写或小写组合（例如，键或值的前缀），因为它将保留以供 AWS 使用。您无法编辑或删除带此前缀的标签键或值。具有此前缀的标签不计入每个资源的标签数限制。
`key`
类型：字符串
必需：否
构成标签的键-值对的一个部分。键是一种常见的标签，行为类似于更具体的标签值的类别。
`value`
类型：字符串
必需：否
构成标签的键-值对的可选部分。值充当标签类别（键）中的描述符。
### Elastic Inference 加速器（已弃用）
**注意**
Amazon Elastic Inference（EI）功能不再向客户开放。
`inferenceAccelerator`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型[InferenceAccelerator](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_InferenceAccelerator.html) 对象
必需：否
用于任务中的容器的 Elastic Inference 加速器。
### 置放约束
`placementConstraints`
类型：[TaskDefinitionPlacementConstraint](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_TaskDefinitionPlacementConstraint.html) 对象数组
必需：否
要用于任务的一组放置约束对象。对于每个任务，您可以指定多达 10 种约束（此限制包括任务定义中的约束和这些在运行时指定的约束）。
对于在 Amazon ECS 托管实例上运行的任务，Amazon ECS 支持 `distinctInstace` 和 `memberOf` 放置约束。使用 `memberOf` 放置约束的任务支持下面的属性：
+ `ecs.subnet-id`
+ `ecs.availability-zone`
+ `ecs.cpu-architecture`
+ `ecs.instance-type`
有关放置约束的更多信息，请参阅[定义 Amazon ECS 将哪些容器实例用于任务](task-placement-constraints.md)。
### 卷
注册任务定义时，您可以选择性地为任务指定卷列表。这样，您便可以在任务中使用数据卷。
有关卷类型和其他参数的更多信息，请参阅[Amazon ECS 任务的存储选项](using_data_volumes.md)。
`name`
类型：字符串
是否必需：是
卷的名称。最多能包含 255 个字母（大写和小写字母）、数字和下划线。此名称已在容器定义`sourceVolume`的`mountPoints`参数中引用。
`host`
类型：[HostVolumeProperties](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_HostVolumeProperties.html) 对象
必需：否
使用绑定挂载主机卷时需指定此参数。`host` 参数的内容确定您的绑定挂载主机卷是否一直保存在主机容器实例上以及存储它的位置上。如果 `host` 参数为空，则系统将为数据卷分配主机路径。但是，在与该卷关联的容器停止运行后，不保证保存数据。
`sourcePath`
类型：字符串
必需：否
在使用 `host` 参数时，指定 `sourcePath` 可声明提供给容器的主机实例上的路径。如果此参数为空，则系统将分配一个主机路径。如果 `host` 参数包含 `sourcePath` 文件位置，则数据卷将在主机实例上的指定位置保留，除非手动将其删除。如果主机实例上不存在 `sourcePath` 值，则系统将创建该值。如果该位置不存在，则将导出源路径文件夹的内容。
在 Amazon ECS 托管实例上，主机文件系统的部分内容为只读。`sourcePath` 必须指向可写目录，例如 `/var` 或 `/tmp`。有关更多信息，请参阅 [将绑定挂载与 Amazon ECS 结合使用](bind-mounts.md)。
`dockerVolumeConfiguration`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：[DockerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DockerVolumeConfiguration.html) 对象
必需：否
使用 Docker 卷时需指定此参数。
`efsVolumeConfiguration`
类型：[EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 对象
必需：否
使用 Amazon EFS 文件系统进行任务存储时需指定此参数。
`fsxWindowsFileServerVolumeConfiguration`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：[FSxWindowsFileServerVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_FSxWindowsFileServerVolumeConfiguration.html) 对象
必需：否
使用适用于 Windows File Server 的 Amazon FSx 文件系统进行任务存储时需指定此参数。
`configuredAtLaunch`
类型：布尔值
必需：否
指示是否应在启动时配置卷。这用于为独立任务或作为服务的一部分创建的任务创建 Amazon EBS 卷。每个任务定义修订只能在启动时在卷配置中配置一个卷。
## 容器定义
当您注册任务定义时，必须指定将传递给容器实例上的 Docker 进程守护程序的容器定义的列表。容器定义中允许以下参数。
**Topics**
+ [
### 名称
](#container_definition_name-managed-instances)
+ [
### Image
](#container_definition_image-managed-instances)
+ [
### 内存
](#container_definition_memory-managed-instances)
+ [
### CPU
](#container_definition_cpu-managed-instances)
+ [
### 端口映射
](#container_definition_portmappings-managed-instances)
+ [
### 私有存储库凭证
](#container_definition_repositoryCredentials-managed-instances)
+ [
### Essential
](#container_definition_essential-managed-instances)
+ [
### 入口点
](#container_definition_entrypoint-managed-instances)
+ [
### 命令
](#container_definition_command-managed-instances)
+ [
### 工作目录
](#container_definition_workingdirectory-managed-instances)
+ [
### 高级容器定义参数
](#advanced_container_definition_params-managed-instances)
+ [
### Linux 参数
](#container_definition_linuxparameters-managed-instances)
### 名称
`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` 选项。
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 内存。同时，此配置还允许容器在需要时使用更多内存资源。
Docker 20.10.0 或更高版本进程守护程序将为容器预留最少 6MiB 的内存。因此，不要为容器指定少于 6MiB 的内存。
Docker 19.03.13-ce 或更早版本的进程守护程序将为容器预留最少 4MiB 的内存。因此，不要为容器指定少于 4MiB 的内存。
如果您尝试通过为任务提供尽可能多的用于特定实例类型的内存来最大程度地利用资源，请参阅[预留 Amazon ECS Linux 容器实例内存](memory-management.md)。
### CPU
`cpu`
类型：整数
必需：否
为容器预留的 `cpu` 单元数。此参数对应于 docker create-container 命令中的 `CpuShares` 和 docker run 命令的 `--cpu-shares` 选项。
此字段对于使用 EC2 容量提供程序的任务是可选的，而且唯一要求是任务内为所有容器保留的 CPU 总量低于任务级 `cpu` 值。
您可以通过将 [Amazon EC2 实例](https://aws.amazon.com/ec2/instance-types/)详细信息页面上列出的每个 EC2 实例类型的 vCPU 数乘以 1024，确定该实例类型可用的 CPU 单元数。
Linux 容器会按照与其分配的量相同的比例，与容器实例上的其他容器共享未分配的 CPU 单元。例如，如果您在单核实例类型上运行一个单容器任务，同时为该容器指定 512 个 CPU 单元，而且这是在容器实例上运行的唯一任务，则该容器可在任何给定间使用完整的 1024 个 CPU 单元。但是，如果您在该容器实例上启动了同一任务的另一个副本，则保证每个任务在需要时至少有 512 个 CPU 单位。此外，如果另一个容器没有使用它，则每个容器都可以浮动到更高的 CPU 使用率。如果两个任务一直都处于 100％ 活动状态，那么它们将限制为 512 个 CPU 单位。
在 Linux 容器实例上，容器实例上的 Docker 进程守护程序使用 CPU 值来计算正在运行的容器的相对 CPU 共享比例。有关更多信息，请参阅 Docker 文档中的 [CPU 共享约束](https://docs.docker.com/engine/reference/run/#cpu-share-constraint)。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 传递给 Docker。
在 Windows 容器实例上，此 CPU 限制将作为绝对限制或配额强制实施。Windows 容器只能访问任务定义中所述的指定的 CPU 量。Null 或零 CPU 值作为 `0` 传递给 Docker，Windows 将其解释为一个 CPU 的 1%。
### 端口映射
`portMappings`
类型：对象数组
必需：否
端口映射将容器的网络端口暴露给外界。这让客户端能够访问您的应用程序。它也用于同一任务内的容器间通信。
对于使用 `awsvpc` 网络模式的任务定义，只能指定 `containerPort`。`hostPort` 始终被忽略，并且容器端口会自动映射到主机上的随机高编号端口。
此参数的大部分字段（包括 `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` 指定公开的端口。
`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` 时，以下规则适用：
+ 您必须使用 `awsvpc` 网络模式。
+ 容器实例必须拥有不低于 1.67.0 版本的容器代理和不低于 1.67.0-1 版本的 `ecs-init` 程序包。
+ 每个容器最多可指定 100 个端口范围。
+ 您不用指定 `hostPortRange`。`hostPortRange` 的值设置如下：
+ 对于使用 `awsvpc` 网络模式的任务中的容器，`hostPort` 将设置为与 `containerPort` 相同的值。这是一种静态映射策略。
+ `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`
类型：整数
必需：否
要为您的容器预留的容器实例上的端口号。
`hostPort` 可以留空或值与 `containerPort` 相同。
Docker 版本 1.6.0 及更高版本的默认临时端口范围在 `/proc/sys/net/ipv4/ip_local_port_range` 下的实例上列出。如果此内核参数不可用，则将使用来自 `49153–65535` 的原定设置临时端口范围。不要尝试指定临时端口范围内的主机端口。这是因为这些都是为自动分配预留的。通常，低于 `32768` 的端口位于临时端口范围之外。
默认预留端口为适用于 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`。
如果您指定的是主机端口，请使用以下语法。
```
"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"
}
}
]
```
### Essential
`essential`
类型：布尔值
必需：否
如果将容器的 `essential` 参数标记为 `true`，并且该容器出于任何原因发生故障或停止，则属于此任务的所有其他容器将停止。如果将容器的 `essential` 参数标记为 `false`，则容器发生故障不会影响任务中的剩余容器。如果省略此参数，则假定容器是主要容器。
所有任务都必须具有至少一个主要容器。如果您有一个由多个容器组成的应用程序，则将用于相同目的的容器分成多个组件，然后将不同的组件分为多个任务定义。有关更多信息，请参阅 [设计适用于 Amazon ECS 的应用程序架构](application_architecture.md)。
### 入口点
`entryPoint`
类型：字符串数组
必需：否
传递给容器的入口点。此参数对应于 docker create-container 命令中的 `Entrypoint` 和 docker run 命令的 `--entrypoint` 选项。
```
"entryPoint": ["string", ...]
```
### 命令
`command`
类型：字符串数组
必需：否
传递给容器的命令。此参数对应于 docker create-container 命令中的 `Cmd` 和 docker run 命令的 `COMMAND` 参数。如果有多个参数，则每个参数都是数组中的分隔字符串。
```
"command": ["string", ...]
```
### 工作目录
`workingDirectory`
类型：字符串
必需：否
在其中运行命令的容器中的工作目录。此参数对应于 docker create-container 命令中的 `WorkingDir` 和 docker run 命令的 `--workdir` 选项。
### 高级容器定义参数
以下高级容器定义参数为 docker run 命令（用于在 Amazon ECS 容器实例上启动容器）提供了扩展功能。
**Topics**
+ [
#### 重启策略
](#container_definition_restart_policy-managed-instances)
+ [
#### 运行状况检查
](#container_definition_healthcheck-managed-instances)
+ [
#### 环境
](#container_definition_environment-managed-instances)
+ [
#### 安全性
](#container_definition_security-managed-instances)
+ [
#### 网络设置
](#container_definition_network-managed-instances)
+ [
#### 存储和日志记录
](#container_definition_storage-managed-instances)
+ [
#### 资源要求
](#container_definition_resourcerequirements-managed-instances)
+ [
#### 容器超时
](#container_definition_timeout-managed-instances)
+ [
#### 容器依赖项
](#container_definition_dependency-managed-instances)
+ [
#### 系统控制
](#container_definition_systemcontrols-managed-instances)
+ [
#### 交互式
](#container_definition_interactive-managed-instances)
+ [
#### 伪终端
](#container_definition_pseudoterminal-managed-instances)
#### 重启策略
`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 ECS 托管实例上运行的任务，此字段是可选的。为任务中的所有容器预留的 CPU 总量必须低于任务级的 `cpu` 值。
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 容器代理版本而异：
有关更多示例，请参阅 [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)。
`Elastic Inference accelerator`
Amazon ECS 托管实例上托管的容器不支持此参数。
类型：[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)。
`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` 选项。
您最多可以指定 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"
}
]
```
#### 安全性
`privileged`
类型：布尔值
必需：否
当此参数为 `true` 时，将对该容器提供对主机容器实例的提升特权（类似于 `root` 用户）。此参数对应于 docker create-container 命令中的 `Privileged` 和 docker run 命令的 `--privileged` 选项。
`user`
类型：字符串
必需：否
要在容器内使用的用户。此参数对应于 docker create-container 命令中的 `User` 和 docker run 命令的 `--user` 选项。
使用 `host` 网络模式运行任务时，不应使用根用户（UID 0）运行容器。我们建议使用非根用户来提高安全性。
您可以使用以下格式指定 `user`。如果指定 UID 或 GID，您必须将其指定为一个正整数。
+ `user`
+ `user:group`
+ `uid`
+ `uid:gid`
+ `user:gid`
+ `uid:group`
`readonlyRootFilesystem`
类型：布尔值
必需：否
当此参数为 `true` 时，容器将获得一个只读根文件系统。此参数对应于 docker create-container 命令中的 `ReadonlyRootfs` 和 docker run 命令的 `--read-only` 选项。
`dockerSecurityOptions`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：字符串数组
必需：否
用于为 SELinux 和 AppArmor 多级别安全系统提供自定义标签的字符串列表。此字段对使用 Fargate 的任务中的容器无效。
`ulimits`
类型：[Ulimit](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Ulimit.html) 对象数组
必需：否
要在容器中设置的 `ulimits` 的列表。如果在任务定义中指定了 ulimit 值，则它将覆盖 Docker 设置的默认值。此参数对应于 docker create-container 命令中的 `Ulimits` 和 docker run 命令的 `--ulimit` 选项。有效的命名值在 [Ulimit](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Ulimit.html) 数据类型中显示。
Fargate 上托管的 Amazon ECS 任务使用操作系统设置的默认资源限制值，Fargate 覆盖的 `nofile` 资源限制参数除外。`nofile` 资源限制对容器可以使用的打开文件数量设置限制。默认 `nofile` 软限制是 `1024`，默认硬限制是 `65535`。
此参数要求容器实例上的 Docker Remote API 版本为 1.18 或更高版本。要检查您的容器实例上的 Docker Remote API 版本，请登录到容器实例并运行以下命令：`sudo docker version --format '{{.Server.APIVersion}}'`
`dockerLabels`
类型：字符串到字符串映射
必需：否
要添加到容器的标签的键值映射。此参数对应于 docker create-container 命令中的 `Labels` 和 docker run 命令的 `--label` 选项。
此参数要求容器实例上的 Docker Remote API 版本为 1.18 或更高版本。
```
"dockerLabels": {"string": "string"
...}
```
#### 网络设置
`disableNetworking`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：布尔值
必需：否
当此参数设置为 true 时，容器内会关闭联网。
默认值为 `false`。
```
"disableNetworking": true|false
```
`links`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：字符串数组
必需：否
`link` 参数允许容器相互进行通信，而无需端口映射。只有在任务定义的网络模式被设置为 `bridge` 时才支持此参数。`name:internalName` 构造类似于 Docker 链接中的 `name:alias`。最多可使用 255 个字母（大写和小写字母）、数字、连字符和下划线。
在同一容器实例上并置的容器也许能够相互进行通信，而无需链接或主机端口映射。容器实例上的网络隔离由安全组和 VPC 设置控制。
```
"links": ["name:internalName", ...]
```
`hostname`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：字符串
必需：否
要对您的容器使用的主机名。此参数对应于 docker create-container 命令中的 `Hostname` 和 docker run 命令的 `--hostname` 选项。
```
"hostname": "string"
```
`dnsServers`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：字符串数组
必需：否
提供给容器的 DNS 服务器的列表。
```
"dnsServers": ["string", ...]
```
`extraHosts`
使用 `awsvpc` 网络模式的任务不支持此参数。
类型：对象数组
必需：否
要追加到容器上的 `/etc/hosts` 文件的主机名和 IP 地址映射的列表。
此参数对应于 docker create-container 命令中的 `ExtraHosts` 和 docker run 命令的 `--add-host` 选项。
```
"extraHosts": [
{
"hostname": "string",
"ipAddress": "string"
}
...
]
```
`hostname`
类型：字符串
必需：是，当使用 `extraHosts` 时
要用于 `/etc/hosts` 条目中的主机名。
`ipAddress`
类型：字符串
必需：是，当使用 `extraHosts` 时
要用于 `/etc/hosts` 条目中的 IP 地址。
#### 存储和日志记录
`readonlyRootFilesystem`
类型：布尔值
必需：否
当此参数为 true 时，将对此容器提供对其根文件系统的只读访问权。此参数对应于 docker create-container 命令中的 `ReadonlyRootfs` 和 docker run 命令的 `--read-only` 选项。
默认值为 `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 操作系统的 EC2 实例上运行的任务，请保留默认值 `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 或更高版本。
```
"logConfiguration": {
"logDriver": "awslogs",""splunk", "awsfirelens",
"options": {"string": "string"
...},
"secretOptions": [{
"name": "string",
"valueFrom": "string"
}]
}
```
`logDriver`
类型：字符串
有效值：`"awslogs","splunk","awsfirelens"`
必需：是，当使用 `logConfiguration` 时
要用于容器的日志驱动程序。默认情况下，前面列出的有效值是一些日志驱动程序，Amazon ECS 容器代理可以与它们进行通信。
支持的日志驱动程序为 `awslogs`、`splunk` 和 `awsfirelens`。
有关在任务定义中如何使用 `awslogs` 日志驱动程序以将容器日志发送到 CloudWatch Logs 的更多信息，请参阅[将 Amazon ECS 日志发送到 CloudWatch](using_awslogs.md)。
有关使用 `awsfirelens` 日志驱动程序的更多信息，请参阅[将 Amazon ECS 日志发送到 AWS 服务或 AWS Partner](using_firelens.md)。
如果具有未列出的自定义驱动程序，您可以复制 [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`
此选项定义日志消息从容器到 `awslogs` 日志驱动程序的交付模式。当来自容器的日志流中断时，您选择的交付模式会影响应用程序的可用性。
如果使用 `blocking` 模式并且流向 CloudWatch 的日志流中断，则来自容器代码写入 `stdout` 和 `stderr` 流的调用将阻塞。因此，应用程序的日志线程将阻塞。这可能会导致应用程序失去响应并导致容器运行状况检查失败。
如果您使用 `non-blocking` 模式，则容器的日志将存储在配置了 `max-buffer-size` 选项的内存中中间缓冲区。这样可以防止应用程序在无法将日志发送到 CloudWatch 时失去响应。如果您想确保服务可用性并且可以接受一些日志丢失，建议您使用此模式。有关更多信息，请参阅[在 `awslogs` 容器日志驱动程序中使用非阻塞模式防止日志丢失](https://aws.amazon.com/blogs/containers/preventing-log-loss-with-non-blocking-mode-in-the-awslogs-container-log-driver/)。
`max-buffer-size`
必需：否
默认值：`1m`
使用 `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`。
#### 资源要求
`resourceRequirements`
类型：[ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 对象数组
必需：否
要分配给容器的资源的类型和数量。目前唯一支持的资源为 GPU。
`type`
类型：字符串
是否必需：是
要分配给容器的资源类型。支持的值为 `GPU`。
`value`
类型：字符串
是否必需：是
指定的资源类型的值。
如果使用 `GPU` 类型，则该值是 Amazon ECS 容器代理将为容器保留的物理 `GPUs` 数量。为某个任务中的所有容器预留的 GPU 的数量不能超过该任务在其上启动的容器实例的可用 GPU 的数量。
GPU 不适用于在 Fargate 上运行的任务。
#### 容器超时
`startTimeout`
类型：整数
必需：否
示例值：`120`
在放弃解析容器的依赖项之前要等待的持续时间（以秒为单位）。
例如，在任务定义中指定两个容器，`containerA` 需要依赖 `containerB` 达到 `COMPLETE`、`SUCCESS` 或 `HEALTHY` 状态。如果为 `containerB` 指定了一个 `startTimeout` 值并且它未在该时间内达到所需状态，则 `containerA` 将不会启动。
如果容器不满足依赖性约束或在满足约束之前超时，Amazon ECS 不会将依赖性容器推进到其下一个状态。
最大值为 600 秒（10 分钟）。
`stopTimeout`
类型：整数
必需：否
示例值：`120`
容器由于未自行正常退出而被强制终止前要等待的持续时间（以秒为单位）。
如果未指定该参数，则使用默认值 30 秒。最大值为 86400 秒（24 小时）。
#### 容器依赖项
`dependsOn`
类型：[ContainerDependency](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ContainerDependency.html) 对象的数组
必需：否
针对容器启动和关闭定义的依赖项。一个容器可以包含多个依赖项。当针对容器启动定义依赖项时，对于容器关闭，将反转此项。有关示例，请参阅[容器依赖项](example_task_definitions.md#example_task_definition-containerdependency)。
如果容器不满足依赖性约束或在满足约束之前超时，Amazon ECS 不会将依赖性容器推进到其下一个状态。
此参数需要任务或服务使用平台版本 `1.3.0` 或更高版本（Linux）或 `1.0.0`（Windows）。
```
"dependsOn": [
{
"containerName": "string",
"condition": "string"
}
]
```
`containerName`
类型：字符串
是否必需：是
必须符合指定条件的容器名称。
`condition`
类型：字符串
是否必需：是
容器的依赖项条件。以下是可用的条件及其行为：
+ `START`：此条件将立即模拟链接和卷的行为。此条件将验证从属容器是否是在允许其他容器启动前启动的。
+ `COMPLETE`：此条件将验证从属容器是否在允许其他容器启动前运行完成（退出）。这对于运行脚本然后退出的非主要容器非常有用。无法在基本容器上设置此条件。
+ `SUCCESS`：此条件与 `COMPLETE` 相同，但它还要求容器退出并具有 `zero` 状态。无法在基本容器上设置此条件。
+ `HEALTHY`：此条件将验证从属容器是否在允许其他容器启动前传递其容器运行状况检查。这要求从属容器已在任务定义中配置运行状况检查。仅在任务启动时确认此条件。
#### 系统控制
`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` 参数。执行此操作具有以下缺点：
+ 如果为任何容器设置了 `systemControls`，则它将应用于该任务中的所有容器。如果您为单个任务中的多个容器设置了不同的 `systemControls`，最后启动的容器将确定哪个 `systemControls` 生效。
如果您要设置 IPC 资源命名空间以用于任务中的容器，则以下条件将适用于您的系统控制。有关更多信息，请参阅 [IPC 模式](task_definition_parameters.md#task_definition_ipcmode)。
+ 对于使用 `host` IPC 模式的任务，不支持 IPC 命名空间 `systemControls`。
+ 对于使用 `task` IPC 模式的任务，IPC 命名空间 `systemControls` 值适用于任务中的所有容器。
```
"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`。在 Fargate 上，只接受容器中存在的命名空间 `Sysctls`。
Fargate 支持所有此类值。
`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`。
### Linux 参数
`linuxParameters`
类型：[LinuxParameters](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LinuxParameters.html) 对象
必需：否
应用到容器的特定于 Linux 的修改，例如 Linux 内核功能。
`capabilities`
类型：[KernelCapabilities](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_KernelCapabilities.html) 对象
必需：否
容器的 Linux 功能，这些功能已在 Docker 提供的默认配置中添加或删除。
`devices`
类型：[设备](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Device.html)对象数组
必需：否
对容器公开的任何主机设备。此参数对应于 docker create-container 命令中的 `Devices` 和 docker run 命令的 `--device` 选项。
`initProcessEnabled`
类型：布尔值
必需：否
在容器内运行 `init` 进程，转发信号和获得进程。此参数对应于 docker run 命令的 `--init` 选项。
`maxSwap`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：整数
必需：否
容器可以使用的交换内存总量（以 MiB 为单位）。此参数会转换为 docker run 命令的 `--memory-swap` 选项，值为容器内存与 `maxSwap` 值之和。
`swappiness`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：整数
必需：否
使用此参数，您可以调整容器的内存 swappiness 行为。除非绝对必要，否则 `swappiness` 值为 `0` 将导致交换不会发生。`swappiness` 值为 `100` 将导致页面被非常积极地交换。有效值为 `0` 到 `100` 之间的整数。如果未指定`swappiness`参数，则使用默认值`60`。如果未指定`maxSwap`的值，则此参数将被忽略。此参数对应于 docker run 命令的 `--memory-swappiness` 选项。
`sharedMemorySize`
Amazon ECS 托管实例上运行的任务不支持此参数。
类型：整数
必需：否
`/dev/shm` 卷的大小（以 MiB 为单位）。此参数对应于 docker run 命令的 `--shm-size` 选项。
`tmpfs`
类型：[Tmpfs](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_Tmpfs.html) 对象数组
必需：否
tmpfs 挂载的容器路径、挂载选项和大小（以 MiB 为单位）。此参数对应于 docker run 命令的 `--tmpfs` 选项。
# Fargate 的 Amazon ECS 任务定义参数
任务定义包括以下各部分：任务系列、AWS Identity and Access Management（IAM）任务角色、网络模式、容器定义、卷和启动类型。任务定义中需要系列和容器定义。相反，任务角色、网络模式、卷和启动类型是可选的。
您可以在 JSON 文件中使用这些参数来配置任务定义。
下面是 Fargate 的每个任务定义参数的更详细描述。
## 系列
`family`
类型：字符串
是否必需：是
当您注册任务定义时，将为其提供一个系列，与任务定义的多个版本的名称类似，它是使用修订号指定的。注册到某个特定系列的第一个任务定义将获得修订 1，而随后注册的任何任务定义将获得后续修订号。
## 容量
注册任务定义时，您可以指定 Amazon ECS 应根据哪个容量来验证任务定义。如果任务定义未根据指定的兼容性进行验证，则返回客户端异常。
任务定义中允许以下参数。
`requiresCompatibilities`
类型：字符串数组
必需：否
有效值：`FARGATE`
根据其验证任务定义的容量。这将启动一项检查，以确保任务定义中使用的所有参数都符合 Fargate 的要求
## 任务 角色
`taskRoleArn`
类型：字符串
必需：否
注册任务定义时，可以为 IAM 角色提供任务角色，此角色可使任务中的容器有权代表您调用其关联策略中指定的 AWS API。有关更多信息，请参阅 [Amazon ECS 任务 IAM 角色](task-iam-roles.md)。
## 任务执行 角色
`executionRoleArn`
类型：字符串
必需：条件
任务执行角色的 Amazon 资源名称（ARN），该角色授予 Amazon ECS 容器代理代表您进行 AWS API 调用的权限。
任务执行 IAM 角色是必需的，具体取决于任务的要求。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。
## 网络模式
`networkMode`
类型：字符串
是否必需：是
在任务中用于容器的 Docker 联网模式。对于 Fargate 托管的 Amazon ECS 任务，要求使用 `awsvpc` 网络模式。
## 运行时平台
`operatingSystemFamily`
类型：字符串
必需：条件
原定设置：LINUX
对于在 Fargate 上托管的 Amazon ECS 任务，此参数是必需的。
当您注册任务定义时，您可以指定操作系统系列。
有效值为 `LINUX`、`WINDOWS_SERVER_2025_FULL`、`WINDOWS_SERVER_2025_CORE`、`WINDOWS_SERVER_2022_FULL`、`WINDOWS_SERVER_2022_CORE`、`WINDOWS_SERVER_2019_FULL` 和 `WINDOWS_SERVER_2019_CORE`。
服务中使用的所有任务定义对于此参数都必须具有相同的值。
当任务定义是服务的一部分时，此值必须与服务 `platformFamily` 值匹配。
`cpuArchitecture`
类型：字符串
必需：条件
原定设置：X86\$164
如果将参数保留为 `null`，则在 Fargate 上托管的任务启动时会自动分配默认值。
当您注册任务定义时，您可以指定 CPU 架构。有效值为 `X86_64` 和 `ARM64`。
服务中使用的所有任务定义对于此参数都必须具有相同的值。
当您有 Linux 任务时，可以将该值设置为 `ARM64`。有关更多信息，请参阅 [适用于 64 位 ARM 工作负载的 Amazon ECS 任务定义](ecs-arm64.md)。
## 任务大小
注册任务定义时，您可以指定用于任务的总 CPU 和内存量。这独立于容器定义级别的 `cpu` 和 `memory` 值。对于 Fargate 上托管的任务（Linux 和 Windows），这些字段是必填字段，支持的 `cpu` 和 `memory` 有具体值。
任务定义中允许以下参数：
`cpu`
类型：字符串
是否必需：是
任务级 CPU 和内存参数是必需的，用于确定运行任务的实例类型和大小。对于 Windows 任务，这些值不会在运行时强制执行，因为 Windows 没有可以轻松地对一组容器强制实施集体资源限制的原生机制。如果您想强制执行资源限制，建议使用适用于 Windows 容器的容器级资源。
要为任务提供的 CPU 单位的硬限制。您可以通过 CPU 单位数或虚拟 CPU（vCPU）数字符串的方式在 JSON 文件中将 CPU 值。例如，您可以使用 `1024`（CPU 单位数）或 `1 vCPU`（vCPU 数）来指定 CPU 值。注册任务定义时，vCPU 值将转换为指示 CPU 单元的整数。
此字段为必填字段，并且必须使用以下值之一，这决定了 `memory` 参数支持的值范围。下表显示了任务级 CPU 和内存的有效组合。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/task_definition_parameters.html)
`memory`
类型：字符串
是否必需：是
任务级 CPU 和内存参数是必需的，用于确定运行任务的实例类型和大小。对于 Windows 任务，这些值不会在运行时强制执行，因为 Windows 没有可以轻松地对一组容器强制实施集体资源限制的原生机制。如果您想强制执行资源限制，建议使用适用于 Windows 容器的容器级资源。
要向任务提供的内存硬限制。您可以通过以二进制兆字节（MiB）或千兆字节（GB）字符串方式在任务定义中指定内存值。例如，您可以使用 `3072`（以 MiB 为单位）或 `3 GB`（以 GB 为单位）指定内存值。注册任务定义时，GB 值将转换为指示 MiB 的整数。
此字段为必填字段，并且必须使用以下值之一，这决定了 `cpu` 参数支持的值范围：
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_cn/AmazonECS/latest/developerguide/task_definition_parameters.html)
## 容器定义
当您注册任务定义时，必须指定将传递给容器实例上的 Docker 进程守护程序的容器定义的列表。容器定义中允许以下参数。
**Topics**
+ [
### 标准容器定义参数
](#standard_container_definition_params)
+ [
### 高级容器定义参数
](#advanced_container_definition_params)
+ [
### 其他容器定义参数
](#other_container_definition_params)
### 标准容器定义参数
以下任务定义参数是必需的参数或在大多数容器定义中使用。
**Topics**
+ [
#### 名称
](#container_definition_name)
+ [
#### Image
](#container_definition_image)
+ [
#### 内存
](#container_definition_memory)
+ [
#### 端口映射
](#container_definition_portmappings)
+ [
#### 私有存储库凭证
](#container_definition_repositoryCredentials)
#### 名称
`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` 选项。
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` 指定公开的端口。
对于 Fargate 上的 Windows 容器，不能将端口 3150 用于 `containerPort`。这是因为它是预留的。
`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` 时，以下规则适用：
+ 您必须使用 `awsvpc` 网络模式。
+ 此参数同时适用于 Linux 和 Windows 操作系统。
+ 容器实例必须拥有不低于 1.67.0 版本的容器代理和不低于 1.67.0-1 版本的 `ecs-init` 程序包。
+ 每个容器最多可指定 100 个端口范围。
+ 您不用指定 `hostPortRange`。`hostPortRange` 的值设置如下：
+ 对于使用 `awsvpc` 网络模式的任务中的容器，`hostPort` 将设置为与 `containerPort` 相同的值。这是一种静态映射策略。
+ `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`
类型：整数
必需：否
要为您的容器预留的容器实例上的端口号。
`hostPort` 可以留空或值与 `containerPort` 相同。
Docker 版本 1.6.0 及更高版本的默认临时端口范围在 `/proc/sys/net/ipv4/ip_local_port_range` 下的实例上列出。如果此内核参数不可用，则将使用来自 `49153–65535` 的原定设置临时端口范围。不要尝试指定临时端口范围内的主机端口。这是因为这些都是为自动分配预留的。通常，低于 `32768` 的端口位于临时端口范围之外。
默认预留端口为适用于 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`。
如果您指定的是主机端口，请使用以下语法。
```
"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)
+ [
#### 运行状况检查
](#container_definition_healthcheck)
+ [
#### 环境
](#container_definition_environment)
+ [
#### 网络设置
](#container_definition_network)
+ [
#### 存储和日志记录
](#container_definition_storage)
+ [
#### 安全性
](#container_definition_security)
+ [
#### 资源限制
](#container_definition_limits)
+ [
#### Docker 标签
](#container_definition_labels)
#### 重启策略
`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`。
对于使用 Fargate 的任务，此字段为可选字段。为任务中的所有容器预留的 CPU 总量必须低于任务级的 `cpu` 值。
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 容器代理版本而异：
在 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`
在 Fargate 上托管的容器不支持此参数。
类型：[ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 对象
必需：否
Amazon ECS 容器代理为容器预留的物理 `GPUs` 的数量。为某个任务中的所有容器预留的 GPU 的数量不得超过该任务在其上启动的容器实例的可用 GPU 的数量。有关更多信息，请参阅 [适用于 GPU 工作负载的 Amazon ECS 任务定义](ecs-gpu.md)。
`Elastic Inference accelerator`
在 Fargate 上托管的容器不支持此参数。
类型：[ResourceRequirement](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ResourceRequirement.html) 对象
必需：否
对于 `InferenceAccelerator` 类型，`value` 与任务定义中指定的 `InferenceAccelerator` 的 `deviceName` 匹配。有关更多信息，请参阅 [Elastic Inference 加速器名称（已弃用）](#elastic-Inference-accelerator)。
`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`
这不适用于 Fargate 上的 Windows 容器。
类型：对象数组
必需：否
包含要传递到容器的环境变量的文件列表。此参数对应于 docker run 命令的 `--env-file` 选项。
您最多可以指定 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`
在 Fargate 上运行的任务不支持此参数。
类型：布尔值
必需：否
当此参数设置为 true 时，容器内会关闭联网。
默认值为 `false`。
```
"disableNetworking": true|false
```
`links`
使用 `awsvpc` 网络模式的任务不支持此参数。
类型：字符串数组
必需：否
`link` 参数允许容器相互进行通信，而无需端口映射。只有在任务定义的网络模式被设置为 `bridge` 时才支持此参数。`name:internalName` 构造类似于 Docker 链接中的 `name:alias`。最多可使用 255 个字母（大写和小写字母）、数字、连字符和下划线。
在同一容器实例上并置的容器也许能够相互进行通信，而无需链接或主机端口映射。容器实例上的网络隔离由安全组和 VPC 设置控制。
```
"links": ["name:internalName", ...]
```
`hostname`
类型：字符串
必需：否
要对您的容器使用的主机名。此参数对应于 docker create-container 命令中的 `Hostname` 和 docker run 命令的 `--hostname` 选项。
如果使用 `awsvpc` 网络模式，则不支持 `hostname` 参数。
```
"hostname": "string"
```
`dnsServers`
在 Fargate 上运行的任务不支持此参数。
类型：字符串数组
必需：否
提供给容器的 DNS 服务器的列表。
```
"dnsServers": ["string", ...]
```
`extraHosts`
使用 `awsvpc` 网络模式的任务不支持此参数。
类型：对象数组
必需：否
要追加到容器上的 `/etc/hosts` 文件的主机名和 IP 地址映射的列表。
此参数对应于 docker create-container 命令中的 `ExtraHosts` 和 docker run 命令的 `--add-host` 选项。
```
"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 操作系统的 EC2 实例上运行的任务，请保留默认值 `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 或更高版本。
+ 您必须在任务之外安装任何其他软件。例如，Fluentd 输出聚合函数或运行 Logstash 以将 Gelf 日志发送到的远程主机。
```
"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`、`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`
必需：否
默认值：`10m`
使用 `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)。
`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"
```
#### 资源限制
`ulimits`
类型：对象数组
必需：否
列表 `ulimit` 值为容器定义。此值将覆盖操作系统的默认资源配额设置。此参数对应于 docker create-container 命令中的 `Ulimits` 和 docker run 命令的 `--ulimit` 选项。
Fargate 上托管的 Amazon ECS 任务使用操作系统设置的默认资源限制值，`nofile` 资源限制参数除外。`nofile` 资源限制对容器可以使用的打开文件数量设置限制。在 Fargate 上，默认的 `nofile` 软限制为 ` 65535`，硬限制为 `65535`。您可以将两个限制的值最高设置为 `1048576`。有关更多信息，请参阅 [任务资源限制](fargate-tasks-services.md#fargate-resource-limits)。
此参数要求容器实例上的 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)
+ [
#### 容器依赖项
](#container_definition_dependson)
+ [
#### 容器超时
](#container_definition_timeout)
+ [
#### 系统控制
](#container_definition_systemcontrols)
+ [
#### 交互式
](#container_definition_interactive)
+ [
#### 伪终端
](#container_definition_pseudoterminal)
#### 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.html) 对象
必需：否
容器的 Linux 功能，这些功能已从 Docker 提供的默认配置中删除。有关这些 Linux 功能的更多信息，请参阅 [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html) Linux 手册页面。
`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` 选项。
当您使用 Fargate 启动类型时，不支持 `devices` 参数。
类型：[设备](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`
在 Fargate 上运行的任务不支持此参数。
容器可以使用的交换内存总量（以 MiB 为单位）。此参数会转换为 docker run 命令的 `--memory-swap` 选项，值为容器内存与 `maxSwap` 值之和。
如果指定`maxSwap`值为`0`，则该容器不使用交换。接受的值为`0`或任何正整数。如果省略 `maxSwap` 参数，该容器将为其运行所在的容器实例使用交换配置。必须为要使用的`swappiness`参数设置`maxSwap`值。
`sharedMemorySize`
`/dev/shm` 卷的大小值（以 MiB 为单位）。此参数对应于 docker run 命令的 `--shm-size` 选项。
如果您使用的任务使用 Fargate，则不支持 `sharedMemorySize` 参数。
类型：整数
`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.3.0` 或更高版本（Linux）或 `1.0.0`（Windows）。
```
"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 不会将依赖性容器推进到其下一个状态。
此参数需要任务或服务使用平台版本 `1.3.0` 或更高版本（Linux）。最大值为 120 秒。
`stopTimeout`
类型：整数
必需：否
示例值：`120`
容器由于未自行正常退出而被强制终止前要等待的持续时间（以秒为单位）。
此参数需要任务或服务使用平台版本 `1.3.0` 或更高版本（Linux）。如果未指定该参数，则使用默认值 30 秒。最大值为 120 秒。
#### 系统控制
`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` 参数。执行此操作具有以下缺点：
+ 如果为任何容器设置了 `systemControls`，则它将应用于该任务中的所有容器。如果您为单个任务中的多个容器设置了不同的 `systemControls`，最后启动的容器将确定哪个 `systemControls` 生效。
如果您要设置 IPC 资源命名空间以用于任务中的容器，则以下条件将适用于您的系统控制。有关更多信息，请参阅 [IPC 模式](#task_definition_ipcmode)。
+ 对于使用 `host` IPC 模式的任务，不支持 IPC 命名空间 `systemControls`。
+ 对于使用 `task` IPC 模式的任务，IPC 命名空间 `systemControls` 值适用于任务中的所有容器。
Windows 容器不支持此参数。
如果任务使用平台版本 `1.4.0` 或更高版本（Linux），则在 AWS 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`。在 Fargate 上，只接受容器中存在的命名空间 `Sysctls`。
Fargate 支持所有此类值。
`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](#ContainerDefinition-elastic-inference)。
`deviceType`
类型：字符串
是否必需：是
要使用的 Elastic Inference 加速器。
## 代理配置
`proxyConfiguration`
类型：[ProxyConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ProxyConfiguration.html) 对象
必需：否
App Mesh 代理的配置详细信息。
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 卷。Fargate 上托管的 Linux 任务支持 Amazon EBS 卷。有关更多信息，请参阅 [将 Amazon EBS 卷与 Amazon ECS 结合使用](ebs-volumes.md)。
+ Amazon EFS 卷——提供简单的可扩展和持久的文件存储以供您的 Amazon ECS 任务使用。使用 Amazon EFS 时，存储容量是弹性的。它会随着您添加和删除文件而自动增加和缩减。您的应用程序可以在需要时获得所需存储。Fargate 上托管的任务支持 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 容器不支持此选项。
+ 绑定挂载 – 挂载到容器中的主机上的文件或目录。运行任务时支持绑定挂载主机卷。要使用绑定挂载主机卷，请在任务定义中指定 `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**
+ [
### 临时存储
](#task_definition_ephemeralStorage)
+ [
### IPC 模式
](#task_definition_ipcmode)
+ [
### PID 模式
](#task_definition_pidmode)
+ [
### 故障注入
](#task_definition_faultInjection)
### 临时存储
`ephemeralStorage`
类型：[EphemeralStorage](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EphemeralStorage.html) 对象
必需：否
要为任务分配的临时存储量（以 GB 为单位）。此参数用于扩展可用的临时存储总量，超出原定设置数量，可用于在 AWS Fargate 上托管的任务。有关更多信息，请参阅 [将绑定挂载与 Amazon ECS 结合使用](bind-mounts.md)。
仅平台版本 `1.4.0` 或更高版本（Linux）或者 `1.0.0` 或更高版本（Windows）支持此参数。
### IPC 模式
`ipcMode`
在 Fargate 上运行的任务不支持此参数。
类型：字符串
必需：否
用于任务中的容器的 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` 将适用于任务中的所有容器。
**注意**
使用 Fargate 启动类型的 Windows 容器或任务不支持此参数。
### PID 模式
`pidMode`
类型：字符串
有效值：`host` \$1 `task`
必需：否
用于任务中的容器的过程命名空间。有效值为 `host` 或 `task`。在 Linux 容器上，唯一的有效值为 `task`。例如，监控 sidecar 可能需要 `pidMode` 访问有关在同一任务中运行的其他容器的信息。
如果指定了 `task`，则指定任务中的所有容器将共享相同的过程命名空间。
如果未指定任何值，则默认值为每个容器的私有命名空间。
**注意**
如果任务使用平台版本 `1.4.0` 或更高版本（Linux），则在 AWS Fargate 上托管的任务仅支持此参数。Fargate 上的 Windows 容器不支持此参数。
### 故障注入
`enableFaultInjection`
类型：布尔值
有效值：`true` \$1 `false`
必需：否
如果在任务的有效载荷中将此参数设置为 `true`，则 Amazon ECS 和 Fargate 将接受来自该任务的容器的故障注入请求。默认情况下，此参数设置为 `false`。
# 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`。
# Amazon ECS 任务定义模板
空任务定义模板如下所示。您可以使用此模板创建任务定义，这些任务定义随后可粘贴到控制台 JSON 输入区域或保存到文件并与 AWS CLI `--cli-input-json` 选项结合使用。有关更多信息，请参阅 [Fargate 的 Amazon ECS 任务定义参数](task_definition_parameters.md)。
**EC2 模板**
```
{
"family": "",
"taskRoleArn": "",
"executionRoleArn": "",
"networkMode": "none",
"containerDefinitions": [
{
"name": "",
"image": "",
"repositoryCredentials": {
"credentialsParameter": ""
},
"cpu": 0,
"memory": 0,
"memoryReservation": 0,
"links": [""],
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"protocol": "tcp"
}
],
"restartPolicy": {
"enabled": true,
"ignoredExitCodes": [0],
"restartAttemptPeriod": 180
},
"essential": true,
"entryPoint": [""],
"command": [""],
"environment": [
{
"name": "",
"value": ""
}
],
"environmentFiles": [
{
"value": "",
"type": "s3"
}
],
"mountPoints": [
{
"sourceVolume": "",
"containerPath": "",
"readOnly": true
}
],
"volumesFrom": [
{
"sourceContainer": "",
"readOnly": true
}
],
"linuxParameters": {
"capabilities": {
"add": [""],
"drop": [""]
},
"devices": [
{
"hostPath": "",
"containerPath": "",
"permissions": ["read"]
}
],
"initProcessEnabled": true,
"sharedMemorySize": 0,
"tmpfs": [
{
"containerPath": "",
"size": 0,
"mountOptions": [""]
}
],
"maxSwap": 0,
"swappiness": 0
},
"secrets": [
{
"name": "",
"valueFrom": ""
}
],
"dependsOn": [
{
"containerName": "",
"condition": "COMPLETE"
}
],
"startTimeout": 0,
"stopTimeout": 0,
"hostname": "",
"user": "",
"workingDirectory": "",
"disableNetworking": true,
"privileged": true,
"readonlyRootFilesystem": true,
"dnsServers": [""],
"dnsSearchDomains": [""],
"extraHosts": [
{
"hostname": "",
"ipAddress": ""
}
],
"dockerSecurityOptions": [""],
"interactive": true,
"pseudoTerminal": true,
"dockerLabels": {
"KeyName": ""
},
"ulimits": [
{
"name": "nofile",
"softLimit": 0,
"hardLimit": 0
}
],
"logConfiguration": {
"logDriver": "splunk",
"options": {
"KeyName": ""
},
"secretOptions": [
{
"name": "",
"valueFrom": ""
}
]
},
"healthCheck": {
"command": [""],
"interval": 0,
"timeout": 0,
"retries": 0,
"startPeriod": 0
},
"systemControls": [
{
"namespace": "",
"value": ""
}
],
"resourceRequirements": [
{
"value": "",
"type": "InferenceAccelerator"
}
],
"firelensConfiguration": {
"type": "fluentbit",
"options": {
"KeyName": ""
}
}
}
],
"volumes": [
{
"name": "",
"host": {
"sourcePath": ""
},
"configuredAtLaunch": true,
"dockerVolumeConfiguration": {
"scope": "shared",
"autoprovision": true,
"driver": "",
"driverOpts": {
"KeyName": ""
},
"labels": {
"KeyName": ""
}
},
"efsVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"transitEncryption": "DISABLED",
"transitEncryptionPort": 0,
"authorizationConfig": {
"accessPointId": "",
"iam": "ENABLED"
}
},
"fsxWindowsFileServerVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"authorizationConfig": {
"credentialsParameter": "",
"domain": ""
}
}
}
],
"placementConstraints": [
{
"type": "memberOf",
"expression": ""
}
],
"requiresCompatibilities": ["EC2"],
"cpu": "",
"memory": "",
"tags": [
{
"key": "",
"value": ""
}
],
"pidMode": "task",
"ipcMode": "task",
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "",
"properties": [
{
"name": "",
"value": ""
}
]
},
"inferenceAccelerators": [
{
"deviceName": "",
"deviceType": ""
}
],
"ephemeralStorage": {
"sizeInGiB": 0
},
"runtimePlatform": {
"cpuArchitecture": "X86_64",
"operatingSystemFamily": "WINDOWS_SERVER_20H2_CORE"
}
}
```
**Fargate 模板**
**重要**
对于 Fargate，您必须包括具有以下值之一的 `operatingSystemFamily` 参数：
`LINUX`
`WINDOWS_SERVER_2019_FULL`
`WINDOWS_SERVER_2019_CORE`
`WINDOWS_SERVER_2022_FULL`
`WINDOWS_SERVER_2022_CORE`
```
{
"family": "",
"runtimePlatform": {"operatingSystemFamily": ""},
"taskRoleArn": "",
"executionRoleArn": "",
"networkMode": "awsvpc",
"platformFamily": "",
"containerDefinitions": [
{
"name": "",
"image": "",
"repositoryCredentials": {"credentialsParameter": ""},
"cpu": 0,
"memory": 0,
"memoryReservation": 0,
"links": [""],
"portMappings": [
{
"containerPort": 0,
"hostPort": 0,
"protocol": "tcp"
}
],
"essential": true,
"entryPoint": [""],
"command": [""],
"environment": [
{
"name": "",
"value": ""
}
],
"environmentFiles": [
{
"value": "",
"type": "s3"
}
],
"mountPoints": [
{
"sourceVolume": "",
"containerPath": "",
"readOnly": true
}
],
"volumesFrom": [
{
"sourceContainer": "",
"readOnly": true
}
],
"linuxParameters": {
"capabilities": {
"add": [""],
"drop": [""]
},
"devices": [
{
"hostPath": "",
"containerPath": "",
"permissions": ["read"]
}
],
"initProcessEnabled": true,
"sharedMemorySize": 0,
"tmpfs": [
{
"containerPath": "",
"size": 0,
"mountOptions": [""]
}
],
"maxSwap": 0,
"swappiness": 0
},
"secrets": [
{
"name": "",
"valueFrom": ""
}
],
"dependsOn": [
{
"containerName": "",
"condition": "HEALTHY"
}
],
"startTimeout": 0,
"stopTimeout": 0,
"hostname": "",
"user": "",
"workingDirectory": "",
"disableNetworking": true,
"privileged": true,
"readonlyRootFilesystem": true,
"dnsServers": [""],
"dnsSearchDomains": [""],
"extraHosts": [
{
"hostname": "",
"ipAddress": ""
}
],
"dockerSecurityOptions": [""],
"interactive": true,
"pseudoTerminal": true,
"dockerLabels": {"KeyName": ""},
"ulimits": [
{
"name": "msgqueue",
"softLimit": 0,
"hardLimit": 0
}
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {"KeyName": ""},
"secretOptions": [
{
"name": "",
"valueFrom": ""
}
]
},
"healthCheck": {
"command": [""],
"interval": 0,
"timeout": 0,
"retries": 0,
"startPeriod": 0
},
"systemControls": [
{
"namespace": "",
"value": ""
}
],
"resourceRequirements": [
{
"value": "",
"type": "GPU"
}
],
"firelensConfiguration": {
"type": "fluentd",
"options": {"KeyName": ""}
}
}
],
"volumes": [
{
"name": "",
"host": {"sourcePath": ""},
"configuredAtLaunch":true,
"dockerVolumeConfiguration": {
"scope": "task",
"autoprovision": true,
"driver": "",
"driverOpts": {"KeyName": ""},
"labels": {"KeyName": ""}
},
"efsVolumeConfiguration": {
"fileSystemId": "",
"rootDirectory": "",
"transitEncryption": "ENABLED",
"transitEncryptionPort": 0,
"authorizationConfig": {
"accessPointId": "",
"iam": "ENABLED"
}
}
}
],
"requiresCompatibilities": ["FARGATE"],
"cpu": "",
"memory": "",
"tags": [
{
"key": "",
"value": ""
}
],
"ephemeralStorage": {"sizeInGiB": 0},
"pidMode": "task",
"ipcMode": "none",
"proxyConfiguration": {
"type": "APPMESH",
"containerName": "",
"properties": [
{
"name": "",
"value": ""
}
]
},
"inferenceAccelerators": [
{
"deviceName": "",
"deviceType": ""
}
]
}
```
您可以使用以下 AWS CLI 命令生成此任务定义模板。
```
aws ecs register-task-definition --generate-cli-skeleton
```
# Amazon ECS 任务定义示例
您可以复制示例和代码段，以开始创建自己的任务定义。
您可以复制这些示例，然后在使用控制台中的**通过 JSON 配置**选项时粘贴它们。确保自定义示例，例如使用您的账户 ID。您可以在任务定义 JSON 中包含这些代码段。有关更多信息，请参阅[使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)和[Fargate 的 Amazon ECS 任务定义参数](task_definition_parameters.md)。
有关更多任务定义示例，请参阅 GitHub 上的 [AWS 示例任务定义](https://github.com/aws-samples/aws-containers-task-definitions)。
**Topics**
+ [
## Webserver
](#example_task_definition-webserver)
+ [
## `splunk` 日志驱动程序
](#example_task_definition-splunk)
+ [
## `fluentd` 日志驱动程序
](#example_task_definition-fluentd)
+ [
## `gelf` 日志驱动程序
](#example_task_definition-gelf)
+ [
## 外部实例上的工作负载
](#ecs-anywhere-runtask)
+ [
## Amazon ECR 映像和任务定义 IAM 角色
](#example_task_definition-iam)
+ [
## 带命令的入口点
](#example_task_definition-ping)
+ [
## 容器依赖项
](#example_task_definition-containerdependency)
+ [
## 任务定义中的卷
](#volume_sample_task_defs)
+ [
## Windows 示例任务定义
](#windows_sample_task_defs)
## Webserver
下面是用于设置 Web 服务器的示例任务定义（使用 Fargate 上的 Linux 容器）：
```
{
"containerDefinitions": [
{
"command": [
"/bin/sh -c \"echo ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
' > /usr/local/apache2/htdocs/index.html && httpd-foreground\""
],
"entryPoint": [
"sh",
"-c"
],
"essential": true,
"image": "public.ecr.aws/docker/library/httpd:2.4",
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group" : "/ecs/fargate-task-definition",
"awslogs-region": "us-east-1",
"awslogs-stream-prefix": "ecs"
}
},
"name": "sample-fargate-app",
"portMappings": [
{
"containerPort": 80,
"hostPort": 80,
"protocol": "tcp"
}
]
}
],
"cpu": "256",
"executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
"family": "fargate-task-definition",
"memory": "512",
"networkMode": "awsvpc",
"runtimePlatform": {
"operatingSystemFamily": "LINUX"
},
"requiresCompatibilities": [
"FARGATE"
]
}
```
下面是用于设置 Web 服务器的示例任务定义（使用 Fargate 上的 Windows 容器）：
```
{
"containerDefinitions": [
{
"command": ["New-Item -Path C:\\inetpub\\wwwroot\\index.html -Type file -Value ' Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
'; C:\\ServiceMonitor.exe w3svc"],
"entryPoint": [
"powershell",
"-Command"
],
"essential": true,
"cpu": 2048,
"memory": 4096,
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"name": "sample_windows_app",
"portMappings": [
{
"hostPort": 80,
"containerPort": 80,
"protocol": "tcp"
}
]
}
],
"memory": "4096",
"cpu": "2048",
"networkMode": "awsvpc",
"family": "windows-simple-iis-2019-core",
"executionRoleArn": "arn:aws:iam::012345678910:role/ecsTaskExecutionRole",
"runtimePlatform": {"operatingSystemFamily": "WINDOWS_SERVER_2019_CORE"},
"requiresCompatibilities": ["FARGATE"]
}
```
## `splunk` 日志驱动程序
以下代码段演示如何在任务定义中使用 `splunk` 日志驱动程序，以将日志发送到远程服务。Splunk 令牌参数指定为密钥选项，因为它可能被视为敏感数据。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
```
"containerDefinitions": [{
"logConfiguration": {
"logDriver": "splunk",
"options": {
"splunk-url": "https://cloud.splunk.com:8080",
"tag": "tag_name",
},
"secretOptions": [{
"name": "splunk-token",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:splunk-token-KnrBkD"
}],
```
## `fluentd` 日志驱动程序
以下代码段演示如何在任务定义中使用 `fluentd` 日志驱动程序，以将日志发送到远程服务。`fluentd-address` 值被指定为密钥选项，因为它可能会视为敏感数据。有关更多信息，请参阅 [将敏感数据传递给 Amazon ECS 容器](specifying-sensitive-data.md)。
```
"containerDefinitions": [{
"logConfiguration": {
"logDriver": "fluentd",
"options": {
"tag": "fluentd demo"
},
"secretOptions": [{
"name": "fluentd-address",
"valueFrom": "arn:aws:secretsmanager:region:aws_account_id:secret:fluentd-address-KnrBkD"
}]
},
"entryPoint": [],
"portMappings": [{
"hostPort": 80,
"protocol": "tcp",
"containerPort": 80
},
{
"hostPort": 24224,
"protocol": "tcp",
"containerPort": 24224
}]
}],
```
## `gelf` 日志驱动程序
以下代码段演示如何在任务定义中使用 `gelf` 日志驱动程序，以将日志发送到远程主机（此主机运行将 Gelf 日志作为输入的 Logstash）。有关更多信息，请参阅 [logConfiguration](task_definition_parameters.md#ContainerDefinition-logConfiguration)。
```
"containerDefinitions": [{
"logConfiguration": {
"logDriver": "gelf",
"options": {
"gelf-address": "udp://logstash-service-address:5000",
"tag": "gelf task demo"
}
},
"entryPoint": [],
"portMappings": [{
"hostPort": 5000,
"protocol": "udp",
"containerPort": 5000
},
{
"hostPort": 5000,
"protocol": "tcp",
"containerPort": 5000
}
]
}],
```
## 外部实例上的工作负载
注册 Amazon ECS 任务定义时，请使用 `requiresCompatibilities` 参数并指定 `EXTERNAL` 在外部实例上运行 Amazon ECS工作负载时验证任务定义是否兼容。如果您使用控制台注册任务定义，则必须使用 JSON 编辑器。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。
**重要**
如果您的任务需要任务执行 IAM 角色，请确保在任务定义中指定了该角色。
部署工作负载时，请使用 `EXTERNAL` 启动类型时创建服务或运行独立任务。
以下是此示例的表定义。
------
#### [ Linux ]
```
{
"requiresCompatibilities": [
"EXTERNAL"
],
"containerDefinitions": [{
"name": "nginx",
"image": "public.ecr.aws/nginx/nginx:latest",
"memory": 256,
"cpu": 256,
"essential": true,
"portMappings": [{
"containerPort": 80,
"hostPort": 8080,
"protocol": "tcp"
}]
}],
"networkMode": "bridge",
"family": "nginx"
}
```
------
#### [ Windows ]
```
{
"requiresCompatibilities": [
"EXTERNAL"
],
"containerDefinitions": [{
"name": "windows-container",
"image": "mcr.microsoft.com/windows/servercore/iis:windowsservercore-ltsc2019",
"memory": 256,
"cpu": 512,
"essential": true,
"portMappings": [{
"containerPort": 80,
"hostPort": 8080,
"protocol": "tcp"
}]
}],
"networkMode": "bridge",
"family": "windows-container"
}
```
------
## Amazon ECR 映像和任务定义 IAM 角色
以下代码段使用 `123456789012.dkr.ecr.us-west-2.amazonaws.com` 注册表中带 `v1` 标签的名为 `aws-nodejs-sample` 的 Amazon ECR 映像。此任务中的容器继承来自 `arn:aws:iam::123456789012:role/AmazonECSTaskS3BucketRole` 角色的 IAM 权限。有关更多信息，请参阅 [Amazon ECS 任务 IAM 角色](task-iam-roles.md)。
```
{
"containerDefinitions": [
{
"name": "sample-app",
"image": "123456789012.dkr.ecr.us-west-2.amazonaws.com/aws-nodejs-sample:v1",
"memory": 200,
"cpu": 10,
"essential": true
}
],
"family": "example_task_3",
"taskRoleArn": "arn:aws:iam::123456789012:role/AmazonECSTaskS3BucketRole"
}
```
## 带命令的入口点
以下代码段演示使用入口点和命令参数的 Docker 容器的语法。此容器将对 `example.com` 执行四次 ping 操作，然后退出。
```
{
"containerDefinitions": [
{
"memory": 32,
"essential": true,
"entryPoint": ["ping"],
"name": "alpine_ping",
"readonlyRootFilesystem": true,
"image": "alpine:3.4",
"command": [
"-c",
"4",
"example.com"
],
"cpu": 16
}
],
"family": "example_task_2"
}
```
## 容器依赖项
此代码段展示了具有多个容器（其中指定了容器依赖项）的任务定义的语法。在以下任务定义中，`envoy` 容器必须达到正常运行状态（由必需的容器运行状况检查参数决定），然后 `app` 容器才能启动。有关更多信息，请参阅 [容器依赖项](task_definition_parameters.md#container_definition_dependson)。
```
{
"family": "appmesh-gateway",
"runtimePlatform": {
"operatingSystemFamily": "LINUX"
},
"proxyConfiguration":{
"type": "APPMESH",
"containerName": "envoy",
"properties": [
{
"name": "IgnoredUID",
"value": "1337"
},
{
"name": "ProxyIngressPort",
"value": "15000"
},
{
"name": "ProxyEgressPort",
"value": "15001"
},
{
"name": "AppPorts",
"value": "9080"
},
{
"name": "EgressIgnoredIPs",
"value": "169.254.170.2,169.254.169.254"
}
]
},
"containerDefinitions": [
{
"name": "app",
"image": "application_image",
"portMappings": [
{
"containerPort": 9080,
"hostPort": 9080,
"protocol": "tcp"
}
],
"essential": true,
"dependsOn": [
{
"containerName": "envoy",
"condition": "HEALTHY"
}
]
},
{
"name": "envoy",
"image": "840364872350.dkr.ecr.region-code.amazonaws.com/aws-appmesh-envoy:v1.15.1.0-prod",
"essential": true,
"environment": [
{
"name": "APPMESH_VIRTUAL_NODE_NAME",
"value": "mesh/meshName/virtualNode/virtualNodeName"
},
{
"name": "ENVOY_LOG_LEVEL",
"value": "info"
}
],
"healthCheck": {
"command": [
"CMD-SHELL",
"echo hello"
],
"interval": 5,
"timeout": 2,
"retries": 3
}
}
],
"executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole",
"networkMode": "awsvpc"
}
```
## 任务定义中的卷
使用以下内容来了解如何在任务中指定卷。
+ 有关如何配置 Amazon EBS 卷的信息，请参阅[指定 Amazon ECS 部署时的 Amazon EBS 卷配置](configure-ebs-volume.md)。
+ 有关如何配置 Amazon EFS 卷的信息，请参阅[使用控制台为 Amazon ECS 配置 Amazon EFS 文件系统](tutorial-efs-volumes.md)。
+ 有关如何配置适用于 Windows File Server 的 FSx 卷的信息，请参阅[了解为 Amazon ECS 配置适用于 Windows File Server 的 FSx 文件系统](tutorial-wfsx-volumes.md)。
+ 有关如何配置 Docker 卷的信息，请参阅 [适用于 Amazon ECS 的 Docker 卷示例](docker-volume-examples.md)。
+ 有关如何配置绑定挂载的信息，请参阅[Amazon ECS 绑定挂载示例](bind-mount-examples.md)。
## Windows 示例任务定义
以下示例任务定义可帮助您在 Amazon ECS 上开始使用 Windows 容器。
**Example 适用于 Windows 的 Amazon ECS 控制台示例应用程序**
以下任务定义是 Amazon ECS 的首次运行向导中生成的 Amazon ECS 控制台示例应用程序；它已转为使用 `microsoft/iis` Windows 容器映像。
```
{
"family": "windows-simple-iis",
"containerDefinitions": [
{
"name": "windows_sample_app",
"image": "mcr.microsoft.com/windows/servercore/iis",
"cpu": 1024,
"entryPoint":["powershell", "-Command"],
"command":["New-Item -Path C:\\inetpub\\wwwroot\\index.html -Type file -Value '
Amazon ECS Sample App Amazon ECS Sample App
Congratulations!
Your application is now running on a container in Amazon ECS.
'; C:\\ServiceMonitor.exe w3svc"],
"portMappings": [
{
"protocol": "tcp",
"containerPort": 80
}
],
"memory": 1024,
"essential": true
}
],
"networkMode": "awsvpc",
"memory": "1024",
"cpu": "1024"
}
```