本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 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`。