Amazon Elastic Container Service
开发人员指南 (API 版本 2014-11-13)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使用 Amazon ECS 参数

在使用 ecs-cli composeecs-cli compose service 命令管理 Amazon ECS 任务和服务时,Amazon ECS 任务定义中存在与 Docker 复合文件中的字段不对应的特定字段。您可以通过 --ecs-params 标志使用 ECS 参数文件指定这些值。默认情况下,此命令将在当前目录中查找一个名为 ecs-params.yml 的 ECS 参数文件。但是,您也可以使用 --ecs-params 选项指定 ECS 参数文件的其他文件名或路径。

目前,该文件支持以下架构:

version: 1 task_definition: ecs_network_mode: string task_role_arn: string task_execution_role: string task_size: cpu_limit: string mem_limit: string pid_mode: string ipc_mode: string services: <service_name>: essential: boolean repository_credentials: credentials_parameter: string cpu_shares: integer mem_limit: string mem_reservation: string gpu: string init_process_enabled: boolean healthcheck: test: ["CMD", "curl -f http://localhost"] interval: string timeout: string retries: integer start_period: string secrets: - value_from: string name: string docker_volumes: - name: string scope: string autoprovision: driver: string driver_opts: boolean string: string labels: string: string run_params: network_configuration: awsvpc_configuration: subnets: - subnet_id1 - subnet_id2 security_groups: - secgroup_id1 - secgroup_id2 assign_public_ip: ENABLED task_placement: strategy: - type: string field: string constraints: - type: string expression: string service_discovery: container_name: string container_port: integer private_dns_namespace: vpc: string id: string name: string description: string public_dns_namespace: id: string name: string service_discovery_service: name: string description: string dns_config: type: string ttl: integer healthcheck_custom_config: failure_threshold: integer

