任務定義參數 - Amazon Elastic Container Service
系列啟動類型任務角色任務執行角色網路模式執行時間平台任務大小容器定義Elastic Inference 加速器名稱任務置放限制條件代理組態磁碟區標籤其他任務定義參數

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

任務定義參數

任務定義分為單獨的部分：任務系列、 AWS Identity and Access Management (IAM) 任務角色、網路模式、容器定義、磁碟區、任務放置限制和啟動類型。任務定義中需要系列和容器定義。相對的，任務角色、網路模式、磁碟區、任務置放限制及啟動類型則為選用的。

您可以在 JSON 檔案中使用這些參數來設定任務定義。如需詳細資訊，請參閱 記錄選項任務定義範例。

以下是每個任務定義參數更詳細的描述。

系列

family

類型：字串

必要：是

當您註冊任務定義時，您會指定它的系列，這類似於任務定義以修訂版號碼指定的多個版本名稱。在特定系列註冊的第一個任務定義會得到修訂版 1，之後註冊的任何任務定義，則得到連續的修訂版號碼。

啟動類型

當您註冊任務定義時，您可以指定 Amazon ECS 驗證任務定義所依據的啟動類型。如果任務定義不會依據指定的相容性進行驗證，則會傳回用戶端例外狀況。如需詳細資訊，請參閱 Amazon ECS 啟動類型。

任務定義允許使用以下參數。

requiresCompatibilities

類型：字串陣列

必要：否

有效值: EC2 | FARGATE | EXTERNAL

驗證任務定義所依據的啟動類型。這會啟動檢查，以確保任務定義中使用的所有參數都能滿足啟動類型的要求。

任務角色

taskRoleArn

類型：字串

必要：否

當您註冊任務定義時，您可以為 IAM 角色提供任務角色，該角色可讓任務許可中的容器，代您呼叫其關聯政策中指定的 AWS API。如需詳細資訊，請參閱 任務 IAM 角色。

在您啟動 Amazon ECS 最佳化 Windows Server AMI 時，Windows 上任務的 IAM 角色要求設定 -EnableTaskIAMRole 選項。您的容器還必須執行一些組態程式碼，以使用此功能。如需詳細資訊，請參閱 任務 Windows IAM 角色的其他組態。

任務執行角色

executionRoleArn

類型：字串

必要：有條件

任務執行角色的 Amazon 資源名稱 (ARN)，可授與 Amazon ECS 容器代理程式的權限，以代表您進行 AWS API 呼叫。

注意

視任務需求而定，任務執行 IAM 角色是必要的項目。如需詳細資訊，請參閱 Amazon ECS 任務執行 IAM 角色。

網路模式

networkMode

類型：字串

必要：否

任務中的容器所使用的 Docker 聯網模式。對於在 Amazon EC2 Linux 執行個體上託管的 Amazon ECS 任務，有效值為 none、bridge、awsvpc 以及 host。如果未指定網路模式，預設網路模式為 bridge。對於在 Amazon EC2 Windows 執行個體上託管的 Amazon ECS 任務，有效值為 default 和 awsvpc。如果未指定網路模式，會使用 default 網路模式。對於在 Fargate 上託管的 Amazon ECS 任務，需要使用awsvpc網路模式。

如果網路模式設為 none，任務的容器即沒有外部連線，並且無法在容器定義中指定連接埠映射。

如果網路模式為 bridge，任務會使用 Linux 上的 Docker 內建虛擬網路，該虛擬網路會在託管任務的每個 Amazon EC2 執行個體內執行。Linux 上的內建虛擬網路會使用 bridge Docker 網路驅動程式。

如果網路模式為 host，任務會使用主機網路，並直接將容器連接埠映射至託管任務的 Amazon EC2 執行個體 ENI，以略過 Docker 的內建虛擬網路。動態連接埠映射無法在此網路模式下使用。任務定義中使用此模式的容器必須指定特定 hostPort 數字。主機上的連接埠號碼無法由多個任務使用。因此，您無法在單一 Amazon EC2 執行個體上執行同一個任務定義的多個任務。

重要

執行使用 host 網路模式的任務時，為了獲得更好的安全性，不要使用根使用者 (UID 0) 執行容器。作為最佳安全實務，請一律使用非根使用者。

對於 Amazon EC2 啟動類型，如果網路模式為awsvpc，則會將任務分配一個 elastic network interface，您必須在建立服務或使用任務定義執行任務NetworkConfiguration時指定一個。如需詳細資訊，請參閱 Amazon EC2 執行個體上任務的任務聯網。

如果網路模式為 default，任務會使用 Windows 上的 Docker 內建虛擬網路，該虛擬網路會在託管任務的每個 Amazon EC2 執行個體內執行。Windows 上的內建虛擬網路會使用 nat Docker 網路驅動程式。

對於 Fargate 啟動類型，當網路模式為時awsvpc，工作會配置 elastic network interface，而且您必須在建立服務或使用工作定義執行工作NetworkConfiguration時指定一個。如需詳細資訊，請參閱 Fargate 工作網路。awsvpc 網路模式為容器提供最高聯網效能，因為它們使用的是 Amazon EC2 網路堆疊。公開的容器連接埠會直接映射至連接的彈性網路介面連接埠。因此，您無法使用動態主機連接埠對應。

host 和 awsvpc 網路模式為容器提供最高聯網效能，因為它們使用的是 Amazon EC2 網路堆疊。使用 host 和 awsvpc 網路模式，公開的容器連接埠會直接映射到對應的主機連接埠 (適用於 host 網路模式) 或已連接的彈性網路介面連接埠 (適用於 awsvpc 網路模式)。因此，您無法使用動態主機連接埠對應。

如果使用 Fargate 啟動類型，則需要 awsvpc 網路模式。如果使用 EC2 啟動類型，允許的網路模式取決於基礎 EC2 執行個體的作業系統。如果是 Linux，則可以使用任何網路模式。如果是 Windows，則會使用 default 和 awsvpc 模式。

執行時間平台

operatingSystemFamily

類型：字串

必要：有條件

預設：LINUX

在 Fargate 上託管的 Amazon ECS 任務需要此參數。

在註冊任務定義時，您會指定作業系統系列。

在 Fargate 上託管的 Amazon ECS 任務的有效值為 LINUX、WINDOWS_SERVER_2019_FULL、WINDOWS_SERVER_2019_CORE、WINDOWS_SERVER_2022_FULL 和 WINDOWS_SERVER_2022_CORE 。

在 EC2 上託管的 Amazon ECS 任務的有效值為 LINUX、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

類型：字串

必要：有條件

預設：X86_64

在 Fargate 上託管的 Amazon ECS 任務需要此參數。如果參數保留為 null，則會在 Fargate 上託管的任務啟動時自動指派預設值。

在註冊任務定義時，您會指定 CPU 架構。有效值為 X86_64 和 ARM64。

服務中使用的所有任務定義都必須與此參數具有相同的值。

若您具有 Fargate 啟動類型或 EC2 啟動類型的 Linux 任務，則可將值設定為 ARM64。如需詳細資訊，請參閱 在 Amazon ECS 上使用 64 位元 ARM 工作負載。

任務大小

當您註冊任務定義時，您可以指定任務使用的 CPU 和記憶體總計。這和容器定義層級的 cpu 和 memory 值是分開的。對於在 Amazon EC2 執行個體上託管的任務，這些欄位是選用欄位。對於在 Fargate (Linux 和 Windows 皆可) 上託管的任務，這些欄位為必填欄位，而且受支援的 cpu 和 memory 具有特定值。

注意

Windows 容器會忽略任務層級的 CPU 和記憶體參數。我們建議為 Windows 容器指定容器層級的資源。

任務定義允許使用以下參數：

cpu

類型：字串

必要：有條件

注意

Windows 容器不支援此參數。

針對任務呈現的 CPU 單位硬性限制。它可以使用 CPU 單位 (例如1024) 或在工作定義中使用 vCPUs (例如，1 vCPU或1 vcpu) 來表示。註冊任務定義時，vCPU 值會轉換為整數，指出 CPU 單位。

對於在 EC2 或外部執行個體上執行的任務，此欄位是選用欄位。如果您的叢集沒有任何一個已註冊的容器執行個體具有可用的請求 CPU 單位，則任務會失敗。在 EC2 或外部執行個體上執行的任務支援值介於 0.125 vCPU 和 10 vCPU 之間。

對於在 Fargate 上 (Linux 和 Windows 容器皆可) 執行的任務，此欄位為必填欄位，而且您必須使用下列其中一個值，以決定 memory 參數的受支援值範圍。下表顯示有效的任務層級 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
memory

類型：字串

必要：有條件

注意

Windows 容器不支援此參數。

