Skip to content

Commit 41889d8

Browse files
slackslack
committed
doc(processes): move process stuff under one roof
1 parent c78e2c1 commit 41889d8

2 files changed

Lines changed: 155 additions & 136 deletions

File tree

‎src/applications/managing-app-lifecycle.md‎

Lines changed: 0 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,92 +1,5 @@
11
# Managing an Application
22

3-
## Scaling an Application
4-
5-
Applications deployed on Deis [scale out via the process model][]. Use `deis scale` to control the number of
6-
[Containers][container] that power your app.
7-
8-
```
9-
$ deis scale cmd=5 -a iciest-waggoner
10-
Scaling processes... but first, coffee!
11-
done in 3s
12-
=== iciest-waggoner Processes
13-
--- cmd:
14-
iciest-waggoner-v2-cmd-09j0o up (v2)
15-
iciest-waggoner-v2-cmd-3r7kp up (v2)
16-
iciest-waggoner-v2-cmd-gc4xv up (v2)
17-
iciest-waggoner-v2-cmd-lviwo up (v2)
18-
iciest-waggoner-v2-cmd-kt7vu up (v2)
19-
```
20-
21-
If you have multiple process types for your application you may scale the process count for each type separately. For
22-
example, this allows you to manage web process indepenetly from background workers. For more information on process
23-
types see our documentation for [Managing App Processes](managing-app-processes.md).
24-
25-
In this example, we are scaling the process type `web` to 5 but leaving the process type `background` with one worker.
26-
27-
```
28-
$ deis scale web=5
29-
Scaling processes... but first, coffee!
30-
done in 4s
31-
=== scenic-icehouse Processes
32-
--- web:
33-
scenic-icehouse-v2-web-7lord up (v2)
34-
scenic-icehouse-v2-web-jn957 up (v2)
35-
scenic-icehouse-v2-web-rsekj up (v2)
36-
scenic-icehouse-v2-web-vwhnh up (v2)
37-
scenic-icehouse-v2-web-vokg7 up (v2)
38-
--- background:
39-
scenic-icehouse-v2-background-yf8kh up (v2)
40-
```
41-
42-
!!! note
43-
The default process type for Dockerfile and Docker Image applications is 'cmd' rather than 'web'.
44-
45-
Scaling a process down, by reducing the process count, sends a `TERM` signal to the processes, followed by a `SIGKILL`
46-
if they have not exited within 30 seconds. Depending on your application, scaling down may interrupt long-running HTTP
47-
client connections.
48-
49-
For example, scaling from 5 processes to 3:
50-
51-
```
52-
$ deis scale web=3
53-
Scaling processes... but first, coffee!
54-
done in 1s
55-
=== scenic-icehouse Processes
56-
--- background:
57-
scenic-icehouse-v2-background-yf8kh up (v2)
58-
--- web:
59-
scenic-icehouse-v2-web-7lord up (v2)
60-
scenic-icehouse-v2-web-rsekj up (v2)
61-
scenic-icehouse-v2-web-vokg7 up (v2)
62-
```
63-
64-
## Restarting an Application Processes
65-
66-
If you need to restart an application process, you may use `deis ps:restart`. Behind the scenes, Deis Workflow instructs
67-
Kubernetes to terminate the old process and launch a new one in its place.
68-
69-
```
70-
$ deis ps
71-
=== scenic-icehouse Processes
72-
--- web:
73-
scenic-icehouse-v2-web-7lord up (v2)
74-
scenic-icehouse-v2-web-rsekj up (v2)
75-
scenic-icehouse-v2-web-vokg7 up (v2)
76-
--- background:
77-
scenic-icehouse-v2-background-yf8kh up (v2)
78-
$ deis ps:restart scenic-icehouse-v2-background-yf8kh
79-
Restarting processes... but first, coffee!
80-
done in 6s
81-
=== scenic-icehouse Processes
82-
--- background:
83-
scenic-icehouse-v2-background-yd87g up (v2)
84-
```
85-
86-
Notice that the process name has changed from `scenic-icehouse-v2-background-yf8kh` to
87-
`scenic-icehouse-v2-background-yd87g`. In a multi-node Kubernetes cluster, this may also have the effect of scheduling
88-
the Pod to a new node.
89-
903
## Track Application Changes
914

