1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
3 <article class="specification">
5 <title>Ganeti node/cluster installation tutorial</title>
7 <para>Documents Ganeti version 1.2</para>
10 <title>Introduction</title>
12 <para>Ganeti is a cluster virtualization management system. This document
13 explains how to bootstrap a Ganeti node and create a running cluster. You
14 need to repeat most of the steps in this document for every node you want to
15 install, but of course we recommend creating some semi-automatic procedure
16 if you plan to deploy Ganeti on a medium/large scale.
19 <para>This document is divided into two main sections:
23 <simpara>Installation of the core system and base components</simpara>
26 <simpara>Configuration of the environment for Ganeti</simpara>
30 Each of these is divided into sub-sections. While a full Ganeti system will
31 need all of the steps specified, some are not strictly required for every
32 environment. Which ones they are, and why, is specified in the
33 corresponding sections.
36 <para>While Ganeti itself is distribution-agnostic most of the examples in
37 this document will be targeted at Debian or debian derived distributions.
38 You are expected to be familiar with your distribution, its package
39 management system, and Xen before trying to use Ganeti.
42 <para>A basic Ganeti terminology glossary is provided in the introductory
43 section of the "admin guide". Please refer to that if you are uncertain
44 about the terms we are using.
50 <title>Installing the system and base components</title>
53 <title>Installing the base system</title>
58 <para>Please install your operating system as you would normally do. The
59 only requirement you need to be aware of at this stage is to partition
60 leaving enough space for a big LVM volume group which will then host
61 your instance file systems. You can even create the volume group at
62 installation time, of course: the default volume group name Ganeti 1.2
63 uses is "xenvg" but you may name it differently should you wish to, as
64 long as the name is the same for all the nodes in the cluster.
70 <title>Installing Xen</title>
72 <para>Mandatory: While Ganeti is developed with the ability to modularly
73 run on different virtualization environments in mind the only one
74 currently useable on a live system is Xen.
77 <para>Please follow your distribution's recommended way to install and set
78 up Xen, or install Xen from the upstream source, if you wish, following
82 <para>For example under Debian 4.0 or 3.1+backports you can install the
83 relevant xen-linux-system package, which will pull in both the hypervisor
84 and the relevant kernel. On Ubuntu (from Gutsy on) the package is called
88 <para>After installing Xen you need to reboot into your xenified dom0
89 system. Again on some distributions this might involve configuring GRUB
96 <title>Installing DRBD</title>
98 <para>Recommended: DRBD is required if you want to use the high
99 availability (HA) features of Ganeti, but optional if you don't require
100 HA or only run Ganeti on single-node clusters. You can upgrade a non-HA
101 cluster to an HA one later, but you might need to export and reimport
102 all your instances to take advantage of the new features.
105 <para>Now the bad news: unless your distribution already provides it
106 installing DRBD might involve recompiling your kernel or anyway fiddling
107 with it. Hopefully at least the xenified kernel source to start from will
111 <para>Under Debian you can just install the drbd0.7-module-source and
112 drbd0.7-utils packages, and your kernel source, and then run
113 module-assistant to compile the drbd0.7 module. The commands:
120 should do it for you.
123 <para>The good news is that you don't need to configure DRBD at all.
124 Ganeti will do it for you for every instance you set up. If you have the
125 DRBD utils installed and the module in your kernel you're fine. Please
126 check that your system is configured to load the module at every boot.
135 <title>Setting up the environment for Ganeti</title>
138 <title>Configuring the network</title>
140 <para>Ganeti relies on Xen running in "bridge mode", which means the
141 instances network interfaces will be attached to a software bridge
142 running in dom0. Xen by default creates such a bridge at startup, but
143 your distribution might have a different way to do things.
147 In Debian, in order to enable the default Xen behaviour, you have to edit
148 /etc/xen/xend-config.sxp and replace (network-script network-dummy) with
149 (network-script network-bridge). The recommended Debian way to configure
150 things, though, is to edit your /etc/network/interfaces file and
151 substitute your normal ethernet stanza with something like:
155 iface br0 inet static
156 address YOUR_IP_ADDRESS
159 broadcast YOUR_BROADCAST_ADDRSS
161 # dns-* options are implemented by the resolvconf package, if installed
162 dns-nameservers YOUR_DNS_SERVERS
163 dns-search YOUR_SEARCH_PATH
172 Beware that the default name Ganeti uses is xen-br0 (which was used in
173 Xen 2.0) while Xen 3.0 uses xenbr0 by default. The default bridge your
174 cluster will use for new instances can be specified at cluster
181 <title>Configuring LVM</title>
184 If you haven't configured your LVM volume group at install time you need
185 to do it before trying to initialize the Ganeti cluster. This is done by
186 formatting the devices/partitions you want to use for it and then adding
187 them to the relevant volume group:
193 vgcreate xenvg /dev/sda4 /dev/sdb /dev/sdc1
198 If you want to add a device later you can do so with the
199 <citerefentry><refentrytitle>vgextend</refentrytitle>
200 <manvolnum>8</manvolnum></citerefentry> command.
203 vgextend xenvg /dev/sdd
208 As said before you may choose a different name for the volume group,
209 as long as you stick to the same name on all the nodes of a cluster.
214 <title>Installing Ganeti</title>
216 <para>It's now time to install the Ganeti software itself if you haven't
217 done it yet. You can do it from source, with the usual steps:
225 or you can install the package relevant to your distribution, for
226 example in Debian/Ubuntu:
229 dpkg -i ganeti_VERSION_all.deb
232 or, if you have a source repository that holds the Ganeti software:
235 apt-get install ganeti
242 <title>Installing the Operating System support packages</title>
244 <para>Another important component for Ganeti is the OS support packages,
245 which let different operating systems be used as instances. You can
246 install them by installing the relevant ganeti-instance-OS package.
252 <title>Initializing the cluster</title>
254 <para>Mandatory: only on one node per cluster.
258 <para>The last step is to initialize the cluster. After you've repeated
259 the above process or some semi-automatic form of it on all of your
260 nodes choose one as the master, and execute:
263 gnt-cluster init CLUSTERNAME
266 Options you can pass to gnt-cluster init include the default bridge
267 name (-b), the cluster-wide name for the volume group (-g) and the
268 secondary ip address for the initial node should you wish to keep the
269 data replication network separate. Invoke it with --help to see all the
273 <para>The cluster name must exist in DNS. You must choose a name
274 different from any of the nodes names for a multi-node cluster. In
275 general the best choice is to have a completely unique name for each
281 <title>Joining the nodes to the cluster.</title>
283 <para>Mandatory: for all the other nodes.
287 If you have already initialized your cluster you need to join the other
288 nodes to it. You can do so by executing the following command on the
291 gnt-node add NODENAME
294 The only option is (-s), which sets the node's secondary ip address for
295 replication purposes, if you are using a separate replication network.
302 <title>This is it!</title>
304 <para>Now you can follow the "admin guide" to use your new Ganeti cluster.