針對任務呈現的記憶體硬性限制 (MiB)。它可以使用 MiB (例如1024) 或在任務定義中使用 GB (例如1GB或1 GB) 來表示。註冊任務定義時，GB 值會轉換為整數，指出 MiB。

對於在 Amazon EC2 執行個體上託管的任務，此欄位為選用欄位，可使用任意值。如果指定任務層級的記憶體值，則容器層級的記憶體值是選用的。如果您的叢集沒有任何一個已註冊的容器執行個體具有可用的請求記憶體，則任務會失敗。您可以盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化。如需詳細資訊，請參閱 容器實例內存管理。

對於在 Fargate 上 (Linux 和 Windows 皆可) 託管的任務，此欄位為必填欄位，而且您必須使用下列其中一個值，以決定 cpu 參數的受支援值的範圍：

記憶體值 (單位為 MiB，以 GB 為單位的近似等值)

CPU 數值

Fargate 支援的作業系統

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

256 (.25 vCPU)

Linux

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

512 (.5 vCPU)

Linux

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

1024 (1 vCPU)

Linux、Windows

介於 4096 (4 GB) 與 16384 (16 GB) 之間，以 1024 (1 GB) 為單位遞增

2048 (2 vCPU)

Linux、Windows

介於 8192 (8 GB) 與 30720 (30 GB) 之間，以 1024 (1 GB) 為單位遞增

4096 (4 vCPU)

Linux、Windows

介於 16 GB 與 60 GB 之間，以 4 GB 為單位遞增

注意

此選項需要 Linux 平台 1.4.0 或更新版本。

8192 (8 vCPU)

Linux

介於 32 GB 與 120 GB 之間，以 8 GB 為單位遞增

注意

此選項需要 Linux 平台 1.4.0 或更新版本。

16384 (16vCPU)

Linux

容器定義

註冊任務定義時，您必須指定容器定義清單，以傳遞到容器執行個體上的 Docker 常駐程式。容器定義允許使用以下參數。

標準容器定義參數

下列任務定義參數為必要參數，或是會在大部分的容器定義中使用。

名稱

name

類型：字串

必要：否

容器的名稱。可以包含最多可達 255 個字元 (大小寫)、數字、連字號和底線。如果您在任務定義中連結多個容器，則一個容器的 name 可以輸入另一個容器的 links。這是為了連結容器。

映像

image

類型：字串

必要：否

用來啟動容器的映像。此字串會直接傳遞至 Docker 常駐程式。根據預設，Docker Hub 登錄檔中的映像為可用。您也可以使用 repository-url/image:tag 或 repository-url/image@digest 指定其他存放庫。允許最多 255 個字元 (大小寫)、數字、連字號、底線、等號、句號、正斜線、井號。此參數會映射至 Docker Remote API 的建立容器區段中的 Image 以及 docker run 的 IMAGE 參數。

  • 當新的任務啟動時，Amazon ECS 容器代理會提取最新版本的指定映像和標籤，以供容器使用。但是，儲存庫映像後續的更新將不會散佈到已在執行中的任務。

  • 支援私有登錄檔中的映像。如需詳細資訊，請參閱 任務的私有登錄檔身分驗證。

  • 可使用完整的 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)。

記憶體

memory

類型：整數

必要：否

提供給容器使用的記憶體數量 (MiB)。如果您的容器嘗試使用超過此處指定的記憶體，容器便會終止。為任務中所有容器預留的記憶體總量必須低於任務 memory 值 (如果已指定一個)。此參數會映射到 Docker Remote API 的建立容器區段中的 Memory 以及 docker run 的 --memory 選項。

如果使用 Fargate 啟動類型，這是選用參數。

如果使用 EC2 啟動類型，您必須指定任務層級的記憶體值或容器層級的記憶體值。如果您同時指定容器層級的 memory 和 memoryReservation 值,則 memory 值必須大於 memoryReservation 值。如果指定 memoryReservation，則會從放置容器的容器執行個體可用記憶體資源中減去該值。否則，即使用 memory 的值。

Docker 20.10.0 或更新版本的常駐程式會為容器保留最低 6 MiB 的記憶體。因此，不要為容器指定少於 6 MiB 的記憶體。

Docker 19.03.13-ce 或更舊版本的常駐程式會為容器保留最低 4 MiB 的記憶體。因此，不要為容器指定少於 4 MiB 的記憶體。

注意

若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「容器實例內存管理」。

memoryReservation

類型：整數

必要：否

為容器保留的記憶體軟性限制 (MiB)。當系統記憶體爭用時，Docker 會嘗試將容器記憶體保持在此軟性限制。但是，您的容器可以在需要時使用更多記憶體。容器可以使用最多達到以 memory 參數指定的硬性限制 (如適用)，或容器執行個體上的所有可用記憶體，以先達到者為準。此參數會映射到 Docker Remote API 的建立容器區段中的 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 的記憶體。

注意

若您嘗試盡可能為特定執行個體類型的任務提供最多的記憶體，以將資源使用率最大化，請參閱「容器實例內存管理」。

連接埠映射

portMappings

類型：物件陣列

必要：否

連接埠映射可讓容器存取主機容器執行個體上的連接埠，以傳送或接收流量。

針對使用 awsvpc 網路模式的任務定義，只指定 containerPort。hostPort 可維持空白，或其值必須與 containerPort 相同。

Windows 上的連接埠映射會使用 NetNAT 閘道地址，而非 localhost。Windows 沒有連接埠映射回送，所以您無法從主機本身存取容器的映射連接埠。

此參數的大部分欄位 (containerPort、hostPort、protocol) 會映射到 Docker Remote API 的建立容器區段中的 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。

有效的通訊協定值："HTTP" | "HTTP2" | "GRPC"

containerPort

類型：整數

必要：是 (當使用 portMappings 時)

容器上的連接埠號碼，該號碼繫結到使用者指定或自動指派的主機連接埠。

如果在使用 Fargate 啟動類型的任務中使用容器，則必須使用 containerPort 來指定公開連接埠。

對於 Fargate 上的 Windows 容器，您不得將連接埠 3150 用於 containerPort。這是因為其已保留。

假設您在 EC2 啟動類型的任務中使用容器，並且指定容器連接埠而非主機連接埠。然後，您的容器會自動在暫時性連接埠範圍中接收到主機連接埠。如需詳細資訊，請參閱 hostPort。使用此方式自動指派的連接埠映射不包含在容器執行個體 100 個保留連接埠的配限制中。

containerPortRange

類型：字串

必要：否

綁定到動態映射主機連接埠範圍之容器上的連接埠號碼範圍。

您只能使用 register-task-definition API 來設定此參數。此選項可在 portMappings 參數中使用。如需詳細資訊，請參閱 AWS Command Line Interface 參考中的「register-task-definition」。

指定 containerPortRange 時，以下規則適用：

  • 您必須使用 bridge 網路模式或 awsvpc 網路模式。

  • 此參數適用於 EC2 和 AWS Fargate 啟動類型。

  • 此參數適用於 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 代理。

    如需詳細資訊，請參閱上的問題 #11185 GitHub。

    如需有關如何在 Docker 常駐程式組態檔案中關閉 Docker 代理的詳細資訊，請參閱《Amazon ECS 開發人員指南》中的 Docker 常駐程式。

您可以呼叫 DescribeTasks 來檢視 hostPortRange，此即綁定到容器連接埠的主機連接埠。

傳送到 EventBridge的 Amazon ECS 任務事件中不包含連接埠範圍。如需詳細資訊，請參閱 使用以下方式自動回應 Amazon ECS 錯誤 EventBridge。

hostPortRange

類型：字串

必要：否

與網路繫結搭配使用之主機上的連接埠號碼範圍。這由 Docker 指派，並由 Amazon ECS 代理程式交付。

hostPort

類型：整數

必要：否

要為您的容器保留之容器執行個體上的連接埠號碼。

如果在使用 Fargate 啟動類型的任務中使用容器，hostPort 可維持空白，或其值與 containerPort 相同。

假設您在 EC2 啟動類型的任務中使用容器。您可以為容器連接埠對應指定非保留的主機連接埠。這稱為靜態主機連接埠對應。或者，您可以在指定 containerPort 時省略 hostPort (或將其設定為 0)。您的容器會針對您的容器執行個體作業系統和 Docker 版本，自動接收暫時性連接埠範圍內的連接埠。這稱為動態主機連接埠對應。

Docker 1.6.0 版和更新版本的預設暫時性連接埠範圍列在 /proc/sys/net/ipv4/ip_local_port_range 下的執行個體上。如果此核心參數不可用，會使用預設的 49153–65535 暫時性連接埠範圍。請勿嘗試在暫時性連接埠範圍中指定主機連接埠。這是因為其已保留以便自動指派。一般而言，低於 32768 的連接埠便會位於暫時性連接埠範圍之外。

