forked from cloudfoundry/docs-dev-guide
-
Notifications
You must be signed in to change notification settings - Fork 0
/
using-tasks.html.md.erb
201 lines (143 loc) · 9.28 KB
/
using-tasks.html.md.erb
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
---
title: Running Tasks
owner: CAPI/CLI
---
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.
## <a id='about-tasks'></a> 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.
<%= 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 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:
1. A user initiates a task in Cloud Foundry using one of the following mechanisms:
* The `cf run-task APPNAME "TASK"` command. For more information, see [Running Tasks](#run-tasks).
* A Cloud Controller v3 API call. For more information, see [Tasks](http://v3-apidocs.cloudfoundry.org/version/3.0.0/index.html#tasks) in the Cloud Foundry API documentation.
* 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. Cloud Foundry creates a container specifically for the task.
1. Cloud Foundry runs the task on the container using the value passed to the `cf run-task` command.
1. Cloud Foundry destroys the container.
The container also inherits environment variables, service bindings, and security groups bound to the app.
<p class="note"><strong>Note:</strong> You cannot SSH into the container running a task.</p>
### <a id='task-logging-execution-history'></a> 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.
## <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 [List tasks](http://v3-apidocs.cloudfoundry.org/version/3.0.0/index.html#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](https://cli.cloudfoundry.org/en-US/v7/run-task.html) in the cf CLI.
<% if vars.platform_code == 'PCF' %>
<%= partial '/pcf/core/2-7/tasks_rec_alloc_pcf' %>
<% else %>
<%= partial 'tasks_rec_alloc_oss' %>
<% end %>
## <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"><strong>Note:</strong> To run tasks with the cf CLI, you must install cf CLI v6.23.0 or later, or install cf CLI v7. For information about downloading, installing, and uninstalling the cf CLI., see <a href="../cf-cli/install-go-cli.html">Installing the Cloud Foundry Command Line Interface</a>.</p>
<p class="note"><strong>Note:</strong> To run a task on v6 cf CLI without starting the app, push the app with <code>cf push -i 0</code> and then run the task. You can run the app later by scaling up its instance count.</p>
### <a id='run-tasks-v6'></a> Run a Task on an App with cf CLI v6
To run a task on an app with cf CLI v6:
1. Push your app by running:
```
cf push APP-NAME
```
1. 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:
<pre class="terminal">
$ 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.
</pre>
<p class="note"><strong>Note:</strong> To re-run a task, you must run it as a new task using the above command.</p>
1. 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:
<pre class="terminal">
$ 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
</pre>
The following example displays the logs of a failed task:
<pre class="terminal">
$ 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
</pre>
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.
### <a id='run-tasks-v7'></a> Run a Task on an App with cf CLI v7
To run a task on an app with cf CLI v7:
1. Configure your v3 API manifest with a task as a process type. For more information, see [The app manifest specification](https://v3-apidocs.cloudfoundry.org/version/3.78.0/index.html#the-app-manifest-specification) in the Cloud Foundry API documentation.
1. Push your app by running:
```
cf push APP-NAME --task
```
1. Run your task on the deployed app by running:
```
cf run-task APP-NAME --name TASK-NAME
```
<p class="note"><strong>Note:</strong> <code>cf run-task</code> allows the optional flags <code>--process</code> and <code>--command</code>. If provided, <code>--command</code> overrides the manifest property.</p>
The following example runs a database migration as a task on the `my-app` app:
<pre class="terminal">
$ 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.
</pre>
1. To display the recent logs of the app and all its tasks, run:
```
cf logs APP-NAME --recent
```
## <a id='list-tasks'></a> List Tasks Running on an App
To list the tasks for a given app, run `cf tasks APP-NAME`. For example:
<pre class="terminal">
$ 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
</pre>
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. |
## <a id='cancel-task'></a> 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:
<pre class="terminal">
$ cf terminate-task my-app 2
Terminating task 2 of app my-app in org jdoe-org / space development as [email protected]...
OK
</pre>