root / docs / cyclades-admin-guide.rst @ 70f13b0f
History | View | Annotate | Download (10.9 kB)
1 |
.. _cyclades-admin-guide: |
---|---|
2 |
|
3 |
=================== |
4 |
Administrator Guide |
5 |
=================== |
6 |
|
7 |
This is the cyclades administrator guide. |
8 |
|
9 |
It contains instructions on how to download, install and configure |
10 |
the synnefo components necessary to deploy the Compute Service. It also covers |
11 |
maintenance issues, e.g., upgrades of existing deployments. |
12 |
|
13 |
The guide assumes you are familiar with all aspects of downloading, installing |
14 |
and configuring packages for the Linux distribution of your choice. |
15 |
|
16 |
Overview |
17 |
-------- |
18 |
|
19 |
This guide covers the following: |
20 |
|
21 |
Architecture |
22 |
Node types needed for a complete deployment of cyclades, |
23 |
and their roles. Throughout this guide, `node` refers to a physical machine |
24 |
in the deployment. |
25 |
Installation |
26 |
The installation of services and synnefo software components for a working |
27 |
deployment of cyclades, either from source packages or the provided |
28 |
packages for Debian Squeeze. |
29 |
Configuration |
30 |
Configuration of the various software components comprising an cyclades |
31 |
deployment. |
32 |
Upgrades/Changelogs |
33 |
Upgrades of existing deployments of cyclades to newer versions, associated |
34 |
Changelogs. |
35 |
|
36 |
.. _cyclades-architecture: |
37 |
|
38 |
Architecture |
39 |
------------ |
40 |
|
41 |
Nodes in an cyclades deployment belong in one of the following types. |
42 |
For every type, we list the services that execute on corresponding nodes. |
43 |
|
44 |
.. _DB_NODE: |
45 |
|
46 |
DB |
47 |
** |
48 |
|
49 |
A node [or more than one nodes, if using an HA configuration], running a DB |
50 |
engine supported by the Django ORM layer. The DB is the single source of |
51 |
truth for the servicing of API requests by cyclades. |
52 |
|
53 |
*Services:* PostgreSQL / MySQL |
54 |
|
55 |
.. _APISERVER_NODE: |
56 |
|
57 |
APISERVER |
58 |
********* |
59 |
A node running the ``api`` application contained in |
60 |
:ref:`snf-cyclades-app <snf-cyclades-app>`. Any number of |
61 |
:ref:`APISERVER <APISERVER_NODE>` nodes |
62 |
can be used, in a load-balancing configuration, without any |
63 |
special consideration. Access to a common DB ensures consistency. |
64 |
|
65 |
*Services:* Web server, vncauthproxy |
66 |
|
67 |
|
68 |
.. _QUEUE_NODE: |
69 |
|
70 |
QUEUE |
71 |
***** |
72 |
A node running the RabbitMQ software, which provides AMQP functionality. More |
73 |
than one :ref:`QUEUE <QUEUE_NODE>` nodes may be deployed, in an HA |
74 |
configuration. Such deployments require shared storage, provided e.g., by DRBD. |
75 |
|
76 |
*Services:* RabbitMQ [rabbitmq-server] |
77 |
|
78 |
|
79 |
.. _LOGIC_NODE: |
80 |
|
81 |
LOGIC |
82 |
***** |
83 |
|
84 |
A node running the business logic of synnefo, in Django. It dequeues |
85 |
messages from QUEUE nodes, and provides the context in which business logic |
86 |
functions run. It uses Django ORM to connect to the common DB and update the |
87 |
state of the system, based on notifications received from the rest of the |
88 |
infrastructure, over AMQP. |
89 |
|
90 |
*Services:* the synnefo logic dispatcher, ``snf-dispatcher`` |
91 |
|
92 |
|
93 |
.. _GANETI_NODES: |
94 |
.. _GANETI_MASTER: |
95 |
.. _GANETI_NODE: |
96 |
|
97 |
GANETI-MASTER and GANETI-NODE |
98 |
***************************** |
99 |
A single GANETI-MASTER and a large number of GANETI-NODEs constitute the |
100 |
Ganeti backend for synnefo, which undertakes all VM management functions. |
101 |
Any APISERVER can issue commands to the GANETI-MASTER, over RAPI, to effect |
102 |
changes in the state of the VMs. The GANETI-MASTER runs the Ganeti request |
103 |
queue. |
104 |
|
105 |
*Services:* |
106 |
* only on :ref:`GANETI-MASTER <GANETI_MASTER>`: |
107 |
* the synnefo Ganeti monitoring daemon, ``snf-ganeti-eventd`` |
108 |
* the synnefo Ganeti hook, ``ganeti/snf-ganeti-hook.py``. |
109 |
* on every :ref:`GANETI-NODE <GANETI_NODE>`: |
110 |
* a deployment-specific KVM ifup script |
111 |
* properly configured :ref:`NFDHCPD <cyclades-nfdhcpd-setup>` |
112 |
|
113 |
.. _WEBAPP_NODE: |
114 |
|
115 |
Installation |
116 |
------------ |
117 |
|
118 |
Installation of cyclades is a two step process: |
119 |
|
120 |
1. install the external services (prerequisites) on which cyclades depends |
121 |
2. install the synnefo software components associated with cyclades |
122 |
|
123 |
Prerequisites |
124 |
************* |
125 |
.. _cyclades-install-ganeti: |
126 |
|
127 |
Ganeti installation |
128 |
``````````````````` |
129 |
Synnefo requires a working Ganeti installation at the backend. Installation |
130 |
of Ganeti is not covered by this document, please refer to |
131 |
`ganeti documentation <http://docs.ganeti.org/ganeti/current/html>`_ for all the |
132 |
gory details. A successful Ganeti installation concludes with a working |
133 |
:ref:`GANETI-MASTER <GANETI_NODES>` and a number of :ref:`GANETI-NODEs <GANETI_NODES>`. |
134 |
|
135 |
.. _cyclades-install-db: |
136 |
|
137 |
Database |
138 |
```````` |
139 |
|
140 |
Database installation is done as part of the |
141 |
:ref:`snf-webproject <snf-webproject>` component. |
142 |
|
143 |
.. _cyclades-install-rabbitmq: |
144 |
|
145 |
RabbitMQ |
146 |
```````` |
147 |
|
148 |
RabbitMQ is used as a generic message broker for cyclades. It should be |
149 |
installed on two seperate :ref:`QUEUE <QUEUE_NODE>` nodes in a high availability |
150 |
configuration as described here: |
151 |
|
152 |
http://www.rabbitmq.com/pacemaker.html |
153 |
|
154 |
After installation, create a user and set its permissions: |
155 |
|
156 |
.. code-block:: console |
157 |
|
158 |
$ rabbitmqctl add_user <username> <password> |
159 |
$ rabbitmqctl set_permissions -p / <username> "^.*" ".*" ".*" |
160 |
|
161 |
The values set for the user and password must be mirrored in the |
162 |
``RABBIT_*`` variables in your settings, as managed by |
163 |
:ref:`snf-common <snf-common>`. |
164 |
|
165 |
.. todo:: Document an active-active configuration based on the latest version |
166 |
of RabbitMQ. |
167 |
|
168 |
.. _cyclades-install-vncauthproxy: |
169 |
|
170 |
vncauthproxy |
171 |
```````````` |
172 |
|
173 |
To support OOB console access to the VMs over VNC, the vncauthproxy |
174 |
daemon must be running on every :ref:`APISERVER <APISERVER_NODE>` node. |
175 |
|
176 |
.. note:: The Debian package for vncauthproxy undertakes all configuration |
177 |
automatically. |
178 |
|
179 |
Download and install the latest vncauthproxy from its own repository, |
180 |
at `https://code.grnet.gr/git/vncauthproxy`, or a specific commit: |
181 |
|
182 |
.. code-block:: console |
183 |
|
184 |
$ bin/pip install -e git+https://code.grnet.gr/git/vncauthproxy@INSERT_COMMIT_HERE#egg=vncauthproxy |
185 |
|
186 |
Create ``/var/log/vncauthproxy`` and set its permissions appropriately. |
187 |
|
188 |
Alternatively, build and install Debian packages. |
189 |
|
190 |
.. code-block:: console |
191 |
|
192 |
$ git checkout debian |
193 |
$ dpkg-buildpackage -b -uc -us |
194 |
# dpkg -i ../vncauthproxy_1.0-1_all.deb |
195 |
|
196 |
.. warning:: |
197 |
**Failure to build the package on the Mac.** |
198 |
|
199 |
``libevent``, a requirement for gevent which in turn is a requirement for |
200 |
vncauthproxy is not included in `MacOSX` by default and installing it with |
201 |
MacPorts does not lead to a version that can be found by the gevent |
202 |
build process. A quick workaround is to execute the following commands:: |
203 |
|
204 |
$ cd $SYNNEFO |
205 |
$ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy |
206 |
<the above fails> |
207 |
$ cd build/gevent |
208 |
$ sudo python setup.py -I/opt/local/include -L/opt/local/lib build |
209 |
$ cd $SYNNEFO |
210 |
$ sudo pip install -e git+https://code.grnet.gr/git/vncauthproxy@5a196d8481e171a#egg=vncauthproxy |
211 |
|
212 |
.. todo:: Mention vncauthproxy bug, snf-vncauthproxy, inability to install using pip |
213 |
.. todo:: kpap: fix installation commands |
214 |
|
215 |
.. _cyclades-install-nfdhcpd: |
216 |
|
217 |
NFDHCPD |
218 |
``````` |
219 |
|
220 |
Setup Synnefo-specific networking on the Ganeti backend. |
221 |
This part is deployment-specific and must be customized based on the |
222 |
specific needs of the system administrators. |
223 |
|
224 |
A reference installation will use a Synnefo-specific KVM ifup script, |
225 |
NFDHCPD and pre-provisioned Linux bridges to support public and private |
226 |
network functionality. For this: |
227 |
|
228 |
Grab NFDHCPD from its own repository (https://code.grnet.gr/git/nfdhcpd), |
229 |
install it, modify ``/etc/nfdhcpd/nfdhcpd.conf`` to reflect your network |
230 |
configuration. |
231 |
|
232 |
Install a custom KVM ifup script for use by Ganeti, as |
233 |
``/etc/ganeti/kvm-vif-bridge``, on GANETI-NODEs. A sample implementation is |
234 |
provided under ``/contrib/ganeti-hooks``. Set ``NFDHCPD_STATE_DIR`` to point |
235 |
to NFDHCPD's state directory, usually ``/var/lib/nfdhcpd``. |
236 |
|
237 |
.. todo:: soc: document NFDHCPD installation, settle on KVM ifup script |
238 |
|
239 |
.. _cyclades-install-snfimage: |
240 |
|
241 |
snf-image |
242 |
````````` |
243 |
|
244 |
Install the :ref:`snf-image <snf-image>` Ganeti OS provider for image |
245 |
deployment. |
246 |
|
247 |
For :ref:`cyclades <cyclades>` to be able to launch VMs from specified |
248 |
Images, you need the snf-image OS Provider installed on *all* Ganeti nodes. |
249 |
|
250 |
Please see `https://code.grnet.gr/projects/snf-image/wiki`_ |
251 |
for installation instructions and documentation on the design |
252 |
and implementation of snf-image. |
253 |
|
254 |
Please see `https://code.grnet.gr/projects/snf-image/files` |
255 |
for the latest packages. |
256 |
|
257 |
Images should be stored in ``extdump``, or ``diskdump`` format in a directory |
258 |
of your choice, configurable as ``IMAGE_DIR`` in |
259 |
:file:`/etc/default/snf-image`. |
260 |
|
261 |
synnefo components |
262 |
****************** |
263 |
|
264 |
You need to install the appropriate synnefo software components on each node, |
265 |
depending on its type, see :ref:`Architecture <cyclades-architecture>`. |
266 |
|
267 |
Most synnefo components have dependencies on additional Python packages. |
268 |
The dependencies are described inside each package, and are setup |
269 |
automatically when installing using :command:`pip`, or when installing |
270 |
using your system's package manager. |
271 |
|
272 |
Please see the page of each synnefo software component for specific |
273 |
installation instructions, where applicable. |
274 |
|
275 |
Install the following synnefo components: |
276 |
|
277 |
Nodes of type :ref:`APISERVER <APISERVER_NODE>` |
278 |
Components |
279 |
:ref:`snf-common <snf-common>`, |
280 |
:ref:`snf-webproject <snf-webproject>`, |
281 |
:ref:`snf-cyclades-app <snf-cyclades-app>` |
282 |
Nodes of type :ref:`GANETI-MASTER <GANETI_MASTER>` and :ref:`GANETI-NODE <GANETI_NODE>` |
283 |
Components |
284 |
:ref:`snf-common <snf-common>`, |
285 |
:ref:`snf-cyclades-gtools <snf-cyclades-gtools>` |
286 |
Nodes of type :ref:`LOGIC <LOGIC_NODE>` |
287 |
Components |
288 |
:ref:`snf-common <snf-common>`, |
289 |
:ref:`snf-webproject <snf-webproject>`, |
290 |
:ref:`snf-cyclades-app <snf-cyclades-app>`. |
291 |
|
292 |
Configuration |
293 |
------------- |
294 |
|
295 |
This section targets the configuration of the prerequisites for cyclades, |
296 |
and the configuration of the associated synnefo software components. |
297 |
|
298 |
synnefo components |
299 |
****************** |
300 |
|
301 |
cyclades uses :ref:`snf-common <snf-common>` for settings. |
302 |
Please refer to the configuration sections of |
303 |
:ref:`snf-webproject <snf-webproject>`, |
304 |
:ref:`snf-cyclades-app <snf-cyclades-app>`, |
305 |
:ref:`snf-cyclades-gtools <snf-cyclades-gtools>` for more |
306 |
information on their configuration. |
307 |
|
308 |
Ganeti |
309 |
`````` |
310 |
|
311 |
Set ``GANETI_NODES``, ``GANETI_MASTER_IP``, ``GANETI_CLUSTER_INFO`` based on |
312 |
your :ref:`Ganeti installation <cyclades-install-ganeti>` and change the |
313 |
`BACKEND_PREFIX_ID`` setting, using an custom ``PREFIX_ID``. |
314 |
|
315 |
Database |
316 |
```````` |
317 |
|
318 |
Once all components are installed and configured, |
319 |
initialize the Django DB: |
320 |
|
321 |
.. code-block:: console |
322 |
|
323 |
$ snf-manage syncdb |
324 |
$ snf-manage migrate |
325 |
|
326 |
and load fixtures ``{users, flavors, images}``, |
327 |
which make the API usable by end users by defining a sample set of users, |
328 |
hardware configurations (flavors) and OS images: |
329 |
|
330 |
.. code-block:: console |
331 |
|
332 |
$ snf-manage loaddata /path/to/users.json |
333 |
$ snf-manage loaddata flavors |
334 |
$ snf-manage loaddata images |
335 |
|
336 |
.. warning:: |
337 |
Be sure to load a custom users.json and select a unique token |
338 |
for each of the initial and any other users defined in this file. |
339 |
**DO NOT LEAVE THE SAMPLE AUTHENTICATION TOKENS** enabled in deployed |
340 |
configurations. |
341 |
|
342 |
sample users.json file: |
343 |
|
344 |
.. literalinclude:: ../../synnefo/db/fixtures/users.json |
345 |
|
346 |
`download <../_static/users.json>`_ |
347 |
|
348 |
RabbitMQ |
349 |
```````` |
350 |
|
351 |
Change ``RABBIT_*`` settings to match your :ref:`RabbitMQ setup |
352 |
<cyclades-install-rabbitmq>`. |
353 |
|
354 |
.. include:: ../../Changelog |