Page last updated:
Warning: Pivotal Cloud Foundry (PCF) v2.4 is no longer supported because it has reached the End of General Support (EOGS) phase as defined by the Support Lifecycle Policy. To stay up to date with the latest software and security updates, upgrade to a supported version.
Page last updated:
This topic describes how to run tasks in Cloud Foundry. A task is an app or script whose code is included as part of a deployed app, but runs independently in its own container.
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 will be billed accordingly.
Tasks are used to perform one-off jobs, which include the following:
- 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
Tasks are always executed 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:
A user initiates a task in Cloud Foundry using one of the following mechanisms:
cf run-task APPNAME "TASK"command. See the Running Tasks section of this topic for more information.
- Cloud Controller v3 API call. See the Tasks API reference page for more information.
- Cloud Foundry Java Client. See the Cloud Foundry Java Client Library and Cloud Foundry Java Client topics for more information.
Cloud Foundry creates a container specifically for the task.
Cloud Foundry runs the task on the container using the value passed to the
Cloud Foundry destroys the container.
The container also inherits environment variables, service bindings, and security groups bound to the app.
Note: 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.
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 documentation for the Cloud Controller v3 API.
In addition, admins can set the default memory and disk usage quotas for tasks on a global level. Initially, tasks use the same memory and disk usage defaults as apps. However, the default memory and disk allocations for tasks can be defined separately from the default app memory and disk allocations.
The default memory and disk allocations are defined using the Default App Memory and Default Disk Quota per App fields. These fields are available in the Application Developer Controls configuration screen of Pivotal Application Service (PAS).
You can use the Cloud Foundry Command Line Interface (cf CLI) to run a task in the context of an app.
Note: To run tasks with the cf CLI, you must install cf CLI v6.23.0 or later. See the Installing the Cloud Foundry Command Line Interface topic for information about downloading, installing, and uninstalling the cf CLI.
Note: To run a task 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.
To run a task on an app, perform the following steps:
- Push your app:
$ cf push APP-NAME
- Run your task on the deployed app:
$ cf run-task APP-NAME "TASK" --name TASK-NAME
The following example runs a database migration as a task on the
$ 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@example.com... OK Task 1 has been submitted successfully for execution.
Note: To re-run a task, you must run it as a new task using the above command.
cf logs APP-NAME --recent command to display the recent logs of the app and all its tasks.
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 CreateArticles (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 CreateArticles: 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.
To list the tasks for a given app, run the
cf tasks APP-NAME. For example:
$ cf tasks my-app Getting tasks for app my-app in org jdoe-org / space development as firstname.lastname@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
Each task has one of the following states:
|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.|
After running a task, you may be able to cancel it before it finishes. To cancel a running task, use the
cf terminate-task APP-NAME TASK-ID command. For example:
$ cf terminate-task my-app 2 Terminating task 2 of app my-app in org jdoe-org / space development as email@example.com... OK