task_definition 下列出的字段对应于要包含在您的 Amazon ECS 任务定义中的字段。

  • ecs_network_mode – 对应于 ECS 任务定义中的 networkMode。支持的值为 nonebridgehostawsvpc。默认值为 bridge。如果您使用的是任务联网,则此字段必须设置为 awsvpc。有关更多信息,请参阅网络模式

  • task_role_arn –‐ 要与任务关联的 IAM 角色的名称或完整 ARN。有关更多信息,请参阅任务角色

  • task_execution_role – 任务执行角色的名称或完整 ARN。如果您希望任务能够将容器应用程序日志存储在 CloudWatch 中或允许您的任务从 Amazon ECR 拉取容器映像,则此字段是必填字段。有关更多信息,请参阅Amazon ECS 任务执行 IAM 角色

  • task_size – 任务的 CPU 和内存值。如果使用的是 EC2 启动类型,则此字段是可选的,并且可使用任何值。如果使用的是 Fargate 启动类型,此字段是必填的,并且您必须对 cpumemory 参数使用以下几组值。

    CPU value Memory value (MiB)
    256 (.25 vCPU) 512 (0.5GB), 1024 (1GB), 2048 (2GB)
    512 (.5 vCPU) 1024 (1GB), 2048 (2GB), 3072 (3GB), 4096 (4GB)
    1024 (1 vCPU) 2048 (2GB), 3072 (3GB), 4096 (4GB), 5120 (5GB), 6144 (6GB), 7168 (7GB), 8192 (8GB)
    2048 (2 vCPU) Between 4096 (4GB) and 16384 (16GB) in increments of 1024 (1GB)
    4096 (4 vCPU) Between 8192 (8GB) and 30720 (30GB) in increments of 1024 (1GB)

    有关更多信息,请参阅任务大小

  • pid_mode – 用于任务中的容器的过程命名空间。有效值为 hosttask。如果指定了 host,则在同一容器实例上指定了 host PID 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的 IPC 资源。如果指定了 task,则指定任务中的所有容器将共享相同的过程命名空间。如果未指定任何值,则默认值为私有命名空间。有关更多信息,请参阅 Docker 运行参考 中的 PID 设置

    如果使用了 host PID 模式,请注意,发生非预期的过程命名空间公开的风险会提高。有关更多信息,请参阅 Docker 安全性

    注意

    使用 Fargate 启动类型的 Windows 容器或任务不支持此参数。

  • ipc_mode – 用于任务中的容器的 IPC 资源命名空间。有效值为 hosttasknone。如果指定了 host,则在同一容器实例上指定了 host IPC 模式的任务中的所有容器将与主机 Amazon EC2 实例共享相同的 IPC 资源。如果指定了 task,则指定任务中的所有容器将共享相同的 IPC 资源。如果指定了 none,则任务的容器中的 IPC 资源是私有的,不与任务中或容器实例上的其他容器共享。如果未指定任何值,则 IPC 资源命名空间共享取决于容器实例上的 Docker 守护程序设置。有关更多信息,请参阅 Docker 运行参考 中的 IPC 设置

    如果使用了 host IPC 模式,请注意,发生非预期的 IPC 命名空间公开的风险会提高。有关更多信息,请参阅 Docker 安全性

    如果您使用 systemControls 为任务中的容器设置具有命名空间的内核参数,则以下内容将适用于您的 IPC 资源命名空间。有关更多信息,请参阅 Amazon Elastic Container Service Developer Guide 中的系统控制

    • 对于使用 host IPC 模式的任务,不支持与 IPC 命名空间相关的 systemControls

    • 对于使用 task IPC 模式的任务,与 IPC 命名空间相关的 systemControls 将适用于任务中的所有容器。

    注意

    使用 Fargate 启动类型的 Windows 容器或任务不支持此参数。

  • services – 对应于您的 Docker 复合文件中列出的服务,其中 service_name 与要运行的容器的名称匹配。其字段将合并到容器定义中。

    • essential – 如果将容器的 essential 参数标记为 true,并且该容器出于任何原因发生故障或停止,则属于此任务的所有其他容器将停止。如果将容器的 essential 参数标记为 false,则容器发生故障不会影响任务中的剩余容器。默认值为 true

      所有任务都必须具有至少一个主要容器。如果您有一个由多个容器组成的应用程序,则应将用于相同目的的容器分成多个组件,然后将不同的组件分为多个任务定义。

    • repository_credentials – 如果您使用私有存储库拉取映像,repository_credentials 让您为包含私有存储库凭证的私有密钥的名称指定一个 AWS Secrets Manager 密钥 ARN 作为 credential_parameter。有关更多信息,请参阅任务的私有注册表身份验证

    • cpu_shares –此参数映射到 Docker 复合文件参考中的 cpu_shares。如果您使用的是 Docker compose 版本 3,则此字段是可选的,并且必须在 ECS params 文件而不是复合文件中指定。在 Docker compose 版本 2 中,此字段可以在复合文件或 ECS params 文件中指定。如果在 ECS params 文件中指定它,则值将覆盖复合文件中存在的值。

    • mem_limit –此参数映射到 Docker 复合文件参考中的 mem_limit。如果您使用的是 Docker compose 版本 3,则此字段是可选的,并且必须在 ECS params 文件而不是复合文件中指定。在 Docker compose 版本 2 中,此字段可以在复合文件或 ECS params 文件中指定。如果在 ECS params 文件中指定它,则值将覆盖复合文件中存在的值。

    • mem_reservation –此参数映射到 Docker 复合文件参考中的 mem_reservation。如果您使用的是 Docker compose 版本 3,则此字段是可选的,并且必须在 ECS params 文件而不是复合文件中指定。在 Docker compose 版本 2 中,此字段可以在复合文件或 ECS params 文件中指定。如果在 ECS params 文件中指定它,则值将覆盖复合文件中存在的值。

    • gpu – Amazon ECS 容器代理将为容器预留的物理 GPU 的数量。此参数将映射到任务定义中的 resourceRequirements 字段。有关更多信息,请参阅在 Amazon ECS 上使用 GPU

    • init_process_enabled – 此参数让您能够在容器内运行可转发信号并获得进程的 init 进程。此参数将映射到 docker run--init 选项。

      This parameter requires version 1.25 of the Docker Remote API or greater on your container instance.

    • healthcheck –此参数映射到 Docker 复合文件参考中的 healthchecktest 字段也可指定为 command,并且必须是字符串或列表。如果它是列表,则第一个项目必须是 NONECMDCMD-SHELL。如果它是字符串,则等同于指定 CMD-SHELL 后跟该字符串。intervaltimeoutstart_period 字段指定为字符串格式的持续时间。例如:2.5s10s1m30s2h23m5h34m56s

      注意

      如果未指定任何单位,则假定为秒。例如,可以指定 10s 或只指定 10

    • secrets – 此参数使您可以向容器中注入敏感数据,方法是将您的敏感数据存储在 AWS Systems Manager Parameter Store 参数中,然后在容器定义中引用它们。有关更多信息,请参阅 指定敏感数据

      • value_from – 这是要向容器公开的 AWS Systems Manager Parameter Store ARN 或名称。如果 Systems Manager Parameter Store 参数存在于要启动的任务所在的区域,则可以使用密钥的完整 ARN 或名称。如果参数存在于不同的区域,则必须指定完整的 ARN。

      • name – 要在容器上设置为环境变量的值。

  • docker_volumes – 此参数允许您创建 Docker 卷。name 键是必需的,scopeautoprovisiondriverdriver_optslabels 与任务定义中的 Docker 卷配置字段相对应。有关更多信息,请参阅 Amazon Elastic Container Service API Reference 中的 DockerVolumeConfiguration。使用 docker_volumes 键定义的卷可以按名称在复合文件中引用(即使未在复合文件中指定)。