SSH 的預設保留連接埠為 22，Docker 連接埠為 2375 和 2376，Amazon ECS 容器代理程式連接埠則為 51678-51680。任何使用者先前為執行中任務指定的主機連接埠也會在執行任務時保留。在任務停止後，便會釋放主機連接埠。目前預留的連接埠會顯示在 describe-container-instances 輸出的 remainingResources 中。容器執行個體一次最多可預留 100 個連接埠，包括預設的預留連接埠。自動指派的連接埠不計入 100 個預留連接埠的限制。

name

類型：字串

必要：否，需要在服務中設定 Service Connect

用於連接埠映射的名稱。此參數僅適用於 Service Connect。此參數是您在服務的 Service Connect 組態中使用的名稱。

如需詳細資訊，請參閱 Service Connect。

下列範例中使用了 Service Connect 的兩個必要欄位。


"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 容器代理程式」。

若您指定主機連接埠，請使用以下語法。

"portMappings": [
    {
        "containerPort": integer,
        "hostPort": integer
    }
    ...
]

若您希望取得自動指派的主機連接埠，請使用以下語法。

"portMappings": [
    {
        "containerPort": integer
    }
    ...
]

私有儲存庫憑證

repositoryCredentials

類型：RepositoryCredentials 物件

必要：否

私有登錄檔身分驗證的儲存庫登入資料。

如需詳細資訊，請參閱 任務的私有登錄檔身分驗證。

credentialsParameter

類型：字串

必要：是 (當使用 repositoryCredentials 時)

包含私有儲存庫憑證密碼的 Amazon Resource Name (ARN)。

如需詳細資訊，請參閱 任務的私有登錄檔身分驗證。

注意

當您使用 Amazon ECS API 或 AWS 軟體開發套件時，如果密碼與您正在啟動的任務位於相同的區域中，則您可以使用完整 ARN 或機密名稱。 AWS CLI使用時 AWS Management Console，您必須指定密碼的完整 ARN。

以下是任務定義的程式碼片段，其會顯示所需的參數：


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

進階容器定義參數

以下進階容器定義參數會為用於在 Amazon ECS 容器執行個體上啟動容器的 docker run 命令提供延伸功能。

運作狀態檢查

healthCheck

用於容器的容器運作狀態檢查命令和相關的設定參數。如需詳細資訊，請參閱 使用容器運作狀態檢查判斷 Amazon ECS 任務運作狀態。

command

表示容器執行的命令的字串陣列，用於確定運作狀態是否良好。此字串陣列的開頭可以是 CMD，如此能直接執行命令引數；或是 CMD-SHELL，藉以使用容器預設的 shell 來執行命令。如果均尚未指定，則使用 CMD。

在中註冊工作定義時 AWS Management Console，請使用逗號分隔的指令清單。這些命令會在建立任務定義後轉換為字串。以下為運作狀態檢查的範例輸入。

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

使用 AWS Management Console JSON 面板、或 API 註冊工作定義時 AWS CLI，請將命令清單括在括弧中。以下為運作狀態檢查的範例輸入。

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

結束代碼 0 (沒有 stderr 輸出) 表示成功，而任何非零的結束代碼則表示失敗。如需詳細資訊，請參閱 Docker Remote API 建立容器區段中的 HealthCheck。

interval

每個運作狀態檢查的時間間隔 (以秒為單位)。您可以指定 5 至 300 秒之間的值。預設 值為 30 秒。

timeout

判定為失敗之前，等待運作狀態檢查成功執行的時間 (以秒為單位)。您可以指定 2 至 60 秒之間的值。預設值為 5 秒。

retries

容器運作狀態判定為不良之前，重試失敗的運作狀態檢查的次數上限。您可以指定 1 至 10 次嘗試。預設值為重試三次。

startPeriod

選用的寬限期，讓容器有時間引導，不將失敗的運作狀態檢查計入重試次數上限。您可以指定 0 至 300 秒之間的值。預設情況下，startPeriod 是停用的。

Environment

cpu

類型：整數

必要：否

Amazon ECS 容器代理程式保留給容器的 cpu 數量。在 Linux 上，此參數會映射到 Docker Remote API 的建立容器區段中的 CpuShares 以及 docker run 的 --cpu-shares 選項。

針對使用 Fargate 啟動類型的任務，此欄位為選用。為任務中所有容器預訂的 CPU 總量必須低於任務階層的 cpu 值。

注意

您可以決定每個 Amazon EC2 執行個體類型可用的 CPU 單位數。若要執行此操作，請將 Amazon EC2 執行個體詳細資訊頁面上為執行個體類型列出的 vCPU 數乘上 1,024。

Linux 容器會按照與其配置數量相同的比例，與容器執行個體上的其他容器共用未配置的 CPU 單位。例如，若您在單一核心執行個體類型上執行單一容器任務，為該容器指定 512 個 CPU 單位。此外，該任務是在容器執行個體上運行的唯一任務。在此範例中，該容器便可在任何指定的時間內使用完整 1,024 個 CPU 單位。但是，假設您在該容器執行個體上啟動相同任務的另一個複本。每個任務都可以保證在需要的時候取得最少 512 個 CPU 單位。同樣，如果其他容器沒有使用剩餘的 CPU，每個容器都可以浮動到更高的 CPU 用量。但若兩個任務都一直維持在 100% 作用中的狀態，兩者能夠取得的單位數便會限制在 512 個 CPU 單位。

在 Linux 容器執行個體上，容器執行個體的 Docker 常駐程式會使用 CPU 值計算執行中容器的相對 CPU 共用比例。如需詳細資訊，請參閱 Docker 文件中的 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、零和值為一的 CPU 值會以兩個 CPU 共享傳遞給 Docker。

在 Windows 容器執行個體上，CPU 配額會強制為絕對配額。Windows 容器只能存取任務定義中定義的指定 CPU 數量。Null 或零的 CPU 值會以 0 形式傳遞給 Docker。然後 Windows 將此值解讀為一個 CPU 的 1%。

如需其他範例，請參閱 Amazon ECS 如何管理 CPU 和記憶體資源。

gpu

類型：ResourceRequirement 物件

必要：否

Amazon ECS 容器代理程式保留給容器的實體 GPUs 數量。為任務中所有容器保留的 GPU 數量不得超過任務啟動所在之容器執行個體上可用的 GPU 數量。如需詳細資訊，請參閱 在 Amazon ECS 上使用 GPU。

注意

Windows 容器或在 Fargate 上託管的容器不支援此參數。

Elastic Inference accelerator

類型：ResourceRequirement 物件

必要：否

對於 InferenceAccelerator 類型，value 符合任務定義中指定之 InferenceAccelerator 的 deviceName。如需詳細資訊，請參閱 Elastic Inference 加速器名稱。

注意

自 2023 年 4 月 15 日起，不 AWS 會將新客戶加入 Amazon Elastic Inference (EI)，並協助目前客戶將工作負載遷移到提供更優惠價格和效能的選項。2023 年 4 月 15 日之後，新客戶將無法在 Amazon、Amazon ECS 或 Amazon Amazon EC2 使用亞馬遜 SageMaker EI 加速器啟動執行個體。但是，在過去 30 天內至少使用過一次 Amazon EI 的客戶將被視為目前客戶，並且可以繼續使用該服務。

注意

Windows 容器或在 Fargate 上託管的容器不支援此參數。

essential

類型：布林值

必要：否

假設容器的 essential 參數標記為 true，並且該容器因為任何理由失敗或停止。然後，會停止屬於該任務一部分的所有其他容器。若容器的 essential 參數標記為 false，則其失敗將不會影響任務中其餘的容器。若省略此參數，則容器會假設為「基本」。

所有任務都必須至少有一個基本容器。假設您有一個由多個容器組成的應用程式。然後，將用於一般用途的容器分組為元件，並把不同的元件分到多個任務定義。如需詳細資訊，請參閱 架構您的應用程式。

"essential": true|false
entryPoint
重要

舊版的 Amazon ECS 容器代理程式無法正確處理 entryPoint 參數。若您在使用 entryPoint 時發生任何問題，請更新您的容器代理，或改將您的命令和引數作為 command 陣列項目輸入。

類型：字串陣列

必要：否

傳遞至容器的進入點。此參數會映射到 Docker Remote API 的建立容器區段中的 Entrypoint 以及 docker run 的 --entrypoint 選項。如需 Docker ENTRYPOINT 參數的詳細資訊，請參閱 https://docs.docker.com/engine/reference/builder/#entrypoint。

"entryPoint": ["string", ...]
command

類型：字串陣列

必要：否

