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`
類型：物件
必要：否
當您為任務儲存使用 [FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 檔案系統時，指定此參數。
`fileSystemId`
類型：字串
必要：是
要使用的 FSx for Windows File Server 檔案系統 ID。
`rootDirectory`
類型：字串
必要：是
FSx for Windows File Server 檔案系統中的目錄，其將掛載做為主機內的根目錄。
`authorizationConfig`
`credentialsParameter`
類型：字串
必要：是
授權憑證選項：
+ [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 秘密的 Amazon Resource Name (ARN)。
+ [Systems Manager](https://docs.aws.amazon.com/systems-manager/latest/userguide/integration-ps-secretsmanager.html) 參數的 Amazon Resource Name (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 託管的完整網域名稱。
## 儲存 FSx for Windows File Server 磁碟區憑證的方法
有兩種不同的方法可存放憑證，以便與憑證參數搭配使用。
+ **AWS Secrets Manager 秘密**
您可以使用*其他類型的秘密*類別，在 AWS Secrets Manager 主控台中建立此登入資料。您可以為每個鍵/值對、使用者名稱/管理員以及密碼/*密碼*新增一列。
+ **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 設定 FSx for Windows File Server 檔案系統
了解如何啟動 Amazon ECS 最佳化 Windows 執行個體，該執行個體同時託管 FSx for Windows File Server 檔案系統，以及可存取該檔案系統的容器。若要這樣做，請先建立 Directory Service AWS Managed Microsoft Active Directory。接著，您可以建立 Amazon FSx for Windows File Server 檔案系統，以及具有 Amazon EC2 執行個體與任務定義的 Amazon ECS 叢集。您可以設定容器的任務定義，以使用 FSx for Windows File Server 檔案系統。最後，您將測試檔案系統。
每次啟動或刪除 Active Directory 或 FSx for Windows File Server 檔案系統時，需要 20 至 45 分鐘。請準備保留至少 90 分鐘以完成教學課程，或在幾個工作階段中完成教學課程。
## 教學課程的先決條件
+ 管理使用者。請參閱 [設定以使用 Amazon ECS。](get-set-up-for-amazon-ecs.md)。
+ (選用) 用於透過 RDP 存取連線至 EC2 Windows 執行個體的 `PEM` 金鑰對。如需有關如何建立金鑰對的資訊，請參閱 *Amazon EC2 User Guide* 中的 [Amazon EC2 key pairs and Amazon EC2 instances](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html)。
+ 具有至少一個公有、一個私有子網路和一個安全群組的 VPC。您可以使用預設 VPC。您不需要 NAT 閘道或裝置。 Directory Service 不支援與 Active Directory 搭配的網路位址轉譯 (NAT)。為了可以運作，Active Directory、FSx for Windows File Server 檔案系統、ECS 叢集和 EC2 執行個體必須位於 VPC 內。如需 VPCs和作用中目錄的詳細資訊，請參閱[建立 VPC](https://docs.aws.amazon.com/vpc/latest/userguide/create-vpc.html) 和[建立 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. 在導覽窗格中，選擇 **Roles** (角色)。
1. 選擇 **AWS 受管角色**。
1. 選擇 **Permissions, Attach policies.** (許可、連接政策。)。
1. 若要縮小可連接的政策，請使用 **Filter** (篩選)。
1. 選取適用的政策，然後選擇 **Attach Policy** (連接政策)。
1. 請參閱 [Amazon ECS 任務執行 IAM 角色](task_execution_IAM_role.md) 來檢查您是否擁有 ecsTaskExecutionRole，並查看如何在沒有的情況下建立一個。
建議您針對實際生產環境中的最低許可自訂角色政策。為了完成本教學課程，請確認下列 AWS 受管政策已連接至您的 ecsTaskExecutionRole。連接政策 (如果尚未連接)。使用上一節中提供的程序來連接 AWS 受管政策。
+ SecretsManagerReadWrite
+ AmazonFSxReadOnlyAccess
+ AmazonSSMReadOnlyAccess
+ AmazonECSTaskExecutionRolePolicy
## 步驟 2：建立 Windows Active Directory (AD)
1. 請遵循 *Directory Service 管理指南*中[建立 AWS Managed Microsoft AD](https://docs.aws.amazon.com/directoryservice/latest/admin-guide/ms_ad_getting_started.html#ms_ad_getting_started_create_directory) AWS 中所述的步驟。使用您在本教學課程中指定的 VPC。在*建立 AWS Managed Microsoft AD* 的步驟 3 中，儲存使用者名稱和管理員密碼以用於下列步驟。另外，請記下完整目錄 DNS 名稱，以供後續步驟中使用。您可以在建立 Active Directory 期間完成以下步驟。
1. 建立要在下列步驟中使用的 AWS Secrets Manager 秘密。如需詳細資訊，請參閱[《Secrets Manager 使用者指南》中的 Secrets Manager 入門](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html#get-started)。 AWS **
1. 開啟 [Secrets Manager 主控台](https://console.aws.amazon.com//secretsmanager/)。
1. 按一下 **Store a new secret** (存放新機密)。
1. 選取 **Other type of secrets** (其他機密類型)。
1. 對於 **Secret key/value** (機密鍵/值)，在第一個資料列中建立具有值 **admin** 的索引鍵 **username**。按一下 **\$1 Add row** (\$1 新增列)。
1. 在新資料列中，建立索引鍵 **password**。對於值，輸入您在*建立 AWS 受管 AD 目錄*的步驟 3 中輸入的密碼。
1. 按一下 **Next** (下一步) 按鈕。
1. 提供機密名稱和描述。按一下 **Next (下一步)**。
1. 按一下 **Next (下一步)**。按一下 **Store** (存放)。
1. 從 **Secrets** (機密) 頁面清單上，按一下您剛才建立的機密。
1. 儲存新機密的 ARN，以便在後續步驟中使用。
1. 您可以繼續進行下一個步驟，同時建立 Active Directory。
## 步驟 3：驗證並更新安全群組
在此步驟中，您會驗證並更新您正在使用的安全群組的規則。為此，您可以使用為 VPC 建立的預設安全群組。
**驗證並更新安全群組。**
您需要建立或編輯安全群組，以便連接埠可以接收和傳送資料，請參閱 *FSx for Windows File Server 使用者指南*中的 [Amazon VPC 安全群組](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/limit-access-security-groups.html#fsx-vpc-security-groups)。您可以藉由建立安全群組傳入規則完成此操作，規則顯示在以下傳入規則資料表的第一列。此規則允許來自網路界面 (及其關聯執行個體) 的傳入流量，而這些網路界面會指派給安全群組。您建立的所有雲端資源都位於同一 VPC 內，並連接至相同的安全群組。因此，此規則允許所需的流量往來於 FSx for Windows File Server 檔案系統、Active Directory 和 ECS 執行個體。其他傳入規則允許流量提供網站和 RDP 存取服務，以便連線至您的 ECS 執行個體。
下表顯示本教學課程所需的安全群組傳入規則。
| Type | 通訊協定 | 連接埠範圍 | 來源 |
| --- | --- | --- | --- |
| 所有流量 | 全部 | 全部 | *sg-securitygroup* |
| HTTPS | TCP | 443 | 0.0.0.0/0 |
| RDP | TCP | 3389 | 您的筆記型電腦 IP 地址 |
下表顯示本教學課程所需的安全群組傳出規則。
| Type | 通訊協定 | 連接埠範圍 | 目標 |
| --- | --- | --- | --- |
| 所有流量 | 全部 | 全部 | 0.0.0.0/0 |
1. 開啟 [EC2 主控台](https://console.aws.amazon.com//ec2/)並從左側選單選取 **Security Groups** (安全群組)。
1. 從現在顯示的安全群組清單中，選取您要用於本教學課程的安全群組左側的核取方塊。
隨即顯示您的安全群組詳細資訊。
1. 編輯傳入和傳出規則，方法是選取 **Inbound rules** (傳入規則) 或 **Outbound rules** (傳出規則) 索引標籤，然後選擇 **Edit inbound rules** (編輯傳入規則) 或 **Edit outbound rules** (編輯傳出規則) 按鈕。編輯規則以與上表中顯示的規則相符。稍後在本教學課程中建立 EC2 執行個體後，請使用 EC2 執行個體的公有 IP 位址編輯傳入規則 RDP 來源，詳情請參閱 *Amazon EC2 User Guide* 中的 [Connect to your Windows instance using RDP](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connecting_to_windows_instance.html)。
## 步驟 4：建立 FSx for Windows File Server 檔案系統
在您的安全群組經過驗證和更新，且您的 Active Directory 已建立並處於作用中狀態之後，請在與您的 Active Directory 相同的 VPC 中建立 FSx for Windows File Server 檔案系統。請依照下列步驟，建立 FSx for Windows File Server 檔案系統，以供您的 Windows 任務使用。
**建立第一個檔案系統。**
1. 開啟 [Amazon FSx 主控台](https://console.aws.amazon.com//fsx/)。
1. 在儀表板上，選擇 **Create file system** (建立檔案系統) 以啟動檔案系統建立精靈。
1. 在 **Select file system type** (選取檔案系統類型) 頁面中，選擇 **FSx for Windows File Server**，然後選擇 **Next** (下一步)。**Create file system** (建立檔案系統) 頁面隨即顯示。
1. 在 **File system details** (檔案系統詳細資訊) 區段中，輸入檔案系統的名稱。命名檔案系統可讓您更輕鬆地尋找和管理檔案系統。您最多可使用 256 個 Unicode 字元。允許的字元如下：英文字母、數字、空格和特殊字元加號 (\$1)、減號 (-)、等號 (=)、句點 (.)、下劃線 (\$1)、冒號 (:) 和斜線 (/)。
1. 對於 **Deployment type** (部署類型)，請選擇 **Single-AZ** (單一可用區)，部署在單一可用區域中部署的檔案系統。*單一可用區 2* 是最新一代的單一可用區域檔案系統，支援 SSD 和 HDD 儲存。
1. 對於 **Storage type** (儲存類型)，請選擇 **EBS**。
1. 對於 **Storage capacity** (儲存容量)，請輸入最小儲存容量。
1. 保留 **Throughput capacity** (輸送容量) 的預設設定。
1. 在**網路與安全**區段中，選擇您為 Directory Service 目錄選擇的相同 Amazon VPC。
1. 對於 **VPC Security Groups** (VPC 安全群組) 下，選擇您在*步驟 3：驗證並更新您的安全群組*中驗證的安全群組。
1. 對於 **Windows authentication** (Windows 身分驗證)，選擇 **AWS 受管 Microsoft Active Directory**，然後從清單中選擇您的 Directory Service 目錄。
1. 對於 **Encryption** (加密)，請保留 **aws/fsx (default)** (aws/fsx (預設)) 的預設 **Encryption key** (加密金鑰) 設定。
1. 請保留 **Maintenance preferences** (維護偏好設定) 的預設設定。
1. 按一下 **Next** (下一步) 按鈕。
1. 檢閱顯示在 **Create file system** (建立檔案系統) 頁面上的檔案系統組態。請注意建立檔案系統後，您可以修改哪些檔案系統設定，以供參考。選擇 **Create file system (建立檔案系統)**。
1. 請注意檔案系統 ID。您會在稍後的步驟中需要使用。
您可以在建立 FSx for Windows File Server 檔案系統時，繼續建立叢集和 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. 若要建立 Auto Scaling 群組，請從 **Auto Scaling group (ASG)** (Auto Scaling 群組 (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. 前往 [https://console.aws.amazon.com/ec2/](https://console.aws.amazon.com/ec2/) 開啟 Amazon EC2 主控台。
1. 從導覽列中選取要使用的「區域」。
1. 在 **EC2 儀表板**中，選擇 **Launch instance** (啟動執行個體)。
1. 在 **Name (名稱)** 輸入唯一的名稱。
1. 針對**應用程式和作業系統映像 (Amazon Machine Image)**，在**搜尋**欄位中，輸入您擷取到的 AMI 名稱。
1. 對於**執行個體類型**，選擇 t2.medium 或 t2.micro。
1. 在 **Key pair (login)** (金鑰對 (登入)) 欄位中，選擇一個金鑰對。如果您未指定金鑰對，則
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. 準備就緒後，請選取 acknowledgment (確認) 欄位，再選擇 **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 definitio** (建立新任務定義)、**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：執行任務並檢視結果
在執行任務之前，請確認 FSx for Windows File Server 檔案系統的狀態為 **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. 針對 **Launch Type** (啟動類型)，選擇 **EC2**。
1. 在部署組態下，針對**任務定義**選擇 **fsx-windows**，然後選擇**建立**。
1. 當您的任務狀態為**執行中**時，請選擇任務 ID。
1. 在**容器**下，當容器 1 狀態為**已停止**時，選取容器 2 以檢視容器的詳細資訊。
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：清除
**注意**
刪除 FSx for Windows File Server 檔案系統或 AD 需要 20 到 45 分鐘的時間。您必須等到 FSx for Windows File Server 檔案系統刪除操作完成後，才能開始 AD 刪除操作。
**刪除 FSx for Windows File Server 檔案系統。**
1. 開啟 [Amazon FSx 主控台](https://console.aws.amazon.com//fsx/)
1. 選取您剛建立之 FSx for Windows File Server 檔案系統左側的選項按鈕。
1. 選擇**動作**。
1. 選取 **Delete file system** (刪除檔案系統)。
**刪除 AD。**
1. 開啟 [Directory Service 主控台](https://console.aws.amazon.com//directoryservicev2/)。
1. 選擇您剛建立之 AD 左側的選項按鈕。
1. 選擇**動作**。
1. 選擇 **Delete directory** (刪除目錄)。
**刪除叢集。**
1. 開啟主控台，網址為 [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2)。
1. 在導覽窗格中選擇**叢集**，然後選擇 **windows-fsx-cluster**。
1. 選擇 **Delete cluster (刪除叢集)**。
1. 輸入短語，然後選擇**刪除**。
**終止 EC2 執行個體。**
1. 開啟 [Amazon EC2 主控台](https://console.aws.amazon.com//ec2/)。
1. 從左側選單中，選取 **Instances** (執行個體)。
1. 勾選您建立之 EC2 執行個體左側的核取方塊。
1. 按一下**執行個體狀態**和**終止執行個體**。
**刪除密碼。**
1. 開啟 [Secrets Manager 主控台](https://console.aws.amazon.com//secretsmanager/)。
1. 選取您為此逐步解說所建立的機密。
1. 按一下 **Actions** (動作)。
1. 選擇 **Delete secret** (刪除機密)。
# 搭配 Amazon ECS 使用 Docker 磁碟區
使用 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 中「Create a volume」區段的 `DriverOpts`。
`labels`
類型：字串
必要：否
自訂中繼資料，新增到您的 Docker 磁碟區。
`mountPoints`
類型：物件陣列
必要：否
容器中資料磁碟區的掛載點。此參數會映射至 Docker API 中 create-container 的 `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` 範圍，以便持續保留磁碟區，請將 autoprovision 設定為 `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 伺服器端點取代 `NFS_SERVER`。
```
"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 執行個體上託管的任務，可以將資料連接至主機 Amazon EC2 執行個體的生命週期，方法是在任務定義中指定 `host` 與選用的 `sourcePath` 值。如需詳細資訊，請參閱 Docker 文件中的 [Bind mounts](https://docs.docker.com/engine/storage/bind-mounts/)。
以下是綁定掛載的常用案例。
+ 若要提供空白的資料磁碟區以便在一個或多個容器中掛載。
+ 若要在一個或多個容器中掛載主機資料磁碟區。
+ 若要與相同任務中的其他容器共用來源容器的資料磁碟區。
+ 若要將 Dockerfile 中的路徑及其內容公開給一個或多個容器。
## 使用綁定掛載時的考量
使用綁定掛載時，請考量下列事項。
+ 在預設情況下， AWS Fargate 使用平台版本 `1.4.0`或更新版本 (Linux) `1.0.0`或更新版本 (Windows) 在 上託管的任務，會接收至少 20 GiB 的暫時性儲存，以進行綁定掛載。您可以透過在任務定義中指定 `ephemeralStorage` 參數來增加暫時性儲存的總量，最多可達 200 GiB。
+ 若要在執行任務時將 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 容器代理程式任務清除服務最終會予以刪除。根據預設，這會在容器退出的 3 小時後發生。不過，您可以使用 `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` 設定會授予主機上的容器延伸功能，相當於根存取。在此範例中，它用於檢查主機的掛載資料表以進行診斷。如需詳細資訊，請參閱[避免以特權方式執行容器 (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 執行個體上的指定位置，直到您手動將其刪除為止。如果 `sourcePath` 值不存在於主機 Amazon EC2 執行個體，Docker 常駐程式將建立該值。如果位置存在，將匯出來源路徑資料夾的內容。
`mountPoints`
類型：物件陣列
必要：否
容器中資料磁碟區的掛載點。此參數會映射至 Docker API 中 create-container 的 `Volumes`，以及 docker run 的 `--volume` 選項。
Windows 容器可在 `$env:ProgramData` 所在的相同磁碟上掛載整個目錄。Windows 容器無法在不同的磁碟機上掛載目錄，且掛載點不能跨磁碟機使用。您必須指定掛載點，將 Amazon EBS 磁碟區直接連接至 Amazon ECS 任務。
`sourceVolume`
類型：字串
必要：是 (當使用 `mountPoints` 時)
要掛載的磁碟區名稱。
`containerPath`
類型：字串
必要：是 (當使用 `mountPoints` 時)
掛載磁碟區之容器中的路徑。
`readOnly`
類型：布林值
必要：否
如果此數值為 `true`，容器擁有磁碟區的唯讀存取權。如果此值為 `false`，則容器可寫入磁碟區。預設值為 `false`。
對於在執行 Windows 作業系統之 EC2 執行個體上執行的任務，將該值保留為預設值 `false`。
`ephemeralStorage`
類型：物件
必要：否
為任務配置的暫時性儲存量。對於 AWS Fargate 使用平台版本 `1.4.0`或更新版本 (Linux) 或更新版本 (`1.0.0`Windows) 在 上託管的任務，此參數用於擴展可用的暫時性儲存總量，超過預設數量。
您可以使用 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"
}
]
}
]
```
**若要將 Docker 文件中的路徑及其內容公開給容器**
在此範例中，您有一個 Dockerfile，它會寫入您想要掛載在容器內的資料。此範例適用於 Fargate 或 Amazon EC2 執行個體上託管的任務。
1. 建立 Dockerfile。下列範例使用公有 Amazon Linux 2 容器映像，並在我們想要在容器內部掛載的 `/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`。可以在 Docker 檔案中變更這些許可。在下列範例中，`/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` 值為每個 Web 伺服器定義容器，這些值會建立 `webroot` 磁碟區與指向該容器文件根目錄之 `containerPath` 值的關聯性。
```
"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` 參數，容器使用其執行所在的容器執行個體的交換組態。必須設定 `maxSwap` 值，才能使用 `swappiness` 參數。
`swappiness`
您可藉此調整容器的記憶體交換行為。`swappiness` 的值若為 `0` 將導致交換不會發生 (除非有需要)。為 `100` 的 `swappiness` 值導致積極地交換頁面。接受的值為介於 `0` 與 `100` 之間的整數。如果未指定 `swappiness` 參數，則會使用預設值 `60`。如果未對 `maxSwap` 指定值，則會忽略此參數。此參數會對應 docker run 的 `--memory-swappiness` 選項。
在以下範例中，提供了 JSON 語法。
```
"containerDefinitions": [{
...
"linuxParameters": {
"maxSwap": integer,
"swappiness": integer
},
...
}]
```
## 考量事項
當您使用每個容器交換組態時，請考量下列事項。
+ 必須在託管任務的 Amazon EC2 執行個體上啟用和配置交換空間，容器才能使用這些空間。根據預設，Amazon ECS 最佳化 AMI 沒有啟用交換功能。您必須在執行個體上啟用交換，才能使用此功能。如需詳細資訊，請參閱 *Amazon EC2 User Guide* 中的 [Instance Store Swap Volumes](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` 容器定義參數，每個容器都有一個為 `60` 的預設 `swappiness` 值。此外，交換總用量限制為容器記憶體的兩倍。
+ 如果您在 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 容器時，對於基於 ARM 的應用程式，可以使用 X86\$164 CPU 架構或 ARM64 架構。如需詳細資訊，請參閱[64 位元 ARM 工作負載的 Amazon ECS 任務定義](ecs-arm64.md)。
## 任務 CPU 和記憶體
AWS Fargate 的 Amazon ECS 任務定義需要您指定任務層級的 CPU 和記憶體。只要在任務層級指定這些資源，就可以滿足大多數使用案例。下表顯示有效的任務層級 CPU 和記憶體組合。您可以在任務定義中將記憶體值指定為以 MiB 或 GB 為單位的字串。例如，可指定 `3072` MiB 作為記憶體值，也可指定 `3 GB` GB 作為記憶體值。您可以在 JSON 檔案中將 CPU 值指定為以 CPU 為單位或虛擬 CPU (vCPU) 為單位的字串。例如，可指定 `1024` 個 CPU 單位作為 CPU 值，也可指定 `1 vCPU` 個 vCPU 作為 CPU 值。
| CPU 數值 | 記憶體數值 | AWS Fargate 支援的作業系統 |
| --- | --- | --- |
| 256 (.25 vCPU) | 512 MiB、1 GB、2 GB | Linux |
| 512 (.5 vCPU) | 1 GB、2 GB、3 GB、4 GB | Linux |
| 1024 (1 vCPU) | 2 GB、3 GB、4 GB、5 GB、6 GB、7 GB、8 GB | 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 任務提取容器映像，需要透過路由至網際網路，或可將請求路由至網際網路的 NAT 閘道，將公有 IP 地址指派給任務的彈性網路界面。若要讓私有子網路中的 Fargate 任務提取容器映像，您需要子網路中的 NAT 閘道以將請求路由到網際網路。在 Amazon ECR 中託管容器映像時，可以將 Amazon ECR 設定為使用介面 VPC 端點。在這種情況下，任務的私有 IPv4 地址會用於映像提取。如需有關 Amazon ECR 介面端點的詳細資訊，請參閱 *Amazon Elastic Container Registry User Guide* 中的 [Amazon ECR interface VPC endpoints (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 管理主控台 方法是在 AWS CLI 和 SDKs 中描述任務。例如，您可以使用時間戳記來評估任務下載容器映像所花費的時間，並決定是否應最佳化容器映像大小，或使用 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) 延遲載入容器映像
在使用 Linux 平台版本 `1.4.0` 的 Fargate 上，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 Index Builder](https://awslabs.github.io/cfn-ecr-aws-soci-index-builder/)。CloudFormation AWS 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 '.'
```
# EC2 Windows 執行個體的 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 Developer 在 Amazon ECS 主控台中提供任務定義建議](using-amazon-q.md)
## JSON 驗證
Amazon ECS 主控台 JON 編輯器會對 JSON 檔案的以下方面進行驗證：
+ 該檔案為有效的 JSON 檔案。
+ 該檔案不包含任何無關的金鑰。
+ 該檔案包含 `familyName` 參數。
+ `containerDefinitions` 下至少會有一個項目。
## CloudFormation 堆疊
下列行為適用於 2023 年 1 月 12 日之前在新版 Amazon ECS 主控台中建立的任務定義。
建立任務定義後，Amazon ECS 主控台會自動建立名稱開頭為 `ECS-Console-V2-TaskDefinition-` 的 CloudFormation 堆疊。如果您使用 AWS CLI 或 AWS 開發套件取消註冊任務定義，則必須手動刪除任務定義堆疊。如需詳細資訊，請參閱 *CloudFormation User Guide* 中的 [Deleting a stack](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. 在**任務定義系列**中，請為任務定義指定唯一名稱。
1. 在**啟動類型**中，選擇應用程式環境。主控台預設為 **AWS Fargate** (即無伺服器模式)。Amazon ECS 會使用此值來執行驗證，確保任務定義參數對基礎結構類型有效。
1. 對於 **Operating system/Architecture** (作業系統/架構)，選擇適用於任務的作業系統和 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_tw/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 Resource Name (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 的記憶體，因此為容器指定的記憶體不可少於 6 MiB。
由於 Docker 19.03.13-ce 或更早版本常駐程式會為容器預留最低 4 MiB 的記憶體，因此為容器指定的記憶體不可少於 4 MiB。
+ 在**記憶體軟限制**中，輸入為容器保留的記憶體軟限制 (GB)。
當系統記憶體爭用時，Docker 會嘗試將容器記憶體保持在此軟性限制。如果您未指定任務層級的記憶體，您必須為**記憶體硬限制**和**記憶體軟限制**之一 (或兩者) 指定非零整數。如果同時指定兩者，**記憶體硬限制**必須大於**記憶體軟限制**。
Windows 容器不支援此功能。
1. (選用) 展開**環境變數**區段，以指定要注入到容器中的環境變數。您可以使用鍵值對單獨指定環境變數，也可以透過指定 Amazon S3 儲存貯體中託管的環境變數檔案來批量指定環境變數。如需有關如何設定環境變數檔案格式的資訊，請參閱 [將個別環境變數傳遞至 Amazon ECS 容器](taskdef-envfiles.md)。
在指定秘密儲存的環境變數時，請在**金鑰**欄位中輸入秘密名稱。然後，在 **ValueFrom** 欄位中輸入 Systems Manager Parameter Store 秘密或 Secrets Manager 秘密的完整 ARN
1. (選用) 選擇**使用日誌收集**選項來指定日誌組態。每個可用的日誌驅動程式都有要指定的日誌驅動程式選項。預設選項會將容器日誌傳送至 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** – 將任務設定為將容器日誌傳送至 Amazon Kinesis Data Streams。系統會提供預設日誌驅動程式選項，用於將日誌傳送至 Kinesis Data Streams 串流。若要指定不同的串流名稱，請變更驅動程式選項值。
+ **將日誌匯出至 Amazon OpenSearch Service** – 將任務設定為將容器日誌傳送至 OpenSearch Service 網域。務必提供日誌驅動程式選項。
+ **將日誌匯出至 Amazon S3** – 將任務設定為將容器日誌傳送至 Simple Storage Service (Amazon S3) 儲存貯體。系統會提供預設日誌驅動程式選項，但您必須指定有效的 Amazon S3 儲存貯體名稱。
1. (選用) 設定其他容器參數。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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 與 Amazon FSx for Windows File Server。在執行任務或建立/更新服務時，可於部署階段設定的磁碟區包括 Amazon EBS。
1. 在**磁碟區類型**欄位中，選擇與您所選組態類型相容的磁碟區類型，然後設定磁碟區類型。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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 and Prometheus (Prometheus libraries instrumentation)** (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 and 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. (選用) 展開 **Tags** (標籤) 區段，將標籤作為鍵值對新增至任務定義中。
+ [新增標籤] 選擇**新增標籤**，然後執行下列操作︰
+ 在**索引鍵**中，輸入索引鍵名稱。
+ 在**值**中，進入索引鍵值。
+ [移除標籤] 在標籤旁邊，選擇 **移除標籤**。
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 Developer 在 Amazon ECS 主控台中提供任務定義建議
在 Amazon ECS 主控台中使用 JSON 編輯器建立任務定義時，您可以透過 Amazon Q Developer 為任務定義提供 AI 產生的程式碼建議。
您可以使用內嵌聊天功能，讓 Amazon Q Developer 透過對話介面產生、解釋或重構任務定義 JSON。您可以在任務定義的任何位置插入產生的建議，並自行決定是否接受提議的變更。Amazon ECS 還增強了現有的內嵌建議功能，可利用 Amazon Q Developer 的智慧能力。
在使用 JSON 編輯器建立任務定義時，您可以讓 Amazon Q Developer 提供建議，協助更快速地建立任務定義。您可以啟用基於屬性的內嵌建議功能，也可以藉助 Amazon Q Developer 建議自動完成範例程式碼的完整區塊。
您可在支援 Amazon Q Developer 的區域中使用此功能。如需詳細資訊，請參閱 [AWS Services by Regions](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/)。
## 先決條件
先決條件如下：
+ 除主控台許可外，在主控台中建立任務定義的使用者，若要獲取建議，必須具備 `codewhisperer:GenerateRecommendations` 許可；若要使用內嵌聊天功能，則需具備 `q:SendMessage` 許可。如需詳細資訊，請參閱[透過 Amazon Q Developer 在主控台中提供建議所需的許可](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 Developer 聊天方塊隨即顯示。
此時輸入您的請求。
Amazon Q Developer 將產生然後更新 JSON 檔案。
若要接受變更，請選擇**全部接受**
1. 選擇**建立**。
# 使用主控台更新 Amazon ECS 任務定義
*任務定義修訂版*是目前任務定義的複本，並以新參數值取代現有參數值。您未修改的所有參數都位於新修訂版中。
若要更新任務定義，請建立任務定義修訂版。如果任務定義是用於服務，則您必須更新該服務才能使用更新的任務定義。
在建立修訂版時，您可以修改以下容器屬性和環境屬性。
+ 容器映像 URI
+ 連接埠映射
+ 環境變數
+ 基礎設施需求
+ 任務大小
+ 容器大小
+ 任務 角色
+ 任務執行 角色
+ 磁碟區和容器掛載點
+ 私有登錄檔
使用 JSON 編輯器時，您可以讓 Amazon Q 提供建議。如需詳細資訊，請參閱[使用 Amazon Q Developer 在 Amazon ECS 主控台中提供任務定義建議](using-amazon-q.md)
## JSON 驗證
Amazon ECS 主控台 JON 編輯器會對 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 開發套件取消註冊任務定義，則必須手動刪除任務定義堆疊。如需詳細資訊，請參閱 *CloudFormation User Guide* 中的 [Deleting a stack](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 Neuron 機器學習工作負載的 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 執行個體類型的 Amazon EC2 GPU 型容器執行個體可讓您存取 NVIDIA GPU。如需詳細資訊，請參閱 *Amazon EC2 Instance Types guide* 中的 [Linux Accelerated Computing Instances](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 固定至適當容器以獲得最佳效能。
支援下列 Amazon EC2 GPU 型執行個體類型。如需詳細資訊，請參閱 [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) | vCPUs | 記憶體 (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 參數存放區 API，擷取 Amazon ECS 最佳化 AMIs) ID。若使用此參數，您無需手動查詢 Amazon ECS 最佳化 AMI ID。如需 Systems Manager 參數存放區 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
```
# 搭配 Amazon ECS 受管執行個體使用 GPU
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 技術，為機器學習訓練與高效能運算提供最高效能。
在搭配 Amazon ECS 受管執行個體使用已啟用 GPU 的執行個體類型時，執行個體上會預先安裝 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`：具有 CUDA 工具組的基礎映像，用於 GPU 運算。
+ `tensorflow/tensorflow:latest-gpu`：支援 GPU 的 TensorFlow。
+ `pytorch/pytorch:latest-cuda`：支援 GPU 的 PyTorch。
如需有關 Amazon ECS 受管執行個體上涉及使用 GPU 的 Amazon ECS 任務定義範例，請參閱[在 Amazon ECS 任務定義中指定 GPU](ecs-gpu-specifying.md)。
## 考量事項
**注意**
對 g2 執行個體系列類型的支援已被棄用。
p2 執行個體系列類型僅在早於 Amazon ECS GPU 最佳化 AMI `20230912` 之前的版本上支援。如果您需要繼續使用 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 容器執行時間需要在容器中設定一些環境變數才能正常運作。如需這些環境變數的清單，請參閱 [Specialized Configurations with 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 不會對其進行設定。因此，請確保容器映像會設定它們，或在容器定義中設定它們。
+ Amazon ECS GPU 最佳化 AMI 版本 `20230929` 和更新版本支援 p5 執行個體類型系列。
+ Amazon ECS GPU 最佳化 AMI 版本 `20230913` 和更新版本支援 g4 執行個體類型系列。如需詳細資訊，請參閱[Amazon ECS 最佳化 Linux AMI](ecs-optimized_AMI.md)。Amazon ECS 主控台的 Create Cluster (建立叢集) 工作流程中不支援此系列。若要使用這些執行個體類型，您必須使用 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 設定之任務定義的任務。
## 使用啟動範本
您可以建立啟動範本。
+ 建立使用 AMI 的 Amazon ECS 最佳化 GPU AMI ID 的啟動範本。如需有關如何建立啟動範本的資訊，請參閱 *Amazon EC2 User Guide* 中的 [Create a new launch template using parameters you define](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/create-launch-template.html#create-launch-template-define-parameters)。
將從前一步驟取得的 AMI ID 用於 **Amazon Machine Image**。如需有關如何使用 Systems Manager 參數指定 AMI ID 的資訊，請參閱 *Amazon EC2 User Guide* 中的 [Specify a Systems Manager parameter in a launch template](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。
+ 將 *bottlerocket\$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
若要使用容器執行個體的 GPU 和 Docker 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 容器語法。此容器會使用 2 個 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 User Guide* 中的 [Run commands when you launch an EC2 instance with user data input](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 User Guide* 中的 [Run commands when you launch an EC2 instance with user data input](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. 設定所需的 Amazon ECS 代理程式，並在 `release.auto.pkrvars.hcl` 或 `overrides.auto.pkrvars.hcl` 中取得 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 執行個體組合。
+ 您需要使用具有加速 AVC (H.264) 和 HEVC (H.265) 解碼器的 Xilinx U30 媒體轉碼卡的 Linux 應用程式。
**重要**
使用其他解碼器的應用程式在 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 在 上提供 AMIs AWS Marketplace](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 documentation](https://developer.hashicorp.com/packer/docs) (《Packer 文件》)。
## 任務定義需求
若要在 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。
| 執行個體類型 | vCPUs | 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 Neuron 機器學習工作負載的 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)。SDK 包含編譯器、執行時間和分析工具，可最佳化機器學習晶片的 AWS 機器學習效能。 AWS Neuron 支援熱門的機器學習架構，例如 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 個 NeuronCores。對於 Trn1, Trn2 和 Inf2，每個晶片都有 2 NeuronCores。您可以對每個 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 或 AWS Inferentia 晶片。您可使用 `linuxParameters` 參數並指定裝置詳細資訊來執行此動作。如需詳細資訊，請參閱[任務定義需求](#ecs-inference-requirements)。
## 使用 Amazon ECS 最佳化 Amazon Linux 2023 (Neuron) AMI
Amazon ECS 提供以 Amazon Linux 2023 為基礎的 Amazon ECS 最佳化 AMI，適用於 AWS Trainium 和 AWS Inferentia 工作負載。它隨附 Docker 的 AWS Neuron 驅動程式和執行期。此 AMI 使得在 Amazon ECS 上執行機器學習推論工作負載更輕鬆。
建議在啟動 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 深度學習容器提供。此容器包含 AWS Neuron 執行期和 TensorFlow Serving 應用程式。啟動時，此容器會從 Amazon S3 中擷取您的模型、使用儲存的模型啟動 Neuron TensorFlow Serving，並等待預測請求。在以下範例中，容器映像擁有 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 深度學習 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)。下表詳細說明特定於每種執行個體類型的晶片。
| 執行個體類型 | vCPUs | 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 實驗室 (Intel 公司) 的 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 AWS Marketplace AMIs[https://aws.amazon.com/marketplace/pp/prodview-h24gzbgqu75zq](https://aws.amazon.com/marketplace/pp/prodview-h24gzbgqu75zq)。
+ 由 Amazon Web Services 提供的 Habana 深度學習 AMI。由於其不包含在內，您需要單獨安裝 Amazon ECS 容器代理程式。
+ 使用 Packer 建置由 [GitHub 儲存庫](https://github.com/aws-samples/aws-habana-baseami-pipeline)提供的自訂 AMI。如需詳細資訊，請參閱 [Packer documentation](https://developer.hashicorp.com/packer/docs) (《Packer 文件》)。
# 在 Amazon ECS 任務定義中指定深度學習
若要在 Amazon ECS 上執行 Habana Gaudi 加速深度學習容器，您的任務定義必須包含預先建置容器的容器定義，該容器使用 AWS 深度學習容器提供的 Habana SynapseAI 為 TensorFlow 或 PyTorch 提供深度學習模型。
以下容器映像擁有 TensorFlow 2.7.0 和 Ubuntu 20.04。在 GitHub 上維護為 Habana Gaudi 加速器最佳化的預先建置的 Deep Learning Containers 完整清單。如需詳細資訊，請參閱 [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 實驗室系統管理介面工具 (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"
},
...
}
```
以下為顯示"hello world" 的 ARM 架構的任務定義範例。
```
{
"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 容器，當任務定義參數包含特殊字元 (例如 `& \ < > ^ |`) 時，請執行下列任一選項：
+ 在整個參數字串前後加上雙引號，並新增逸出字元 (`\`)
範例
```
"awslogs-multiline-pattern": "\"^[|DEBUG|INFO|WARNING|ERROR\"",
```
+ 在每個特殊字元前後加上逸出字元 (`^`)
範例
```
"awslogs-multiline-pattern": "^^[^|DEBUG^|INFO^|WARNING^|ERROR",
```
## EC2
如果對任務使用 EC2，並且想要開啟 `awslogs` 日誌驅動程式，則 Amazon ECS 容器執行個體需要至少 1.9.0 版的容器代理程式。如需如何檢查代理程式版本及更新至最新版本的資訊，請參閱「[更新 Amazon ECS 容器代理程式](ecs-agent-update.md)」。
**注意**
您必須使用 Amazon ECS 最佳化 AMI，或至少具有 `1.9.0-1` 版 `ecs-init` 套件的自訂 AMI。使用自訂 AMI 時，您必須透過在 **docker run** 陳述式或環境變數檔案中使用下列環境變數，確保啟動代理程式時 Amazon EC2 執行個體上可使用 `awslogs` 記錄驅動程式。
```
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` 物件。一個是用於 WordPress 容器，該容器將日誌發送到名為 `awslogs-wordpress` 的日誌群組。另一個用於 MySQL 容器，該容器將日誌發送到名為 `awslogs-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 Reference* 中的 [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
您可以使用 FireLens for Amazon ECS 來使用任務定義參數，將日誌路由到 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 容器先於所有使用它的容器啟動，並於所有使用它的容器停止後才停止。
若要使用此功能，您必須為任務建立 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 容器之間指定容器順序時，會覆寫預設的啟動容器順序。
+ 託管於 Linux 上的 AWS Fargate 和 Linux 上的 Amazon EC2 的任務支援 Amazon ECS 的 FireLens。Windows 容器不支援 FireLens。
如需如何為 Windows 容器設定集中式記錄的相關資訊，請參閱 [Centralized logging for Windows containers on Amazon ECS using Fluent Bit](https://aws.amazon.com/blogs/containers/centralized-logging-for-windows-containers-on-amazon-ecs-using-fluent-bit/) (《使用 Fluent Bit 為 Amazon ECS 上的 Windows 容器設定集中式記錄》)。
+ 您可以使用 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` 網路模式的工作，具有 FireLens 配置的容器必須在任何依賴該模式的應用程式容器啟動之前啟動。若要控制容器的起始順序，請在工作定義中使用相依性條件。如需詳細資訊，請參閱[容器相依性](task_definition_parameters.md#container_definition_dependson)。
**注意**
如果您在使用 FireLens 配置的容器定義中使用相依性條件參數，請確定每個容器都有 `START` 或 `HEALTHY` 條件需求。
+ 根據預設，FireLens 將叢集和任務定義名稱以及叢集的 Amazon Resource Name (ARN) 作為中繼資料索引鍵新增到 stout/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` 部分中將 `false` 設定為 `enable-ecs-log-metadata`。
```
"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 Agent 版本 `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 日誌
對於高日誌輸送量案例，我們建議搭配 FireLens 和 使用`awsfirelens`日誌驅動程式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`， AWS 需要 第 3 Fluent Bit版或更新版本。如需可用版本的資訊，請參閱 [AWS 以取得 Fluent Bit 版本](https://github.com/aws/aws-for-fluent-bit/releases)。
## 了解區塊
Fluent Bit 會以稱為*區塊的*單位處理資料。當 INPUT 外掛程式接收資料時，引擎會建立區塊，在傳送至 OUTPUT 目的地之前儲存在記憶體或檔案系統上。
緩衝行為取決於 INPUT 區段中的`storage.type`設定。根據預設， Fluent Bit會使用記憶體緩衝。對於高輸送量或生產案例，檔案系統緩衝可提供更好的彈性。
如需詳細資訊，請參閱 Fluent Bit 文件中的[區塊](https://docs.fluentbit.io/manual/administration/buffering-and-storage#chunks)和《》中的[什麼是區塊？](https://github.com/aws-samples/amazon-ecs-firelens-examples/tree/mainline/examples/fluent-bit/oomkill-prevention#what-is-a-chunk) AWS 》以取得Fluent Bit範例儲存庫。
## 記憶體緩衝 （預設）
根據預設， Fluent Bit會使用記憶體緩衝 (`storage.type memory`)。您可以使用 `Mem_Buf_Limit` 參數限制每個 INPUT 外掛程式的記憶體用量。
下列範例顯示記憶體緩衝的輸入組態：
```
[INPUT]
Name tcp
Tag ApplicationLogs
Port 5170
storage.type memory
Mem_Buf_Limit 5MB
```
**重要**
`Mem_Buf_Limit` 超過外掛程式的 時， 會Fluent Bit暫停輸入，並遺失新記錄。這可能會導致背壓並拖慢您的應用程式。Fluent Bit 日誌中會顯示下列警告：
```
[input] tcp.1 paused (mem buf overlimit)
```
記憶體緩衝適用於日誌輸送量低至中等的簡單使用案例。對於需要資料遺失的高輸送量或生產案例，請改用檔案系統緩衝。
如需詳細資訊，請參閱 Fluent Bit 文件中的[緩衝和記憶體](https://docs.fluentbit.io/manual/administration/buffering-and-storage#buffering-and-memory)，以及 中的[僅限記憶體緩衝](https://github.com/aws-samples/amazon-ecs-firelens-examples/tree/mainline/examples/fluent-bit/oomkill-prevention#case-1-memory-buffering-only-default-or-storagetype-memory) AWS ，以取得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\$1 的記憶體，因為每個區塊最多可使用 4–5 MB。在記憶體受限的環境中，降低此值。例如，如果您有 50 MB 可用於緩衝，請將此設為 8–10 個區塊。
`storage.type filesystem`
啟用輸入外掛程式的檔案系統儲存。儘管名稱為 ， 還是Fluent Bit使用 `mmap`將區塊映射到記憶體和磁碟，在不犧牲效能的情況下提供持久性。
`storage.total_limit_size`
特定 OUTPUT 外掛程式緩衝資料的最大磁碟空間。達到此限制時，會捨棄該輸出的最舊記錄。如需調整大小的詳細資訊，請參閱 [了解 `storage.total_limit_size`](#firelens-storage-sizing)。
`threaded true`
在自己的執行緒中執行輸入，與 Fluent Bit的主要事件迴圈分開。這可防止慢速輸入封鎖整個管道。
如需詳細資訊，請參閱 Fluent Bit 文件中的[檔案系統緩衝](https://docs.fluentbit.io/manual/administration/buffering-and-storage#filesystem-buffering)，以及 AWS 中Fluent Bit的範例儲存庫中的[檔案系統和記憶體緩衝](https://github.com/aws-samples/amazon-ecs-firelens-examples/tree/mainline/examples/fluent-bit/oomkill-prevention#case-2-filesystem-and-memory-buffering-storagetype-filesystem)。
## 了解 `storage.total_limit_size`
每個 OUTPUT 外掛程式上的 `storage.total_limit_size` 參數會控制該輸出緩衝資料的最大磁碟空間。達到此限制時，會捨棄該輸出的最舊記錄，為新資料騰出空間。當磁碟空間完全用盡時， Fluent Bit 無法將記錄排入佇列，而且會遺失。
使用以下公式`storage.total_limit_size`，根據您的日誌速率和所需的復原時段計算適當的 ：
```
If log rate is in KB/s, convert to MB/s first:
log_rate (MB/s) = log_rate (KB/s) / 1000
storage.total_limit_size (GB) = log_rate (MB/s) × duration (hours) × 3600 (seconds/hour) / 1000 (MB to GB)
```
下表顯示常見日誌速率和復原時段的範例計算：
| 日誌速率 | 1 小時 | 6 小時 | 12 小時 | 24 小時 |
| --- | --- | --- | --- | --- |
| 0.25 MB/s | 0.9 GB | 5.4 GB | 10.8 GB | 21.6 GB |
| 0.5 MB/s | 1.8 GB | 10.8 GB | 21.6 GB | 43.2 GB |
| 1 MB/s | 3.6 GB | 21.6 GB | 43.2 GB | 86.4 GB |
| 5 MB/s | 18 GB | 108 GB | 216 GB | 432 GB |
| 10 MB/s | 36 GB | 216 GB | 432 GB | 864 GB |
若要觀察尖峰輸送量並選擇適當的緩衝區大小，請使用[量值輸送量 FireLens 範例](https://github.com/aws-samples/amazon-ecs-firelens-examples/tree/mainline/examples/measure-throughput)。
使用公式、範例計算和基準測試，選擇適合`storage.total_limit_size`的執行通道，以便在中斷期間進行最佳復原。
## Amazon ECS 任務儲存需求
在 OUTPUT 區段中加總所有`storage.total_limit_size`值，並新增額外負荷緩衝區。此總計會決定 Amazon ECS 任務定義中所需的儲存空間。例如，3 個輸出 × 10 GB，每個 = 30 GB \$1 緩衝 (5–10 GB) = 總共需要 35–40 GB。如果總計超過可用儲存體， Fluent Bit可能無法將記錄排入佇列，而且它們將會遺失。
下列儲存選項可供使用：
綁定掛載 （暫時性儲存）
+ 對於 AWS Fargate，預設值為 20 GB 的暫時性儲存 （上限為 200 GB)。在任務定義`ephemeralStorage`中使用 設定 。如需詳細資訊，請參閱*AWS CloudFormation 《 使用者指南*》中的 [EphemeralStorage](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-ephemeralstorage.html)。
+ 對於 EC2，使用 Amazon ECS 最佳化 AMI （在作業系統和 Docker 之間共用） 時，預設值為 30 GB。透過變更根磁碟區大小來增加 。
Amazon EBS 磁碟區
+ 提供高可用性、耐用、高效能的區塊儲存。
+ 需要磁碟區組態，並在任務定義`mountPoint`中指向 `storage.path`（預設：`/var/log/flb-storage/`)。
+ 如需詳細資訊，請參閱[在 Amazon ECS 任務定義中將磁碟區組態延至啟動時進行](specify-ebs-config.md)。
Amazon EFS 磁碟區
+ 提供簡單、可擴展的檔案儲存。
+ 需要磁碟區組態，並在任務定義`mountPoint`中指向 `storage.path`（預設：`/var/log/flb-storage/`)。
+ 如需詳細資訊，請參閱[在 Amazon ECS 任務定義中指定 Amazon EFS 檔案系統](specify-efs-config.md)。
如需資料磁碟區的詳細資訊，請參閱 [Amazon ECS 任務的儲存選項](using_data_volumes.md)。
## 最佳化輸出組態
網路問題、服務中斷和目的地限流可防止日誌交付。適當的輸出組態可確保彈性而不會遺失資料。
當輸出排清失敗時， Fluent Bit可以重試 操作。下列參數控制重試行為：
`retry_limit`
捨棄記錄之前，初次嘗試後的重試次數上限。預設為 1。例如， `retry_limit 3`表示總共 4 次嘗試 (1 次初始 \$1 3 次重試）。對於生產環境，我們建議使用 15 或更高版本，這涵蓋了幾分鐘的中斷和指數退避。
將`False`無限次重試設為 `no_limits`或 ：
+ 透過記憶體緩衝，無限次重試會導致輸入外掛程式在達到記憶體限制時暫停。
+ 使用檔案系統緩衝時，最舊的記錄會在達到 `storage.total_limit_size` 時捨棄。
耗盡所有重試嘗試 (1 次初始 \$1 `retry_limit` 重試） 後，會捨棄記錄。 AWS 具有 `auto_retry_requests true`（預設） 的外掛程式會在 Fluent Bit的重試機制之前提供額外的重試層。如需詳細資訊，請參閱 Fluent Bit 文件中的[設定重試](https://docs.fluentbit.io/manual/administration/scheduling-and-retries#configure-retries)。
例如，`retry_limit 3`使用預設設定 (`scheduler.base 5`、`scheduler.cap 2000`、`net.connect_timeout 10s`) 提供大約 70 秒的排程器等待時間 (10 秒 \$1 20 秒 \$1 40 秒）、40 秒的網路連線逾時 (4 次嘗試 × 10 秒），加上 AWS 外掛程式重試，根據網路條件和作業系統 TCP 逾時，總計大約 2–10 分鐘。
`scheduler.base`
重試之間的基本秒數 （預設值：5)。我們建議 10 秒。
`scheduler.cap`
重試之間的秒數上限 （預設值：2000)。我們建議 60 秒。
重試之間的等待時間使用指數退避與抖動：
```
wait_time = random(base, min(base × 2^retry_number, cap))
```
例如，使用 `scheduler.base 10`和 `scheduler.cap 60`：
+ 第一次重試：隨機等待 10-20 秒
+ 第二次重試：隨機等待 10-40 秒
+ 第三次重試和更新時間：隨機等待 10-60 秒 （上限）
如需詳細資訊，請參閱 Fluent Bit 文件中的[設定重試和聯網的等待時間](https://docs.fluentbit.io/manual/administration/scheduling-and-retries#configure-wait-time-for-retry)。 [https://docs.fluentbit.io/manual/administration/networking](https://docs.fluentbit.io/manual/administration/networking)
`workers`
平行輸出處理的執行緒數目。多個工作者允許並行排清，在處理許多區塊時提高輸送量。
`auto_retry_requests`
AWS 外掛程式特定的設定，可在 的Fluent Bit內建重試機制之前提供額外的重試層。預設值為 `true`。啟用時， AWS 輸出外掛程式會在內部重試失敗的請求，再將請求視為失敗的排清並受`retry_limit`組態約束。
`[SERVICE]` 區段中的 `Grace` 參數會設定關機期間Fluent Bit等待的時間，以排清緩衝的資料。`Grace` 期間必須與容器的 協調`stopTimeout`。在接收 之前，請確定 `stopTimeout`超過允許 Fluent Bit完成排清的`Grace`期間`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
```
## 了解資料遺失案例
長時間中斷或輸出目的地發生問題時，記錄可能會遺失。本指南中的組態建議是將資料遺失降至最低的最佳方法，但無法保證長時間故障期間的零遺失。了解這些案例可協助您設定 Fluent Bit以最大化彈性。
記錄可能會以兩種方式遺失：儲存填滿時捨棄最舊的記錄，或在系統無法接受更多資料時捨棄最新的記錄。
### 捨棄的最早記錄
當重試嘗試用盡或`storage.total_limit_size`填滿且需要為新資料騰出空間時，會捨棄最舊的緩衝記錄。
超過重試限制
在 AWS 外掛程式重試 （如果 `auto_retry_requests true`) 加上 1 次初始Fluent Bit嘗試加上`retry_limit`重試後發生。若要緩解，`retry_limit no_limits`為每個 OUTPUT 外掛程式設定無限次重試：
```
[OUTPUT]
Name cloudwatch_logs
Match ApplicationLogs
retry_limit no_limits
auto_retry_requests true
```
無限次重試可防止因重試耗盡而捨棄記錄，但可能導致 `storage.total_limit_size` 填滿。
已達到儲存限制 （檔案系統緩衝）
當輸出目的地無法使用的時間超過您設定的 `storage.total_limit_size` 緩衝時間時，便會發生。例如，以 1 MB/s 日誌速率的 10 GB 緩衝區可提供大約 2.7 小時的緩衝時間。若要緩解、增加`storage.total_limit_size`每個 OUTPUT 外掛程式並佈建足夠的 Amazon ECS 任務儲存：
```
[OUTPUT]
Name cloudwatch_logs
Match ApplicationLogs
storage.total_limit_size 10G
```
### 拒絕的最新記錄
當磁碟空間耗盡或輸入因 而暫停時，會捨棄最新的記錄`Mem_Buf_Limit`。
磁碟空間用盡 （檔案系統緩衝）
當磁碟空間完全用盡時，便會發生。 Fluent Bit 無法將新記錄排入佇列並遺失。若要緩解，請加總所有`storage.total_limit_size`值並佈建足夠的 Amazon ECS 任務儲存體。如需詳細資訊，請參閱[Amazon ECS 任務儲存需求](#firelens-storage-task-requirements)。
已達到記憶體限制 （記憶體緩衝）
當輸出目的地無法使用且記憶體緩衝區填滿時，便會發生。暫停的輸入外掛程式會停止接受新記錄。若要緩解，請使用 `storage.type filesystem`以獲得更好的彈性，或增加 `Mem_Buf_Limit`。
### 將資料遺失降至最低的最佳實務
請考慮下列最佳實務，將資料遺失降至最低：
+ **使用檔案系統緩衝 –** 設定 `storage.type filesystem`以在中斷期間獲得更好的彈性。
+ **適當大小儲存** – 根據`storage.total_limit_size`日誌速率和所需的復原時段計算。
+ **佈建足夠的磁碟** – 確保 Amazon ECS 任務有足夠的暫時性儲存、Amazon EBS 或 Amazon EFS。
+ **設定重試行為** – 平衡 `retry_limit`（耗盡重試後捨棄記錄） 和 `no_limits`（無限期重試，但可能會填滿儲存體）。
## 使用多目的地記錄來確保可靠性
將日誌傳送至多個目的地可消除單一失敗點。例如，如果 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 *`模式，因此所有記錄都會獨立傳送至兩個目的地。在某個目的地中斷期間，日誌會繼續流向另一個目的地，而失敗的排清會在檔案系統緩衝區中累積以供稍後重試。
## 搭配尾端輸入外掛程式使用檔案型記錄
對於日誌遺失是重大考量的高輸送量案例，您可以使用替代方法：讓應用程式將日誌寫入磁碟上的檔案，並設定 Fluent Bit 使用`tail`輸入外掛程式讀取它們。此方法完全略過 Docker 記錄驅動程式層。
使用尾端外掛程式以檔案為基礎的記錄可提供下列優點：
+ **位移追蹤** – 尾端外掛程式可以將檔案位移存放在資料庫檔案中 （使用 `DB`選項），在Fluent Bit重新啟動時提供耐用性。這有助於防止在容器重新啟動期間日誌遺失。
+ **輸入層級緩衝** – 您可以使用 直接在輸入外掛程式上設定記憶體緩衝區限制`Mem_Buf_Limit`，以更精細地控制記憶體用量。
+ **避免 Docker 額外負荷** – 日誌會直接從檔案移至 ，Fluent Bit而不會傳遞 Docker 的日誌緩衝區。
若要使用此方法，您的應用程式必須將日誌寫入檔案，而不是 `stdout`。應用程式容器和Fluent Bit容器都會掛載存放日誌檔案的共用磁碟區。
下列範例顯示具有最佳實務的尾端輸入組態：
```
[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
```
使用尾端輸入外掛程式時，請考慮下列事項：
+ 為您的應用程式日誌實作日誌輪換，以防止磁碟耗盡。監控基礎磁碟區指標以衡量效能。
+ 根據您的日誌格式考慮設定`Ignore_Older`，例如 `Read_from_Head`、 和多行剖析器。
如需詳細資訊，請參閱 Fluent Bit 文件中的 [Tail](https://docs.fluentbit.io/manual/pipeline/inputs/tail)。如需最佳實務，請參閱《》中的 [Tail config with best practices](https://github.com/aws/aws-for-fluent-bit/blob/mainline/troubleshooting/debugging.md#tail-config-with-best-practices) AWS for Fluent Bit troubleshooting guide。
## 直接記錄到 FireLens
在任務定義中指定 `awsfirelens` 日誌驅動程式時，Amazon ECS 代理程式會將下列環境變數插入容器中：
`FLUENT_HOST`
指派給 FireLens 容器的 IP 位址。
如果搭配 `bridge` 網路模式使用 EC2，應用程式容器中的 `FLUENT_HOST` 環境變數可能會在重新啟動 FireLens 日誌路由器容器 (容器定義中具有 `firelensConfiguration` 物件的容器) 之後變得不準確。這是因為 `FLUENT_HOST` 是動態 IP 位址，重新啟動之後可能發生變更。從應用程式容器直接向 `FLUENT_HOST` IP 位址寫入日誌的操作，可能會在該位址變更後開始失敗。如需有關重新啟動個別容器的詳細資訊，請參閱[使用容器重新啟動政策在 Amazon ECS 任務中重新啟動個別容器](container-restart-policy.md)。
`FLUENT_PORT`
流利轉送通訊協定正在接聽的連接埠。
您可以使用這些環境變數，使用 Fluent Forward 通訊協定直接從應用程式程式碼登入Fluent Bit日誌路由器，而不是寫入 `stdout`。此方法略過 Docker 記錄驅動程式層，可提供下列優點：
+ **低延遲** – 日誌會直接傳送至 ，Fluent Bit而不會傳遞 Docker 的記錄基礎設施。
+ **結構化記錄** – 原生傳送結構化日誌資料，無需 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 可能會耗盡緩衝區記憶體，並捨棄緩衝區訊息，以便新增新訊息。
使用此選項時，請考慮下列事項：
+ EC2 與具有平台版本 `1.4.0` 或更新版本的 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
}
]
}
```
# AWS 適用於 Amazon ECS Fluent Bit的影像儲存庫
AWS 為 CloudWatch Logs 和 Firehose 提供具有外掛程式Fluent Bit的影像。我們建議您將 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)。
**AWS for Fluent Bit** 映像可在 Amazon ECR Public Gallery 和 Amazon ECR 儲存庫的 Amazon ECR 上取得，以獲得高可用性。
## Amazon ECR Public Gallery
AWS 適用於Fluent Bit映像的 可在 Amazon ECR Public Gallery 上取得。這是下載 AWS 適用於Fluent Bit映像的 的建議位置，因為它是公有儲存庫，可從所有 使用 AWS 區域。如需詳細資訊，請參閱 Amazon ECR Public Gallery 上的 [aws-for-fluent-bit](https://gallery.ecr.aws/aws-observability/aws-for-fluent-bit)。
### Linux
Amazon ECR Public Gallery 中的 AWS for Fluent Bit映像支援具有 `ARM64`或 `x86-64`架構的 Amazon Linux 作業系統。
您可以透過指定具有所需Fluent Bit映像標籤 AWS 的儲存庫 URL，從 Amazon ECR Public Gallery 提取映像的 。在 Amazon ECR Public Gallery 的**映像標籤**索引標籤中可找到可用的映像標籤。
以下顯示 Docker CLI 要使用的語法。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
例如，您可以使用此 Docker CLI 命令 AWS 為Fluent Bit版本提取「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 適用於 Fluent Bit 3.0.0
除了 AWS Fluent Bit版本的現有 之外`2.x`， AWS Fluent Bit還支援新的主要版本 `3.x`。新的主要版本包括將映像從 Amazon Linux 2 升級至 Amazon Linux 2023，並將Fluent Bit版本`1.9.10`升級至 `4.1.1`。如需詳細資訊，請參閱 上[AWS 儲存Fluent Bit庫](https://github.com/aws/aws-for-fluent-bit/blob/mainline/VERSIONS.md)的 GitHub。
下列範例示範 Fluent Bit `3.x` 映像 AWS 的更新標籤：
您可以針對 AWS Fluent Bit映像的 使用多架構標籤。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:3
```
### Windows
Amazon ECR Public Gallery 中的 AWS for Fluent Bit映像支援具有下列作業系統的`AMD64`架構：
+ Windows Server 2022 Full
+ Windows Server 2022 Core
+ Windows Server 2019 Full
+ Windows Server 2019 Core
AWS Fargate 上的 Windows 容器不支援 FireLens。
您可以透過指定具有所需Fluent Bit映像標籤 AWS 的儲存庫 URL，從 Amazon ECR Public Gallery 提取映像的 。在 Amazon ECR Public Gallery 的**映像標籤**索引標籤中可找到可用的映像標籤。
以下顯示 Docker CLI 要使用的語法。
```
docker pull public.ecr.aws/aws-observability/aws-for-fluent-bit:tag
```
例如，您可以使用此 Docker AWS CLI 命令提取影像的最新穩定 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 上使用，以獲得高可用性。下列命令可用來擷取映像 URIs並在指定的 中建立映像可用性 AWS 區域。
### Linux
您可以使用下列命令擷取最新穩定的 AWS Fluent Bit 映像 URI。
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/stable \
--region us-east-1
```
您可以使用下列命令來查詢 Systems Manager 參數存放區參數，列出所有版本的 AWS for Fluent Bit 映像。
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit \
--region us-east-1
```
您可以在範本中 CloudFormation 參考 Systems Manager 參數存放區名稱，以參考最新穩定的 AWS 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 Fluent Bit 映像 URI。
```
aws ssm get-parameters \
--names /aws/service/aws-for-fluent-bit/windowsservercore-stable \
--region us-east-1
```
您可以使用下列命令來查詢 Systems Manager 參數存放區參數，列出所有版本的 AWS for Fluent Bit 映像。
```
aws ssm get-parameters-by-path \
--path /aws/service/aws-for-fluent-bit/windowsservercore \
--region us-east-1
```
您可以在範本中 CloudFormation 參考 Systems Manager 參數存放區名稱，以參考最新穩定的 AWS 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 Resource Name (ARN)，其中包含路由日誌所需的任務許可。
使用 建立新的任務定義時 AWS 管理主控台，有一個 FireLens 整合區段，可讓您輕鬆地新增日誌路由器容器。如需詳細資訊，請參閱[使用主控台建立 Amazon ECS 任務定義](create-task-definition.md)。
Amazon ECS 轉換日誌組態並產生 Fluentd 或 Fluent Bit 輸出組態。輸出配置掛載在流利位和 `/fluentd/etc/fluent.conf` 流利位 `/fluent-bit/etc/fluent-bit.conf` 的日誌路由容器中。
**重要**
FireLens 會監聽連接埠 `24224`。因此為了確保 FireLens 日誌路由器無法在任務之外連線，您不能在任務使用的安全群組中允許連接埠 `24224` 上的傳入流量。對於使用 `awsvpc` 網路模式的任務，這是與任務相關聯的安全群組。對於使用 `host` 網路模式的任務，這是與託管任務的 Amazon EC2 執行個體相關聯的安全群組。對於使用 `bridge` 網路模式的任務，請不要建立使用連接埠 `24224` 的任何連接埠映射。
根據預設，Amazon ECS 會在日誌項目中新增其他欄位，以協助識別日誌的來源。
+ `ecs_cluster` - 任務所屬叢集的名稱。
+ `ecs_task_arn` – 容器所屬任務的完整 Amazon Resource Name (ARN)。
+ `ecs_task_definition` - 任務正在使用的任務定義名稱和修訂版本。
+ `ec2_instance_id`：託管容器的 Amazon EC2 執行個體 ID。此欄位僅用於使用 EC2 啟動類型的任務。
如果不想要中繼資料，您可以將 `enable-ecs-log-metadata` 設定為 `false`。
以下任務定義範例定義了一個日誌路由器容器，其使用 Fluent Bit，將其日誌路由至 CloudWatch Logs。其還定義了一個應用程式容器，該容器使用日誌組態將日誌路由至 Amazon Data Firehose，並將用於緩衝事件的記憶體設定為 2 MiB。
**注意**
如需更多任務定義範例，請參閱 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
```
**注意**
FireLens 管理 `match` 組態。您無需在任務定義中指定 `match` 組態。
## 使用自訂組態檔案
您可以指定自訂組態檔案。組態檔格式是您所使用日誌路由器的原生格式。如需詳細資訊，請參閱 [Fluentd Config File Syntax](https://docs.fluentd.org/configuration/config-file) 與 [YAML Configuration](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`組態檔案類型。不過，您可以使用 for Fluent Bit init 容器，使用 AWS Fargate 上 Amazon S3 中託管 AWS 的組態檔案。如需詳細資訊，請參閱 [ECS 上的 Fluent Bit 的 Init 程序、GitHub 上的多組態支援](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)。 GitHub
`config-file-value`
自訂組態檔案的來源。如果使用 `s3` 組態檔案類型，則組態檔案值是 Amazon S3 儲存貯體和檔案的完整 ARN。如果使用 `file` 組態檔案類型，組態檔案值就是容器映像中或掛載在容器中的磁碟區上的組態檔案的完整路徑。
使用自訂組態檔案時，您必須指定與 FireLens 使用的路徑不同的路徑。Amazon ECS 會為 Fluent Bit 保留 `/fluent-bit/etc/fluent-bit.conf` filepath，並為 Fluentd 保留 `/fluentd/etc/fluent.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`組態檔案類型。不過，您可以使用 for Fluent Bit init 容器，使用 AWS Fargate 上 Amazon S3 中託管 AWS 的組態檔案。如需詳細資訊，請參閱 [ECS 上的 Fluent Bit 的 Init 程序、GitHub 上的多組態支援](https://github.com/aws/aws-for-fluent-bit/blob/mainline/use_cases/init-process-for-fluent-bit/README.md)。 GitHub
# 在 Amazon ECS 中使用非AWS 容器映像
使用私有登錄檔將您的登入資料存放在 中 AWS Secrets Manager，然後在任務定義中參考它們。這可讓您參考 外部私有登錄檔中存在的容器映像 AWS ，這些登錄檔需要在您的任務定義中進行身分驗證。託管於 Fargate、Amazon EC2 執行個體以及使用 Amazon ECS Anywhere 的外部執行個體上的任務支援此功能。
**重要**
如果您的任務定義參考存放在 Amazon ECR 中的映像，則此主題不適用。如需詳細資訊，請參閱 *Amazon Elastic Container Registry User Guide* 中的 [Using Amazon ECR Images with 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 Resource Name (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 Resource Name (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 User Guide* 中的 [Create an AWS Secrets Manager secret](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 User Guide* 中的 [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，應用程式容器中的 `FLUENT_HOST` 環境變數可能會在重新啟動 FireLens 日誌路由器容器 (容器定義中具有 `firelensConfiguration` 物件的容器) 之後變得不準確。這是因為 `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 參數存放區無縫注入容器。這些秘密可以在您的任務中引用為以下任何內容。
1. 被引用為使用 `secrets` 容器定義參數的環境變數。
1. 如果您的日誌平台需要驗證，則被引用為 `secretOptions`。如需詳細資訊，請參閱[紀錄組態選項](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_LogConfiguration.html#API_LogConfiguration_Contents)。
1. 如果從中提取容器的登錄檔需要驗證，則使用 `repositoryCredentials` 容器定義參數的映像會將其參照為提取的秘密。從 Amazon ECR Public Gallery 提取映像時使用此方法。如需詳細資訊，請參閱[任務的私有登錄檔身分驗證](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)。
建議您在設定秘密管理時執行下列動作。
## 使用 AWS Secrets Manager 或 AWS Systems Manager 參數存放區來存放秘密資料
您應該將 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)。
## 使用附屬容器將秘密掛載至磁碟區
由於環境變數的資料外洩風險較高，因此您應該執行附屬容器，從 讀取秘密 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 參數存放區參數中。如需詳細資訊，請參閱[將敏感資料傳遞至 Amazon ECS 容器](specifying-sensitive-data.md)。
任務定義中指定的環境變數可供所有使用者和角色讀取，系統允許這些使用者和角色對任務定義執行 `DescribeTaskDefinition` 動作。
您可以將環境變數透過下列方式傳遞至容器：
+ 個別方式：使用 `environment` 容器定義參數。這會映射到 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) 的 `--env` 選項。
+ 大批方式：使用 `environmentFiles` 容器定義參數列出內含環境變數的一個或多個檔案。檔案必須託管在 Amazon S3 中。這會映射到 [https://docs.docker.com/reference/cli/docker/container/run/](https://docs.docker.com/reference/cli/docker/container/run/) 的 `--env-file` 選項。
以下任務定義片段示範如何指定個別環境變數。
```
{
"family": "",
"containerDefinitions": [
{
"name": "",
"image": "",
...
"environment": [
{
"name": "variable",
"value": "value"
}
],
...
}
],
...
}
```
# 將環境變數傳遞至 Amazon ECS 容器
**重要**
建議您將敏感資料儲存在 AWS Secrets Manager 秘密或 AWS Systems Manager 參數存放區參數中。如需詳細資訊，請參閱[將敏感資料傳遞至 Amazon ECS 容器](specifying-sensitive-data.md)。
環境變數檔案是 Simple Storage Service (Amazon S3) 中的物件，所有 Amazon S3 安全考量事項均適用。
Windows 容器與 Fargate 上的 Windows 容器不支援使用 `environmentFiles` 參數。
您可以建立環境變數檔案，並將其儲存於 Amazon S3 中，將環境變數傳遞至您的容器。
透過在檔案中指定環境變數，您可以批次導入環境變數。在容器定義中指定 `environmentFiles` 物件，其中具有內含環境變數檔案的 Amazon S3 儲存貯體清單。
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 環境檔案類似。
+ 若容器定義所引用的環境變數值為空白且儲存於 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 中建立秘密。建立 Secret Manager 秘密後，更新應用程式程式碼即可擷取秘密。
保護 Secrets Manager 中的敏感資料之前，請先檢閱下列考量事項。
+ 僅支援存放文字資料的秘密，這些秘密是使用 [CreateSecret](https://docs.aws.amazon.com/secretsmanager/latest/apireference/API_CreateSecret.html) API 的 `SecretString` 參數建立的。不支援儲存二進位資料的秘密，即透過 [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 User Guide* 中的 [Retrieve secrets from AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets.html)。
若要擷取存放在 中的敏感資料 AWS Secrets Manager，請參閱 SDK [程式碼範例程式碼庫中的使用 AWS SDKs的 AWS Secrets Manager](https://docs.aws.amazon.com/code-library/latest/ug/secrets-manager_code_examples.html)程式碼範例。 *AWS *
# 在 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 參數存放區參數中的敏感資料，請參閱 SDK [程式碼範例程式碼庫中的使用 AWS SDKs的 Systems Manager](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html) 程式碼範例。 *AWS *
# 透過 Amazon ECS 環境變數傳遞 Secrets Manager 秘密
在將秘密作為環境變數插入時，可指定秘密的完整內容、秘密內的特定 JSON 金鑰。這可協助您控制向容器公開的敏感資料。如需有關秘密版本控制的詳細資訊，請參閱 *AWS Secrets Manager User Guide* 中的 [What's in a Secrets Manager secret?](https://docs.aws.amazon.com/secretsmanager/latest/userguide/whats-in-a-secret.html#term_version) 章節。
使用環境變數將 Secrets Manager 秘密插入容器時應考量下列事項。
+ 敏感資料會在初次啟動容器時，嵌入您的容器。如果後續更新或輪換秘密，則容器不會自動收到更新的值。您必須啟動新的任務，或如果任務是服務的一部分，您可以更新服務，並使用 **Force new deployment (強制新的部署)** 選項強制服務來啟動新的任務。
+ 容器上執行的應用程式、容器日誌及偵錯工具皆能存取環境變數。
+ 對於 上的 Amazon ECS 任務 AWS Fargate，請考慮下列事項：
+ 若要將秘密的完整內容作為環境變數或在日誌組態中插入，您必須使用平台版本 `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 的詳細資訊，請參閱 [How to connect to Secrets Manager service within a Amazon VPC](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 Resource Name (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 參數存放區參數中，然後在容器定義中參考，藉此將敏感資料注入容器。
使用環境變數將 Systems Manager 秘密插入容器時，應考量下列事項。
+ 敏感資料會在初次啟動容器時，嵌入您的容器。如果後續更新或輪換秘密，則容器不會自動收到更新的值。您必須啟動新的任務，或如果任務是服務的一部分，您可以更新服務，並使用 **Force new deployment (強制新的部署)** 選項強制服務來啟動新的任務。
+ 對於 上的 Amazon ECS 任務 AWS Fargate，應考慮下列事項：
+ 若要將秘密的完整內容作為環境變數或在日誌組態中插入，您必須使用平台版本 `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 User Guide* 中的 [Improve the security of EC2 instances by using VPC endpoints for Systems Manager](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)。
## 將環境變數新增至容器定義
在任務定義的容器定義內，為 `secrets` 指定要在容器中設定的環境變數名稱，以及 Systems Manager Parameter Store 參數 (含有要提供給容器的敏感資料) 的完整 ARN。如需詳細資訊，請參閱[secrets](task_definition_parameters.md#ContainerDefinition-secrets)。
以下是任務定義的程式碼片段，顯示參考 Systems Manager 參數存放區參數的格式。如果 Systems Manager 參數存放區參數與您要啟動的任務位於相同區域中，則您可以使用參數的完整 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 參數存放區參數中的敏感資料，請參閱 SDK [程式碼範例程式碼庫中的使用 AWS SDKs的 Systems Manager](https://docs.aws.amazon.com/code-library/latest/ug/ssm_code_examples.html) 程式碼範例。 *AWS *
# 為 Amazon ECS 記錄組態傳遞秘密
您可以使用 `logConfiguration` 中的 `secretOptions` 參數，傳遞用於記錄的敏感資料。
您可以將秘密儲存於 Secrets Manager 或 Systems Manager 中。
## 使用 Secrets Manager
在您的容器定義內，指定 `logConfiguration` 時，您可指定 `secretOptions`，在該參數中，需提供要在容器中設定的日誌驅動程式選項名稱，以及含有要呈現給容器之敏感資料的 Secrets Manager 秘密之完整 ARN。如需有關建立秘密的詳細資訊，請參閱 [Create an 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"
}]
}]
}]
}
```
## 將環境變數新增至容器定義
在您的容器定義內，將 `secrets` 指定為要在容器中設定的環境變數名稱，以及 Systems Manager 參數存放區參數 (含有要呈現給容器的敏感資料) 的完整 ARN。如需詳細資訊，請參閱[secrets](task_definition_parameters.md#ContainerDefinition-secrets)。
以下是任務定義的程式碼片段，顯示參考 Systems Manager 參數存放區參數的格式。如果 Systems Manager 參數存放區參數與您要啟動的任務位於相同區域中，則您可以使用參數的完整 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` 時，您可用要在容器中設定的日誌驅動程式選項名稱指定 `secretOptions`，以及 Systems Manager 參數存放區參數 (含有要呈現給容器的敏感資料) 的完整 ARN。
**重要**
如果 Systems Manager 參數存放區參數與您要啟動的任務位於相同區域中，則您可以使用參數的完整 ARN 或名稱。如果參數存在於不同區域，則請指定完整 ARN。
以下是任務定義的程式碼片段，顯示參考 Systems Manager 參數存放區參數的格式。
```
{
"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)」中的步驟。
+ 您的使用者具有必要的 IAM 許可，可建立 Secrets Manager 與 Amazon ECS 資源。
## 步驟 1：建立 Secrets Manager 機密
您可以使用 Secrets Manager 主控台為您的敏感資料建立秘密。在本教學課程中，我們將建立基本秘密，以供存放容器中稍後參考的使用者名稱和密碼。如需詳細資訊，請參閱*AWS Secrets Manager 《 使用者指南*》中的[建立 AWS Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。
**要儲存在此秘密中的鍵/值對**是教學課程結尾處容器中的環境變量值。
儲存**秘密 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 definitio** (建立新任務定義)、**Create new task definition with JSON** (使用 JSON 建立新的任務定義)。
1. 在 JSON 編輯器方塊中輸入以下任務定義 JSON 文字，確保為在步驟 1 建立的 Secrets Manager 秘密以及在步驟 2 中更新的任務執行角色，指定完整的 ARN。選擇**儲存**。
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 User Guide* 中的 [Connect to your Linux instance using PuTTY](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/connect-linux-inst-from-windows.html)。
**重要**
如需有關執行個體連線問題的詳細資訊，請參閱 *Amazon EC2 User Guide* 中的 [Troubleshooting Connecting to Your Instance](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. 在**叢集**頁面上，選擇叢集。
1. 選擇 **Delete Cluster (刪除叢集)**。
1. 在確認方塊中，輸入 **delete *叢集名稱***，然後選擇**刪除**。
1. 在以下網址開啟 IAM 主控台：[https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)。
1. 在導覽窗格中，選擇**角色**。
1. 搜尋 `ecsTaskExecutionRole` 的角色清單並加以選取。
1. 選擇**許可**，然後選擇 **ECSSecretsTutorial** 旁邊的 **X**。選擇**移除**。
1. 開啟位於的 Secrets Manager 主控台[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 選取您所建立的 **username\$1value** 秘密，然後選擇 **Actions (動作)**、**Delete secret (刪除秘密)**。
# Amazon ECS 受管執行個體的 Amazon ECS 任務定義參數
任務定義分為不同的部分：任務系列、 AWS Identity and Access Management (IAM) 任務角色、網路模式、容器定義、磁碟區和容量。任務定義中需要系列和容器定義。與此相對，任務角色、網路模式、磁碟區與容量則為選用項目。
您可以在 JSON 檔案中使用這些參數來設定任務定義。
以下是 Amazon ECS 受管執行個體每個任務定義參數的詳細描述。
## 系列
`family`
類型：字串
必要：是
當您註冊任務定義時，您會指定它的系列，這類似於任務定義以修訂版號碼指定的多個版本名稱。在特定系列註冊的第一個任務定義會得到修訂版 1，之後註冊的任何任務定義，則得到連續的修訂版號碼。
## Capacity
在註冊任務定義時，您可以指定 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 Resource Name (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 單位硬性限制。您可以在 JSON 檔案中將 CPU 值指定為以 CPU 為單位或虛擬 CPU (vCPU) 為單位的字串。例如，可指定 `1024` 個 CPU 單位作為 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 (標籤)](#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 代理的組態詳細資訊。
### Tags (標籤)
您套用至任務定義的中繼資料，可用於協助您對任務定義進行分類與整理。每個標籤皆包含索引鍵與選用值。您可以兩個都定義。
以下基本限制適用於 標籤：
+ 每個資源的標籤數上限 - 50
+ 針對每一個資源，每個標籤鍵必須是唯一的，且每個標籤鍵只能有一個值。
+ 索引鍵長度上限 - 128 個 UTF-8 Unicode 字元
+ 值的長度上限 - 256 個 UTF-8 Unicode 字元
+ 如果您的標記結構描述是跨多項服務和資源使用，請記得其他服務可能會有字元使用限制。通常允許的字元為：以 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) 物件
必要：否
此參數會在您為任務儲存使用 Amazon FSx for Windows File Server 檔案系統時指定。
`configuredAtLaunch`
類型：布林值
必要：否
指示是否應在啟動時設定磁碟區。此參數用於為獨立任務或作為服務一部分建立的任務建立 Amazon EBS 磁碟區。每個任務定義修訂版只能在磁碟區組態中於啟動時設定一個磁碟區。
## 容器定義
註冊任務定義時，您必須指定容器定義清單，以傳遞到容器執行個體上的 Docker 常駐程式。容器定義允許使用以下參數。
**Topics**
+ [名稱](#container_definition_name-managed-instances)
+ [影像](#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)
+ [主要](#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 個字母 （大寫和小寫）、數字、連字號和底線。如果您在任務定義中連結多個容器，則一個容器的 `name` 可以輸入另一個容器的 `links`。這是為了連結容器。
### 影像
`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)。
+ 可使用完整的 `registry/repository:tag` 或 `registry/repository@digest` 命名慣例來指定 Amazon ECR 儲存庫中的映像 (例如 `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 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。
Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。
若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「[保留 Amazon ECS Linux 容器執行個體記憶體](memory-management.md)」。
`memoryReservation`
類型：整數
必要：否
為容器保留的記憶體軟性限制 (MiB)。當系統記憶體爭用時，Docker 會嘗試將容器記憶體保持在此軟性限制。但是，您的容器可以在需要時使用更多記憶體。容器可以使用最多達到以 `memory` 參數指定的硬性限制 (如適用)，或容器執行個體上的所有可用記憶體，以先達到者為準。此參數會映射至 docker create-container 命令中的 `MemoryReservation`，以及 docker run 的 `--memory-reservation` 選項。
如果未指定任務層級的記憶體值，您必須為容器定義中的 `memory` 或 `memoryReservation` 之一或兩者指定非零整數。若您同時指定兩者，`memory` 必須大於 `memoryReservation`。如果指定 `memoryReservation`，則會從放置容器的容器執行個體可用記憶體資源中減去該值。否則，即使用 `memory` 的值。
例如，若您的容器通常會使用 128 MiB 的記憶體，但會偶爾短期爆量到 256 MiB 的記憶體。您可以將 `memoryReservation` 設為 128 MiB，並將 `memory` 硬性限制設為 300 MiB。此組態讓容器只從容器執行個體的剩餘資源中保留 128 MiB 的記憶體。同時，其還允許容器在需要時使用更多的記憶體資源。
Docker 20.10.0 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。
Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。
若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「[保留 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/)詳細資訊頁面上為執行個體類型列出的 vCPU 乘上 1,024，來判斷每個 EC2 執行個體類型可用的 CPU 單位數。
Linux 容器會按照與其配置數量相同的比例，與容器執行個體上的其他容器共用未配置的 CPU 單位。例如，若您在單一核心執行個體類型上執行單一容器任務，為該容器指定 512 個 CPU 單位，並且該任務是容器執行個體上唯一執行中的任務，該容器便可在任何指定時間內使用完整的 1,024 個 CPU 單位。但是，若您在該容器執行個體上啟動相同任務的另一個複本，可保證每個任務都可以在需要時取得至少 512 個 CPU 單位。此外，每個容器都可在其他容器沒有使用時浮動到更高的 CPU 用量。若兩個任務都一直維持在 100% 作用中的狀態，兩者能夠取得的單位數便會限制在 512 個 CPU 單位。
在 Linux 容器執行個體上，容器執行個體的 Docker 常駐程式會使用 CPU 值計算執行中容器的相對 CPU 共用比例。如需詳細資訊，請參閱 Docker 文件中的 [CPU share constraint](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 將之轉換為 1,024 個 CPU 共用。CPU 值若為 1，則會以 1 傳遞給 Docker，接著 Linux 核心便會轉換成兩個 CPU 共用。
+ **代理程式版本大於或等於 1.2.0：**Null、零和 1 的 CPU 值，會以 2 傳遞至 Docker。
在 Windows 容器執行個體上，CPU 限制會強制為絕對限制或配額。Windows 容器只能存取任務定義的描述中所指定之 CPU 數量。將空或零的 CPU 值以 `0` 的形式傳遞給 Docker，Windows 會將此值解釋為一個 CPU 的 1%。
### 連接埠映射
`portMappings`
類型：物件陣列
必要：否
連接埠映射會將容器的網路連接埠對外公開，讓用戶端可以存取您的應用程式。這也適用於同一任務中的容器間通訊。
針對使用 `awsvpc` 網路模式的任務定義，只指定 `containerPort`。一律略過 `hostPort`，且容器連接埠會自動映射至主機上的隨機高連接埠號碼。
此參數的大部分欄位 (包括 `containerPort`、`hostPort`、`protocol`) 會映射至 docker create-container 命令中的 `PortBindings`，以及 docker run 的 `--publish` 選項。若任務定義的網路模式設定為 `host`，則主機連接埠必須為未定義，或符合連接埠映射中的容器連接埠。
任務達到 `RUNNING` 狀態後，手動和自動主機及容器連接埠指派會顯示在下列位置：
+ 主控台：選取任務的容器說明的 **Network Bindings** (網路繫結) 區段。
+ AWS CLI：**describe-tasks** 命令輸出的 `networkBindings` 區段。
+ API：`DescribeTasks` 的回應。
+ 中繼資料：任務中繼資料端點。
`appProtocol`
類型：字串
必要：否
用於連接埠映射的應用程式通訊協定。此參數僅適用於 Service Connect。建議您將此參數設定為與您應用程式使用的通訊協定一致。如果您設定此參數，Amazon ECS 會將通訊協定專屬連線處理新增至 Service Connect Proxy。如果您設定此參數，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 代理。
如需詳細資訊，請參閱 GitHub 上的 [Issue \$111185](https://github.com/moby/moby/issues/11185)。
如需有關如何在 Docker 常駐程式組態檔案中關閉 Docker 代理的詳細資訊，請參閱*《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 Resource Name (ARN)。
如需詳細資訊，請參閱[在 Amazon ECS 中使用非AWS 容器映像](private-auth.md)。
當您使用 Amazon ECS API AWS CLI或 AWS SDKs時，如果秘密與您啟動的任務位於相同的區域中，您可以使用完整的 ARN 或秘密的名稱。使用 時 AWS 管理主控台，您必須指定秘密的完整 ARN。
以下是任務定義的程式碼片段，其會顯示所需的參數：
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### 主要
`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` 選項。
### 進階容器定義參數
下列進階容器定義參數會為用於在 Amazon ECS 容器執行個體上啟動容器的 docker run 命令提供延伸功能。
**Topics**
+ [重新啟動政策](#container_definition_restart_policy-managed-instances)
+ [運作狀態檢查](#container_definition_healthcheck-managed-instances)
+ [Environment](#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`
類型：Integer array
必要：否
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
```
使用 JSON AWS 管理主控台 面板 AWS CLI、 或 APIs 註冊任務定義時，請將命令清單括在括號中。以下為運作狀態檢查的範例輸入。
```
[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
```
結束代碼 0 (沒有 `stderr` 輸出) 表示成功，而任何非零的結束代碼則表示失敗。
`interval`
每個運作狀態檢查的時間間隔 (以秒為單位)。您可以指定 5 至 300 秒之間的值。預設值為 30 秒。
`timeout`
判定為失敗之前，等待運作狀態檢查成功執行的時間 (以秒為單位)。您可以指定 2 至 60 秒之間的值。預設值為 5 秒。
`retries`
容器運作狀態判定為不良之前，重試失敗的運作狀態檢查的次數上限。您可以指定 1 至 10 次嘗試。預設值為重試三次。
`startPeriod`
選用的寬限期，讓容器有時間引導，不將失敗的運作狀態檢查計入重試次數上限。您可以指定介於 0 到 300 秒之間的值。預設情況下，`startPeriod` 是停用的。
如果運作狀態檢查在 `startPeriod` 內成功，則代表容器運作狀態良好，之後的任何故障都會計入，累積至重試次數上限。
#### Environment
`cpu`
類型：整數
必要：否
Amazon ECS 容器代理程式保留給容器的 `cpu` 數量。在 Linux 上，此參數會映射至 [Create a container](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 區段中的 `CpuShares`。
對於在 Amazon ECS 受管執行個體上執行的任務，此欄位為選用項目。為任務中所有容器預訂的 CPU 總量必須低於任務階層的 `cpu` 值。
Linux 容器會按照與其配置數量相同的比例，與容器執行個體上的其他容器共用未配置的 CPU 單位。例如，若您在單一核心執行個體類型上執行單一容器任務，為該容器指定 512 個 CPU 單位。此外，該任務是在容器執行個體上運行的唯一任務。在此範例中，該容器便可在任何指定的時間內使用完整 1,024 個 CPU 單位。但是，假設您在該容器執行個體上啟動相同任務的另一個複本。每個任務都可以保證在需要的時候取得最少 512 個 CPU 單位。同樣，如果其他容器沒有使用剩餘的 CPU，每個容器都可以浮動到更高的 CPU 用量。但若兩個任務都一直維持在 100% 作用中的狀態，兩者能夠取得的單位數便會限制在 512 個 CPU 單位。
在 Linux 容器執行個體上，容器執行個體的 Docker 常駐程式會使用 CPU 值計算執行中容器的相對 CPU 共用比例。Linux 核心允許的有效 CPU 共用值，最小為 2，最大為 262144。但是，CPU 參數並非必要項目，且您可以在容器定義中使用小於 2 且大於 262144 的 CPU 值。針對小於 2 且大於 262144 的 CPU 值 (包含 null)，行為會隨您的 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 Resource Name (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 Resource Name (ARN) 或 AWS Systems Manager 參數存放區中參數的完整 ARN。
如果 Systems Manager 參數存放區參數或 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`
類型：物件陣列
必要：否
容器中資料磁碟區的掛載點。此參數會映射至 Docker API 中 create-container 的 `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 常駐程式可用的日誌驅動程式子集。
+ 在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。
```
"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`。
在您嘗試使用 `awslogs-create-group` 之前，您的 IAM 政策必須包含 `logs:CreateLogGroup` 許可。
`awslogs-region`
必要：是
指定 AWS 區域 `awslogs`日誌驅動程式要傳送 Docker 日誌的 。您可以選擇將所有的日誌從不同區域中的叢集傳送至 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 主控台時，讓日誌顯示在 Log (日誌) 窗格中。
`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 時應用程式發生無回應的狀況。如果您想要確保服務的可用性且可以接受一些日誌遺失，我們建議您使用此模式。如需詳細資訊，請參閱 [Preventing log loss with non-blocking mode in the `awslogs` container log driver](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 服務 或 AWS Partner Network 目的地以進行日誌儲存和分析時，您可以設定 `log-driver-buffer-limit`選項來限制記憶體中緩衝的事件數量，然後再傳送至日誌路由器容器。由於高輸送量可能會導致 Docker 內部緩衝區的記憶體不足，因此這可協助解決潛在的日誌受損問題。如需詳細資訊，請參閱[為高輸送量設定 Amazon ECS 日誌](firelens-docker-buffer-limit.md)。
使用 `awsfirelens` 路由日誌時，可指定的其他選項取決於目的地。當您將日誌匯出至 Amazon Data Firehose 時，您可以使用 指定 AWS 區域 ，`region`並使用 指定日誌串流的名稱`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` 作為選項。
在您的容器執行個體上，此參數需要 1.19 版或更新版本的 Docker Remote API。
`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` 對達到 `COMPLETE`、`SUCCESS` 或 `HEALTHY` 狀態的 `containerB` 有相依性。如果為 `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` 設定以維持壽命較長的連線。
不建議您指定單一任務中多個容器的網路相關 `systemControls` 參數，而單一任務也使用 `awsvpc` 或 `host` 網路模式。執行此操作的缺點如下：
+ 如果設定任何容器的 `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) 物件
必要：否
新增至 Docker 或從其提供的預設組態中卸除的容器 Linux 功能。
`devices`
類型：[Device](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` 值若為 `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，之後註冊的任何任務定義，則得到連續的修訂版號碼。
## Capacity
在註冊任務定義時，您可以指定 Amazon ECS 驗證任務定義所依據的容量。如果任務定義不會依據指定的相容性進行驗證，則會傳回用戶端例外狀況。
任務定義允許使用以下參數。
`requiresCompatibilities`
類型：字串陣列
必要：否
有效值:`FARGATE`
驗證任務定義所依據的容量。這會啟動檢查，確保任務定義中使用的所有參數都能滿足 Fargate 的需求
## 任務 角色
`taskRoleArn`
類型：字串
必要：否
當您註冊任務定義時，您可以為 IAM 角色提供任務角色，該角色可讓任務許可中的容器，代您呼叫其關聯政策中指定的 AWS API。如需詳細資訊，請參閱[Amazon ECS 任務 IAM 角色](task-iam-roles.md)。
## 任務執行 角色
`executionRoleArn`
類型：字串
必要：有條件
任務執行角色的 Amazon Resource Name (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 單位硬性限制。您可以在 JSON 檔案中將 CPU 值指定為以 CPU 為單位或虛擬 CPU (vCPU) 為單位的字串。例如，可指定 `1024` 個 CPU 單位作為 CPU 值，也可指定 `1 vCPU` 個 vCPU 作為 CPU 值。註冊任務定義時，vCPU 值會轉換為整數，指出 CPU 單位。
此欄位為必要項目，而且您必須使用下列其中一個值，從而決定 `memory` 參數受支援的值範圍。下表顯示有效的任務層級 CPU 和記憶體組合。
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/zh_tw/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_tw/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)
+ [影像](#container_definition_image)
+ [記憶體](#container_definition_memory)
+ [連接埠映射](#container_definition_portmappings)
+ [私有儲存庫憑證](#container_definition_repositoryCredentials)
#### 名稱
`name`
類型：字串
必要：是
容器的名稱。最多允許 255 個字母 （大寫和小寫）、數字、連字號和底線。如果您在任務定義中連結多個容器，則一個容器的 `name` 可以輸入另一個容器的 `links`。這是為了連結容器。
#### 影像
`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)。
+ 可使用完整的 `registry/repository:tag` 或 `registry/repository@digest` 命名慣例來指定 Amazon ECR 儲存庫中的映像 (例如 `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 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。
Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。
若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「[保留 Amazon ECS Linux 容器執行個體記憶體](memory-management.md)」。
`memoryReservation`
類型：整數
必要：否
為容器保留的記憶體軟性限制 (MiB)。當系統記憶體爭用時，Docker 會嘗試將容器記憶體保持在此軟性限制。但是，您的容器可以在需要時使用更多記憶體。容器可以使用最多達到以 `memory` 參數指定的硬性限制 (如適用)，或容器執行個體上的所有可用記憶體，以先達到者為準。此參數會映射至 docker create-container 命令中的 `MemoryReservation`，以及 docker run 的 `--memory-reservation` 選項。
如果未指定任務層級的記憶體值，您必須為容器定義中的 `memory` 或 `memoryReservation` 之一或兩者指定非零整數。若您同時指定兩者，`memory` 必須大於 `memoryReservation`。如果指定 `memoryReservation`，則會從放置容器的容器執行個體可用記憶體資源中減去該值。否則，即使用 `memory` 的值。
例如，若您的容器通常會使用 128 MiB 的記憶體，但會偶爾短期爆量到 256 MiB 的記憶體。您可以將 `memoryReservation` 設為 128 MiB，並將 `memory` 硬性限制設為 300 MiB。此組態讓容器只從容器執行個體的剩餘資源中保留 128 MiB 的記憶體。同時，其還允許容器在需要時使用更多的記憶體資源。
Windows 容器不支援此參數。
Docker 20.10.0 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。
Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。
若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「[保留 Amazon ECS Linux 容器執行個體記憶體](memory-management.md)」。
#### 連接埠映射
`portMappings`
類型：物件陣列
必要：否
連接埠映射會將容器的網路連接埠對外公開，讓用戶端可以存取您的應用程式。這也適用於同一任務中的容器間通訊。
針對使用 `awsvpc` 網路模式的任務定義，只指定 `containerPort`。一律略過 `hostPort`，且容器連接埠會自動映射至主機上的隨機高連接埠號碼。
Windows 上的連接埠映射會使用 `NetNAT` 閘道地址，而非 `localhost`。Windows 沒有連接埠映射回送，所以您無法從主機本身存取容器的映射連接埠。
此參數的大部分欄位 (包括 `containerPort`、`hostPort`、`protocol`) 會映射至 docker create-container 命令中的 `PortBindings`，以及 docker run 的 `--publish` 選項。若任務定義的網路模式設定為 `host`，則主機連接埠必須為未定義，或符合連接埠映射中的容器連接埠。
任務達到 `RUNNING` 狀態後，手動和自動主機及容器連接埠指派會顯示在下列位置：
+ 主控台：選取任務的容器說明的 **Network Bindings** (網路繫結) 區段。
+ AWS CLI：**describe-tasks** 命令輸出的 `networkBindings` 區段。
+ API：`DescribeTasks` 的回應。
+ 中繼資料：任務中繼資料端點。
`appProtocol`
類型：字串
必要：否
用於連接埠映射的應用程式通訊協定。此參數僅適用於 Service Connect。建議您將此參數設定為與您應用程式使用的通訊協定一致。如果您設定此參數，Amazon ECS 會將通訊協定專屬連線處理新增至 Service Connect Proxy。如果您設定此參數，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 代理。
如需詳細資訊，請參閱 GitHub 上的 [Issue \$111185](https://github.com/moby/moby/issues/11185)。
如需有關如何在 Docker 常駐程式組態檔案中關閉 Docker 代理的詳細資訊，請參閱*《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 Resource Name (ARN)。
如需詳細資訊，請參閱[在 Amazon ECS 中使用非AWS 容器映像](private-auth.md)。
當您使用 Amazon ECS API AWS CLI或 AWS SDKs時，如果秘密與您啟動的任務位於相同的區域中，您可以使用完整的 ARN 或秘密的名稱。使用 時 AWS 管理主控台，您必須指定秘密的完整 ARN。
以下是任務定義的程式碼片段，其會顯示所需的參數：
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### 進階容器定義參數
下列進階容器定義參數會為用於在 Amazon ECS 容器執行個體上啟動容器的 docker run 命令提供延伸功能。
**Topics**
+ [重新啟動政策](#container_definition_restart_policy)
+ [運作狀態檢查](#container_definition_healthcheck)
+ [Environment](#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`
類型：Integer array
必要：否
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
```
使用 JSON AWS 管理主控台 面板 AWS CLI、 或 APIs 註冊任務定義時，請將命令清單括在括號中。以下為運作狀態檢查的範例輸入。
```
[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
```
結束代碼 0 (沒有 `stderr` 輸出) 表示成功，而任何非零的結束代碼則表示失敗。
`interval`
每個運作狀態檢查的時間間隔 (以秒為單位)。您可以指定 5 至 300 秒之間的值。預設值為 30 秒。
`timeout`
判定為失敗之前，等待運作狀態檢查成功執行的時間 (以秒為單位)。您可以指定 2 至 60 秒之間的值。預設值為 5 秒。
`retries`
容器運作狀態判定為不良之前，重試失敗的運作狀態檢查的次數上限。您可以指定 1 至 10 次嘗試。預設值為重試三次。
`startPeriod`
選用的寬限期，讓容器有時間引導，不將失敗的運作狀態檢查計入重試次數上限。您可以指定介於 0 到 300 秒之間的值。預設情況下，`startPeriod` 是停用的。
如果運作狀態檢查在 `startPeriod` 內成功，則代表容器運作狀態良好，之後的任何故障都會計入，累積至重試次數上限。
#### Environment
`cpu`
類型：整數
必要：否
Amazon ECS 容器代理程式保留給容器的 `cpu` 數量。在 Linux 上，此參數會映射至 [Create a container](https://docs.docker.com/reference/api/engine/version/v1.38/#operation/ContainerCreate) 區段中的 `CpuShares`。
對於使用 Fargate 的任務，此欄位為選用項目。為任務中所有容器預訂的 CPU 總量必須低於任務階層的 `cpu` 值。
Linux 容器會按照與其配置數量相同的比例，與容器執行個體上的其他容器共用未配置的 CPU 單位。例如，若您在單一核心執行個體類型上執行單一容器任務，為該容器指定 512 個 CPU 單位。此外，該任務是在容器執行個體上運行的唯一任務。在此範例中，該容器便可在任何指定的時間內使用完整 1,024 個 CPU 單位。但是，假設您在該容器執行個體上啟動相同任務的另一個複本。每個任務都可以保證在需要的時候取得最少 512 個 CPU 單位。同樣，如果其他容器沒有使用剩餘的 CPU，每個容器都可以浮動到更高的 CPU 用量。但若兩個任務都一直維持在 100% 作用中的狀態，兩者能夠取得的單位數便會限制在 512 個 CPU 單位。
在 Linux 容器執行個體上，容器執行個體的 Docker 常駐程式會使用 CPU 值計算執行中容器的相對 CPU 共用比例。Linux 核心允許的有效 CPU 共用值，最小為 2，最大為 262144。但是，CPU 參數並非必要項目，且您可以在容器定義中使用小於 2 且大於 262144 的 CPU 值。針對小於 2 且大於 262144 的 CPU 值 (包含 null)，行為會隨您的 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 Resource Name (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 Resource Name (ARN) 或 AWS Systems Manager 參數存放區中參數的完整 ARN。
如果 Systems Manager 參數存放區參數或 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`
類型：物件陣列
必要：否
容器中資料磁碟區的掛載點。此參數會映射至 Docker API 中 create-container 的 `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 常駐程式可用的日誌驅動程式子集。
+ 在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。
+ 您必須在任務外部安裝任何額外軟體。例如，Fluentd 輸出彙整工具或要傳送 Gelf 日誌執行 Logstash 的遠端主機。
```
"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`。
在您嘗試使用 `awslogs-create-group` 之前，您的 IAM 政策必須包含 `logs:CreateLogGroup` 許可。
`awslogs-region`
必要：是
指定 AWS 區域 `awslogs`日誌驅動程式要傳送 Docker 日誌的 。您可以選擇將所有的日誌從不同區域中的叢集傳送至 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 主控台時，讓日誌顯示在 Log (日誌) 窗格中。
`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` 選項設定的記憶體內中間緩衝區中。這可以防止當無法傳送日誌時應用程式發生無回應的狀況。如果您想要確保服務的可用性且可以接受一些日誌遺失，我們建議您使用此模式。如需詳細資訊，請參閱 [Preventing log loss with non-blocking mode in the `awslogs` container log driver](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 服務 或 AWS Partner Network 目的地以進行日誌儲存和分析時，您可以設定 `log-driver-buffer-limit`選項，以限制在記憶體中緩衝的日誌行數，然後再傳送至日誌路由器容器。由於高輸送量可能會導致 Docker 內部緩衝區的記憶體不足，因此這可協助解決潛在的日誌受損問題。如需詳細資訊，請參閱[為高輸送量設定 Amazon ECS 日誌](firelens-docker-buffer-limit.md)。
使用 `awsfirelens` 路由日誌時，可指定的其他選項取決於目的地。當您將日誌匯出至 Amazon Data Firehose 時，您可以使用 指定 AWS 區域 ，`region`並使用 指定日誌串流的名稱`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` 作為選項。
在您的容器執行個體上，此參數需要 1.19 版或更新版本的 Docker Remote API。
`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`。
您必須先將容器執行個體加入網域，才能啟動此任務定義的任何任務。
在這兩種格式中，以 SSM 或 Amazon S3 中的 ARN 替換 `MyARN`。
`credspec` 必須在 Secrets Manager 中提供 ARN，以取得包含使用者名稱、密碼和要連線之網域的秘密。為了提高安全性，執行個體不會加入網域以進行無網域驗證。執行個體上的其他應用程式無法使用無網域憑證。您可以使用此參數在相同的執行個體上執行任務，即使是任務需要加入不同的網域。如需詳細資訊，請參閱在[使用 Windows 容器的 gMSA](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/windows-gmsa.html) 和[使用 Linux 容器的 gMSA](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) 物件
必要：否
從 Docker 提供的預設組態中移除容器的 Linux 功能。如需這些 Linux 功能的詳細資訊，請參閱 Linux 手冊頁面的[功能 (7)](http://man7.org/linux/man-pages/man7/capabilities.7.html)。
`add`
類型：字串陣列
有效值：`"SYS_PTRACE"`
必要：否
要新增至 Docker 提供之預設組態容器的 Linux 功能。此參數會映射至 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"`
必要：否
要從 Docker 提供之預設組態中移除容器的 Linux 功能。此參數會映射至 docker create-container 命令中的 `CapDrop`，以及 docker run 的 `--cap-drop` 選項。
`devices`
任何要公開給容器的主機裝置。此參數會映射至 docker create-container 命令中的 `Devices`，以及 docker run 的 `--device` 選項。
使用 Fargate 啟動類型時，不支援 `devices` 參數。
類型：[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` 選項。
在您的容器執行個體上，此參數需要 1.25 版或更新版本的 Docker Remote API。
`maxSwap`
在 Fargate 上執行的任務不支援此參數。
容器可以使用的交換記憶體總量 (以 MiB 為單位)。此參數將會轉換為 docker run 的 `--memory-swap` 選項，其中值是容器記憶體與 `maxSwap` 值的總和。
如果將 `maxSwap` 值指定為 `0`，容器不會使用交換。接受的值為 `0` 或任何正整數。如果省略 `maxSwap` 參數，容器使用其執行所在的容器執行個體的交換組態。必須設定 `maxSwap` 值，才能使用 `swappiness` 參數。
`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` 對達到 `COMPLETE`、`SUCCESS` 或 `HEALTHY` 狀態的 `containerB` 有相依性。如果為 `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` 設定以維持壽命較長的連線。
不建議您指定單一任務中多個容器的網路相關 `systemControls` 參數，而單一任務也使用 `awsvpc` 或 `host` 網路模式。執行此操作的缺點如下：
+ 如果設定任何容器的 `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`
類型：字串
必要：是
彈性推論加速器裝置名稱。`deviceName` 也必須在容器定義中參照，請參閱 [Elastic Inference accelerator](#ContainerDefinition-elastic-inference)。
`deviceType`
類型：字串
必要：是
要使用的彈性推論加速器。
## 代理組態
`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` - (必要) `user` 參數在容器定義中定義之代理容器的使用者 ID (UID)。這是用於確保代理忽略自己的流量。如果指定了 `IgnoredGID`，這個欄位可以為空白。
+ `IgnoredGID` - (必要) `user` 參數在容器定義中定義之代理容器的群組 ID (GID)。這是用於確保代理忽略自己的流量。如果指定了 `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)。
+ FSx for Windows File Server 磁碟區 — 提供全受管 Microsoft Windows 檔案伺服器。這些檔案伺服器由 Windows 檔案系統支援。搭配使用 FSx for Windows File Server 與 Amazon ECS 時，您可以使用持續、分散、共用、靜態的檔案儲存來佈建 Windows 任務。如需詳細資訊，請參閱[搭配 Amazon ECS 使用 FSx for Windows File Server 磁碟區](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 執行個體上的指定位置，直到您手動將其刪除為止。如果 `sourcePath` 值不存在於主機 Amazon EC2 執行個體，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 中「Create a volume」區段的 `DriverOpts`。
`labels`
類型：字串
必要：否
自訂中繼資料，新增到您的 Docker 磁碟區。
`efsVolumeConfiguration`
類型：[EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 物件
必要：否
只有使用 Amazon EFS 磁碟區時才會指定此參數。
`fileSystemId`
類型：字串
必要：是
要使用的 Amazon EFS 檔案系統識別碼。
`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 使用者指南》**中的 [EFS 掛載協助程式](https://docs.aws.amazon.com/efs/latest/ug/efs-mount-helper.html)。
`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 ECS 檔案系統時，指定是否使用任務定義中定義的 Amazon EFS 任務 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) 物件
必要：是
此參數在您為任務儲存使用 [Amazon FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 檔案系統時指定。
`fileSystemId`
類型：字串
必要：是
要使用的 FSx for Windows File Server 檔案系統 ID。
`rootDirectory`
類型：字串
必要：是
FSx for Windows File Server 檔案系統中的目錄，其將掛載做為主機內的根目錄。
`authorizationConfig`
`credentialsParameter`
類型：字串
必要：是
授權憑證選項。
**選項：**
+ [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 秘密的 Amazon Resource Name (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 託管的完整網域名稱。
## Tags (標籤)
當您註冊任務定義時，您可以選擇性地指定套用至任務定義的中繼資料標籤。標籤可協助您分類和組織您的任務定義。每個標籤皆包含索引鍵與選用值。您可以兩個都定義。如需詳細資訊，請參閱[標記 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 模式的任務，不支援與 `systemControls` 相關的 IPC 命名空間。
+ 針對使用 `task` IPC 模式的任務，IPC 命名空間相關的 `systemControls` 套用到任務內的所有容器。
**注意**
Windows 容器或使用 Fargate 啟動類型的任務不支援此參數。
### PID 模式
`pidMode`
類型：字串
有效值: `host` \$1 `task`
必要：否
要用於任務中容器的程序命名空間。有效值為 `host` 或 `task`。在 Linux 容器上，唯一的有效值為 `task`。例如，監控附屬可能需要 `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，之後註冊的任何任務定義，則得到連續的修訂版號碼。
## Capacity
在註冊任務定義時，您可以指定 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 Resource Name (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 單位硬性限制。您可以在 JSON 檔案中將 CPU 值指定為以 CPU 為單位或虛擬 CPU (vCPU) 為單位的字串。例如，可指定 `1024` 個 CPU 單位作為 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)
+ [影像](#container_definition_image_ec2)
+ [記憶體](#container_definition_memory_ec2)
+ [連接埠映射](#container_definition_portmappings_ec2)
+ [私有儲存庫憑證](#container_definition_repositoryCredentials_ec2)
#### 名稱
`name`
類型：字串
必要：是
容器的名稱。最多允許 255 個字母 （大寫和小寫）、數字、連字號和底線。如果您在任務定義中連結多個容器，則一個容器的 `name` 可以輸入另一個容器的 `links`。這是為了連結容器。
#### 影像
`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)。
+ 可使用完整的 `registry/repository:tag` 或 `registry/repository@digest` 命名慣例來指定 Amazon ECR 儲存庫中的映像 (例如 `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 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。
Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。
若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「[保留 Amazon ECS Linux 容器執行個體記憶體](memory-management.md)」。
`memoryReservation`
類型：整數
必要：否
為容器保留的記憶體軟性限制 (MiB)。當系統記憶體爭用時，Docker 會嘗試將容器記憶體保持在此軟性限制。但是，您的容器可以在需要時使用更多記憶體。容器可以使用最多達到以 `memory` 參數指定的硬性限制 (如適用)，或容器執行個體上的所有可用記憶體，以先達到者為準。此參數會映射至 docker create-container 命令中的 `MemoryReservation`，以及 docker run 的 `--memory-reservation` 選項。
如果未指定任務層級的記憶體值，您必須為容器定義中的 `memory` 或 `memoryReservation` 之一或兩者指定非零整數。若您同時指定兩者，`memory` 必須大於 `memoryReservation`。如果指定 `memoryReservation`，則會從放置容器的容器執行個體可用記憶體資源中減去該值。否則，即使用 `memory` 的值。
例如，若您的容器通常會使用 128 MiB 的記憶體，但會偶爾短期爆量到 256 MiB 的記憶體。您可以將 `memoryReservation` 設為 128 MiB，並將 `memory` 硬性限制設為 300 MiB。此組態讓容器只從容器執行個體的剩餘資源中保留 128 MiB 的記憶體。同時，其還允許容器在需要時使用更多的記憶體資源。
Windows 容器不支援此參數。
Docker 20.10.0 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。
Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。
若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「[保留 Amazon ECS Linux 容器執行個體記憶體](memory-management.md)」。
#### 連接埠映射
`portMappings`
類型：物件陣列
必要：否
連接埠映射會將容器的網路連接埠對外公開，讓用戶端可以存取您的應用程式。這也適用於同一任務中的容器間通訊。
針對使用 `awsvpc` 網路模式的任務定義，只指定 `containerPort`。一律略過 `hostPort`，且容器連接埠會自動映射至主機上的隨機高連接埠號碼。
Windows 上的連接埠映射會使用 `NetNAT` 閘道地址，而非 `localhost`。Windows 沒有連接埠映射回送，所以您無法從主機本身存取容器的映射連接埠。
此參數的大部分欄位 (包括 `containerPort`、`hostPort`、`protocol`) 會映射至 docker create-container 命令中的 `PortBindings`，以及 docker run 的 `--publish` 選項。若任務定義的網路模式設定為 `host`，則主機連接埠必須為未定義，或符合連接埠映射中的容器連接埠。
任務達到 `RUNNING` 狀態後，手動和自動主機及容器連接埠指派會顯示在下列位置：
+ 主控台：選取任務的容器說明的 **Network Bindings** (網路繫結) 區段。
+ AWS CLI：**describe-tasks** 命令輸出的 `networkBindings` 區段。
+ API：`DescribeTasks` 的回應。
+ 中繼資料：任務中繼資料端點。
`appProtocol`
類型：字串
必要：否
用於連接埠映射的應用程式通訊協定。此參數僅適用於 Service Connect。建議您將此參數設定為與您應用程式使用的通訊協定一致。如果您設定此參數，Amazon ECS 會將通訊協定專屬連線處理新增至 Service Connect Proxy。如果您設定此參數，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 代理。
如需詳細資訊，請參閱 GitHub 上的 [Issue \$111185](https://github.com/moby/moby/issues/11185)。
如需有關如何在 Docker 常駐程式組態檔案中關閉 Docker 代理的詳細資訊，請參閱*《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`。
只有在使用 1.2.0 版或更新版本的 Amazon ECS 容器代理程式 (例如 `amzn-ami-2015.03.c-amazon-ecs-optimized` AMI)，或是使用已更新到 1.3.0 版或更新版本的容器代理程式而啟動的容器執行個體上，才能使用 UDP 支援。若要將您的容器代理更新到最新版本，請參閱「[更新 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 Resource Name (ARN)。
如需詳細資訊，請參閱[在 Amazon ECS 中使用非AWS 容器映像](private-auth.md)。
當您使用 Amazon ECS API AWS CLI或 AWS SDKs時，如果秘密與您啟動的任務位於相同的區域中，您可以使用完整的 ARN 或秘密的名稱。使用 時 AWS 管理主控台，您必須指定秘密的完整 ARN。
以下是任務定義的程式碼片段，其會顯示所需的參數：
```
"containerDefinitions": [
{
"image": "private-repo/private-image",
"repositoryCredentials": {
"credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
}
}
]
```
### 進階容器定義參數
下列進階容器定義參數會為用於在 Amazon ECS 容器執行個體上啟動容器的 docker run 命令提供延伸功能。
**Topics**
+ [重新啟動政策](#container_definition_restart_policy_ec2)
+ [運作狀態檢查](#container_definition_healthcheck_ec2)
+ [Environment](#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`
類型：Integer array
必要：否
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
```
使用 JSON AWS 管理主控台 面板 AWS CLI、 或 APIs 註冊任務定義時，請將命令清單括在括號中。以下為運作狀態檢查的範例輸入。
```
[ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
```
結束代碼 0 (沒有 `stderr` 輸出) 表示成功，而任何非零的結束代碼則表示失敗。
`interval`
每個運作狀態檢查的時間間隔 (以秒為單位)。您可以指定 5 至 300 秒之間的值。預設值為 30 秒。
`timeout`
判定為失敗之前，等待運作狀態檢查成功執行的時間 (以秒為單位)。您可以指定 2 至 60 秒之間的值。預設值為 5 秒。
`retries`
容器運作狀態判定為不良之前，重試失敗的運作狀態檢查的次數上限。您可以指定 1 至 10 次嘗試。預設值為重試三次。
`startPeriod`
選用的寬限期，讓容器有時間引導，不將失敗的運作狀態檢查計入重試次數上限。您可以指定 0 至 300 秒之間的值。預設情況下，`startPeriod` 是停用的。
如果運作狀態檢查在 `startPeriod` 內成功，則代表容器運作狀態良好，之後的任何故障都會計入，累積至重試次數上限。
#### Environment
`cpu`
類型：整數
必要：否
Amazon ECS 容器代理程式保留給容器的 `cpu` 數量。在 Linux 上，此參數會映射至 [Create a container](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 數乘上 1,024。
Linux 容器會按照與其配置數量相同的比例，與容器執行個體上的其他容器共用未配置的 CPU 單位。例如，若您在單一核心執行個體類型上執行單一容器任務，為該容器指定 512 個 CPU 單位。此外，該任務是在容器執行個體上運行的唯一任務。在此範例中，該容器便可在任何指定的時間內使用完整 1,024 個 CPU 單位。但是，假設您在該容器執行個體上啟動相同任務的另一個複本。每個任務都可以保證在需要的時候取得最少 512 個 CPU 單位。同樣，如果其他容器沒有使用剩餘的 CPU，每個容器都可以浮動到更高的 CPU 用量。但若兩個任務都一直維持在 100% 作用中的狀態，兩者能夠取得的單位數便會限制在 512 個 CPU 單位。
在 Linux 容器執行個體上，容器執行個體的 Docker 常駐程式會使用 CPU 值計算執行中容器的相對 CPU 共用比例。Linux 核心允許的有效 CPU 共用值，最小為 2，最大為 262144。但是，CPU 參數並非必要項目，且您可以在容器定義中使用小於 2 且大於 262144 的 CPU 值。針對小於 2 且大於 262144 的 CPU 值 (包含 null)，行為會隨您的 Amazon ECS 容器代理程式版本而異：
+ **代理程式版本 <= 1.1.0：**Null 和零 CPU 值會以 0 傳遞給 Docker。然後 Docker 將此值轉換成 1,024 個 CPU 共享。CPU 值若為 1，則會以 1 傳遞給 Docker，接著 Linux 核心便會轉換成兩個 CPU 共享。
+ **代理程式版本 >= 1.2.0：**Null、零和值為一的 CPU 值會以兩個 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 Resource Name (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 Resource Name (ARN) 或 AWS Systems Manager 參數存放區中參數的完整 ARN。
如果 Systems Manager 參數存放區參數或 Secrets Manager 參數與您啟動 AWS 區域 的任務位於相同的 中，您可以使用秘密的完整 ARN 或名稱。如果參數存在於不同區域，則必須指定完整 ARN。
```
"secrets": [
{
"name": "environment_variable_name",
"valueFrom": "arn:aws:ssm:region:aws_account_id:parameter/parameter_name"
}
]
```
#### 網路設定
`disableNetworking`
類型：布林值
必要：否
當此參數為 true 時，聯網便會在容器中關閉。
Windows 容器或使用 `awsvpc` 網路模式的任務不支援此參數。
預設值為 `false`。
```
"disableNetworking": true|false
```
`links`
類型：字串陣列
必要：否
`link` 參數可讓容器彼此通訊，而無需連接埠映射。只有在任務定義的網路模式設定為 `bridge` 時才支援此參數。`name:internalName` 建構模組與 Docker 連結中的 `name:alias` 類似。最多可輸入 255 個字母 (大小寫)、數字、連字號與底線。
Windows 容器或使用 `awsvpc` 網路模式的任務不支援此參數。
在相同容器執行個體上配置的容器可和彼此通訊，而無需連結或主機連接埠映射。容器執行個體上的網路隔離是由安全群組和 VPC 設定所控制。
```
"links": ["name:internalName", ...]
```
`hostname`
類型：字串
必要：否
您容器要使用的主機名稱。此參數會映射至 docker create-container 中的 `Hostname`，以及 docker run 的 `--hostname` 選項。
如果您使用 `awsvpc` 網路模式，則不支援 `hostname` 參數。
```
"hostname": "string"
```
`dnsServers`
類型：字串陣列
必要：否
提供給容器的 DNS 伺服器清單。
Windows 容器或使用 `awsvpc` 網路模式的任務不支援此參數。
```
"dnsServers": ["string", ...]
```
`dnsSearchDomains`
類型：字串陣列
必要：否
模式：^[a-zA-Z0-9-.]\$10,253\$1[a-zA-Z0-9]\$1
提供給容器的 DNS 搜尋網域清單。此參數會映射至 docker create-container 命令中的 `DnsSearch`，以及 docker run 的 `--dns-search` 選項。
Windows 容器或使用 `awsvpc` 網路模式的任務不支援此參數。
```
"dnsSearchDomains": ["string", ...]
```
`extraHosts`
類型：物件陣列
必要：否
要附加到容器上 `/etc/hosts` 檔案的主機名稱和 IP 地址映射清單。
此參數會映射至 docker create-container 命令中的 `ExtraHosts`，以及 docker run 的 `--add-host` 選項。
Windows 容器或使用 `awsvpc` 網路模式的任務不支援此參數。
```
"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`
類型：物件陣列
必要：否
容器中資料磁碟區的掛載點。此參數會映射至 Docker API 中 create-container 的 `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 常駐程式可用的日誌驅動程式子集。
+ 在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。
+ 在容器執行個體上執行的 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`。
在您嘗試使用 `awslogs-create-group` 之前，您的 IAM 政策必須包含 `logs:CreateLogGroup` 許可。
`awslogs-region`
必要：是
指定 AWS 區域 `awslogs`日誌驅動程式要傳送 Docker 日誌的 。您可以選擇將所有的日誌從不同區域中的叢集傳送至 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 主控台時，讓日誌顯示在 Log (日誌) 窗格中。
`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` 選項設定的記憶體內中間緩衝區中。這可以防止當無法傳送日誌時應用程式發生無回應的狀況。如果您想要確保服務的可用性且可以接受一些日誌遺失，我們建議您使用此模式。如需詳細資訊，請參閱 [Preventing log loss with non-blocking mode in the `awslogs` container log driver](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 服務 或 AWS Partner Network 目的地以進行日誌儲存和分析時，您可以設定 `log-driver-buffer-limit`選項，以限制在記憶體中緩衝的日誌行數，然後再傳送至日誌路由器容器。由於高輸送量可能會導致 Docker 內部緩衝區的記憶體不足，因此這可協助解決潛在的日誌受損問題。如需詳細資訊，請參閱[為高輸送量設定 Amazon ECS 日誌](firelens-docker-buffer-limit.md)。
使用 `awsfirelens` 路由日誌時，可指定的其他選項取決於目的地。當您將日誌匯出至 Amazon Data Firehose 時，您可以使用 指定 AWS 區域 ，`region`並使用 指定日誌串流的名稱`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` 作為選項。
在您的容器執行個體上，此參數需要 1.19 版或更新版本的 Docker Remote API。
`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`。
您必須先將容器執行個體加入網域，才能啟動此任務定義的任何任務。
在這兩種格式中，以 SSM 或 Amazon S3 中的 ARN 替換 `MyARN`。
`credspec` 必須在 Secrets Manager 中提供 ARN，以取得包含使用者名稱、密碼和要連線之網域的秘密。為了提高安全性，執行個體不會加入網域以進行無網域驗證。執行個體上的其他應用程式無法使用無網域憑證。您可以使用此參數在相同的執行個體上執行任務，即使是任務需要加入不同的網域。如需詳細資訊，請參閱在[使用 Windows 容器的 gMSA](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/windows-gmsa.html) 和[使用 Linux 容器的 gMSA](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/linux-gmsa.html)。
`privileged`
類型：布林值
必要：否
此參數為 true 時，容器便會取得主機容器執行個體的更高權限 (類似 `root` 使用者)。建議不要使用 `privileged` 執行容器。在大多數情況下，可以使用特定參數，而不是使用 `privileged` 來指定所需的確切權限。
此參數會映射至 docker create-container 命令中的 `Privileged`，以及 docker run 的 `--privileged` 選項。
Windows 容器或使用 Fargate 啟動類型的任務不支援此參數。
預設值為 `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`
類型：字串陣列
有效值：「沒有新的權限」\$1「AppArmor：描述檔」\$1「標籤：*值*」\$1「憑證規格：*憑證規格路徑*」
必要：否
提供多個安全系統自訂組態的字串清單。
對於 Linux 任務，此參數可用於引用 SELinux 與 AppArmor 多層級安全系統的自訂標籤。
此參數可在設定 Active Directory 身分驗證的容器時用於引用憑證規格檔案。如需詳細資訊，請參閱[了解如何在 Amazon ECS 上為 EC2 Windows 容器使用 gMSA](windows-gmsa.md)及[在 Amazon ECS 上為 EC2 Linux 容器使用 gMSA](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) 物件
必要：否
從 Docker 提供的預設組態中新增或卸除的容器 Linux 功能。如需這些 Linux 功能的詳細資訊，請參閱 Linux 手冊頁面的[功能 (7)](http://man7.org/linux/man-pages/man7/capabilities.7.html)。
`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"`
必要：否
要新增至 Docker 提供之預設組態容器的 Linux 功能。此參數會映射至 docker create-container 命令中的 `CapAdd`，以及 docker run 的 `--cap-add` 選項。
`add`
類型：字串陣列
有效值：`"SYS_PTRACE"`
必要：否
要新增至 Docker 提供之預設組態容器的 Linux 功能。此參數會映射至 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"`
必要：否
要從 Docker 提供之預設組態中移除容器的 Linux 功能。此參數會映射至 docker create-container 命令中的 `CapDrop`，以及 docker run 的 `--cap-drop` 選項。
`devices`
任何要公開給容器的主機裝置。此參數會映射至 docker create-container 命令中的 `Devices`，以及 docker run 的 `--device` 選項。
類型：[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` 選項。
在您的容器執行個體上，此參數需要 1.25 版或更新版本的 Docker Remote API。
`maxSwap`
容器可以使用的交換記憶體總量 (以 MiB 為單位)。此參數將會轉換為 docker run 的 `--memory-swap` 選項，其中值是容器記憶體與 `maxSwap` 值的總和。
如果將 `maxSwap` 值指定為 `0`，容器不會使用交換。接受的值為 `0` 或任何正整數。如果省略 `maxSwap` 參數，容器使用其執行所在的容器執行個體的交換組態。必須設定 `maxSwap` 值，才能使用 `swappiness` 參數。
`sharedMemorySize`
`/dev/shm` 磁碟區的大小值 (以 MiB 為單位)。此參數會對應 docker run 的 `--shm-size` 選項。
類型：整數
`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` 對達到 `COMPLETE`、`SUCCESS` 或 `HEALTHY` 狀態的 `containerB` 有相依性。如果為 `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` 設定以維持壽命較長的連線。
不建議您指定單一任務中多個容器的網路相關 `systemControls` 參數，而單一任務也使用 `awsvpc` 或 `host` 網路模式。執行此操作的缺點如下：
+ 對於使用 `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`
類型：字串
必要：是
彈性推論加速器裝置名稱。`deviceName` 也必須在容器定義中參照，請參閱 [Elastic Inference accelerator](task_definition_parameters.md#ContainerDefinition-elastic-inference)。
`deviceType`
類型：字串
必要：是
要使用的彈性推論加速器。
## 任務置放限制條件
當您註冊任務定義時，您可以提供任務置放限制，自訂 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` - (必要) `user` 參數在容器定義中定義之代理容器的使用者 ID (UID)。這是用於確保代理忽略自己的流量。如果指定了 `IgnoredGID`，這個欄位可以為空白。
+ `IgnoredGID` - (必要) `user` 參數在容器定義中定義之代理容器的群組 ID (GID)。這是用於確保代理忽略自己的流量。如果指定了 `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)。
+ FSx for Windows File Server 磁碟區 — 提供全受管 Microsoft Windows 檔案伺服器。這些檔案伺服器由 Windows 檔案系統支援。搭配使用 FSx for Windows File Server 與 Amazon ECS 時，您可以使用持續、分散、共用、靜態的檔案儲存來佈建 Windows 任務。如需詳細資訊，請參閱[搭配 Amazon ECS 使用 FSx for Windows File Server 磁碟區](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 執行個體上的指定位置，直到您手動將其刪除為止。如果 `sourcePath` 值不存在於主機 Amazon EC2 執行個體，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 中「Create a volume」區段的 `DriverOpts`。
`labels`
類型：字串
必要：否
自訂中繼資料，新增到您的 Docker 磁碟區。
`efsVolumeConfiguration`
類型：[EFSVolumeConfiguration](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_EFSVolumeConfiguration.html) 物件
必要：否
只有使用 Amazon EFS 磁碟區時才會指定此參數。
`fileSystemId`
類型：字串
必要：是
要使用的 Amazon EFS 檔案系統識別碼。
`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 使用者指南》**中的 [EFS 掛載協助程式](https://docs.aws.amazon.com/efs/latest/ug/efs-mount-helper.html)。
`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 ECS 檔案系統時，指定是否使用任務定義中定義的 Amazon EFS 任務 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) 物件
必要：是
此參數在您為任務儲存使用 [Amazon FSx for Windows File Server](https://docs.aws.amazon.com/fsx/latest/WindowsGuide/what-is.html) 檔案系統時指定。
`fileSystemId`
類型：字串
必要：是
要使用的 FSx for Windows File Server 檔案系統 ID。
`rootDirectory`
類型：字串
必要：是
FSx for Windows File Server 檔案系統中的目錄，其將掛載做為主機內的根目錄。
`authorizationConfig`
`credentialsParameter`
類型：字串
必要：是
授權憑證選項。
**選項：**
+ [AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) 秘密的 Amazon Resource Name (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 託管的完整網域名稱。
## Tags (標籤)
當您註冊任務定義時，您可以選擇性地指定套用至任務定義的中繼資料標籤。標籤可協助您分類和組織您的任務定義。每個標籤皆包含索引鍵與選用值。您可以兩個都定義。如需詳細資訊，請參閱[標記 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 模式的任務，不支援與 `systemControls` 相關的 IPC 命名空間。
+ 針對使用 `task` IPC 模式的任務，IPC 命名空間相關的 `systemControls` 套用到任務內的所有容器。
### PID 模式
`pidMode`
類型：字串
有效值: `host` \$1 `task`
必要：否
要用於任務中容器的程序命名空間。有效值為 `host` 或 `task`。例如，監控附屬可能需要 `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**
+ [Web 伺服器](#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)
## Web 伺服器
以下是使用 Fargate 上 Linux 容器並設定 Web 伺服器的任務定義範例：
```
{
"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"
]
}
```
以下是使用 Fargate 上 Windows 容器並設定 Web 伺服器的任務定義範例：
```
{
"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` 日誌驅動程式，將日誌傳送到執行 Logstash (以 Gelf 日誌做為輸入) 的遠端主機。如需詳細資訊，請參閱[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 角色
以下程式碼片段使用稱為 `aws-nodejs-sample` 的 Amazon ECR 映像，具有來自 `123456789012.dkr.ecr.us-west-2.amazonaws.com` 登錄檔的 `v1` 標籤。此任務中的容器會繼承 `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 容器語法。此容器 ping `example.com` 四次，然後結束。
```
{
"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)。
+ 如需有關如何設定 FSx for Windows File Server 磁碟區的資訊，請參閱[了解如何為 Amazon ECS 設定 FSx for Windows File Server 檔案系統](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"
}
```