snf-deploy.rst 16.9 KB
Newer Older
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
1
2
3
4
5
.. _snf-deploy:

snf-deploy tool
^^^^^^^^^^^^^^^

6
7
The `snf-deploy` tool allows you to automatically deploy Synnefo.
You can use `snf-deploy` to deploy Synnefo, in two ways:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
8

9
1. Create a virtual cluster on your local machine and then deploy on that cluster.
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
2. Deploy on a pre-existent cluster of physical nodes running Debian Squeeze.

Currently, `snf-deploy` is mostly useful for testing/demo installations and is
not recommended for production environment Synnefo deployments. If you want to
deploy Synnefo in production, please read first the :ref:`Admin's quick
installation guide <quick-install-admin-guide>` and then the :ref:`Admin's
guide <admin-guide>`.

If you use `snf-deploy` you will setup an up-and-running Synnefo installation,
but the end-to-end functionality will depend on your underlying infrastracture
(e.g.  is nested virtualization enabled in your PC, is the router properly
configured, do nodes have fully qualified domain names, etc.). In any way, it
will enable you to get a grasp of the Web UI/API and base funtionality of
Synnefo and also provide a proper configuration that you can afterwards consult
while reading the Admin guides to set up a production environment that will
scale up and use all available features (e.g. RADOS, Archipelago, etc).

`snf-deploy` is a debian package that should be installed locally and allows
you to install Synnefo on remote nodes (if you go for (2)), or spawn a cluster
of VMs on your local machine using KVM and then install Synnefo on this cluster
(if you go for (1)). To this end, here we will break down our description into
three sections:

a. :ref:`snf-deploy configuration <conf>`
b. :ref:`Creating a virtual cluster <vcluster>` (needed for (1))
c. :ref:`Synnefo deployment <inst>` (either on virtual nodes created on section b,
   or on remote physical nodes)
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
37

38
If you go for (1) you will need to walk through all the sections. If you go for
39
40
(2), you should skip section `(b) <vcluster>`, since you only need sections
`(a) <conf>` and `(c) <inst>`.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
41

42
Before getting any further we should mention the roles that `snf-deploy` refers
43
44
45
to. The Synnefo roles are described in detail :ref:`here
<physical-node-roles>`. Note that multiple roles can co-exist in the same node
(virtual or physical).
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
46

47
Currently, `snf-deploy` recognizes the following combined roles:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
48

49
* **accounts** = **WEBSERVER** + **ASTAKOS**
50
51
52
* **pithos** = **WEBSERVER** + **PITHOS**
* **cyclades** = **WEBSERVER** + **CYCLADES**
* **db** = **ASTAKOS_DB** + **PITHOS_DB** + **CYCLADES_DB**
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
53

54
the following independent roles:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
55

56
* **qh** = **QHOLDER**
57
58
59
60
61
62
63
64
* **cms** = **CMS**
* **mq** = **MQ**
* **ns** = **NS**
* **client** = **CLIENT**
* **router**: The node to do any routing and NAT needed

The above define the roles relative to the Synnefo components. However, in
order to have instances up-and-running, at least one backend must be associated
65
66
67
with Cyclades. Backends are Ganeti clusters, each with multiple **GANETI_NODE**
s. Please note that these nodes may be the same as the ones used for the
previous roles. To this end, `snf-deploy` also recognizes:
68

69
70
* **cluster_nodes** = **G_BACKEND** = All available nodes of a specific backend
* **master_node** = **GANETI_MASTER**
71
72
73
74
75
76
77

Finally, it recognizes the group role:

* **existing_nodes** = **SYNNEFO** + (N x **G_BACKEND**)

In the future, `snf-deploy` will recognize all the independent roles of a scale
out deployment as stated in the :ref:`scale up section <scale-up>`. When that's
78
done, it won't need to introduce its own roles (stated here with lowercase) but
79
80
81
rather use the scale out ones (stated with uppercase on the admin guide).


82
83
.. _conf:

84
85
86
87
88
Configuration (a)
=================

All configuration of `snf-deploy` happens by editting the following files under
``/etc/snf-deploy``:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
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
``nodes.conf``
--------------

This file reflects the hardware infrastucture on which Synnefo is going to be
deployed and is the first to be set before running `snf-deploy`.

