Statistics
| Branch: | Tag: | Revision:

root / docs / install.sgml @ b212bf8b

History | View | Annotate | Download (14.8 kB)

1
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
2
]>
3
  <article class="specification">
4
  <articleinfo>
5
    <title>Ganeti installation tutorial</title>
6
  </articleinfo>
7
  <para>Documents Ganeti version 1.2</para>
8

    
9
  <sect1>
10
    <title>Introduction</title>
11

    
12
    <para>
13
      Ganeti is a cluster virtualization management system. This
14
      document explains how to bootstrap a Ganeti node and create a
15
      running cluster. You need to repeat most of the steps in this
16
      document for every node you want to install, but of course we
17
      recommend creating some semi-automatic procedure if you plan to
18
      deploy Ganeti on a medium/large scale.
19
    </para>
20

    
21
    <para>This document is divided into two main sections:
22

    
23
      <itemizedlist>
24
        <listitem>
25
          <simpara>Installation of the core system and base
26
          components</simpara>
27
        </listitem>
28
        <listitem>
29
          <simpara>Configuration of the environment for
30
          Ganeti</simpara>
31
        </listitem>
32
      </itemizedlist>
33

    
34
    Each of these is divided into sub-sections. While a full Ganeti
35
    system will need all of the steps specified, some are not strictly
36
    required for every environment. Which ones they are, and why, is
37
    specified in the corresponding sections.
38
    </para>
39

    
40
    <para>
41
      While Ganeti itself is distribution-agnostic most of the
42
      examples in this document will be targeted at Debian or
43
      Debian-derived distributions. You are expected to be familiar
44
      with your distribution, its package management system, and Xen
45
      before trying to use Ganeti.
46
    </para>
47

    
48
    <para>
49
      A basic Ganeti terminology glossary is provided in the
50
      introductory section of the "admin guide". Please refer to that
51
      if you are uncertain about the terms we are using.
52
    </para>
53

    
54
  </sect1>
55

    
56
  <sect1>
57
    <title>Installing the system and base components</title>
58

    
59
    <sect2>
60
      <title>Installing the base system</title>
61

    
62
      <para><emphasis role="strong">Mandatory.</emphasis></para>
63

    
64
      <para>
65
        Please install your operating system as you would normally
66
        do. The only requirement you need to be aware of at this stage
67
        is to partition leaving enough space for a big LVM volume
68
        group which will then host your instance file systems. You can
69
        even create the volume group at installation time, of course:
70
        the default volume group name Ganeti 1.2 uses is "xenvg" but
71
        you may name it differently should you wish to, as long as the
72
        name is the same for all the nodes in the cluster.
73
      </para>
74

    
75
    </sect2>
76

    
77
    <sect2>
78
      <title>Installing Xen</title>
79

    
80
      <para>
81
        <emphasis role="strong">Mandatory:</emphasis> While Ganeti is
82
        developed with the ability to modularly run on different
83
        virtualization environments in mind the only one currently
84
        useable on a live system is <ulink
85
        url="http://xen.xensource.com/">Xen</ulink>.
86
      </para>
87

    
88
      <para>
89
        Please follow your distribution's recommended way to install
90
        and set up Xen, or install Xen from the upstream source, if
91
        you wish, following their manual.
92
      </para>
93

    
94
      <para>
95
        For example under Debian 4.0 or 3.1+backports you can install
96
        the relevant xen-linux-system package, which will pull in both
97
        the hypervisor and the relevant kernel. On Ubuntu (from Gutsy
98
        on) the package is called ubuntu-xen-server.
99
      </para>
100

    
101
      <para>
102
        After installing Xen you need to reboot into your xenified
103
        dom0 system. Again on some distributions this might involve
104
        configuring GRUB appropriately.
105
      </para>
106

    
107
    </sect2>
108

    
109
    <sect2>
110
      <title>Installing DRBD</title>
111

    
112
      <para>
113
        Recommended: <ulink url="http://www.drbd.org/">DRBD</ulink>
114
        is required if you want to use the high availability (HA)