925
Deis Workflow tracks all changes to your application. Application changes are the result of either new application code

‎src/applications/managing-app-processes.md‎

Lines changed: 155 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -1,27 +1,25 @@
1-
# Process Types and the Procfile
1+
# Managing Application Processes
22

3-
Deis Workflow observes the [process model][]. As part of this model, a Procfile may be used as a
4-
mechanism for declaring the commands that should be run by your application’s containers. You can
5-
use a Procfile to declare multiple processes for different types of application workers-- for
6-
example, an application server, a job execution timer, or a consumer of the Twitter streaming API.
3+
Deis Workflow manages your application as a set of processes that can be named, scaled and configured according to their
4+
role. This gives you the flexiblity to easily manage the different facets of your application. For example, you may have
5+
web-facing processes that handle HTTP traffic, background worker processes that do async work, and a helper process that
6+
streams from the Twitter API.
77

8-
Multiple process types can be scaled independently of one another. When you first deploy your application
9-
only one `web` or `cmd` processes is spawned. To spawn other process types, use `deis scale <process>=<n>`
10-
to scale those processes accordingly.
8+
By using a Procfile, either checked in to your application or provided via the CLI you can specify the name of the type
9+
and the application command that should run. To spawn other process types, use `deis scale <type>=<n>` to scale those
10+
types accordingly.
1111

1212
## Default Process Types
1313

1414
In the absence of a Procfile, a single, default process type is assumed for each application.
1515

