Skip to content

Commit 8e5bff2

Browse files
mboersmamboersma
committed
docs(scheduler): describe fleet and swarm preview choices
1 parent 6e8fc9a commit 8e5bff2

6 files changed

Lines changed: 170 additions & 2 deletions

File tree

‎docs/customizing_deis/choosing-a-scheduler.rst‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
:title: Choosing a Scheduler
2+
:description: How to choose a scheduler backend for Deis.
3+
4+
5+
.. _choosing_a_scheduler:
6+
7+
Choosing a Scheduler
8+
====================
9+
10+
The :ref:`scheduler` creates, starts, stops, and destroys each :ref:`container`
11+
of your app. For example, a command such as ``deis scale web=3`` tells the
12+
scheduler to run three containers from the Docker image for your app.
13+
14+
Deis defaults to using the `Fleet Scheduler`_. A tech preview of the `Swarm Scheduler`_
15+
is available for testing. Work is ongoing on `Kubernetes`_ and `Mesos`_-based
16+
schedulers with the intent to test those alternatives in future releases of Deis.
17+
18+
19+
Settings set by scheduler
20+
-------------------------
21+
22+
The following etcd keys are set by the scheduler module of the controller component.
23+
24+
Some keys will exist only if a particular ``schedulerModule`` backend is enabled.
25+
26+
============================= ================================================
27+
setting description
28+
============================= ================================================
29+
/deis/scheduler/swarm/host the swarm manager's host IP address
30+
/deis/scheduler/swarm/node used to identify other nodes in the cluster
31+
============================= ================================================
32+
33+
34+
Settings used by scheduler
35+
--------------------------
36+
37+
The following etcd keys are used by the scheduler module of the controller component.
38+
39+
==================================== ===============================================
40+
setting description
41+
==================================== ===============================================
42+
/deis/controller/schedulerModule scheduler backend, either "fleet" or "swarm"
43+
(default: "fleet")
44+
==================================== ===============================================
45+
46+
47+
Fleet Scheduler
48+
---------------
49+
50+
`fleet`_ is a scheduling backend included with CoreOS:
51+
52+
fleet ties together systemd and etcd into a distributed init system. Think of
53+
it as an extension of systemd that operates at the cluster level instead of the
54+
machine level. This project is very low level and is designed as a foundation
55+
for higher order orchestration.
56+
57+
``fleetd`` is already running on the machines provisioned for Deis: no additional
58+
configuration is needed. Commands such as ``deis ps:restart web.1`` or
59+
``deis scale cmd=10`` will use `fleet`_ by default to manage app containers.
60+
61+
To use the Fleet Scheduler backend explicitly, set the controller's
62+
``schedulerModule`` to "fleet":
63+
64+
.. code-block:: console
65+
66+
$ deisctl config controller set schedulerModule=fleet
67+
68+
69+
Swarm Scheduler
70+
---------------
71+
72+
.. important::
73+
74+
The Swarm Scheduler is a technology preview and is not recommended for
75+
production use.
76+
77+
`swarm`_ is a scheduling backend for Docker:
78+
79+
Docker Swarm is native clustering for Docker. It turns a pool of Docker hosts
80+
into a single, virtual host.
81+
82+
..
83+
84+
Swarm serves the standard Docker API, so any tool which already communicates
85+
with a Docker daemon can use Swarm to transparently scale to multiple hosts...
86+
87+
Deis includes an enhanced version of swarm v0.2.0 with node failover and optimized
88+
locking on container creation. The Swarm Scheduler uses a `soft affinity`_ filter
89+
to spread app containers out among available machines.
90+
91+
Swarm requires the Docker Remote API to be available at TCP port 2375. If you are
92+
upgrading an earlier installation of Deis, please refer to the CoreOS documentation
93+
to `enable the remote API`_.
94+
95+
.. note::
96+
97+
**Known Issues**
98+
99+
- It is not yet possible to change the default affinity filter.
100+
- If swarm can't create all the containers requested, Deis returns an error
101+
and leaves some containers in the "created" state. Until this behavior is fixed,
102+
be mindful of resource limitations on your cluster.
103+
- App containers will not be rescheduled if deis-registry is unavailable.
104+
105+
To test the Swarm Scheduler backend, first install and start the swarm components:
106+
107+
.. code-block:: console
108+
109+
$ deisctl install swarm && deisctl start swarm
110+
111+
Then set the controller's ``schedulerModule`` to "swarm":
112+
113+
.. code-block:: console
114+
115+
$ deisctl config controller set schedulerModule=swarm
116+
117+
The Swarm Scheduler is now active. Commands such as ``deis destroy`` or
118+
``deis scale web=9`` will use `swarm`_ to manage app containers.
119+
120+
To monitor Swarm Scheduler operations, watch the logs of the swarm-manager
121+
component, or spy on Docker events directly on the swarm-manager machine:
122+
123+
.. code-block:: console
124+
125+
$ deisctl journal swarm-manager
126+
$ docker -H 172.17.8.102:2395 events
127+
2015-04-30T17:31 172.17.8.100:5000/hungry-variable:v5: (from node:deis-01) pull
128+
2015-04-30T17:31 172.17.8.100:5000/hungry-variable:v5: (from node:deis-02) pull
129+
2015-04-30T17:31 02a570: (from 172.17.8.100:5000/hungry-variable:v5 node:deis-01) create
130+
2015-04-30T17:31 02a570: (from 172.17.8.100:5000/hungry-variable:v5 node:deis-01) start
131+
2015-04-30T17:31 61e59c: (from 172.17.8.100:5000/hungry-variable:v5 node:deis-02) create
132+
2015-04-30T17:31 61e59c: (from 172.17.8.100:5000/hungry-variable:v5 node:deis-02) start
133+
134+
135+
.. _Kubernetes: http://kubernetes.io/
136+
.. _Mesos: http://mesos.apache.org/
137+
.. _fleet: https://github.com/coreos/fleet#fleet---a-distributed-init-system
138+
.. _swarm: https://github.com/docker/swarm#swarm-a-docker-native-clustering-system
139+
.. _`soft affinity`: https://docs.docker.com/swarm/scheduler/filter/#soft-affinitiesconstraints
140+
.. _`enable the remote API`: https://coreos.com/docs/launching-containers/building/customizing-docker/