115
        features of Ganeti, but optional if you don't require HA or
116
        only run Ganeti on single-node clusters. You can upgrade a
117
        non-HA cluster to an HA one later, but you might need to
118
        export and reimport all your instances to take advantage of
119
        the new features.
120
      </para>
121

    
122
      <para>
123
        Now the bad news: unless your distribution already provides it
124
        installing DRBD might involve recompiling your kernel or
125
        anyway fiddling with it. Hopefully at least the xenified
126
        kernel source to start from will be provided.
127
      </para>
128

    
129
      <para>
130
        Under Debian you can just install the drbd0.7-module-source
131
        and drbd0.7-utils packages, and your kernel source, and then
132
        run module-assistant to compile the drbd0.7 module. The
133
        following commands should do it:
134
      </para>
135

    
136
      <screen>
137
m-a update
138
m-a a-i drbd0.7
139
      </screen>
140

    
141
      <para>
142
        The good news is that you don't need to configure DRBD at all.
143
        Ganeti will do it for you for every instance you set up.  If
144
        you have the DRBD utils installed and the module in your
145
        kernel you're fine. Please check that your system is
146
        configured to load the module at every boot.
147
      </para>
148

    
149
    </sect2>
150

    
151
    <sect2>
152
      <title>Other required software</title>
153

    
154
      <para>Besides Xen and DRBD, you will need to install the
155
      following:</para>
156

    
157
      <itemizedlist>
158
        <listitem>
159
          <simpara><ulink url="http://sourceware.org/lvm2/">LVM
160
          version 2</ulink></simpara>
161
        </listitem>
162
        <listitem>
163
          <simpara><ulink
164
          url="http://www.openssl.org/">OpenSSL</ulink></simpara>
165
        </listitem>
166
        <listitem>
167
          <simpara><ulink
168
          url="http://www.openssh.com/portable.html">OpenSSH</ulink></simpara>
169
        </listitem>
170
        <listitem>
171
          <simpara><ulink url="http://bridge.sourceforge.net/">Bridge
172
          utilities</ulink></simpara>
173
        </listitem>
174
        <listitem>
175
          <simpara><ulink
176
          url="http://fping.sourceforge.net/">fping</ulink></simpara>
177
        </listitem>
178
        <listitem>
179
          <simpara><ulink
180
          url="http://developer.osdl.org/dev/iproute2">iproute2</ulink></simpara>
181
        </listitem>
182
        <listitem>
183
          <simpara><ulink
184
          url="ftp://ftp.inr.ac.ru/ip-routing/iputils-current.tar.gz">arping</ulink>
185
          (part of iputils package)</simpara>
186
        </listitem>
187
        <listitem>
188
          <simpara><ulink
189
          url="http://www.kernel.org/pub/linux/utils/raid/mdadm/">mdadm</ulink>
190
          (Linux Software Raid tools)</simpara>
191
        </listitem>
192
        <listitem>
193
          <simpara><ulink url="http://www.python.org">Python 2.4</ulink></simpara>
194
        </listitem>
195
        <listitem>
196
          <simpara><ulink url="http://twistedmatrix.com/">Python
197
          Twisted library</ulink> - the core library is
198
          enough</simpara>
199
        </listitem>
200
        <listitem>
201
          <simpara><ulink
202
          url="http://pyopenssl.sourceforge.net/">Python OpenSSL
203
          bindings</ulink></simpara>
204
        </listitem>
205
      </itemizedlist>
206

    
207
      <para>These programs are supplied as part of most Linux
208
      distributions, so usually they can be installed via apt or
209
      similar methods. Also many of them will already be installed on
210
      a standard machine. On Debian Etch you can use this command line
211
      to install all of them:</para>
212

    
213
      <screen>
214
# apt-get install lvm2 ssh bridge-utils iproute iputils-arping \
215
  fping python2.4 python-twisted-core python-pyopenssl openssl
216
      </screen>
217

    
218
      <para>
219
        When installing from source, you will also need the following:
220
      </para>
221
      <itemizedlist>