16-
All applications built using [Heroku's Buildpacks][buildpacks] implicitly declare a
17-
`web` process type, which starts the application server. Rails 4, for example, has the following
18-
process type:
16+
Applications built using [Buildpacks][buildpacks] via `git push` implicitly receive a `web` process type, which starts
17+
the application server. Rails 4, for example, has the following process type:
1918

2019
web: bundle exec rails server -p $PORT
2120

22-
All applications utilizing [Dockerfile deployments][dockerfile] have an implied `cmd`
23-
process type, which spawns the default process of a Docker image as specified by the
24-
`Dockerfile`'s `CMD` directive:
21+
All applications utilizing [Dockerfiles][dockerfile] have an implied `cmd` process type, which runs the
22+
Dockerfile's `CMD` directive unmodified:
2523

2624
$ cat Dockerfile
2725
FROM centos:latest
@@ -30,58 +28,140 @@ process type, which spawns the default process of a Docker image as specified by
3028
CMD python -m SimpleHTTPServer 5000
3129
EXPOSE 5000
3230

33-
For applications utilizing [Docker image deployments][docker image], a `cmd` process
34-
type is also implied and spawns the default process of the image.
31+
For the above Dockerfile-based application, the `cmd` process type would run the Docker `CMD` of `python -m SimpleHTTPServer 5000`.
3532

33+
Applications utilizing [remote Docker images][docker image], a `cmd` process type is also implied, and runs the `CMD`
34+
specified in the Docker image.
3635

37-
## Declaring Process Types
38-
39-
Developers utilizing [Heroku's Buildpacks][buildpacks] or [Dockerfile deployments][dockerfile] and
40-
wishing to override the implied, default process types, or declare additional process
41-
types may do so by including a file named `Procfile` in the root of their application's source
42-
tree.
36+
!!! note
37+
The `web` and `cmd` process types are special as they’re the only process types that will
38+
receive HTTP traffic from Workflow’s routers. Other process types can be named arbitrarily.
4339

44-
Developers utilizing [Docker image deployments][docker image] may accomplish this with a
45-
`Procfile` in their working directory or by referencing a `Procfile` using the `--procfile` option
46-
of the `deis pull` command. For example:
40+
## Declaring Process Types
4741

48-
$ deis pull deis/example-go:latest --procfile="cmd: /app/bin/boot"
42+
If you use [Buildpack][buildpacks] or [Dockerfile][dockerfile] builds and want to override or specify additional process
43+
types, simply include a file named `Procfile` in the root of your application's source tree.
4944

50-
The format of a `Procfile` is one process type per line, with each line containing:
45+
The format of a `Procfile` is one process type per line, with each line containing the command to invoke:
5146

5247
<process type>: <command>
5348

5449
The syntax is defined as:
5550

56-
`<process type>` – an alphanumeric string, is a name for your command, such as web, worker,
57-
urgentworker, clock, etc.
58-
59-
`<command>` – a command line to launch the process, such as `rake jobs:work`.
51+
* `<process type>` – an alphanumeric string, is a name for your command, such as web, worker, urgentworker, clock, etc.
52+
* `<command>` – a command line to launch the process, such as `rake jobs:work`.
53+
54+
This example Procfile specifies two types, `web` and `sleeper`. The `web` process launches a web server on port 5000 and
55+
a simple process which sleeps for 900 seconds and exits.
56+
57+
```
58+
$ cat Procfile
59+
web: bundle exec ruby web.rb -p ${PORT:-5000}
60+
sleeper: sleep 900
61+
```
62+
63+
If you are using [remote Docker images][docker image], you may define process types by either running `deis pull` with a
64+
`Procfile` in your working directory, or by passing a stringified Procfile to the `--procfile` CLI option.
65+
66+
For example:
67+
68+
```
69+
$ deis pull deis/example-go:latest --procfile="cmd: /app/bin/boot"
70+
```
71+
72+
Or via a Procfile:
73+
74+
```
75+
$ cat Procfile
76+
cmd: /bin/boot
77+
sleeper: echo "sleeping"; sleep 900
78+
$ deis pull -a steely-mainsail deis/example-go
79+
Creating build... done
80+
$ deis scale sleeper=1 -a steely-mainsail
81+
Scaling processes... but first, coffee!
82+
done in 0s
83+
=== steely-mainsail Processes
84+
--- cmd:
85+
steely-mainsail-v3-cmd-nyrim up (v3)
86+
--- sleeper:
87+
steely-mainsail-v3-sleeper-oq1jr up (v3)
88+
```
6089

6190
!!! note
62-
The `web` and `cmd` process types are special as they’re the only process types that will
63-
receive HTTP traffic from Workflow’s routers. Other process types can be named arbitrarily.
91+
Only process types of `web` and `cmd` will be scaled to 1 automatically. If you have additional process types
92+
remember to scale the process counts after creation.
6493

94+
To remove a process type simply scale it to 0:
6595

66-
## Scaling Processes
96+
```
97+
$ deis scale sleeper=0 -a steely-mainsail
98+
Scaling processes... but first, coffee!
99+
done in 3s
100+
=== steely-mainsail Processes
101+
--- cmd:
102+
steely-mainsail-v3-cmd-nyrim up (v3)
103+
```
67104

68-
Once an application has been deployed, its process types can be scaled independently of one
69-
another. For example, consider the following `Procfile`:
70-
71-
web: bundle exec rails server -p $PORT
72-
worker: bundle exec rake resque:work
73-
74-
Given the `Procfile` above, the `web` process could be scaled out:
75-
76-
$ deis scale web=5
77-
78-
And the `worker` process could be left alone, or scaled out independently, to whatever extent is
79-
required:
80-
81-
$ deis scale worker=3
105+
## Scaling Processes
82106

83-
Scaling a process type directly changes the number of [Containers][container] running that process.
107+
Applications deployed on Deis Workflow [scale out via the process model][]. Use `deis scale` to control the number of
108+
[Containers][container] that power your app.
109+
110+
```
111+
$ deis scale cmd=5 -a iciest-waggoner
112+
Scaling processes... but first, coffee!
113+
done in 3s
114+
=== iciest-waggoner Processes
115+
--- cmd:
116+
iciest-waggoner-v2-cmd-09j0o up (v2)
117+
iciest-waggoner-v2-cmd-3r7kp up (v2)
118+
iciest-waggoner-v2-cmd-gc4xv up (v2)
119+
iciest-waggoner-v2-cmd-lviwo up (v2)
120+
iciest-waggoner-v2-cmd-kt7vu up (v2)
121+
```
122+
123+
If you have multiple process types for your application you may scale the process count for each type separately. For
124+
example, this allows you to manage web process indepenetly from background workers. For more information on process
125+
types see our documentation for [Managing App Processes](managing-app-processes.md).
126+
127+
In this example, we are scaling the process type `web` to 5 but leaving the process type `background` with one worker.
128+
129+
```
130+
$ deis scale web=5
131+
Scaling processes... but first, coffee!
132+
done in 4s
133+
=== scenic-icehouse Processes
134+
--- web:
135+
scenic-icehouse-v2-web-7lord up (v2)
136+
scenic-icehouse-v2-web-jn957 up (v2)
137+
scenic-icehouse-v2-web-rsekj up (v2)
138+
scenic-icehouse-v2-web-vwhnh up (v2)
139+
scenic-icehouse-v2-web-vokg7 up (v2)
140+
--- background:
141+
scenic-icehouse-v2-background-yf8kh up (v2)
142+
```
84143

144+
!!! note
145+
The default process type for Dockerfile and Docker Image applications is 'cmd' rather than 'web'.
146+
147+
Scaling a process down, by reducing the process count, sends a `TERM` signal to the processes, followed by a `SIGKILL`
148+
if they have not exited within 30 seconds. Depending on your application, scaling down may interrupt long-running HTTP
149+
client connections.
150+
151+
For example, scaling from 5 processes to 3:
152+
153+
```
154+
$ deis scale web=3
155+
Scaling processes... but first, coffee!
156+
done in 1s
157+
=== scenic-icehouse Processes
158+
--- background:
159+
scenic-icehouse-v2-background-yf8kh up (v2)
160+
--- web:
161+
scenic-icehouse-v2-web-7lord up (v2)
162+
scenic-icehouse-v2-web-rsekj up (v2)
163+
scenic-icehouse-v2-web-vokg7 up (v2)
164+
```
85165

86166
## Web vs Cmd Process Types
87167

@@ -97,6 +177,32 @@ If migrating an application from Heroku Buildpacks to a Docker-based deployment,
97177
automatically convert the `web` process type to `cmd`. To do this, you'll have to manually scale
98178
down the old process type and scale the new process type up.
99179

180+
## Restarting an Application Processes
181+
182+
If you need to restart an application process, you may use `deis ps:restart`. Behind the scenes, Deis Workflow instructs
183+
Kubernetes to terminate the old process and launch a new one in its place.
184+
185+
```
186+
$ deis ps
187+
=== scenic-icehouse Processes
188+
--- web:
189+
scenic-icehouse-v2-web-7lord up (v2)
190+
scenic-icehouse-v2-web-rsekj up (v2)
191+
scenic-icehouse-v2-web-vokg7 up (v2)
192+
--- background:
193+
scenic-icehouse-v2-background-yf8kh up (v2)
194+
$ deis ps:restart scenic-icehouse-v2-background-yf8kh
195+
Restarting processes... but first, coffee!
196+
done in 6s
197+
=== scenic-icehouse Processes
198+
--- background:
199+
scenic-icehouse-v2-background-yd87g up (v2)
200+
```
201+
202+
Notice that the process name has changed from `scenic-icehouse-v2-background-yf8kh` to
203+
`scenic-icehouse-v2-background-yd87g`. In a multi-node Kubernetes cluster, this may also have the effect of scheduling
204+
the Pod to a new node.
205+
100206
[container]: ../reference-guide/terms.md#container
101207
[process model]: https://devcenter.heroku.com/articles/process-model
102208
[buildpacks]: ../applications/using-buildpacks.md

0 commit comments

Comments
 (0)