Defines the nodes' hostnames and their IPs. Currently `snf-deploy` expects all
nodes to reside in the same network subnet and domain, and share the same
gateway and nameserver. Since Synnefo requires FQDNs to operate, a nameserver
is going to be automatically setup in the cluster by `snf-deploy`. Thus, the
nameserver's IP should appear among the defined node IPs. From now on, we will
refer to the nodes with their hostnames. This implies their FQDN and their IP.

Also, defines the nodes' authentication credentials (username, password).
Furthermore, whether nodes have an extra disk (used for LVM/DRBD storage in
Ganeti backends) or not. The VM container nodes should have three separate
network interfaces (either physical or vlans) each in the same collision
domain; one for the node's public network, one for VMs' public network and one
for VMs' private networks. In order to support the most common case, a router
is setup on the VMs' public interface and does NAT (hoping the node has itself
internet access).

The nodes defined in this file can reflect a number of physical nodes, on which
you will deploy Synnefo (option (2)), or a number of virtual nodes which will
get created by `snf-deploy` using KVM (option (1)), before deploying Synnefo.
As we will see in the next sections, one should first set up this file and then
tell `snf-deploy` whether the nodes on this file should be created, or treated
as pre-existing.

An example ``nodes.conf`` file looks like this:

FIXME: example file here

``synnefo.conf``
----------------

This file reflects the way Synnefo will be deployed on the nodes defined at
``nodes.conf``.

The important section here is the roles. In this file we assing each of the
roles described in the :ref:`introduction <snf-deploy>` to a specific node. The
node is one of the nodes defined at ``nodes.conf``. Note that we refer to nodes
with their short hostnames.

Here we also define all credentials related to users needed by the various
Synnefo services (database, RAPI, RabbitMQ) and the credentials of a test
end-user (`snf-deploy` simulates a user signing up).

Furthermore, define the Pithos shared directory which will hold all the Pithos
related data (maps and blocks).

Finally, define the name of the bridge interfaces controlled by Synnefo, and a
testing Image to register after everything is up and running.

An example ``setup.conf`` file (based on the previous ``nodes.conf`` example)
looks like this:

FIXME: example file here

``ganeti.conf``
---------------

This file reflects the way Ganeti clusters will be deployed on the nodes
defined at ``nodes.conf``.

Here we include all info with regard to Ganeti backends. That is: the master
node, its floating IP, the volume group name (in case of LVM support) and the
VMs' public network associated to it. Please note that currently Synnefo
expects different public networks per backend but still can support multiple
public networks per backend.

FIXME: example file here

``deploy.conf``
---------------

This file customizes `snf-deploy` itself.

It defines some needed directories and also includes options that have to do
with the source of the packages to be deployed. Specifically, whether to deploy
using local packages found under a local directory or deploy using an apt
repository. If deploying from local packages, there is also an option to first
download the packages from a custom URL and save them under the local directory
for later use.

FIXME: example file here

``vcluster.conf``
-----------------

This file defines options that are relevant to the virtual cluster creationi, if
one chooses to create one.

There is an option to define the URL of the Image that will be used as the host
OS for the VMs of the virtual cluster. Also, options for defining an LVM space
or a plain file to be used as a second disk. Finally, networking options to
define where to bridge the virtual cluster.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
187
188


189
190
.. _vcluster:

191
192
Virtual Cluster Creation (b)
============================
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
193

194
195
196
197
198
199
200
201
202
203
204
205
206
207
As stated in the introduction, `snf-deploy` gives you the ability to create a
local virtual cluster using KVM and then deploy Synnefo on top of this cluster.
The number of cluster nodes is arbitrary and is defined in ``nodes.conf``.

This section describes the creation of the virtual cluster, on which Synnefo
will be deployed in the :ref:`next section <inst>`. If you want to deploy
Synnefo on existing physical nodes, you should skip this section.

The first thing you need to deploy a virtual cluster, is a Debian Base image,
which will be used to spawn the VMs. We already provide an 8GB Debian Squeeze
Base image with preinstalled keys and network-manager hostname hooks. This
resides on our production Pithos service. Please see the corresponding
``squeeze_image_url`` variable in ``vcluster.conf``. The image can be fetched
by running:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
208
209
210

.. code-block:: console

211
   snf-deploy vcluster image
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
212

213
214
This will download the image from the URL defined at ``squeeez_image_url``
(Pithos by default) and save it locally under ``/var/lib/snf-deploy/images``.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
215

216
217
218
219
TODO: mention related options: --img-dir, --extra-disk, --lvg, --os