222
        <listitem>
223
          <simpara>make</simpara>
224
        </listitem>
225
        <listitem>
226
          <simpara>tar</simpara>
227
        </listitem>
228
        <listitem>
229
          <simpara>gzip or bzip2</simpara>
230
        </listitem>
231
      </itemizedlist>
232

    
233
      <para>
234
        Again, these are available in most if not all linux distributions. For Debian, do:
235
      <screen>
236
# apt-get install make tar gzip bzip2
237
      </screen>
238
      </para>
239
    </sect2>
240

    
241
  </sect1>
242

    
243

    
244
  <sect1>
245
    <title>Setting up the environment for Ganeti</title>
246

    
247
    <sect2>
248
      <title>Configuring the network</title>
249

    
250
      <para>Ganeti relies on Xen running in "bridge mode", which means the
251
      instances network interfaces will be attached to a software bridge
252
      running in dom0. Xen by default creates such a bridge at startup, but
253
      your distribution might have a different way to do things.
254
      </para>
255

    
256
      <para>
257
      In Debian, in order to enable the default Xen behaviour, you
258
      have to edit <filename>/etc/xen/xend-config.sxp</filename> and
259
      replace <computeroutput>(network-script
260
      network-dummy)</computeroutput> with
261
      <computeroutput>(network-script
262
      network-bridge)</computeroutput>. The recommended Debian way to
263
      configure things, though, is to edit your
264
      <filename>/etc/network/interfaces</filename> file and substitute
265
      your normal ethernet stanza with something like:</para>
266

    
267
      <screen>
268
auto br0
269
iface br0 inet static
270
        address <replaceable>YOUR_IP_ADDRESS</replaceable>
271
        netmask <replaceable>YOUR_NETMASK</replaceable>
272
        network <replaceable>YOUR_NETWORK</replaceable>
273
        broadcast <replaceable>YOUR_BROADCAST_ADDRESS</replaceable>
274
        gateway <replaceable>YOUR_GATEWAY</replaceable>
275
        bridge_ports <replaceable>eth0</replaceable>
276
        bridge_stp off
277
        bridge_fd 0
278
      </screen>
279

    
280
    <para>
281
      Beware that the default name Ganeti uses is
282
      <hardware>xen-br0</hardware> (which was used in Xen 2.0)
283
      while Xen 3.0 uses <hardware>xenbr0</hardware> by
284
      default. The default bridge your cluster will use for new
285
      instances can be specified at cluster initialization time.
286
    </para>
287

    
288
    </sect2>
289

    
290
    <sect2>
291
      <title>Configuring LVM</title>
292

    
293
      <para>
294
        If you haven't configured your LVM volume group at install
295
        time you need to do it before trying to initialize the Ganeti
296
        cluster. This is done by formatting the devices/partitions you
297
        want to use for it and then adding them to the relevant volume
298
        group:
299
       </para>
300

    
301
       <screen>
302
pvcreate /dev/sda4
303
pvcreate /dev/sdb
304
pvcreate /dev/sdc1
305
vgcreate xenvg /dev/sda4 /dev/sdb /dev/sdc1
306
       </screen>
307

    
308
      <para>
309
	If you want to add a device later you can do so with the
310
	<citerefentry><refentrytitle>vgextend</refentrytitle>
311
	<manvolnum>8</manvolnum></citerefentry> command:
312
      </para>
313

    
314
      <screen>
315
pvcreate /dev/sdd
316
vgextend xenvg /dev/sdd
317
      </screen>
318

    
319
      <para>
320
        As said before you may choose a different name for the volume group,
321
        as long as you stick to the same name on all the nodes of a cluster.
322
      </para>
323
    </sect2>
324

    
325
    <sect2>
326
      <title>Installing Ganeti</title>
327

    
328
      <para>
329
        It's now time to install the Ganeti software itself. You can
330
        do it from source, with the usual steps (note that the
331
        <option>localstatedir</option> options must be set to
332
        <filename class="directory">/var</filename>):
333
      </para>
334

    
335
        <screen>