傳遞至容器的命令。此參數會映射至 Docker Remote API 的建立容器區段中的 Cmd 以及 docker run 的 COMMAND 參數。如需 Docker CMD 參數的詳細資訊，請參閱 https://docs.docker.com/engine/reference/builder/#cmd。如果有多個引數，確保每個引數在陣列中是分開的字串。

"command": ["string", ...]
workingDirectory

類型：字串

必要：否

容器內要執行命令的工作目錄。此參數會映射到 Docker Remote API 的建立容器區段中的 WorkingDir 以及 docker run 的 --workdir 選項。

"workingDirectory": "string"
environmentFiles

類型：物件陣列

必要：否

內含要傳遞至容器之環境變數的檔案清單。此參數會映射到 docker run 的 --env-file 選項。

這不適用於 Windows 容器。

您最多可以指定 10 個環境檔案。檔案副檔名必須是 .env。環境檔案中的每一行都包含 VARIABLE=VALUE 格式的環境變數。以 # 開頭的行會被視為註解，而忽略。如需適合的環境變數檔案語法的詳細資訊，請參閱《在檔案中宣告預設環境變數》。

如果在容器定義中指定了個別環境變數，它們的優先順序高於環境檔案中包含的變數。如果指定了內含相同變數的多個環境檔案，則處理順序為由上而下。建議您使用唯一的變數名稱。如需詳細資訊，請參閱 使用工作定義參數將環境變數傳遞至容器。

value

類型：字串

必要：是

包含環境變數檔案的 Amazon S3 物件的 Amazon Resource Name (ARN)。

type

類型：字串

必要：是

要使用的檔案類型。唯一支援的值為 s3。

environment

類型：物件陣列

必要：否

傳遞至容器的環境變數。此參數會映射到 Docker Remote API 的建立容器區段中的 Env 以及 docker run 的 --env 選項。

重要

不建議在敏感資訊 (例如登入資料) 使用純文字環境變數。

name

類型：字串

必要：是 (當使用 environment 時)

環境變數的名稱。

value

類型：字串

必要：是 (當使用 environment 時)

環境變數的值。

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

類型：物件陣列

必要：否

代表公開到容器之秘密的物件。如需詳細資訊，請參閱 將敏感資料傳遞至容器。

name

類型：字串

必要：是

要設定為容器上環境變數的值。

valueFrom

類型：字串

必要：是

公開給容器的秘密。支援的值可以是 AWS Secrets Manager 秘密的完整 Amazon 資源名稱 (ARN)，或參數存放區中參數的完整 ARN。 AWS Systems Manager

注意

如果系 Systems Manager 參數存放區參數與您正在啟動的工 AWS 區域 作相同，您可以使用完整 ARN 或密碼名稱。如果參數存在於不同區域，則必須指定完整 ARN。

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

Network settings (網路設定)

disableNetworking

類型：布林值

必要：否

當此參數為 true 時，聯網便會在容器中關閉。此參數會映射到 Docker Remote API 建立容器區段中的 NetworkDisabled。

注意

Windows 容器或使用 awsvpc 網路模式的任務不支援此參數。

預設值為 false。

"disableNetworking": true|false

類型：字串陣列

必要：否

link 參數可讓容器彼此通訊，而無需連接埠映射。只有在任務定義的網路模式設定為 bridge 時才支援此參數。name:internalName 建構模組與 Docker 連結中的 name:alias 類似。可以包含最多可達 255 個字元 (大小寫)、數字、連字號和底線。如需連結 Docker 容器的詳細資訊，請前往 https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/。此參數會映射到 Docker Remote API 的建立容器區段中的 Links 以及 docker run 的 --link 選項。

注意

Windows 容器或使用 awsvpc 網路模式的任務不支援此參數。

重要

在相同容器執行個體上配置的容器可和彼此通訊，而無需連結或主機連接埠映射。容器執行個體上的網路隔離是由安全群組和 VPC 設定所控制。

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

類型：字串

必要：否

您容器要使用的主機名稱。此參數會映射到 Docker Remote API 的建立容器區段中的 Hostname 以及 docker run 的 --hostname 選項。

注意

如果您使用 awsvpc 網路模式，則不支援 hostname 參數。

"hostname": "string"
dnsServers

類型：字串陣列

必要：否

提供給容器的 DNS 伺服器清單。此參數會映射到 Docker Remote API 的建立容器區段中的 Dns 以及 docker run 的 --dns 選項。

注意

Windows 容器或使用 awsvpc 網路模式的任務不支援此參數。

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

類型：字串陣列

必要：否

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

提供給容器的 DNS 搜尋網域清單。此參數會映射到 Docker Remote API 的建立容器區段中的 DnsSearch 以及 docker run 的 --dns-search 選項。

注意

Windows 容器或使用 awsvpc 網路模式的任務不支援此參數。

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

類型：物件陣列

必要：否

要附加到容器上 /etc/hosts 檔案的主機名稱和 IP 地址映射清單。

此參數會映射到 Docker Remote API 的建立容器區段中的 ExtraHosts 以及 docker run 的 --add-host 選項。

注意

Windows 容器或使用 awsvpc 網路模式的任務不支援此參數。

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

類型：字串

必要：是 (當使用 extraHosts 時)

要在 /etc/hosts 項目中使用的主機名稱。

ipAddress

類型：字串

必要：是 (當使用 extraHosts 時)

要在 /etc/hosts 項目中使用的 IP 地址。

儲存與記錄

readonlyRootFilesystem

類型：布林值

必要：否

此參數為 true 時，容器會取得根檔案系統的唯讀存取權。此參數會映射到 Docker Remote API 的建立容器區段中的 ReadonlyRootfs 以及 docker run 的 --read-only 選項。

注意

Windows 容器不支援此參數。

預設值為 false。

"readonlyRootFilesystem": true|false
mountPoints

類型：物件陣列

必要：否

容器中資料磁碟區的掛接點。此參數會映射到 Docker Remote API 的建立容器區段中的 Volumes 以及 docker run 的 --volume 選項。

Windows 容器可在 $env:ProgramData 所在的相同磁碟上掛載整個目錄。Windows 容器無法在不同的磁碟機上掛載目錄，而且無法跨磁碟機使用掛載點。

sourceVolume

類型：字串

必要：是 (當使用 mountPoints 時)

要掛載的磁碟區名稱。

containerPath

類型：字串

必要：是 (當使用 mountPoints 時)

要掛載磁碟區之容器中的路徑。

readOnly

類型：布林值

必要：否

如果此數值為 true，容器擁有磁碟區的唯讀存取權。如果此值為 false，則容器可寫入磁碟區。預設值為 false。

volumesFrom

類型：物件陣列

必要：否

要從其他容器掛載的資料磁碟區。此參數會映射到 Docker Remote API 的建立容器區段中的 VolumesFrom 以及 docker run 的 --volumes-from 選項。

sourceContainer

類型：字串

必要：是 (當使用 volumesFrom 時)

要從其中掛載磁碟區的容器名稱。

readOnly

類型：布林值

必要：否

如果此數值為 true，容器擁有磁碟區的唯讀存取權。如果此值為 false，則容器可寫入磁碟區。預設值為 false。

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

類型：LogConfiguration物件

必要：否

容器的日誌組態規格。

例如，使用日誌組態的任務定義，請參閱任務定義範例。

此參數會映射到 Docker Remote API 的建立容器區段中的 LogConfig 以及 docker run 的 --log-driver 選項。根據預設，容器會和 Docker 常駐程式使用一樣的日誌記錄驅動程式。不過，容器可以在容器定義中使用此參數指定日誌驅動程式，和 Docker 常駐程式使用不同的日誌驅動程式。若要讓容器使用不同的日誌驅動程式，必須在容器執行個體上適當設定日誌系統 (或在不同的日誌伺服器上使用遠端記錄選項)。如需支援的不同日誌驅動程式選項的詳細資訊，請參閱 Docker 文件中的 Configure logging drivers (設定日誌驅動程式)。

指定容器的日誌組態時，請考量下列事項：

  • Amazon ECS 支援 Docker 常駐程式可用的日誌驅動程式子集。未來的 Amazon ECS 容器代理程式版本可能會提供更多可用的其他日誌驅動程式。

  • 在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。

  • 對於使用 EC2 啟動類型的任務，在容器執行個體上執行的 Amazon ECS 容器代理程式，必須使用 ECS_AVAILABLE_LOGGING_DRIVERS 環境變數註冊在該執行個體上可用的日誌驅動程式，才能讓放置在該執行個體上的容器使用這些日誌組態選項。如需詳細資訊，請參閱 Amazon ECS 容器代理程式組態。

  • 對於使用 Fargate 啟動類型的任務，由於您無法存取託管任務的基礎設施，因此任何需要的額外軟體，都必須安裝在任務外部。例如，Fluentd 輸出彙整工具或要傳送 Gelf 日誌執行 Logstash 的遠端主機。

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

