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

ecs-cli compose

说明

在 ECS 集群上利用 docker-compose 式命令管理 Amazon ECS 任务。

注意

要使用 Amazon ECS CLI 创建 Amazon ECS 服务,请参阅 ecs-cli compose service

ecs-cli compose 命令使用 Docker 复合文件创建任务定义和管理任务。此时,最新版本的 Amazon ECS CLI 支持 Docker 复合文件语法版本 1、2 和 3。

注意

Amazon ECS CLI 只支持 Docker 复合文件语法的主要版本。因此,复合文件中指定的版本必须为字符串 "1""1.0""2""2.0""3""3.0"

默认情况下,此命令将在当前目录中查找一个名为 docker-compose.yml 的复合文件。但是,您也可以使用 --file 选项指定复合文件的其他文件名或路径。这在使用 Amazon ECS CLI 一次性管理多个复合文件中的任务和服务时特别有用。

ecs-cli compose 命令将项目名称与其创建的任务定义和服务结合使用。当 CLI 从复合文件创建任务定义时,任务定义将称为 project-name。当 CLI 从复合文件创建服务时,服务将称为 service-project-name。默认情况下,项目名称是当前工作目录的名称。但是,您也可以使用 --project-name 选项指定自己的项目名称。

注意

Amazon ECS CLI 只能管理使用 CLI 创建的任务、服务和容器实例。要管理并非使用 Amazon ECS CLI 创建的任务、服务和容器实例,请使用 AWS Command Line Interface 或 AWS 管理控制台。

Amazon ECS CLI 的复合文件中支持以下参数:

  • command

  • cpu_shares

  • dns

  • dns_search

  • entrypoint

  • environment:如果复合文件中未指定环境变量值,但该值存在于 shell 环境中,则 shell 环境变量值将传递到为任何关联的任务或服务创建的任务定义。

    重要

    建议不要对敏感信息 (如凭证数据) 使用纯文本环境变量。

  • env_file

    重要

    建议不要对敏感信息 (如凭证数据) 使用纯文本环境变量。

  • extra_hosts

  • hostname

  • image

  • labels

  • links

  • log_driver (仅限复合文件版本 1)

  • log_opt (仅限复合文件版本 1)

  • logging (仅限复合文件版本 2)

    • driver

    • options

  • mem_limit (以字节为单位)

  • mem_reservation (以字节为单位)

  • ports

  • privileged

  • read_only

  • security_opt

  • ulimits

  • user

  • volumes

  • volumes_from

  • working_dir

重要

此时不支持 build 指令。

有关 Docker 复合文件语法的更多信息,请参阅 Docker 文档中的复合文件参考

重要

Some features described may only be available with the latest version of the ECS CLI. To obtain the latest version, see 安装 Amazon ECS CLI.

使用 Amazon ECS 参数

由于 Amazon ECS 任务定义中存在与 Docker 复合文件中的字段不对应的特定字段,因此,您可使用 --ecs-params 标记指定这些值。默认情况下,此命令将在当前目录中查找一个名为 ecs-params.yml 的 ECS params 文件。但是,您也可以使用 --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 services: <service_name>: essential: boolean cpu_shares: integer mem_limit: string mem_reservation: string healthcheck: test: ["CMD", "curl -f http://localhost"] interval: string timeout: string retries: integer start_period: string run_params: network_configuration: awsvpc_configuration: subnets: - subnet_id1 - subnet_id2 security_groups: - secgroup_id1 - secgroup_id2 assign_public_ip: ENABLED

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)

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

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

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

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

    • 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 文件中指定它,则值将覆盖复合文件中存在的值。

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

      注意

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

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 启动类型结合使用的任务中,则请求将失败。

语法

ecs-cli compose [--verbose] [--file compose-file] [--project-name project-name] [--task-role-arn value] [--ecs-params value] [--region value] [--cluster-config value] [--ecs-profile value] [--aws-profile value] [--cluster value] [--help] [--task-role-arn role_value] [--cluster cluster_name] [--region region] [--ecs-params ecs-params.yml] [subcommand] [arguments] [--help]

选项

名称 描述

--verbose, --debug

提高命令输出的详细程度以帮助诊断。

必需:否

--file, -f compose-file

指定要使用的 Docker 复合文件。此时,最新版本的 Amazon ECS CLI 支持 Docker 复合文件语法版本 1 和 2。 如果在 ecs-cli compose 运行时设置 COMPOSE_FILE 环境变量,则 Docker 复合文件将设置为该环境变量的值。

类型:字符串

默认值:./docker-compose.yml

必需:否

--project-name, -p project-name

指定要使用的项目名称。如果在运行 ecs-cli compose 时设置 COMPOSE_PROJECT_NAME 环境变量,则项目名称将设置为该环境变量的值。

类型:字符串

默认值:当前目录名。

必需:否

--task-role-arn role_value

指定该任务中的容器可以代入的 IAM 角色的短名称或完整的 Amazon 资源名称 (ARN)。该任务中的所有容器都将被授予在该角色中指定的权限。

类型:字符串

必需:否

--cluster, -c cluster_name

指定要使用的 ECS 集群名称。默认为使用 configure 命令配置的群集。

类型:字符串

必需:否

--region, -r region

指定要使用的 AWS 区域。默认为使用 configure 命令配置的群集。

类型:字符串

必需:否

--ecs-profile ecs_profile

Specifies the name of the ECS profile configuration to use. Defaults to the profile configured using the configure profile command.

Type: String

Required: No

--aws-profile aws_profile

Specifies the AWS profile to use. Enables you to use the AWS credentials from an existing named profile in ~/.aws/credentials.

Type: String

Required: No

--cluster-config cluster_config_name

Specifies the name of the ECS cluster configuration to use. Defaults to the cluster configuration set as the default.

Type: String

Required: No

--help, -h

显示指定命令的帮助文本。

类型:布尔值

必需:否

可用子命令

ecs-cli compose 命令支持以下子命令。其中,每条子命令均具有关联的标记,这些标记可通过 --help 标记显示。

create

从复合文件创建 Amazon ECS 任务定义。有关更多信息,请参阅 ecs-cli compose create

pslist

列出集群中由构成项目启动的所有容器。

run [containerName] ["command ..."] ...

使用为容器提供的一次性命令来启动覆盖命令的所有容器。

scale n

将正在运行的任务数扩展至指定计数。

start

从通过复合文件创建的任务定义启动单个任务。有关更多信息,请参阅 ecs-cli compose start

stopdown

停止由构成项目创建的所有正在运行的任务。

up

从复合文件创建 ECS 任务定义 (如果该任务定义不存在) 并在群集上运行该任务的一个实例 (createstart 的组合)。有关更多信息,请参阅 ecs-cli compose up

service [subcommand]

从复合文件创建 ECS 服务。有关更多信息,请参阅 ecs-cli compose service

帮助

显示指定命令的帮助文本。