336
./configure --localstatedir=/var
337
make
338
make install
339
mkdir /srv/ganeti/ /srv/ganeti/os /srv/ganeti/export
340
        </screen>
341

    
342
      <para>
343
        You also need to copy from the source archive the file
344
        <filename>docs/examples/ganeti.initd</filename> to
345
        <filename>/etc/init.d/ganeti</filename> and register it into
346
        your distribution's startup scripts, for example in Debian:
347
      </para>
348
      <screen>update-rc.d ganeti defaults 20 80</screen>
349

    
350
    </sect2>
351

    
352
    <sect2>
353
      <title>Installing the Operating System support packages</title>
354

    
355
      <para>
356
        Another important component for Ganeti are the OS support
357
        packages, which let different operating systems be used as
358
        instances. You can grab a simple package that allows
359
        installing Debian Etch instances on the project web site
360
        (after download, untar it and follow the instructions in the
361
        <filename>README</filename> file).
362
      </para>
363

    
364
      <para>
365
        Alternatively, you can create your own OS definitions, see
366
        <citerefentry>
367
        <refentrytitle>ganeti-os-interface</refentrytitle>
368
        <manvolnum>8</manvolnum>
369
        </citerefentry>.
370
      </para>
371

    
372
    </sect2>
373

    
374
    <sect2>
375
      <title>Initializing the cluster</title>
376

    
377
      <para><emphasis role="strong">Mandatory:</emphasis> only on one
378
      node per cluster.</para>
379

    
380

    
381
      <para>The last step is to initialize the cluster. After you've repeated
382
        the above process or some semi-automatic form of it on all of your
383
        nodes choose one as the master, and execute:
384
      </para>
385

    
386
      <screen>
387
gnt-cluster init <replaceable>CLUSTERNAME</replaceable>
388
      </screen>
389

    
390
      <para>
391
        If the node's network interface which will be used for access
392
        from outside the cluster is not named
393
        <hardware>xen-br0</hardware>, you need to use the
394
        <option>--master-netdev=<replaceable>IFNAME</replaceable></option>
395
        option, replacing <replaceable>IFNAME</replaceable> with the
396
        correct one for your case (e.g. <hardware>xenbr0</hardware>,
397
        <hardware>eth0</hardware>, etc.). Usually this will be the
398
        same as the default bridge name (see below).
399
      </para>
400

    
401
      <para>
402
        Other options you can pass to <command>gnt-cluster
403
        init</command> include the default bridge name
404
        (<option>-b</option>), the cluster-wide name for the volume
405
        group (<option>-g</option>) and the secondary ip address for
406
        the initial node should you wish to keep the data replication
407
        network separate. Invoke it with <option>--help</option> to
408
        see all the possibilities.
409
      </para>
410

    
411
      <para>
412
        Note that the cluster name must exist in DNS. You must choose
413
        a name different from any of the nodes names for a multi-node
414
        cluster. In general the best choice is to have a unique name
415
        for a cluster, even if it consists of only one machine, as you
416
        will be able to expand it later without any problem.
417
      </para>
418
    </sect2>
419

    
420
    <sect2>
421
      <title>Joining the nodes to the cluster.</title>
422

    
423
      <para>
424
        <emphasis role="strong">Mandatory:</emphasis> for all the
425
        other nodes.
426
      </para>
427

    
428
      <para>
429
        If you have already initialized your cluster you need to join the other
430
        nodes to it. You can do so by executing the following command on the
431
        master node:
432
        <screen>
433
gnt-node add <replaceable>NODENAME</replaceable>
434
        </screen>
435

    
436
        The only option is <option>-s</option>, which sets the node's
437
        secondary ip address for replication purposes, if you are
438
        using a separate replication network.
439
      </para>
440
    </sect2>
441

    
442
  </sect1>
443

    
444
  <sect1>
445
    <title>This is it!</title>
446

    
447
    <para>
448
      Now you can follow the admin guide to use your new Ganeti
449
      cluster.
450
    </para>
451

    
452
  </sect1>
453

    
454

    
455
  </article>