Skip to content

Commit 379368e

Browse files
carmstrongcarmstrong
committed
docs(managing_deis): add docs for running a stateless cluster
1 parent 7596196 commit 379368e

4 files changed

Lines changed: 208 additions & 0 deletions

File tree

‎docs/_includes/_ceph-dependency-description.rst‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
The Deis :ref:`control-plane` makes use of `Ceph`_ to provide persistent storage for
2+
the :ref:`registry`, :ref:`database`, and :ref:`logger` components. The additional
3+
operational complexity of Ceph is tolerated because of the need for persistent
4+
storage for platform high availability.
5+
6+
Alternatively, persistent storage can be achieved by running an external S3-compatible
7+
blob store, PostgreSQL database, and log service. For users on AWS, the convenience
8+
of Amazon S3 and Amazon RDS make the prospect of running a Ceph-less Deis cluster
9+
quite reasonable.
10+
11+
Running a Deis cluster without Ceph provides several advantages:
12+
13+
* Removal of state from the control plane (etcd is still used for configuration)
14+
* Reduced resource usage (Ceph can use up to 2GB of RAM per host)
15+
* Reduced complexity and operational burden of managing Deis
16+
17+
.. _`Ceph`: http://ceph.com/

‎docs/managing_deis/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ Managing Deis
2121
platform_monitoring
2222
production_deployments
2323
recovering-ceph-quorum
24+
running-stateless-cluster
2425
security_considerations
2526
ssl-endpoints
2627
upgrading-deis

‎docs/managing_deis/production_deployments.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,14 @@ Production deployments
99
Many Deis users are running Deis quite successfully in production. When readying a Deis deployment
1010
for production workloads, there are some additional (but optional) recommendations.
1111

12+
Running a stateless control plane
13+
---------------------------------
14+
15+
.. include:: ../_includes/_ceph-dependency-description.rst
16+
17+
See :ref:`running-stateless-cluster` for details on removing this operational
18+
complexity.
19+
1220
Preseeding containers
1321
---------------------
1422