Once you have the image, then you need to setup the local machine's networking
appropriately. You can do this by running:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
220
221
222

.. code-block:: console

223
   snf-deploy vcluster network
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
224

225
226
227
228
This will add a bridge (defined with the ``bridge`` option inside
``vcluster.conf``), iptables to allow traffic from/to the cluster, and enable
forwarding and NAT for the selected network subnet (defined inside
``nodes.conf`` in the ``subnet`` option).
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
229

230
231
232
To complete the preparation, you need a DHCP server that will provide the
selected hostnames and IPs to the cluster (defined under ``[ips]`` in
``nodes.conf``). To do so, run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
233
234
235

.. code-block:: console

236
   snf-deploy vcluster dhcp
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
237

238
239
240
241
This will launch a dnsmasq instance, acting only as DHCP server and listening
only on the cluster's bridge. Every time you make changes inside ``nodes.conf``
you should re-create the dnsmasq related files (under ``/etc/snf-deploy``) by
passing --save-config option.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
242

243
244
After running all the above preparation tasks we can finally create the cluster
defined in ``nodes.conf`` by running:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
245
246
247

.. code-block:: console

248
249
250
251
252
   snf-deploy vcluster create

This will launch all the needed KVM virtual machines, snapshotting the image we
fetched before. Their taps will be connected with the already created bridge
and their primary interface will get the given address.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
253

254
Now that we have the nodes ready, we can move on and deploy Synnefo on them.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
255
256


257
258
.. _inst:

259
260
261
Synnefo Installation (c)
========================

262
At this point you should have an up-and-running cluster, either virtual
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
263
(created in the :ref:`previous section <vcluster>` on your local machine) or
264
265
266
267
268
269
physical on remote nodes. The cluster should also have valid hostnames and IPs.
And all its nodes should be defined in ``nodes.conf``.

You should also have set up ``synnefo.conf`` to reflect which Synnefo component
will reside in which node.

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
Node Requirements
-----------------

 - OS: Debian Squeeze
 - authentication: `root` with same password for all nodes
 - primary network interface: `eth0`
 - primary IP in the same IPv4 subnet and network domain
 - spare network interfaces: `eth1`, `eth2` (or vlans on `eth0`)

In case you have created a virtual cluster as described in the :ref:`section
(b) <vcluster>`, the above requirements are already taken care of. In case of a
physical cluster, you need to set them up manually by yourself, before
proceeding with the Synnefo installation.

Preparing the Synnefo deployment
--------------------------------

The following actions are mandatory and must run before the actual deployment.
In the following we refer to the sub commands of ``snf-deploy prepare`` and
what they actually do.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
290

291
292
293
294
295
Synnefo expects FQDNs and therefore a nameserver (BIND) should be setup in a
node inside the cluster. All nodes along with your local machine should use
this nameserver and search in the corresponding network domain. To this end,
add to your local ``resolv.conf`` (please change the default values with the
ones of your custom configuration):
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
296

297
298
299
300
.. code-block:: console

   search <your_domain> synnefo.deploy.local
   nameserver 192.168.0.1
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
301

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
302
303
304
305
WARNING: In case you are running the installation on physical nodes please
ensure that they have the same `resolv.conf` and it does not change during
and after installation (because of NetworkManager hooks or something..)

306
307
To actually setup the nameserver in the node specified as ``ns`` in
``synnefo.conf`` run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
308
309
310

.. code-block:: console

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
311
   snf-deploy prepare ns
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
312

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
313
314
To do some node tweaking and install correct `id_rsa/dsa` keys and `authorized_keys`
needed for password-less intra-node communication run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
315

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
316
.. code-block:: console
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
317

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
318
   snf-deploy prepare hosts
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
319

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
320
321
322
At this point you should have a cluster with FQDNs and reverse DNS lookups
ready for the Synnefo deployment. To sum up, we mention all the node
requirements for a successful Synnefo installation, before proceeding.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
323

324
To check the network configuration (FQDNs, connectivity):
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
325
326
327

.. code-block:: console

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
328
   snf-deploy prepare check
329
330
331

WARNING: In case ping fails check ``/etc/nsswitch.conf`` hosts entry and put dns
after files!!!
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
332

333
334
335
336
To setup the apt repository and update each nodes' package index files:

.. code-block:: console

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
337
338
339
340
341
342
343
344
   snf-deploy prepare apt

