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

ecs-cli compose

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

Note

To create Amazon ECS services with the Amazon ECS CLI, see ecs-cli compose service.

The ecs-cli compose command uses a project name with the task definitions and services it creates. When the CLI creates a task definition from a compose file, the task definition is called project-name. When the CLI creates a service from a compose file, the service is called service-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. For more information about obtaining 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] [--registry-creds value] [--region region] [--cluster-config cluster_config_name] [--ecs-profile ecs_profile] [--aws-profile aws_profile] [--cluster cluster_name] [--help] [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

--registry-creds value

Specifies the ECS registry credentials file to use. Defaults to the latest output file from the ecs-cli registry-creds up command, if one exists. For more information, see ecs-cli registry-creds.

Default: ./ecs-registry-creds_[TIMESTAMP].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 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 task definition from your compose file. For more information, see ecs-cli compose create.

ps, list

Lists all the containers in your cluster that were started by the compose project.

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

Starts all containers overriding commands with the supplied one-off commands for the containers.

scale n

Scales the number of running tasks to the specified count.

start

Starts a single task from the task definition created from your compose file. For more information, see ecs-cli compose start.

stop, down

Stops all the running tasks created by the compose project.

up

Creates an ECS task definition 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). For more information, see ecs-cli compose up.

service [subcommand]

Creates an ECS service from your compose file. For more information, see ecs-cli compose service.

help

Shows the help text for the specified command.