Amazon Elastic Container Service
Developer Guide (API Version 2014-11-13)

ecs-cli compose service

Manage Amazon ECS services with docker-compose-style commands on an ECS cluster. For more information on how Docker compose file syntax works with the ECS CLI, see Using Docker Compose File Syntax.

Note

To run tasks with the Amazon ECS CLI instead of creating services, see ecs-cli compose.

The ecs-cli compose service command uses a project name with the task definitions and services that it creates. When the Amazon ECS CLI creates a task definition and service from a compose file, the task definition and service are called project-name. By default, the project name is the name of the directory that contains your Docker compose file. However, you can also specify your own project name with the --project-name option.

Note

The Amazon ECS CLI can only manage tasks, services, and container instances that were created with the Amazon ECS CLI. To manage tasks, services, and container instances that were not created by the Amazon ECS CLI, use the AWS Command Line Interface or the AWS Management Console.

Important

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

Syntax

ecs-cli compose [--verbose] [--file compose_file] [--project-name project_name] [--task-role-arn task_role_arn] [--ecs-params ecs_params_file] [--region region] [--cluster-config cluster_config_name] [--ecs-profile ecs_profile] [--aws-profile aws_profile] [--cluster cluster_name] [--help] service [subcommand] [arguments] [--help]

Options

Name Description

--verbose, --debug

Increases the verbosity of command output to aid in diagnostics.

Required: No

--file, -f compose_file

Specifies the Docker compose file to use. At this time, the latest version of the Amazon ECS CLI supports Docker compose file syntax versions 1, 2, and 3. If the COMPOSE_FILE environment variable is set when ecs-cli compose is run, then the Docker compose file is set to the value of that environment variable.

Type: String

Default: ./docker-compose.yml

Required: No

--project-name, -p project_name

Specifies the project name to use. If the COMPOSE_PROJECT_NAME environment variable is set when ecs-cli compose is run, then the project name is set to the value of that environment variable.

Type: String

Default: The current directory name.

Required: No

--task-role-arn role_value

Specifies the short name or full Amazon Resource Name (ARN) of the IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.

Type: String

Required: No

--ecs-params ecs_params_file

Specifies the ECS parameters that are not native to Docker compose files. For more information, see Using Amazon ECS Parameters.

Default: ./ecs-params.yml

Required: No

--region, -r region

Specifies the AWS Region to use. Defaults to the cluster configured using the configure command.

Type: String

Required: No

--cluster-config cluster_config_name

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

Type: String

Required: No

--ecs-profile ecs_profile

Specifies the name of the Amazon 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, -c cluster_name

Specifies the Amazon ECS cluster name to use. Defaults to the cluster configured using the configure command.

Type: String

Required: No

--help, -h

Shows the help text for the specified command.

Required: No

Available Subcommands

The ecs-cli compose service command supports the following subcommands. Each of these subcommands has their own flags associated with them, which can be displayed using the --help flag.

create

Creates an Amazon ECS service from your compose file. The service is created with a desired count of 0, so no containers are started by this command. For more information, see ecs-cli compose service create.

start

Starts one copy of each of the containers on the created Amazon ECS service. This command updates the desired count of the service to 1. For more information, see ecs-cli compose service start.

up

Creates an Amazon ECS service from your compose file (if it does not already exist) and runs one instance of that task on your cluster (a combination of create and start). This command updates the desired count of the service to 1. For more information, see ecs-cli compose service up.

ps, list

Lists all the containers in your cluster that belong to the service created with the compose project. For more information, see ecs-cli compose service ps, list.

scale

Scales the desired count of the service to the specified count. For more information, see ecs-cli compose service scale.

stop

Stops the running tasks that belong to the service created with the compose project. This command updates the desired count of the service to 0. For more information, see ecs-cli compose service stop.

rm, delete, down

Updates the desired count of the service to 0 and then deletes the service. For more information, see ecs-cli compose service rm, delete, down.