Finally Synnefo needs a shared file system, so we need to setup the NFS server
on node ``pithos`` defined in ``synnefo.conf``:

.. code-block:: console

   snf-deploy prepare nfs
345

346
347
If everything is setup correctly and all prerequisites are met, we can start
the Synnefo deployment.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
348

349
350
351
352
Synnefo deployment
------------------

To install the Synnefo stack on the existing cluster run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
353
354
355
356
357

.. code-block:: console

   snf-deploy synnefo -vvv

358
This might take a while.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
359

360
361
362
If this finishes without errors, check for successful installation by visiting
from your local machine (make sure you have already setup your local
``resolv.conf`` to point at the cluster's DNS):
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
363
364
365
366
367
368
369

| https://accounts.synnefo.deploy.local/im/

and login with:

| username: dimara@grnet.gr password: lala

370
371
372
373
374
375
376
or the ``user_name`` and ``user_passwd`` defined in your ``synnefo.conf``.
Take a small tour checking out Pithos and the rest of the Web UI. You can
upload a sample file on Pithos to see that Pithos is working. Do not try to
create a VM yet, since we have not yet added a Ganeti backend.

If everything seems to work, we go ahead to the last step which is adding a
Ganeti backend.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
377
378

Adding a Ganeti Backend
379
-----------------------
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
380

381
382
383
384
385
386
387
Assuming that everything works as expected, you must have Astakos, Pithos, CMS,
DB and RabbitMQ up and running. Cyclades should work too, but partially. That's
because no backend is registered yet. Let's setup one. Currently, Synnefo
supports only Ganeti clusters as valid backends. They have to be created
independently with `snf-deploy` and once they are up and running, we register
them to Cyclades. From version 0.12, Synnefo supports multiple Ganeti backends.
`snf-deploy` defines them in ``ganeti.conf``.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
388

389
After setting up ``ganeti.conf``, run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
390
391
392

.. code-block:: console

393
394
395
396
397
398
399
400
401
   snf-deploy backend create --backend-name ganeti1 -vvv

where ``ganeti1`` should have previously been defined as a section in
``ganeti.conf``. This will create the ``ganeti1`` backend on the corresponding
nodes (``cluster_nodes``, ``master_node``) defined in the ``ganeti1`` section
of the ``ganeti.conf`` file. If you are an experienced user and want to deploy
more than one Ganeti backend you should create multiple sections in
``ganeti.conf`` and re-run the above command with the corresponding backend
names.
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
402

403
404
After creating and adding the Ganeti backend, we need to setup the backend
networking. To do so, we run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
405

406
407
.. code-block:: console

408
   snf-deploy backend network --backend-name ganeti1
409
410

And finally, we need to setup the backend storage:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
411
412
413

.. code-block:: console

414
   snf-deploy backend storage --backend-name ganeti1
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
415

416
417
418
419
420
421
422
423
424
425
This command will first check the ``extra_disk`` in ``nodes.conf`` and try to
find it on the nodes of the cluster. If the nodes indeed have that disk,
`snf-deploy` will create a PV and the corresponding VG and will enable LVM and
DRBD storage in the Ganeti cluster.

If the option is blank or `snf-deploy` can't find the disk on the nodes, LVM
and DRBD will be disabled and only Ganeti's ``file`` disk template will be
enabled.

To test everything went as expected, visit from your local machine:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
426
427
428
429
430

.. code-block:: console

    https://cyclades.synnefo.deploy.local/ui/

431
432
and try to create a VM. Also create a Private Network and try to connect it. If
everything works, you have setup Synnefo successfully. Enjoy!
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
433
434


435
436
snf-deploy as a DevTool
=======================
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
437

438
439
440
441
442
For developers, a single node setup is highly recommended and `snf-deploy` is a
very helpful tool. `snf-deploy` also supports updating packages that are
locally generated. For this to work please add all \*.deb files in packages
directory (see ``deploy.conf``) and set the ``use_local_packages`` option to
``True``. Then run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
443
444
445

.. code-block:: console

Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
446
447
   snf-deploy synnefo update --use-local-packages
   snf-deploy backend update --backend-name ganeti2 --use-local-packages
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
448

449
450
For advanced users, `snf-deploy` gives the ability to run one or more times
independently some of the supported actions. To find out which are those, run:
Dimitris Aragiorgis's avatar
Dimitris Aragiorgis committed
451
452
453

.. code-block:: console

454
   snf-deploy run --help