run_params 下列出的字段针对所需的值,因为任何 API 调用的选项未与任务定义明确相关联,例如 compose up (RunTask) 和 compose service up (CreateService)。目前,run_params 下唯一受支持的参数为 network_configuration,该参数在使用任务联网时和使用 Fargate 启动类型的任务时是必需参数。

  • network_configuration – 如果您为 ecs_network_mode 指定 awsvpc,则是必需的。它使用一个带以下子字段的嵌套参数 awsvpc_configuration

    • subnets – 要与您的任务关联的已用子网 ID 的列表。列出的子网必须与要在其上启动任务的实例位于同一 VPC 和可用区中。

    • security_groups – 要与您的任务关联的安全组 ID 的列表。列出的安全性必须与要在其上启动任务的实例位于同一 VPC 中。

    • assign_public_ip – 此字段支持的值为 ENABLEDDISABLED。此字段仅用于使用 Fargate 启动类型的任务。如果此字段存在于将任务联网与 EC2 启动类型结合使用的任务中,则请求将失败。

  • task_placement – 此参数允许您指定任务放置选项。如果使用的是 EC2 启动类型,则是可选的。Fargate 启动类型不支持。有关更多信息,请参阅Amazon ECS 任务放置

    它具有以下子字段:

    • strategy – 对象列表,带有 2 个键。有效键为 typefield

      • type – 有效值为 randombinpackspread。如果指定了 random,则不应提供 field 键。

      • field – 有效值取决于策略类型。

        • 对于 spread,有效值为 instanceIdhost 或属性键-值对,例如 attribute:ecs.instance-type =~ t2.*

        • 对于 binpack,有效值为 cpumemory

    • constraints – 对象列表,带有 2 个键。有效键为 typeexpression

      • type – 有效值为 distinctInstancememberOf。如果指定了 distinctInstance,则不应提供 expression 键。

      • expression – 当类型为 memberOf 时,有效值为属性或任务组的键-值对,例如 task:group == databasesattribute:color =~ green

  • service_discovery – 此参数可用于使用 Amazon Route 53 自动命名 API 操作配置 Amazon ECS Service Discovery以管理服务的任务的 DNS 条目。有关更多信息,请参阅教程:使用 Amazon ECS CLI 创建使用Service Discovery的 Amazon ECS 服务