類型：字串

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

必要：是 (當使用 logConfiguration 時)

容器要使用的日誌驅動程式。根據預設，先前列出的有效值是 Amazon ECS 容器代理程式可用來通訊的日誌驅動程式。

針對使用 Fargate 啟動類型的任務，支援的日誌驅動程式為 awslogs、splunk 和 awsfirelens。

針對使用 EC2 啟動類型的任務，支援的日誌驅動程式為 awslogs、fluentd、gelf、json-file、journald、logentries、syslog、splunk 和 awsfirelens。

如需如何在工作定義中使用記awslogs錄驅動程式將容器記錄檔傳送至 CloudWatch 記錄的詳細資訊，請參閱使用 awslogs 日誌驅動程式。

如需使用 awsfirelens 日誌驅動程式的詳細資訊，請參閱自訂日誌路由。

注意

如果您有未列出的自訂驅動程式，您可以分叉提供的 Amazon ECS 容器代理程式專案， GitHub並對其進行自訂以搭配該驅動程式使用。我們鼓勵您為想要進行的變更提交提取請求。但是，我們目前不支援執行此軟體經修改的複本。

在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。

options

類型：字串到字串映射

必要：否

要傳送到日誌驅動程式的索引鍵/值映射組態選項。

當您使用 FireLens 將記錄路由傳送至記錄檔儲存和分析的 AWS Partner Network 目的地 AWS 服務 或目的地時，您可以設定log-driver-buffer-limit選項，以限制記憶體中緩衝的事件數目，然後再傳送至記錄路由器容器。由於高輸送量可能會導致 Docker 內部緩衝區的記憶體不足，因此這可協助解決潛在的日誌受損問題。如需詳細資訊，請參閱 Fluentd 緩衝區限制。

在您的容器執行個體上，此參數需要 1.19 版或更新版本的 Docker Remote API。

secretOptions

類型：物件陣列

必要：否

此物件代表要傳送至日誌組態的秘密。日誌組態中使用的秘密可能包括身分驗證權杖、憑證或加密金鑰。如需詳細資訊，請參閱 將敏感資料傳遞至容器。

name

類型：字串

必要：是

要設定為容器上環境變數的值。

valueFrom

類型：字串

必要：是

公開到容器日誌組態的秘密。

"logConfiguration": {
	"logDriver": "splunk",
	"options": {
		"splunk-url": "https://cloud.splunk.com:8080",
		"splunk-token": "...",
		"tag": "...",
		...
	},
	"secretOptions": [{
		"name": "splunk-token",
		"valueFrom": "/ecs/logconfig/splunkcred"
	}]
}
firelensConfiguration

類型：FirelensConfiguration物件

必要：否

容 FireLens 器的組態。這是用來指定及設定容器日誌的日誌路由器。如需詳細資訊，請參閱 使用自訂記錄路由。

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

類型：字串到字串映射

必要：否

