using-tasks.html.md.erb

---
title: Running tasks in your apps
owner: CAPI/CLI
---

A task is an app or script, the code of which is included as part of a deployed app, but runs
independently in its own container. This topic describes how to run tasks in <%= vars.app_runtime_first %>.


## <a id='about-tasks'></a> Tasks in <%= vars.app_runtime_abbr %>

In contrast to a long-running process (LRP), tasks run for a finite amount of time, then stop. Tasks run in their own containers and are designed to use minimal resources. After a task runs, <%= vars.app_runtime_abbr %> destroys the container running the task.

As a single use object, a task can be checked for its state and for a success or failure message.

<%= vars.tasks_ai %>

### <a id='use-cases'></a> Use cases for tasks

Tasks are used to perform one-off jobs, which include:

* Migrating a database
* Sending an email
* Running a batch job
* Running a data processing script
* Processing images
* Optimizing a search index
* Uploading data
* Backing-up data
* Downloading content

### <a id='task-processes'></a> How tasks are run

Tasks are always run asynchronously, meaning that they run independently from the parent app or other tasks that run on the same app.

The life cycle of a task is as follows:

1. A user initiates a task in <%= vars.app_runtime_abbr %> using one of the following mechanisms:
   * The `cf run-task APP-NAME "TASK"` command. For more information, see [Running tasks in your apps](#run-tasks).
   * A Cloud Controller v3 API call. For more information, see the [Cloud Foundry API documentation](http://v3-apidocs.cloudfoundry.org/version/3.0.0/index.html#tasks).
   * The Cloud Foundry Java Client. For more information, see [Cloud Foundry Java Client Library](../buildpacks/java/java-client.html) and the [Cloud Foundry Java Client](https://github.com/cloudfoundry/cf-java-client) repository on GitHub.

1. <%= vars.app_runtime_abbr %> creates a container specifically for the task.

1. <%= vars.app_runtime_abbr %> runs the task on the container using the value passed to the `cf run-task` command.

1. <%= vars.app_runtime_abbr %> destroys the container.

The container also inherits environment variables, service bindings, and security groups bound to the app.

<p class="note">
<span class="note__title"><strong>Note</strong></span>
You cannot SSH into the container running a task.
</p>

### <a id='task-logging-execution'></a> Task logging and execution history

Any data or messages the task outputs to stdout or stderr is available in the firehose logs of the app. A syslog drain attached to the app receives the task log output.
The task execution history is retained for one month.


## <a id='manage-tasks'></a> Manage tasks

At the system level, a user with admin-level privileges can use the Cloud Controller v3 API to view all tasks that are running within an org or space. For
more information, see the [Cloud Foundry API documentation](http://v3-apidocs.cloudfoundry.org/version/3.0.0/index.html#list-tasks).

Admins can set the default memory, disk usage and log rate quotas for tasks on a global level.

Tasks use the same memory, disk usage, and log rate limit defaults as apps, unless you customize them using the `cf run-task` command.
For more information about the `cf run-task` command, enter `cf help run-task`.

<%= partial 'tasks_rec_alloc_oss' %>


## <a id='run-tasks'></a> Run a task on an app

You can use the Cloud Foundry Command Line Interface (cf CLI) to run a task in the context of an app.

<p class="note important">
<span class="note__title"><strong>Important</strong></span>
To run tasks with the cf CLI, you must install cf CLI v8. To download, install, and uninstall the cf CLI, see <a href="../cf-cli/install-go-cli.html">Installing the Cloud Foundry Command Line Interface</a>.</li>
</p>


### <a id='run-tasks'></a> Run a task on an app with cf CLI

To run a task on an app with cf CLI v8:

1. Configure your v3 API manifest with a task as a process type. For more information, see the [Cloud Foundry API documentation](https://v3-apidocs.cloudfoundry.org/version/3.78.0/index.html#the-app-manifest-specification).

1. In a terminal, push your app by running:

    ```
    cf push APP-NAME --task
    ```
    Where `APP-NAME` is the name of your app.

1. Run your task on the deployed app by running:

    ```
    cf run-task APP-NAME --name TASK-NAME
    ```

    Where:
    <ul>
      <li><code>APP-NAME</code> is the name of your app.</li>
      <li><code>TASK-NAME</code> is the name you want to give the task.</li>
    </ul>

    <p class="note important">
    <span class="note__title"><strong>Important</strong></span>
    <code>cf run-task</code> allows you to include the <code>--process</code> and <code>--command</code> flags. Including  the <code>--command</code> flag overrides the manifest property.
    </p>

    The following example command runs a task on the `example-app` app:

    <pre class="terminal">
    cf run-task example-app --name example-task
    </pre>

    When the task runs successfully, you see terminal output similar to the following example:
    <pre class="terminal">
    Creating task for app example-app in org example-org / space development as admin@example.org...
    OK
    Task 1 has been submitted successfully for execution.
    </pre>

1. To display the recent logs of the app and all its tasks, run:

    ```
    cf logs APP-NAME --recent
    ```
    Where `APP-NAME` is the name of your app.

## <a id='get-task'></a> Get a task for an app

To get a task for a given app:

1. In a terminal window, run:

    ```
    cf task APP-NAME TASK-ID
    ```

    Where `APP-NAME` is the name of your app and `TASK-ID` is the ID of the task you want to get.

    The command returns output similar to the following example:

    <pre class="terminal">
    Getting task 4 for app static in org org-1 / space space-1 as admin...

    id:               4
    name:             125c884d
    state:            FAILED
    start time:       2024-11-22T17:41:19Z
    command:          custom_command
    memory in mb:     256
    disk in mb:       1024
    log rate limit:   -1
    failure reason:   APP/TASK/125c884d: Exited with status 127
    </pre>

Tasks can be in the states shown in the following table:

| State | Description |
| ----- | ----------- |
| `RUNNING` | The task is in progress. |
| `FAILED` | The task did not complete. This state occurs when a task does not work correctly or a user cancels the task. |
| `SUCCEEDED` | The task completed successfully. |


## <a id='list-tasks'></a> List tasks running on an app

To list the tasks for a given app:

1. In a terminal window, run:

    ```
    cf tasks APP-NAME
    ```
    Where `APP-NAME` is the name of your app. The command returns output similar to the following example:
    <pre class="terminal">
    Getting tasks for app example-app in org example-org / space development as admin@example.org...
    OK

    id   name       state       start time                      command
    2    339044ef   FAILED      Wed, 23 Nov 2016 21:52:52 UTC   echo foo; sleep 100; echo bar
    1    8d0618cf   SUCCEEDED   Wed, 23 Nov 2016 21:37:28 UTC   bin/rails db:migrate
    </pre>

Tasks can be in these states:

| State | Description |
| ----- | ----------- |
| `RUNNING` | The task is in progress. |
| `FAILED` | The task did not complete. This state occurs when a task does not work correctly or a user cancels the task. |
| `SUCCEEDED` | The task completed successfully. |


## <a id='cancel-task'></a> Cancel a task

After you run a task, you might be able to cancel it before it finishes.

To cancel a running task:

1. In a terminal window, run:

    ```
    cf terminate-task APP-NAME TASK-ID
    ```
    Where:
    <ul>
      <li><code>APP-NAME</code> is the name of your app.</li>
      <li><code>TASK-NAME</code> is the name you want to give the task.</li>
    </ul>

    The previous command returns output similar to the following example:
    <pre class="terminal">
    Terminating task 2 of app example-app in org example-org / space development as admin@example.org...
    OK
    </pre>