Statistics
| Branch: | Revision:

root / README @ 6cee02d4

History | View | Annotate | Download (10.8 kB)

1
ganeti-instance-image
2
=====================
3

    
4
This is a guest OS definition for Ganeti (http://code.google.com/p/ganeti). It
5
will install a Linux-based image using either a tarball or qemu-img disk image
6
file. This definition also allows for manual creation of an instance by simply
7
setting only the disks up and allowing you to boot via the install cd manually.
8
The goal of this instance is to allow fast and flexible installation of
9
instances without the need for external tools such as debootstrap.
10

    
11
Installation
12
------------
13

    
14
In order to install this package from source, you need to determine what options
15
ganeti itself has been configured with. If ganeti was built directly from
16
source, then the only place it looks for OS definitions is ``/srv/ganeti/os``,
17
and you need to install the OS under it::
18

    
19
  ./configure --prefix=/usr --localstatedir=/var \
20
    --sysconfdir=/etc \
21
    --with-os-dir=/srv/ganeti/os
22
  make && make install
23

    
24
If ganeti was installed from a package, its default OS path should already
25
include /usr/share/ganeti/os, so you can just run::
26

    
27
  ./configure -prefix=/usr --localstatedir=/var \
28
    --sysconfdir=/etc
29
  make && make install
30

    
31
Note that you need to repeat this procedure on all nodes of the cluster.
32

    
33
The actual path that ganeti has been installed with can be determined by looking
34
for a file named _autoconf.py under a ganeti directory in the python modules
35
tree (e.g.  ``/usr/lib/python2.4/site-packages/ganeti/_autoconf.py``). In this
36
file, a variable named OS_SEARCH_PATH will list all the directories in which
37
ganeti will look for OS definitions.
38

    
39
Configuration of instance creation
40
----------------------------------
41

    
42
The kind of instance created can be customized via a settings file. This file
43
may or may not be installed by default, as the instance creation will work
44
without it. The creation scripts will look for it in
45
``$sysconfdir/default/ganeti-instance-image``, so if you have run configure with
46
the parameter ``--sysconfdir=/etc``, the final filename will be
47
``/etc/default/ganeti-instance-image``.
48

    
49
The following settings will be examined in this file:
50

    
51
- CDINSTALL:  If 'yes' only setup disks for a cd based install or manual
52
              installation via other means. It will not deploy any images or
53
              create any partitions. (default: no)
54
- SWAP:       Create a swap partition (tarball only) (default: yes)
55
- IMAGE_NAME: Name for the image to use. Generally they will have names similar
56
              to: centos-5.4, debian-5.0, etc. The naming is free form depending
57
              on what you name the file itself.
58
- IMAGE_TYPE: Create instance by either using a gzipped tarball or an image
59
              created by qemu-img. Accepts either 'tarball' or 'qemu'.
60
              (default: qemu).
61
- IMAGE_DIR:  Override default location for images.
62
              (default: ``$localstatedir/cache/ganeti-instance-image``)
63
- ARCH:       Define the architecture of the image to use. Accepts either 'x86'
64
              or 'x86_64'.
65
- CUSTOMIZE_DIR: A directory containing customization script for the instance.
66
              (by default $sysconfdir/ganeti/instance-image.d) See
67
              "Customization of the instance" below.
68
- IMAGE_DEBUG: Enable verbose output for instance scripts.
69

    
70
Note that the settings file is important on the node that the instance is
71
installed on, not the cluster master. This is indeed not a very good model of
72
using this OS but currently the OS interface in ganeti is limiting.
73

    
74
Creation of Deployment Images
75
-----------------------------
76

    
77
There are three types that are supported for deploying images.
78

    
79
  * tarball
80
  * qemu image
81
  * dump
82

    
83
Tarball
84
~~~~~~~
85

    
86
Tarball based images are quite simply a tarball of a working system. An good
87
example use case for this is deploying a Gentoo instance using a stage4 tarball.
88
The only requirement is that the tarball is gzipped instead of bzip2 for speed.
89
If you wish use a kernel inside of the VM instead of externally, make sure that
90
a working kernel, grub config are install in the tarball. Enable the 'grub'
91
custom script to install the grub boot image during installation.
92

    
93
Qemu Images
94
~~~~~~~~~~~
95

    
96
To create a new qemu based disk image, you will need to able the ``CDINSTALL``
97
option and install the VM using the distro's provided installation medium. It is
98
not recommended to build images on systems outside of ganeti (such as libvirt)
99
as we have encountered issues with systems segfaulting.
100

    
101
Once the instance has been created, boot the instance and point it to the
102
install medium::
103

    
104
  gnt-instance start -H cdrom_image_path=path/to/iso/ubuntu-9.10.iso, \
105
    boot_order=cdrom instance-name
106

    
107
Once the base image has been installed, ensure you have the acpid package
108
installed so that ganeti can shutdown the VM properly. Once you are happy with
109
your base image, shutdown the VM, activate the disks,  and create the disk
110
image using qemu-img. Its recommended you use qcow2 with compression to reduce
111
the amount of disk space used::
112

    
113
 # activate disks
114
 gnt-instance activate-disks instance-name
115
 # create image
116
 qemu-img convert -c -f host_device /dev/drbd1 \
117
    -O qcow2 $IMAGE_DIR/ubuntu-9.10-x86_64.img
118

    
119
Note: Older versions of qemu-img may not support the ``host_device`` format so
120
use ``raw`` instead which should work in theory.
121

    
122
Dump
123
~~~~
124

    
125
The last, and most efficient type of disk image is creating filesystem dumps
126
using the dump command. The advantage with using dumps is that its much faster
127
to deploy using it, and it also has built-in compression. The disadvantage is
128
that you need to install grub manually which might be an issue on some operating
129
systems. We currently support grub 1, but anything using grub 2 will have issues
130
that I haven't found a solution for yet.
131

    
132
You will need to create images for both the boot and root partition (if you
133
include a boot partition).
134

    
135
Create a base image for an instance just like its described in Qemu Images. Make
136
sure the instance is shutdown and then issue the following commands (assuming
137
the activated disk is drbd1)::
138

    
139
  dump -0 -q -z9 -f ${IMAGE_DIR}/${IMAGE_NAME}-${ARCH}-boot.dump \
140
    /dev/mapper/drbdq-1
141

    
142
  dump -0 -q -z9 -f ${IMAGE_DIR}/${IMAGE_NAME}-${ARCH}-root.dump \
143
    /dev/mapper/drbdq-3
144

    
145
Partition Layout
146
~~~~~~~~~~~~~~~~
147

    
148
Currently the partition layout is locked into a specific way in order to make it
149
work more elegantly with ganeti. We might change this to be more flexible in the
150
future, however you *must* use the following layout otherwise ganeti will not
151
install the VM correctly. Currently the following partition layout is assumed:
152

    
153
With swap::
154
 /dev/$disk1    /boot
155
 /dev/$disk2    swap
156
 /dev/$disk3    /
157

    
158
Without swap::
159
 /dev/$disk1    /boot
160
 /dev/$disk2    /
161

    
162
NOTE: If you have kernel_path set, /boot will not be created and all partition
163
numbers will go up by one. For example:
164

    
165
With swap::
166
 /dev/$disk1    swap
167
 /dev/$disk2    /
168

    
169
Without swap::
170
 /dev/$disk1    /
171

    
172
Image Naming
173
~~~~~~~~~~~~
174

    
175
The naming convention that is used is the following:
176

    
177
tarball:    $IMAGE_NAME-$ARCH.tar.gz
178
qemu-img:   $IMAGE_NAME-$ARCH.img
179
dump:       $IMAGE_NAME-$ARCH-boot.dump
180
            $IMAGE_NAME-$ARCH-root.dump
181

    
182
Useful Scripts
183
~~~~~~~~~~~~~~
184

    
185
There are a set of useful scripts located in /usr/share/ganeti/os/image/tools
186
that you are welcome to use. These scripts are all intended to be run on the
187
master node::
188

    
189
  mount-disks $instance_name
190
  umount-disks $instance_name
191

    
192
This will mount or umount an instance to /tmp/${instance_name}_root
193

    
194
  ``make-dump $instance_name [ $IMAGE_DIR ]``
195

    
196
Create dump images for the given OS variant. You can override the default
197
$IMAGE_DIR setting by giving it as a second argument.
198

    
199
  ``make-qemu-img $instance_name [ $IMAGE_DIR ]``
200

    
201
Create an qemu image for the given OS variant.
202

    
203
Customization of the instance
204
-----------------------------
205

    
206
If run-parts is in the os create script, and the CUSTOMIZE_DIR (by default
207
$sysconfdir/ganeti/instance-image.d, /etc/ganeti/instance-image.d if you
208
configured the os with --sysconfdir=/etc) directory exists any executable whose
209
name matches the run-parts execution rules (quoting run-parts(8): the names must
210
consist entirely of upper and lower case letters, digits, underscores, and
211
hyphens) is executed to allow further personalization of the installation. The
212
following environment variables are passed, in addition to the ones ganeti
213
passes to the OS scripts:
214

    
215
TARGET:     directory in which the filesystem is mounted
216
BLOCKDEV:   ganeti block device
217
ROOT_DEV:   device in which the root (/) filesystem resides (the one mounted in
218
            TARGET)
219
BOOT_DEV:   device in which the boot (/boot) filesystem resides
220
IMAGE_TYPE: type of image being used (tarball, qemu, dump)
221

    
222
The scripts in CUSTOMIZE_DIR can exit with an error code to signal an error in
223
the instance creation, should they fail.
224

    
225
The scripts in CUSTOMIZE_DIR should not start any long-term processes or daemons
226
using this directory, otherwise the installation will fail because it won't be
227
able to umount the filesystem from the directory, and hand the instance back to
228
Ganeti.
229

    
230
Included Custom Scripts
231
-----------------------
232

    
233
This OS definition includes three optional customization scripts that are
234
disabled by default. They are not required but are useful.
235

    
236
Grub
237
~~~~
238

    
239
When enabled, this can setup two things:
240

    
241
- Install grub into the MBR
242
- Setup serial access to grub
243

    
244
In general, the MBR will only be installed if you're not using a qemu image
245
type, or the ``kernel_path`` parameter is empty or initiating an import.  There
246
is currently no support for install a grub2 MBR (which Ubuntu Karmic requires).
247
Its recommended that you only use the qemu image type for Ubuntu Karmic until we
248
fix this.
249

    
250
If ``serial_console`` is ``True`` then this script will try to enable serial
251
support for grub.
252

    
253
Interfaces
254
~~~~~~~~~~
255

    
256
When enabled, it would try to setup networking for eth0 and enable DHCP. It
257
assumes you already have a DHCP client installed on the guest OS. This currently
258
supports the following operating systems:
259

    
260
- Redhat (CentOS/Fedora)
261
- Debian/Ubuntu
262
- Gentoo
263
- OpenSUSE
264

    
265
If you need to set a static ip for instances, you can do that by creating
266
several files in a manner described below.
267

    
268
Subnets:
269

    
270
Create a file in ``/etc/ganeti/instance-image/networks/subnets`` that has a
271
useful name such as ``vlan42``. This file will describe subnet routing
272
information such as the netmask and gateway. The following is an example:
273

    
274
  NETMASK=255.255.255.0
275
  GATEWAY=192.168.1.1
276

    
277
Instance:
278

    
279
Create a file in ``/etc/ganeti/instance-image/networks/instances`` and name it
280
the FQDN of the instance. The file will describe the IP address for the instance
281
and which subnet it resides on. For example, we could create a file named
282
``myinstance.osuosl.org`` and have the following in it:
283

    
284
  ADDRESS=192.168.1.100
285
  SUBNET=vlan42
286

    
287
SSH
288
~~~
289

    
290
When enabled, it will clear out any generated ssh keys that the image may have
291
so that each instance have *unique* host keys. Currently its disabled for
292
Debian/Ubuntu since the keys won't be regenerated via the init script. We plan
293
to fix this manually at some point in the future.
294

    
295
# vi: set tw=80 ft=rst :