‎docs/managing_deis/running-stateless-cluster.rst‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
:title: Running a stateless cluster
2+
:description: Configuring the cluster to remove Ceph from the control plane.
3+
4+
.. _running-stateless-cluster:
5+
6+
Running a stateless cluster
7+
===========================
8+
9+
.. include:: ../_includes/_ceph-dependency-description.rst
10+
11+
This guide is intended to assist users who are interested in removing the Ceph
12+
dependency of the Deis control plane.
13+
14+
.. note::
15+
16+
This guide was adapted from content graciously provided by Deis community member
17+
`Arne-Christian Blystad`_.
18+
19+
Requirements
20+
------------
21+
22+
External services are required to replace the internal store components:
23+
24+
* S3-compatible blob store (like `Amazon S3`_)
25+
* PostgreSQL database (like `Amazon RDS`_)
26+
* Log drain service with syslog log format compatibility (like `Papertrail`_)
27+
28+
Understanding component changes
29+
-------------------------------
30+
31+
Either directly or indirectly, all components in the :ref:`control-plane`
32+
require Ceph (:ref:`store`). Some components require changes to accommodate
33+
the removal of Ceph. The necessary changes are described below.
34+
35+
Logger
36+
^^^^^^
37+
38+
The :ref:`logger` component provides a syslog-compatible endpoint to consume
39+
application logs, which it writes to a shared Ceph filesystem. These logs are
40+
read by the :ref:`controller` component. The :ref:`logspout` talks to the Docker
41+
daemon on each host, listens for log events from running applications, and ships
42+
them to the logger.
43+
44+
The Logger component is not necessary in a Ceph-less Deis cluster. Instead of
45+
using the Logger, we will route all the logs directly to another syslog
46+
compatible endpoint.
47+
48+
Database
49+
^^^^^^^^
50+
51+
The :ref:`database` runs PostgreSQL and uses the Ceph S3 API (provided by
52+
``deis-store-gateway``) to store PostgreSQL backups and WAL logs.
53+
Should the host running database fail, the database component will fail over to
54+
a new host, start up, and replay backups and WAL logs to recover to its
55+
previous state.
56+
57+
We will not be using the database component in the Ceph-less cluster, and will
58+
instead rely on an external database.
59+
60+
Controller
61+
^^^^^^^^^^
62+
63+
The :ref:`controller` component hosts the API that the Deis CLI consumes. The controller
64+
mounts the same Ceph filesystem that the logger writes to. When users run ``deis logs``
65+
to view an application's log files, the controller reads from this shared filesystem.
66+
67+
A Ceph-less cluster will not store logs (instead sending them to an external service),
68+
so the ``deis logs`` command will not work for users.
69+
70+
Registry
71+
^^^^^^^^
72+
73+
The :ref:`registry` component is an instance of the offical Docker registry, and
74+
is used to store application releases. The registry supports any S3 store, so
75+
a Ceph-less cluster will simply reconfigure registry to use another store (typically
76+
Amazon S3 itself).
77+
78+
Builder
79+
^^^^^^^
80+
81+
The :ref:`builder` component is responsible for building applications deployed
82+
to Deis via the ``git push`` workflow. It pushes to registry to store releases,
83+
so it will require no changes.
84+
85+
Store
86+
^^^^^
87+
88+
The :ref:`store` components implement Ceph itself. In a Ceph-less cluster, we
89+
will skip the installation and starting of these components.
90+
91+
Deploying the cluster
92+
---------------------
93+
94+
This guide assumes a typical deployment on AWS by following the :ref:`deis_on_aws`
95+
guide.
96+
97+
Deploy an AWS cluster
98+
^^^^^^^^^^^^^^^^^^^^^
99+
100+
Follow the :ref:`deis_on_aws` installation documentation through the "Configure
101+
DNS" portion.
102+
103+
Configure log shipping
104+
^^^^^^^^^^^^^^^^^^^^^^
105+
106+
The :ref:`logspout` component must be configured to ship logs to somewhere other
107+
than the :ref:`logger` component.
108+
109+
.. code-block:: console
110+
111+
$ HOST=logs.somewhere.com
112+
$ PORT=98765
113+
$ deisctl config logs set host=${HOST} port=${PORT}
114+
115+
Configure registry
116+
^^^^^^^^^^^^^^^^^^
117+
118+
The :ref:`registry` component won't start until it's configured with an S3 store.
119+
120+
.. code-block:: console
121+
122+
$ BUCKET=MYS3BUCKET
123+
$ AWS_ACCESS_KEY=something
124+
$ AWS_SECRET_KEY=something
125+
$ deisctl config registry set s3bucket=${BUCKET} \
126+
bucketName=${BUCKET} \
127+
s3accessKey=${AWS_ACCESS_KEY} \
128+
s3secretKey=${AWS_SECRET_KEY} \
129+
s3region=eu-west-1 \
130+
s3path=/ \
131+
s3encrypt=false \
132+
s3secure=false
133+
$ deisctl config store set gateway/accessKey=${AWS_ACCESS_KEY} \
134+
gateway/secretKey=${AWS_SECRET_KEY} \
135+
gateway/host=s3.amazonaws.com \
136+
gateway/port=80
137+
138+
Configure database settings
139+
^^^^^^^^^^^^^^^^^^^^^^^^^^^
140+
141+
Since we won't be running the :ref:`database`, we need to configure these settings
142+
so the controller knows where to connect.
143+
144+
.. code-block:: console
145+
146+
$ HOST=something.rds.amazonaws.com
147+
$ DB_USER=deis
148+
$ DB_PASS=somethingsomething
149+
$ DATABASE=deis
150+
$ deisctl config database set engine=postgresql_psycopg2 \
151+
host=${HOST} \
152+
port=5432 \
153+
name=${DATABASE } \
154+
user=${DB_USER} \
155+
password=${DB_PASS}
156+
157+
Deploy the platform
158+
^^^^^^^^^^^^^^^^^^^
159+
160+
The typical :ref:`install_deis_platform` documentation can be followed, with
161+
one caveat: since we won't be deploying many of the typical Deis components, we cannot
162+
use ``deisctl install platform`` or ``deisctl start platform`` -- instead, we
163+
use ``deisctl install stateless-platform`` and ``deisctl start stateless-platform``.
164+
165+
These commands tell ``deisctl`` to skip the components that we don't need to use.
166+
167+
Confirm installation
168+
^^^^^^^^^^^^^^^^^^^^
169+
170+
That's it! Deis is now running without Ceph. Issue a ``deisctl list`` to confirm
171+
that the services are started, and see :ref:`using_deis` to start using the cluster.
172+
173+
Upgrading Deis
174+
--------------
175+
176+
When following the :ref:`upgrading-deis` documentation, be sure to use
177+
``stateless-platform`` instead of ``platform``.
178+
179+
.. _`Amazon RDS`: http://aws.amazon.com/rds/
180+
.. _`Amazon S3`: http://aws.amazon.com/s3/
181+
.. _`Arne-Christian Blystad`: https://github.com/blystad
182+
.. _`Papertrail`: https://papertrailapp.com/

0 commit comments

Comments
 (0)