設定日誌路由器時要使用的索引鍵/值映射選項。此欄位是選用欄位，可用於指定自訂組態檔案，或者將額外的中繼資料 (例如任務、任務定義、叢集和容器執行個體詳細資訊) 新增到日誌事件。如果已指定，則要使用的語法為 "options":{"enable-ecs-log-metadata":"true|false","config-file-type:"s3|file","config-file-value":"arn:aws:s3:::mybucket/fluent.conf|filepath"}。如需詳細資訊，請參閱 在作業定義中指定FireLens組態。

type

類型：字串

必要：是

要使用的日誌路由器。有效值為 fluentd 或 fluentbit。

安全

如需有關容器安全的詳細資訊，請參閱《Amazon ECS 最佳實務指南》中的任務和容器安全。

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 和使用 Linux 容器的 gMSA。

privileged

類型：布林值

必要：否

此參數為 true 時，容器便會取得主機容器執行個體的更高權限 (類似 root 使用者)。建議不要使用 privileged 執行容器。在大多數情況下，可以使用特定參數，而不是使用 privileged 來指定所需的確切權限。

此參數會映射到 Docker Remote API 的建立容器區段中的 Privileged 以及 docker run 的 --privileged 選項。

注意

Windows 容器或使用 Fargate 啟動類型的任務不支援此參數。

預設值為 false。

"privileged": true|false
user

類型：字串

必要：否

要在容器內使用的使用者。此參數會映射到 Docker Remote API 的建立容器區段中的 User 以及 docker run 的 --user 選項。

重要

執行使用 host 網路模式的任務時，不要使用根使用者 (UID 0) 執行容器。作為最佳安全實務，請一律使用非根使用者。

您可以使用下列格式指定 user。如果指定 UID 或 GID，您必須使用正整數指定它。

  • user

  • user:group

  • uid

  • uid:gid

  • user:gid

  • uid:group

注意

Windows 容器不支援此參數。

"user": "string"
dockerSecurityOptions

類型：字串陣列

有效值："no-new-privileges" |「裝置:設定檔」|「標籤:值」|「認證規格:」CredentialSpecFilePath

必要：否

提供多個安全系統自訂組態的字串清單。如需有效值的詳細資訊，請參閱 Docker 執行安全性組態。此欄位對使用 Fargate 啟動類型之任務中的容器無效。

對於 EC2 上的 Linux 任務，此參數可用於參考 SELinux 和 AppArmor 多層級安全系統的自訂標籤。

對於 EC2 上的任何任務，此參數可在設定 Active Directory 身分驗證的容器時，用於參考憑證規格檔案。如需詳細資訊，請參閱 在 Amazon EC2 上將 gMSAs 用於視窗容器 及 在 Amazon EC2 上使用gMSALinux容器。

此參數會映射到 Docker Remote API 的建立容器區段中的 SecurityOpt 以及 docker 的 --security-opt 選項。

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

在容器執行個體上執行的 Amazon ECS 容器代理程式必須先使用 ECS_SELINUX_CAPABLE=true 或 ECS_APPARMOR_CAPABLE=true 環境變數註冊，才能讓放置在該執行個體上的容器使用這些安全選項。如需詳細資訊，請參閱 Amazon ECS 容器代理程式組態。

資源限制

ulimits

類型：物件陣列

必要：否

要為容器定義的 ulimit 值清單。此值覆寫作業系統的預設資源配額設定。此參數會映射到 Docker Remote API 的建立容器區段中的 Ulimits 以及 docker run 的 --ulimit 選項。

在 Fargate 上託管的 Amazon ECS 任務會使用作業系統設定的預設資源限制值，但是 nofile 資源限制參數除外。nofile 資源限制會對容器可使用的開放檔案數量設限。在 Fargate 上，預設的 nofile 軟限制為 1024，硬限制為 65535。您可以將兩個限制的值設定為 1048576。如需詳細資訊，請參閱任務資源限制。

在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。

注意

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 類型的硬性限制。

softLimit

類型：整數

必要：是 (當使用 ulimits 時)

ulimit 類型的軟性限制。

Docker 標籤

dockerLabels

類型：字串到字串映射

必要：否

要新增到容器的標籤索引鍵/值映射。此參數會映射到 Docker Remote API 的建立容器區段中的 Labels 以及 docker run 的 --label 選項。

在您的容器執行個體上，此參數需要 1.18 版或更新版本的 Docker Remote API。

"dockerLabels": {"string": "string"
      ...}

其他容器定義參數

在 Amazon ECS 主控台中使用 Configure via JSON (透過 JSON 進行設定) 選項註冊任務定義時，可以使用下列容器定義參數。如需詳細資訊，請參閱 使用主控台建立任務定義。

Linux 參數

linuxParameters

類型：LinuxParameters 物件

必要：否

Linux套用至容器的特定選項，例如KernelCapabilities。

注意

Windows 容器不支援此參數。

"linuxParameters": {
      "capabilities": {
        "add": ["string", ...],
        "drop": ["string", ...]
        }
      }
capabilities

類型：KernelCapabilities 物件

必要：否

從 Docker 提供的預設組態中新增或卸除的容器 Linux 功能。如需預設功能和其他可用功能的詳細資訊，請參閱《Docker 執行參考》中的執行期存取和 Linux 功能。如需這些 Linux 功能的詳細資訊，請參閱 Linux 手冊頁面的功能 (7)。

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 Remote API Create a container (建立容器) 一節中的 CapAdd，以及 Docker run 的 --cap-add 選項。

注意

在 Fargate 上啟動的任務僅支援新增 SYS_PTRACE 核心功能。

add

類型：字串陣列

有效值："SYS_PTRACE"

必要：否

要新增至 Docker 提供之預設組態容器的 Linux 功能。此參數會映射到 Docker Remote API 建立容器區段中的 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 Remote API 建立容器區段中的 CapDrop 以及 Docker run 的 --cap-drop 選項。

devices

任何要公開給容器的主機裝置。此參數會映射到 Docker Remote API 建立容器區段中的 Devices 以及 Docker run 的 --device 選項。

注意

當您使用 Fargate 啟動類型或 Windows 容器時，不支援 devices 參數。

類型：Device 物件的陣列

必要：否

hostPath

主機容器執行個體上裝置的路徑。

類型：字串

必要：是

containerPath

容器內的路徑，其為公開主機設備的目標路徑。

類型：字串

必要：否

permissions

要提供給裝置容器的明確許可。在預設情況下，容器在裝置上具有 read、write 及 mknod 許可。

類型：字串陣列

有效值: read | write | mknod

initProcessEnabled

在容器內執行 init 處理序，該處理序可轉寄訊號及獲得處理序。此參數會映射到 docker run 的 --init 選項。

在您的容器執行個體上，此參數需要 1.25 版或更新版本的 Docker Remote API。

maxSwap

容器可以使用的交換記憶體總量 (以 MiB 為單位)。此參數將會轉換為 docker run 的 --memory-swap 選項，其中值是容器記憶體與 maxSwap 值的總和。

如果將 maxSwap 值指定為 0，容器不會使用交換。接受的值為 0 或任何正整數。如果省略 maxSwap 參數，容器使用其執行所在的容器執行個體的交換組態。必須設定 maxSwap 值，才能使用 swappiness 參數。

注意

如果您使用的是使用 Fargate 啟動類型的任務，則不支援 maxSwap 參數。

sharedMemorySize

/dev/shm 磁碟區的大小值 (以 MiB 為單位)。此參數會映射到 docker run 的 --shm-size 選項。

注意

如果您使用的是使用 Fargate 啟動類型的任務，則不支援 sharedMemorySize 參數。

類型：整數

swappiness

您可使用此參數，調整容器的記憶體交換行為。swappiness 的值若為 0 將導致交換不會發生 (除非有需要)。swappiness 的值若為 100 將導致頻繁交換頁面。接受的值為介於 0 與 100 之間的整數。如果您未指定值，則會使用預設值 60。此外，如果您未對 maxSwap 指定值，則會忽略此參數。此參數會映射到 docker run 的 --memory-swappiness 選項。

注意

如果您使用的是使用 Fargate 啟動類型的任務，則不支援 swappiness 參數。

如果您在 Amazon Linux 2023 上使用任務，則不支援 swappiness 參數。

tmpfs

tmpfs 掛載的容器路徑、掛載選項和大小上限 (以 MiB 為單位)。此參數會映射到 docker run 的 --tmpfs 選項。

注意

如果您使用的是使用 Fargate 啟動類型的任務，則不支援 tmpfs 參數。

類型：Tmpfs 物件的陣列

必要：否

containerPath

要掛載 tmpfs 磁碟區的絕對檔案路徑。

類型：字串

必要：是

mountOptions

tmpfs 磁碟區掛載選項的清單。

類型：字串陣列

必要：否

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

size

tmpfs 磁碟區大小上限 (以 MiB 為單位)。

類型：整數

必要：是

容器相依性

dependsOn

類型：ContainerDependency 物件陣列

必要：否

針對容器啟動和關閉而定義的相依性。容器可包含多個相依性。針對容器啟動而定義相依性時，它會保留給容器關閉。如需範例，請參閱 容器相依性。

注意

如果容器不符合相依性限制或在符合限制之前逾時，Amazon ECS 不會讓相依容器進入下一個狀態。

對於在 Amazon EC2 執行個體上託管的 Amazon ECS 任務，執行個體至少需要容器代理程式的 1.26.0 版本，才能啟用容器相依性。不過，我們建議您使用最新版的容器代理程式。如需檢查代理程式版本及更新至最新版本的資訊，請參閱「更新 Amazon ECS 容器代理程式」。如果您使用的是 Amazon ECS 最佳化 Amazon Linux AMI，您的執行個體至少需要 1.26.0-1 版的 ecs-init 套件。如果您的容器執行個體是從 20190301 版或更新版本啟動，它們會包含所需的容器代理程式和 ecs-init 版本。如需詳細資訊，請參閱 Amazon ECS 最佳化 AMI。

對於在 Fargate 上託管的 Amazon ECS 任務，此參數要求任務或服務使用平台版本 1.3.0 或更新版本 (Linux) 或 1.0.0 (Windows)。

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

類型：字串

必要：是

必須符合指定條件的容器名稱。

condition

類型：字串

必要：是

容器的相依性條件。以下是可用的條件及其行為：

  • START - 此條件會模擬連結和磁碟區目前的行為。該條件可驗證相依容器先啟動後，才允許其他容器啟動。

  • COMPLETE - 此條件驗證相依容器執行到完成 (結束) 後，才允許其他容器啟動。這適合用於只是執行指令碼，然後就退出的非必要容器。無法在基本容器上設定此條件。

  • SUCCESS - 此條件與 COMPLETE 相同，但還要求容器必須以 zero 狀態結束。無法在基本容器上設定此條件。

  • HEALTHY - 此條件會在驗證相依容器傳遞了其容器運作狀態檢查後，才允許其他容器啟動。這會要求相依容器在任務定義中設定運作狀態檢查。僅在任務啟動時才會確認這個條件。

容器逾時

startTimeout

類型：整數

必要：否

範例值：120

解析容器的相依性時在放棄之前等待的持續時間 (以秒為單位)。

例如，您在任務定義中指定兩個容器，其中的 containerA 對達到 COMPLETE、SUCCESS 或 HEALTHY 狀態的 containerB 有相依性。如果為 containerB 指定 startTimeout 值，但在該時間內沒有達到所需狀態，則 containerA 不會啟動。

注意

如果容器不符合相依性限制或在符合限制之前逾時，Amazon ECS 不會讓相依容器進入下一個狀態。

對於在 Fargate 上託管的 Amazon ECS 任務，此參數要求任務或服務使用平台版本 1.3.0 或更新版本 (Linux)。最高值為 120 秒。

stopTimeout

類型：整數

必要：否

範例值：120

當容器本身未正常結束時，強制終止容器之前的等待期間 (以秒為單位)。

對於在 Fargate 上託管的 Amazon ECS 任務，此參數要求任務或服務使用平台版本 1.3.0 或更新版本 (Linux)。如果未指定參數，則會使用預設值 30 秒。最高值為 120 秒。

對於使用 EC2 啟動類型的任務，如果未指定 stopTimeout 參數，會使用 Amazon ECS 容器代理程式組態變數 ECS_CONTAINER_STOP_TIMEOUT 設定的值。如果未設定 stopTimeout 參數或 ECS_CONTAINER_STOP_TIMEOUT 代理程式組態變數，則對於 Linux 容器，預設值為 30 秒，對於 Windows 容器會使用預設值 30 秒。容器執行個體至少需要 1.26.0 版的容器代理程式，才能啟用容器停止逾時值。不過，我們建議您使用最新版的容器代理程式。如需如何檢查代理程式版本及更新至最新版本的資訊，請參閱「更新 Amazon ECS 容器代理程式」。如果您使用的是 Amazon ECS 最佳化 Amazon Linux AMI，您的執行個體至少需要 1.26.0-1 版的 ecs-init 套件。如果您的容器執行個體是從 20190301 版或更新版本啟動，它們會包含所需的容器代理程式和 ecs-init 版本。如需詳細資訊，請參閱 Amazon ECS 最佳化 AMI。

系統控制

systemControls

類型：SystemControl 物件

必要：否

要在容器中設定的命名空間核心參數清單。此參數會映射到 Docker Remote API 的建立容器區段中的 Sysctls 以及 docker run 的 --sysctl 選項。例如，您可以規劃 net.ipv4.tcp_keepalive_time 設定以維持壽命較長的連線。

不建議您指定單一任務中多個容器的網路相關 systemControls 參數，而單一任務也使用 awsvpc 或 host 網路模式。執行此操作的缺點如下：

  • 對於使用包括 Fargate awsvpc 網路模式的任務，如果您設定任何容器的 systemControls，則會套用至任務中的所有容器。如果您針對單一任務中的多個容器設定不同的 systemControls，則最後啟動的容器會判斷哪些 systemControls 生效。

  • 對於使用 host 網路模式的任務，不支援網路命名空間 systemControls。

如果您為任務中的容器設定要使用的 IPC 資源命名空間，以下各項條件套用到您的系統控制。如需詳細資訊，請參閱 IPC 模式。

  • 針對使用 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 支援所有這些值。

value

類型：字串

必要：否

在中指定的命名空間核心參數值namespace。

互動性

interactive

類型：布林值

必要：否

此參數為 true 時，您可部署需要配置 stdin 或 tty 的容器化應用程式。此參數會映射到 Docker Remote API 的建立容器區段中的 OpenStdin 以及 docker run 的 --interactive 選項。

預設值為 false。

虛擬終端機

pseudoTerminal

類型：布林值

必要：否

當此參數為 true 時，會配置 TTY。此參數會映射到 Docker Remote API 的建立容器區段中的 Tty 以及 docker run 的 --tty 選項。

預設值為 false。

Elastic Inference 加速器名稱

注意

自 2023 年 4 月 15 日起，不 AWS 會將新客戶加入 Amazon Elastic Inference (EI)，並協助目前客戶將工作負載遷移到提供更優惠價格和效能的選項。2023 年 4 月 15 日之後，新客戶將無法在 Amazon、Amazon ECS 或 Amazon Amazon EC2 使用亞馬遜 SageMaker EI 加速器啟動執行個體。但是，在過去 30 天內至少使用過一次 Amazon EI 的客戶將被視為目前客戶，並且可以繼續使用該服務。

任務定義的 Elastic Inference 加速器資源要求。如需詳細資訊，請參閱什麼是 Amazon Elastic Inference？ 在 Amazon Elastic Inference 開發人員指南中。

任務定義允許使用以下參數：

deviceName

類型：字串

必要：是

彈性推論加速器裝置名稱。deviceName 也必須在容器定義中參照，請參閱 Elastic Inference accelerator。

deviceType

類型：字串

必要：是

要使用的彈性推論加速器。

任務置放限制條件

當您註冊任務定義時，您可以提供任務置放限制，自訂 Amazon ECS 放置任務的方式。

若您使用的是 Fargate 啟動類型，則不支援任務置放限制條件。根據預設，Fargate 任務會分散在可用區域中。

對於使用 EC2 啟動類型的任務，您可以使用限制，根據可用區域、執行個體類型或自訂屬性來放置任務。如需詳細資訊，請參閱 定義 Amazon ECS 用於執行任務的容器執行個體。

容器定義允許使用以下參數：

expression

類型：字串

必要：否

限制所套用的叢集查詢語言運算式。如需詳細資訊，請參閱 建立運算式以定義 Amazon ECS 任務的容器執行個體。

type

類型：字串

必要：是

限制類型。使用 memberOf，以將選擇限制於特定群組或有效的待選項目。

代理組態

proxyConfiguration

類型：ProxyConfiguration 物件

必要：否

App Mesh 代理的組態詳細資訊。

對於使用 EC2 啟動類型的任務，容器執行個體需要至少 1.26.0 版的容器代理程式和至少 1.26.0-1 版的 ecs-init 套裝服務，才能啟用代理組態。如果您的容器執行個體是從 Amazon ECS 最佳化 AMI 20190301 版或更新版本啟動，則它們會包含所需的容器代理程式和 ecs-init 版本。如需詳細資訊，請參閱 Amazon ECS 最佳化 AMI。

對於使用 Fargate 啟動類型的任務，此功能要求任務或服務必須使用平台版本 1.3.0 或更新版本。

注意

Windows 容器不支援此參數。

"proxyConfiguration": {
    "type": "APPMESH",
    "containerName": "string",
    "properties": [
        {
           "name": "string",
           "value": "string"
        }
    ]
}
type

類型：字串

有效值：APPMESH

必要：否

代理類型。唯一支援的值為 APPMESH。

containerName

類型：字串

必要：是

做為 App Mesh 代理的容器名稱。

properties

類型：KeyValuePair 物件陣列

必要：否

一組網路組態參數，用於提供指定為鍵值組的容器網路介面 (CNI) 外掛程式。

  • IgnoredUID - (必要) 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 或亞馬遜 EC2 執行個體上託管的 Linux 任務，支援 Amazon EBS 磁碟區。如需詳細資訊，請參閱 Amazon EBS 磁碟區。

  • Amazon EFS 磁碟區 — 提供簡單、可擴展且持久的檔案儲存，可與 Amazon ECS 任務搭配使用。利用 Amazon EFS，儲存容量即可有彈性。儲存容量會隨著您新增和移除檔案時自動擴展和縮減。應用程式可在需要時具備所需的儲存容量。在 Fargate 或 Amazon EC2 執行個體上託管的任務支援 Amazon EFS 磁碟區。如需詳細資訊，請參閱 Amazon EFS 磁碟區。

  • FSx for Windows File Server 磁碟區 — 提供全受管 Microsoft Windows 檔案伺服器。這些檔案伺服器由 Windows 檔案系統支援。搭配使用 FSx for Windows File Server 與 Amazon ECS 時，您可以使用持續、分散、共用、靜態的檔案儲存來佈建 Windows 任務。如需詳細資訊，請參閱 FSx for Windows File Server 磁碟區。

    Fargate 上的 Windows 容器不支援此選項。

  • 碼頭磁碟區 — /var/lib/docker/volumes 在主機 Amazon EC2 執行個體上建立的由碼頭管理的磁碟區。Docker 磁碟區驅動程式 (也稱為外掛程式) 用外部儲存系統 (例如 Amazon EBS) 來整合磁碟區。可使用內建 local 磁碟區驅動程式或第三方磁碟區驅動程式。只有在 Amazon EC2 執行個體上執行任務時，才支援 Docker 磁碟區。Windows 容器僅支援local驅動程式的使用。若要使用 Docker 磁碟區，請在您的任務定義中指定 dockerVolumeConfiguration。如需詳細資訊，請參閱使用磁碟區。

  • 繫結掛載 — 裝載至容器的主機上的檔案或目錄。在 AWS Fargate 執行個體或 Amazon EC2 執行個體上執行任務時，支援繫結掛載主機磁碟區。若要使用綁定掛載主機磁碟區，請在任務定義中指定 host 和選用的 sourcePath 值。如需詳細資訊，請參閱使用綁定掛載。

如需詳細資訊，請參閱 在任務中使用資料磁碟區。

容器定義允許使用以下參數。

name

類型：字串

必要：否

磁碟區名稱。最多可使用 255 個字母 (大寫和小寫)、數字、連字號 (-) 和底線 (_)。此名稱會在容器定義mountPoints物件的sourceVolume參數中參照。

host

必要：否

host 參數用於將綁定掛載的生命週期綁定到主機 Amazon EC2 執行個體，而非任務，以及它的儲存位置。如果 host 參數是空的，則 Docker 常駐程式會為您的資料磁碟區指派主機路徑，但其相關聯的容器停止執行後，不保證會保留資料。

Windows 容器可在 $env:ProgramData 所在的相同磁碟上掛載整個目錄。

注意

只有在使用 Amazon EC2 執行個體上託管的任務時，才支援此sourcePath參數。

sourcePath

類型：字串

必要：否

使用 host 參數時，指定 sourcePath 以宣告在主機 Amazon EC2 執行個體上提供給容器的路徑。如果此參數是空的，則 Docker 常駐程式會為您指派主機路徑。如果 host 參數包含 sourcePath 檔案位置，資料磁碟區將保留在主機 Amazon EC2 執行個體上的指定位置，直到您手動將其刪除為止。如果 sourcePath 值不存在於主機 Amazon EC2 執行個體，Docker 常駐程式將建立該值。如果位置存在，將匯出來源路徑資料夾的內容。

configuredAtLaunch

類型：布林值

必要：否

指定磁碟區是否可在啟動時進行設定。設定為時true，您可以在執行獨立工作或建立或更新服務時設定磁碟區。設定為時true，您將無法在工作定義中提供其他磁碟區組態。必須將此參數設定true為設定 Amazon EBS 磁碟區以附加到任務。設定configuredAtLaunch為true並將磁碟區組態延遲至啟動階段，可讓您建立不受磁碟區類型或特定磁碟區設定限制的工作定義。這樣做可讓您的任務定義在不同的執行環境中重複使用。如需詳細資訊，請參閱 Amazon EBS 磁碟區。

dockerVolumeConfiguration

類型：DockerVolumeConfiguration物件

必要：否

此參數只有使用 Docker 磁碟區時才會指定。只有在 EC2 執行個體上執行任務時，才支援 Docker 磁碟區。Windows 容器僅支援local驅動程式的使用。若要使用綁定掛載，請指定 host。

scope

類型：字串

有效值: task | shared

必要：否

決定生命週期的 Docker 磁碟區範圍。範圍受限於 task 的 Docker 磁碟區，會在任務啟動時自動佈建，以及在任務停止時銷毀。範圍為 shared 的 Docker 磁碟區會在任務停止之後保留。

autoprovision

類型：布林值

預設值：false

必要：否

若此數值為 true，Docker 磁碟區便得以建立 (若它尚不存在)。只有在是時才會使用此欄scope位shared。如果scope是task，則必須省略此參數或設定為false。

driver

類型：字串

必要：否

要使用的 Docker 磁碟區驅動程式。驅動程式值必須與 Docker 提供的驅動程式名稱相符，因為此名稱用於工作放置。如果驅動程式是使用 Docker 外掛程式 CLI 安裝的，請使用docker plugin ls從容器執行個體擷取驅動程式名稱。如果驅動程序是通過使用其他方法安裝的，請使用 Docker 插件發現來檢索驅動程序名稱。如需詳細資訊，請參閱 Docker 外掛程式探索。此參數會映射到 Docker Remote API 的建立磁碟區區段中的 Driver 以及 docker volume create 的 --driver 選項。

driverOpts

類型：字串

必要：否

要通過的 Docker 驅動程序特定選項的地圖。此參數會映射到 Docker Remote API 的建立磁碟區區段中的 DriverOpts 以及 docker volume create 的 --opt 選項。

labels

類型：字串

必要：否

自訂中繼資料，新增到您的 Docker 磁碟區。此參數會映射到 Docker Remote API 的建立磁碟區區段中的 Labels 以及 docker volume create 的 --label 選項。

efsVolumeConfiguration

類型：EFS VolumeConfiguration 物件

必要：否

只有使用 Amazon EFS 磁碟區時才會指定此參數。

fileSystemId

類型：字串

必要：是

要使用的 Amazon EFS 檔案系統識別碼。

rootDirectory

類型：字串

必要：否

在 Amazon EFS 檔案系統中的目錄，其將掛載作為主機內的根目錄。如果省略此參數，將使用 Amazon EFS 磁碟區的根目錄。指定 / 的效果與忽略此參數的效果相同。

重要

如果在中指定 EFS 存取點authorizationConfig，則必須省略根目錄參數或將其設定為/，這樣會強制在 EFS 存取點上設定的路徑。

transitEncryption

類型：字串

有效值：ENABLED | DISABLED

必要：否

指定是否要對在 Amazon ECS 主機和 Amazon EFS 伺服器之間傳輸中的 Amazon EFS 資料啟用加密功能。如果使用 Amazon EFS IAM 授權，則必須啟用傳輸加密。如果省略此參數，系統會使用 DISABLED 的預設值。如需詳細資訊，請參閱《Amazon Elastic File System 使用者指南》中的加密傳輸中的資料。

transitEncryptionPort

類型：整數

必要：否

在 Amazon ECS 主機和 Amazon EFS 伺服器之間傳送加密資料時所使用的連接埠。如果未指定傳輸加密連接埠，任務將使用 Amazon EFS 掛載協助程式使用的連接埠選取策略。如需詳細資訊，請參閱《Amazon Elastic File System 使用者指南》中的 EFS 掛載協助程式。

authorizationConfig

類型：EFS AuthorizationConfiguration 物件

必要：否

Amazon EFS 檔案系統的授權組態詳細資訊。

accessPointId

類型：字串

必要：否

要使用的存取點 ID。如果指定存取點，則efsVolumeConfiguration必須省略中的根目錄值或將其設定為/，這樣會強制在 EFS 存取點上設定的路徑。如果使用存取點，則必須在 EFSVolumeConfiguration 中啟用傳輸加密。如需詳細資訊，請參閱《Amazon Elastic File System 使用者指南》中的使用 Amazon EFS 存取點。

iam

類型：字串

有效值：ENABLED | DISABLED

必要：否

指定掛接 Amazon EFS 檔案系統時，是否要使用任務定義中定義的 Amazon ECS 任務 IAM 角色。如果已啟用，必須在 EFSVolumeConfiguration 中啟用傳輸加密。如果省略此參數，系統會使用 DISABLED 的預設值。如需詳細資訊，請參閱任務的 IAM 角色。

FSxWindowsFileServerVolumeConfiguration

類型：F SxWindowsFileServerVolumeConfiguration 對象

必要：是

當您使用適用於 Windows 檔案伺服器的 Amazon FSx 檔案伺服器檔案系統進行任務儲存時，會指定此參數。

fileSystemId

類型：字串

必要：是

要使用的 FSx for Windows File Server 檔案系統 ID。

rootDirectory

類型：字串

必要：是

FSx for Windows File Server 檔案系統中的目錄，其將掛載做為主機內的根目錄。

authorizationConfig
credentialsParameter

類型：字串

必要：是

授權憑證選項。

選項：
domain

類型：字串

必要：是

由 AWS Directory Service for Microsoft Active Directory(AWS Managed Microsoft AD) 目錄或自我託管 EC2 活動目錄託管的完整網域名稱。

標籤

當您註冊任務定義時，您可以選擇性地指定套用至任務定義的中繼資料標籤。標籤可協助您分類和組織您的任務定義。每個標籤皆包含索引鍵與選用值。您可以兩個都定義。如需詳細資訊，請參閱 Amazon ECS 資源標記。

重要

請勿在標籤中加入個人識別資訊或其他機密或敏感資訊。許多 AWS 服務都可以使用標籤，包括帳單。標籤不適用於私有或敏感資料。

標籤物件允許使用以下參數。

key

類型：字串

必要：否

組成標籤的鍵值組的一部分。索引鍵是一般標籤，作用就像更特定標籤值的類別。

value

類型：字串

必要：否

組成標籤的鍵值組的選用部分。值就像標籤類別 (索引鍵) 內的描述項。

其他任務定義參數

在 Amazon ECS 主控台中使用 Configure via JSON (透過 JSON 進行設定) 選項註冊任務定義時，可以使用下列任務定義參數。如需詳細資訊，請參閱 使用主控台建立任務定義。

暫時性儲存

ephemeralStorage

類型：EphemeralStorage 物件

必要：否

為任務配置的暫時性儲存量 (以 GB 為單位)。對於託管於 AWS Fargate的任務，此參數可用來擴充可用的暫時性儲存總量 (超過預設數量)。如需詳細資訊，請參閱 綁定掛載。

注意

只有託管於 AWS Fargate 且使用平台版本 1.4.0 或更新版本 (Linux) 或 1.0.0 或更新版本 (Windows) 的任務才支援此參數。

IPC 模式

ipcMode

類型：字串

必要：否

要用於任務中容器的 IPC 資源命名空間。有效值為 host、task 或 none。如果已指定 host，則任務內對相同容器執行個體指定 host IPC 模式的所有容器，會與主機 Amazon EC2 執行個體共用相同的 IPC 資源。如果已指定 task，則指定任務內的所有容器會共用相同的 IPC 資源。如果已指定 none，則任務內的容器內的 IPC 資源為私有，並且不會與任務中或容器執行個體上的其他容器共用。如果沒有指定值，則 IPC 資源命名空間共用取決於容器執行個體上 Docker 常駐程式的設定。如需詳細資訊，請參閱《Docker run 參考》https://docs.docker.com/engine/reference/run/#ipc-settings---ipc中的 IPC 設定。

如果是使用 host IPC 模式，這會提高將不需要的 IPC 命名空間公開的風險。如需詳細資訊，請參閱 Docker 安全性。

如果是使用 systemControls 來為任務中的容器設定命名空間核心參數，以下各項會套用到您的 IPC 資源命名空間。如需詳細資訊，請參閱 系統控制。

  • 針對使用 host IPC 模式的任務，不支援與 systemControls 相關的 IPC 命名空間。

  • 針對使用 task IPC 模式的任務，IPC 命名空間相關的 systemControls 套用到任務內的所有容器。

注意

Windows 容器或使用 Fargate 啟動類型的任務不支援此參數。

PID 模式

pidMode

類型：字串

有效值: host | task

必要：否

要用於任務中容器的程序命名空間。有效值為 host 或 task。在 Linux 容器的 Fargate 上，唯一有效的值為 task。例如，監控附屬可能需要 pidMode 存取相同任務中執行之其他容器的相關資訊。

如果已指定 host，任務內對相容器執行個體指定 host PID 模式的所有容器，會與主機 Amazon EC2 執行個體共用相同的程序命名空間。

如果已指定 task，則指定任務內的所有容器會共用相同的程序命名空間。

如果未指定任何值，每個容器的預設值會是私有命名空間。如需詳細資訊，請參閱《Docker run 參考》https://docs.docker.com/engine/reference/run/#pid-settings---pid中的 PID 設定。

如果是使用 host PID 模式，這會提高將不需要的程序命名空間公開的風險。如需詳細資訊，請參閱 Docker 安全性。

注意

Windows 容器不支援此參數。

注意

如果任務使用平台版本 1.4.0 或更高版本 (Linux)，只有託管於 AWS Fargate 的任務才支援此參數。Fargate 上的 Windows 容器不支援此參數。