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

ecs-cli compose

Description

Manage Amazon ECS tasks with docker-compose-style commands on an ECS cluster.

Note

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

The ecs-cli compose command works with a Docker compose file to create task definitions and manage tasks. At this time, the latest version of the Amazon ECS CLI supports Docker compose file syntax versions 1 and 2. By default, the command looks for a compose file in the current directory, called docker-compose.yml. However, you can also specify a different file name or path to a compose file with the --file option. This is especially useful for managing tasks and services from multiple compose files at a time with the Amazon ECS CLI.

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 ecscompose-project-name. When the CLI creates a service from a compose file, the service is called ecscompose-service-project-name. By default, the project name is the name of the current working directory. 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 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.

The following parameters are supported in compose files for the Amazon ECS CLI:

  • cap_add

  • cap_drop

  • command

  • cpu_shares

  • dns

  • dns_search

  • entrypoint

  • environment: If an environment variable value is not specified in the compose file, but it exists in the shell environment, the shell environment variable value is passed to the task definition that is created for any associated tasks or services.

    Important

    We do not recommend using plaintext environment variables for sensitive information, such as credential data.

  • env_file

    Important

    We do not recommend using plaintext environment variables for sensitive information, such as credential data.

  • extra_hosts

  • hostname

  • image

  • labels

  • links

  • log_driver (Compose file version 1 only)

  • log_opt (Compose file version 1 only)

  • logging (Compose file version 2 only)

    • driver

    • options

  • mem_limit (in bytes)

  • mem_reservation (in bytes)

  • ports

  • privileged

  • read_only

  • security_opt

  • ulimits

  • user

  • volumes

  • volumes_from

  • working_dir

Important

The build directive is not supported at this time.

For more information about Docker compose file syntax, see the Compose file reference in the Docker documentation.

Syntax

ecs-cli compose [--verbose] [--file compose-file] [--project-name project-name] [--task-role-arn role_value] [--cluster cluster_name] [--region region] [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 and 2. 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

--cluster, -c cluster_name

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

Type: String

Required: No

--region, -r region

Specifies the AWS region 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:

create

Creates an ECS task definition from your compose file.

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.

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)

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.

Examples

Example 1

This example creates a task definition with the project name hello-world from the hello-world.yml compose file.

Copy
ecs-cli compose --project-name hello-world --file hello-world.yml create

Output:

INFO[0000] Using ECS task definition                     TaskDefinition=ecscompose-hello-world:5