‎docs/customizing_deis/controller_settings.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ The following etcd keys are used by the controller component.
4040
setting description
4141
==================================== ======================================================
4242
/deis/controller/registrationMode set registration to "enabled", "disabled", or "admin_only" (default: "enabled")
43+
/deis/controller/schedulerModule scheduler backend (default: "fleet")
4344
/deis/controller/webEnabled enable controller web UI (default: false)
4445
/deis/controller/workers number of web worker processes (default: CPU cores * 2 + 1)
4546
/deis/cache/host host of the cache component (set by cache)

‎docs/customizing_deis/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,7 @@ Customizing Deis
1111

1212
.. toctree::
1313

14+
choosing-a-scheduler
1415
cli-plugins
1516
builder_settings
1617
cache_settings

‎docs/reference/terms/index.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
:title: Deis Components, Usage and Terminolody
1+
:title: Deis Components, Usage and Terminology
22
:description: Deis Components, Usage and Terminology
33

44
.. terms:
@@ -11,6 +11,7 @@ Terms
1111

1212

1313
controller
14+
scheduler
1415

1516
application
1617
container

‎docs/reference/terms/scheduler.rst‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
:title: Scheduler
2+
:description: The scheduler starts and manages containers.
3+
4+
.. _scheduler:
5+
6+
Scheduler
7+
=========
8+
9+
The scheduler is responsible for creating, starting, stopping, and destroying
10+
app :ref:`Containers <container>`. For example, a command such as
11+
``deis scale cmd=10`` tells the scheduler to run ten containers from the
12+
Docker image for your app.
13+
14+
The scheduler must decide which machines are eligible to run these container
15+
jobs. Scheduler backends vary in the details of their job allocation policies
16+
and whether or not they are resource-aware, among other features.
17+
18+
The Deis scheduler is implemented in the :ref:`controller` component. The
19+
scheduler implementation (or "backend") can be changed dynamically to support
20+
different strategies or cluster types.
21+
22+
Follow the :ref:`choosing_a_scheduler` guide to learn about available
23+
options for the Deis scheduler.

‎docs/understanding_deis/components.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@ Each Deis component is deployed as a container or set of containers.
1313

1414
Controller
1515
----------
16-
The controller component is an HTTP API server.
16+
The controller component is an HTTP API server. Among other functions, the
17+
controller contains :ref:`the scheduler <choosing_a_scheduler>`, which decides
18+
where to run app containers.
1719
The ``deis`` command-line client interacts with this component.
1820

1921
.. _database:

0 commit comments

Comments
 (0)