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

Running Tasks

Running tasks manually is ideal in certain situations. For example, suppose that you are developing a task but you are not ready to deploy this task with the service scheduler. Perhaps your task is a one-time or periodic batch job that does not make sense to keep running or restart when it finishes.

To keep a specified number of tasks running or to place your tasks behind a load balancer, use the Amazon ECS service scheduler instead. For more information, see Services.

To run a task

  1. Open the Amazon ECS console at

  2. From the navigation bar, select the region that your cluster is in.

  3. In the navigation pane, choose Task Definitions and select the task definition to run.

    • To run the latest revision of a task definition shown here, select the box to the left of the task definition to run.

    • To run an earlier revision of a task definition shown here, select the task definition to view all active revisions, then select the revision to run.

  4. Choose Actions, Run Task.

  5. For Cluster, choose the cluster to use. For Number of tasks, type the number of tasks to launch with this task definition. For Task Group, type the name of the task group.

  6. (Optional) For Task Placement, you can specify how tasks are placed using task placement strategies and constraints. Choose from the following options:

    • AZ Balanced Spread - distribute tasks across Availability Zones and across container instances in the Availability Zone.

    • AZ Balanced BinPack - distribute tasks across Availability Zones and across container instances with the least available memory.

    • BinPack - distribute tasks based on the least available amount of CPU or memory.

    • One Task Per Host - place, at most, one task from the service on each container instance.

    • Custom - define your own task placement strategy. See Amazon ECS Task Placement for examples.

    For more information, see Amazon ECS Task Placement.

  7. (Optional) To send command or environment variable overrides to one or more containers in your task definition, or to specify an IAM role task override, choose Advanced Options and complete the following steps:

    1. For Task Role Override, choose an IAM role that provides permissions for containers in your task to make calls to AWS APIs on your behalf. For more information, see IAM Roles for Tasks.

      Note that only roles with the Amazon EC2 Container Service Task Role trust relationship are shown here. For more information about creating an IAM role for your tasks, see Creating an IAM Role and Policy for your Tasks.

    2. For Container Overrides, choose a container to which to send a command or environment variable override.

      • For a command override: For Command override, type the command override to send. If your container definition does not specify an ENTRYPOINT, the format should be a comma-separated list of non-quoted strings. For example:


        If your container definition does specify an ENTRYPOINT (such as sh,-c), the format should be an unquoted string, which is surrounded with double quotes and passed as an argument to the ENTRYPOINT command. For example:

        while true; do echo $DATE > /var/www/html/index.html; sleep 1; done
      • For environment variable overrides: Choose Add Environment Variable. For Key, type the name of your environment variable. For Value, type a string value for your environment value (without surrounding quotes).

                                        Environment variable override

        This environment variable override is sent to the container as:

        MY_ENV_VAR="This variable contains a string."
  8. Review your task information and choose Run Task.


    If your task moves from PENDING to STOPPED, or if it displays a PENDING status and then disappears from the listed tasks, your task may be stopping due to an error. For more information, see Checking Stopped Tasks for Errors in the troubleshooting section.