Running tasks in your apps

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 VMware Tanzu Application Service for VMs (TAS for VMs).

About Tasks

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, Cloud Foundry 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.

Note: Running a task consumes an app instance and is billed accordingly.

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

How tasks are run

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

The lifecycle of a task is as follows:

A user initiates a task in TAS for VMs using one of the following mechanisms:
- The cf run-task APP-NAME "TASK" command. For more information, see Running tasks in your apps.
- A Cloud Controller v3 API call. For more information, see the Cloud Foundry API documentation.
- The Cloud Foundry Java Client. For more information, see Cloud Foundry Java Client Library and the Cloud Foundry Java Client repository on GitHub.
Cloud Foundry creates a container specifically for the task.
Cloud Foundry runs the task on the container using the value passed to the cf run-task command.
Cloud Foundry destroys the container.

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

Important You cannot SSH into the container running a task.

Task logging and execution history

Any data or messages the task outputs to STDOUT or STDERR is available on the app’s firehose logs. A syslog drain attached to the app receives the task log output.

The task execution history is retained for one month.

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 List tasks in the Cloud Foundry API documentation.

Admins can set the default memory and disk usage quotas for tasks on a global level. Tasks use the same memory and disk usage defaults as apps unless customized using run-task in the cf CLI.

You configure the default memory and disk allocations using the Default app memory and Default disk quota per app fields in the App Developer Controls pane of the VMware Tanzu Application Service for VMs (TAS for VMs) tile.

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.

Important

To run tasks with the cf CLI, you must install cf CLI v6.23.0 or later, or install cf CLI v7. To download, install, and uninstall the cf CLI, see Installing the Cloud Foundry Command Line Interface.
To run a task using cf CLI v6 without starting the app, push the app with cf push -i 0 and then run the task. You can run the app later by scaling up its instance count.

Run a task on an app with cf CLI v6

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

Push your app by running:
```
cf push APP-NAME
```

Run your task on the deployed app by running:

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

The following example runs a database migration as a task on the my-app app:

$ cf run-task my-app "bin/rails db:migrate" --name my-task
Creating task for app my-app in org jdoe-org / space development as [email protected]...
OK
Task 1 has been submitted successfully for execution.

Important To re-run a task, you must run it as a new task using the command shown earlier in this topic.

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

cf logs APP-NAME --recent

The following example displays the logs of a successful task:

$ cf logs my-app --recent
2017-01-03T15:58:06.57-0800 [APP/TASK/my-task/0]OUT Creating container
2017-01-03T15:58:08.45-0800 [APP/TASK/my-task/0]OUT Successfully created container
2017-01-03T15:58:13.32-0800 [APP/TASK/my-task/0]OUT D, [2017-01-03T23:58:13.322258 #7] DEBUG -- :    (15.9ms)  CREATE TABLE "schema_migrations" ("version" character varying PRIMARY KEY)
2017-01-03T15:58:13.33-0800 [APP/TASK/my-task/0]OUT D, [2017-01-03T23:58:13.337723 #7] DEBUG -- :    (11.9ms)  CREATE TABLE "ar_internal_metadata" ("key" character varying PRIMARY KEY, "value" character varying, "created_at" timestamp NOT NULL, "updated_at" timestamp NOT NULL)
2017-01-03T15:58:13.34-0800 [APP/TASK/my-task/0]OUT D, [2017-01-03T23:58:13.340234 #7] DEBUG -- :    (1.6ms)  SELECT pg_try_advisory_lock(3720865444824511725);
2017-01-03T15:58:13.35-0800 [APP/TASK/my-task/0]OUT D, [2017-01-03T23:58:13.351853 #7] DEBUG -- :   ActiveRecord::SchemaMigration Load (0.7ms)  SELECT "schema_migrations".* FROM "schema_migrations"
2017-01-03T15:58:13.35-0800 [APP/TASK/my-task/0]OUT I, [2017-01-03T23:58:13.357294 #7]  INFO -- : Migrating to Createtopics (20161118225627)
2017-01-03T15:58:13.35-0800 [APP/TASK/my-task/0]OUT D, [2017-01-03T23:58:13.359565 #7] DEBUG -- :    (0.5ms)  BEGIN
2017-01-03T15:58:13.35-0800 [APP/TASK/my-task/0]OUT == 20161118225627 Createtopics: migrating ===================================
2017-01-03T15:58:13.50-0800 [APP/TASK/my-task/0]OUT Exit status 0
2017-01-03T15:58:13.56-0800 [APP/TASK/my-task/0]OUT Destroying container
2017-01-03T15:58:15.65-0800 [APP/TASK/my-task/0]OUT Successfully destroyed container

The following example displays the logs of a failed task:

$ cf logs my-app --recent
2016-12-14T11:09:26.09-0800 [APP/TASK/my-task/0]OUT Creating container
2016-12-14T11:09:28.43-0800 [APP/TASK/my-task/0]OUT Successfully created container
2016-12-14T11:09:28.85-0800 [APP/TASK/my-task/0]ERR bash: bin/rails: command not found
2016-12-14T11:09:28.85-0800 [APP/TASK/my-task/0]OUT Exit status 127
2016-12-14T11:09:28.89-0800 [APP/TASK/my-task/0]OUT Destroying container
2016-12-14T11:09:30.50-0800 [APP/TASK/my-task/0]OUT Successfully destroyed container

If your task name is unique, you can `grep` the output of the `cf logs` command for the task name to view task-specific logs.

Run a task on an app with cf CLI v7

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

Configure your v3 API manifest with a task as a process type. For more information, see The app manifest specification in the Cloud Foundry API documentation.
Push your app by running:
```
cf push APP-NAME --task
```
Run your task on the deployed app by running:
```
cf run-task APP-NAME --name TASK-NAME
```
Where:
- APP-NAME is the name of your app.
- TASK-NAME is the name you want to give the task.
Note cf run-task allows you to include the --process and --command flags. Including the --command flag overrides the manifest property.

The following example command runs a task on the example-app app:
```
$ cf run-task my-app --name my-task
Creating task for app my-app in org jdoe-org / space development as [email protected]...
OK
Task 1 has been submitted successfully for execution.
```
To display the recent logs of the app and all its tasks, run:
```
cf logs APP-NAME --recent
```

List tasks running on an app

To list the tasks for a given app, run cf tasks APP-NAME. For example:

$ cf tasks my-app
Getting tasks for app my-app in org jdoe-org / space development as [email protected]...
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

Each task has one of the following states:

State	Description
RUNNING	The task is currently 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.

Cancel a task

After running a task, you may be able to cancel it before it finishes. To cancel a running task, run cf terminate-task APP-NAME TASK-ID. For example:

$ cf terminate-task my-app 2
Terminating task 2 of app my-app in org jdoe-org / space development as [email protected]...
OK