登录控制台
Amazon Elastic Container Service
开发人员指南 (API 版本 2014-11-13)
AWS 文档 » Amazon EC2 Container Service » 开发人员指南 » 使用 Amazon ECS 命令行界面 » Amazon ECS 命令行参考 » ecs-cli compose service
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异，请参阅 Amazon AWS 入门。

ecs-cli compose service

说明

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

注意

要使用 Amazon ECS CLI 运行任务而不是创建服务，请参阅 ecs-cli compose。

ecs-cli compose service 命令使用 Docker 复合文件创建任务定义和管理服务。此时，Amazon ECS CLI 支持 Docker 复合文件语法版本 1、2 和 3。默认情况下，此命令将在当前目录中查找一个名为 docker-compose.yml 的复合文件。但是，您也可以使用 --file 选项指定复合文件的其他文件名或路径。这在使用 Amazon ECS CLI 一次性管理多个复合文件中的任务和服务时特别有用。

ecs-cli compose service 命令将项目名称与其创建的任务定义和服务结合使用。当 CLI 从复合文件创建任务定义和服务时，任务定义和服务将称为 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.

语法

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] service [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 service 命令支持以下子命令和参数：

create [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--load-balancer-name value|--target-group-arn value] [--container-name value] [--container-port value] [--role value] [--launch-type launch_type] [--health-check-grace-period integer] [--create-log-groups]

从复合文件创建 ECS 服务。将使用预期计数 0 创建服务，因此该命令不会启动任何容器。

--deployment-max-percent 选项指定部署期间可在服务中运行的任务数的上限（服务的 desiredCount 的百分比形式，默认值为 200）。--deployment-min-healthy-percent 选项指定部署期间必须在服务中保持运行和正常状态的所运行服务的数目的下限（以服务的 desiredCount 的百分比形式，默认值为 100）。有关更多信息，请参阅 maximumPercent 和 minimumHealthyPercent。

您可选择借助负载均衡器运行您的服务。负载均衡器将在与服务关联的各个任务间分配流量。有关更多信息，请参阅 服务负载均衡。在创建服务后，在服务定义中指定的负载均衡器名称或目标组 ARN、容器名称和容器端口是不可变的。

注意

您必须先创建负载均衡器资源，然后才能将服务配置为使用它们。您的负载均衡器资源应与您的容器实例位于同一 VPC 中，并且应将它们配置为使用相同的子网。您还必须向容器实例安全组添加一个安全组规则，该规则允许来自负载均衡器的入站流量。有关更多信息，请参阅 创建负载均衡器。

  • 要将服务配置为使用现有 Elastic Load Balancing 传统负载均衡器，您必须指定负载均衡器名称、容器名称 (显示在容器定义中) 和要从负载均衡器访问的容器端口。将此服务中的任务放在容器实例上后，容器实例将注册到在此处指定的负载均衡器。

  • 要将服务配置为使用现有 Elastic Load Balancing 应用程序负载均衡器，您必须指定负载均衡器目标组 ARN、容器名称 (显示在容器定义中) 和要从负载均衡器访问的容器端口。将此服务中的任务放在容器实例上后，容器实例和端口组合将注册为在此处指定的目标组中的目标。

The --health-check-grace-period option specifies the period of time, in seconds, that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks after a task has first started. This is only valid if your service is configured to use a load balancer. If your tasks take a while to start and respond to ELB health checks, you can specify a health check grace period of up to 1,800 seconds during which the ECS service scheduler ignores the Elastic Load Balancing health check status. This grace period can prevent the Amazon ECS service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.

start [--timeout value] [--create-log-groups] [--force-deployment]

在创建的 ECS 服务上启动每个容器的一个副本。此命令将服务的预期数量更新为 1。

--timeout 选项指定等待运行任务计数更改的超时值 (以分钟为单位，支持小数)。如果运行任务计数在指定时间段内未更改，CLI 将超时并返回错误。将超时时间设置为 0 将导致命令返回而不检查是否成功。默认超时值为 5 分钟。

--create-log-groups 选项将创建在复合文件中指定的 CloudWatch 日志组。

包括 --force-deployment 选项时将强制实施服务的新部署。

up [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--load-balancer-name value|--target-group-arn value] [--container-name value] [--container-port value] [--role value] [--timeout value] [--launch-type launch_type] [--health-check-grace-period integer] [--create-log-groups] [--force-deployment]

从复合文件创建 ECS 服务（如果该服务不存在）并在集群上运行该任务的一个实例（create 和 start 的组合）。此命令将服务的预期数量更新为 1。

--deployment-max-percent 选项指定部署期间可在服务中运行的任务数的上限（服务的 desiredCount 的百分比形式，默认值为 200）。--deployment-min-healthy-percent 选项指定部署期间必须在服务中保持运行和正常状态的所运行服务的数目的下限（以服务的 desiredCount 的百分比形式，默认值为 100）。有关更多信息，请参阅 maximumPercent 和 minimumHealthyPercent。

The --timeout option specifies the timeout value in minutes (decimals supported) to wait for the running task count to change. If the running task count has not changed for the specified period of time, then the CLI times out and returns an error. Setting the timeout to 0 causes the command to return without checking for success. The default timeout value is 5 minutes.

The --health-check-grace-period option specifies the period of time, in seconds, that the Amazon ECS service scheduler should ignore unhealthy Elastic Load Balancing target health checks after a task has first started. This is only valid if your service is configured to use a load balancer. If your tasks take a while to start and respond to ELB health checks, you can specify a health check grace period of up to 1,800 seconds during which the ECS service scheduler ignores the Elastic Load Balancing health check status. This grace period can prevent the Amazon ECS service scheduler from marking tasks as unhealthy and stopping them before they have time to come up.

--create-log-groups 选项将创建在复合文件中指定的 CloudWatch 日志组。

包括 --force-deployment 选项时将强制实施服务的新部署。

您可选择借助负载均衡器运行您的服务。负载均衡器将在与服务关联的各个任务间分配流量。有关更多信息，请参阅 服务负载均衡。在创建服务后，在服务定义中指定的负载均衡器名称或目标组 ARN、容器名称和容器端口是不可变的。

注意

您必须先创建负载均衡器资源，然后才能将服务配置为使用它们。您的负载均衡器资源应与您的容器实例位于同一 VPC 中，并且应将它们配置为使用相同的子网。您还必须向容器实例安全组添加一个安全组规则，该规则允许来自负载均衡器的入站流量。有关更多信息，请参阅 创建负载均衡器。

  • 要将服务配置为使用现有 Elastic Load Balancing 传统负载均衡器，您必须指定负载均衡器名称、容器名称 (显示在容器定义中) 和要从负载均衡器访问的容器端口。将此服务中的任务放在容器实例上后，容器实例将注册到在此处指定的负载均衡器。

  • 要将服务配置为使用现有 Elastic Load Balancing 应用程序负载均衡器，您必须指定负载均衡器目标组 ARN、容器名称 (显示在容器定义中) 和要从负载均衡器访问的容器端口。将此服务中的任务放在容器实例上后，容器实例和端口组合将注册为在此处指定的目标组中的目标。

ps、list

列出集群中属于使用复合项目创建的服务的所有容器。

scale [--deployment-max-percent n] [--deployment-min-healthy-percent n] [--timeout value] n

将服务的预期数量扩展至指定计数。

--deployment-max-percent 选项指定部署期间可在服务中运行的任务数的上限（服务的 desiredCount 的百分比形式，默认值为 200）。--deployment-min-healthy-percent 选项指定部署期间必须在服务中保持运行和正常状态的所运行服务的数目的下限（以服务的 desiredCount 的百分比形式，默认值为 100）。有关更多信息，请参阅 maximumPercent 和 minimumHealthyPercent。

The --timeout option specifies the timeout value in minutes (decimals supported) to wait for the running task count to change. If the running task count has not changed for the specified period of time, then the CLI times out and returns an error. Setting the timeout to 0 causes the command to return without checking for success. The default timeout value is 5 minutes.

stop [--timeout value]

停止属于使用复合项目创建的服务的正在运行的任务。此命令将服务的预期数量更新为 0。

The --timeout option specifies the timeout value in minutes (decimals supported) to wait for the running task count to change. If the running task count has not changed for the specified period of time, then the CLI times out and returns an error. Setting the timeout to 0 causes the command to return without checking for success. The default timeout value is 5 minutes.

rm, delete, down [--timeout value]

将服务的预期数量更新为 0，然后删除服务。

The --timeout option specifies the timeout value in minutes (decimals supported) to wait for the running task count to change. If the running task count has not changed for the specified period of time, then the CLI times out and returns an error. Setting the timeout to 0 causes the command to return without checking for success. The default timeout value is 5 minutes.

帮助

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

示例

示例 1

此示例将启动 hello-world 复合文件中的项目名称为 hello-world.yml 的 ECS 服务。 

ecs-cli compose --project-name hello-world --file hello-world.yml service up

输出:

INFO[0000] Using ECS task definition                     TaskDefinition="ecscompose-hello-world:7"
INFO[0000] Created an ECS service                        service=ecscompose-service-hello-world taskDefinition="ecscompose-hello-world:7"
INFO[0000] Updated ECS service successfully              desiredCount=1 serviceName=ecscompose-service-hello-world
INFO[0015] (service ecscompose-service-hello-world) has started 1 tasks: (task 682dc22f-8bfa-4c28-b6f8-3a916bd8f86a).  timestamp=2017-08-18 21:16:00 +0000 UTC
INFO[0060] Service status                                desiredCount=1 runningCount=1 serviceName=ecscompose-service-hello-world
INFO[0060] ECS Service has reached a stable state        desiredCount=1 runningCount=1 serviceName=ecscompose-service-hello-world

示例 2

此示例将由 hello-world 项目创建的服务扩展至预期数量 2。 

ecs-cli compose --project-name hello-world --file hello-world.yml service scale 2

输出:

INFO[0000] Updated ECS service successfully              desiredCount=2 serviceName=ecscompose-service-hello-world
INFO[0000] Service status                                desiredCount=2 runningCount=1 serviceName=ecscompose-service-hello-world
INFO[0030] (service ecscompose-service-hello-world) has started 1 tasks: (task 80602da8-442c-48ea-a8a9-80328c302b89).  timestamp=2017-08-18 21:17:44 +0000 UTC
INFO[0075] Service status                                desiredCount=2 runningCount=2 serviceName=ecscompose-service-hello-world
INFO[0075] ECS Service has reached a stable state        desiredCount=2 runningCount=2 serviceName=ecscompose-service-hello-world

示例 3

此示例将由 hello-world 项目创建的服务扩展至预期数量 ，然后删除服务。0

ecs-cli compose --project-name hello-world --file hello-world.yml service rm

输出:

INFO[0000] Updated ECS service successfully              desiredCount=0 serviceName=ecscompose-service-hello-world
INFO[0000] Service status                                desiredCount=0 runningCount=2 serviceName=ecscompose-service-hello-world
INFO[0015] Service status                                desiredCount=0 runningCount=0 serviceName=ecscompose-service-hello-world
INFO[0015] (service ecscompose-service-hello-world) has stopped 2 running tasks: (task 682dc22f-8bfa-4c28-b6f8-3a916bd8f86a) (task 80602da8-442c-48ea-a8a9-80328c302b89).  timestamp=2017-08-18 21:25:28 +0000 UTC
INFO[0015] ECS Service has reached a stable state        desiredCount=0 runningCount=0 serviceName=ecscompose-service-hello-world
INFO[0015] Deleted ECS service                           service=ecscompose-service-hello-world
INFO[0015] ECS Service has reached a stable state        desiredCount=0 runningCount=0 serviceName=ecscompose-service-hello-world

示例 4

此示例将从 nginx-compose.yml 复合文件创建服务并将其配置为使用现有 应用程序负载均衡器。 

ecs-cli compose -f nginx-compose.yml service up --target-group-arn arn:aws:elasticloadbalancing:us-east-1:aws_account_id:targetgroup/ecs-cli-alb/9856106fcc5d4be8 --container-name nginx --container-port 80 --role ecsServiceRole

示例 5

此示例将从 nginx-compose.yml 复合文件创建服务并将其配置为使用运行状况检查宽限期为 25 秒的现有 应用程序负载均衡器。 

ecs-cli compose -f nginx-compose.yml service up --target-group-arn arn:aws:elasticloadbalancing:us-east-1:aws_account_id:targetgroup/ecs-cli-alb/9856106fcc5d4be8 --container-name nginx --container-port 80 --role ecsServiceRole --health-check-grace-period 25