Amazon Elastic Container Service
开发人员指南 (API Version 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。默认情况下,此命令将在当前目录中查找一个名为 docker-compose.yml 的复合文件。但是,您也可以使用 --file 选项指定复合文件的其他文件名或路径。这在使用 Amazon ECS CLI 一次性管理多个复合文件中的任务和服务时特别有用。

ecs-cli compose 命令将项目名称与其创建的任务定义和服务结合使用。当 CLI 从复合文件创建任务定义时,任务定义将称为 ecscompose-project-name。当 CLI 从复合文件创建服务时,服务将称为 ecscompose-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 文档中的复合文件参考

注意

确保您使用的是最新版本的 Amazon ECS CLI 才能使用所有配置选项。

重要

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 文件。目前,该文件支持以下架构:

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 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

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 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

帮助

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