Statistics
| Branch: | Tag: | Revision:

root / docs / installing.sgml @ 6bf0c9bb

History | View | Annotate | Download (9.9 kB)

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

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

    
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.
17
    </para>
18

    
19
    <para>This document is divided into two main sections:
20

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

    
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.
34
    </para>
35

    
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.
40
    </para>
41

    
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.
45
    </para>
46

    
47
  </sect1>
48

    
49
  <sect1>
50
    <title>Installing the system and base components</title>
51

    
52
    <sect2>
53
      <title>Installing the base system</title>
54

    
55
      <para>Mandatory.
56
      </para>
57

    
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.
65
      </para>
66

    
67
    </sect2>
68

    
69
    <sect2>
70
      <title>Installing Xen</title>
71

    
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.
75
      </para>
76

    
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
79
      their manual.
80
      </para>
81

    
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
85
      ubuntu-xen-server.
86
      </para>
87

    
88
      <para>After installing Xen you need to reboot into your xenified dom0
89
      system. Again on some distributions this might involve configuring GRUB
90
      appropriately.
91
      </para>
92

    
93
    </sect2>
94

    
95
    <sect2>
96
      <title>Installing DRBD</title>
97

    
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.
103
      </para>
104

    
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
108
      be provided.
109
      </para>
110

    
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:
114

    
115
      <programlisting>
116
m-a update
117
m-a a-i drbd0.7
118
      </programlisting>
119

    
120
      should do it for you.
121
      </para>
122

    
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.
127
      </para>
128

    
129
    </sect2>
130

    
131
  </sect1>
132

    
133

    
134
  <sect1>
135
    <title>Setting up the environment for Ganeti</title>
136

    
137
    <sect2>
138
      <title>Configuring the network</title>
139

    
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.
144
      </para>
145

    
146
      <para>
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:
152

    
153
      <programlisting>
154
auto br0
155
iface br0 inet static
156
        address YOUR_IP_ADDRESS
157
        netmask YOUR_NETMASK
158
        network YOUR_NETWORK
159
        broadcast YOUR_BROADCAST_ADDRSS
160
        gateway YOUR_GATEWAY
161
        # dns-* options are implemented by the resolvconf package, if installed
162
        dns-nameservers YOUR_DNS_SERVERS
163
        dns-search YOUR_SEARCH_PATH
164
        bridge_ports eth0
165
        bridge_stp off
166
        bridge_fd 0
167
      </programlisting>
168

    
169
    </para>
170

    
171
    <para>
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
175
      initialization time.
176
    </para>
177

    
178
    </sect2>
179

    
180
    <sect2>
181
      <title>Configuring LVM</title>
182

    
183
      <para>
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:
188

    
189
       <programlisting>
190
pvcreate /dev/sda4
191
pvcreate /dev/sdb
192
pvcreate /dev/sdc1
193
vgcreate xenvg /dev/sda4 /dev/sdb /dev/sdc1
194
       </programlisting>
195
      </para>
196

    
197
      <para>
198
        If you want to add a device later you can do so with the vgextend(8)
199
        command.
200
        <programlisting>
201
pvcreate /dev/sdd
202
vgextend xenvg /dev/sdd
203
        </programlisting>
204
      </para>
205

    
206
      <para>
207
        As said before you may choose a different name for the volume group,
208
        as long as you stick to the same name on all the nodes of a cluster.
209
      </para>
210
    </sect2>
211

    
212
    <sect2>
213
      <title>Installing Ganeti</title>
214

    
215
      <para>It's now time to install the Ganeti software itself if you haven't
216
        done it yet. You can do it from source, with the usual steps:
217

    
218
        <programlisting>
219
./configure
220
make
221
make install
222
        </programlisting>
223

    
224
        or you can install the package relevant to your distribution, for
225
        example in Debian/Ubuntu:
226

    
227
        <programlisting>
228
dpkg -i ganeti_VERSION_all.deb
229
        </programlisting>
230

    
231
        or, if you have a source repository that holds the Ganeti software:
232

    
233
        <programlisting>
234
apt-get install ganeti
235
        </programlisting>
236
      </para>
237

    
238
    </sect2>
239

    
240
    <sect2>
241
      <title>Installing the Operating System support packages</title>
242

    
243
      <para>Another important component for Ganeti is the OS support packages,
244
        which let different operating systems be used as instances. You can
245
        install them by installing the relevant ganeti-instance-OS package.
246
      </para>
247

    
248
    </sect2>
249

    
250
    <sect2>
251
      <title>Initializing the cluster</title>
252

    
253
      <para>Mandatory: only on one node per cluster.
254
      </para>
255

    
256

    
257
      <para>The last step is to initialize the cluster. After you've repeated
258
        the above process or some semi-automatic form of it on all of your
259
        nodes choose one as the master, and execute:
260

    
261
        <programlisting>
262
gnt-cluster init CLUSTERNAME
263
        </programlisting>
264

    
265
        Options you can pass to gnt-cluster init include the default bridge
266
        name (-b), the cluster-wide name for the volume group (-g) and the
267
        secondary ip address for the initial node should you wish to keep the
268
        data replication network separate. Invoke it with --help to see all the
269
        possibilities.
270
      </para>
271

    
272
      <para>The cluster name must exist in DNS. You must choose a name
273
        different from any of the nodes names for a multi-node cluster. In
274
        general the best choice is to have a completely unique name for each
275
        cluster.
276
      </para>
277
    </sect2>
278

    
279
    <sect2>
280
      <title>Joining the nodes to the cluster.</title>
281

    
282
      <para>Mandatory: for all the other nodes.
283
      </para>
284

    
285
      <para>
286
        If you have already initialized your cluster you need to join the other
287
        nodes to it. You can do so by executing the following command on the
288
        master node:
289
        <programlisting>
290
gnt-node add NODENAME
291
        </programlisting>
292

    
293
        The only option is (-s), which sets the node's secondary ip address for
294
        replication purposes, if you are using a separate replication network.
295
      </para>
296
    </sect2>
297

    
298
  </sect1>
299

    
300
  <sect1>
301
    <title>This is it!</title>
302

    
303
    <para>Now you can follow the "admin guide" to use your new Ganeti cluster.
304
    </para>
305

    
306
  </sect1>
307

    
308

    
309
  </article>