The method of supporting guest operating systems in Ganeti is to have, for each guest OS type, a directory containing a number of required files.
There are six required files: create, import, export, rename (executables), ganeti_api_version and variants.list (text file).
All commands will get their input via environment variables. A common set of variables will be exported for all commands, and some of them might have extra ones. Note that all counts are zero-based.
The OS api version that the rest of the environment conforms to.
The instance name the script should operate on.
The name os the instance's OS as Ganeti knows it. This can simplify the OS scripts by providing the same scripts under multiple names, and then the scripts can use this name to alter their behaviour.
Under OS api 15 changing the script behavior based on this variable is deprecated: OS_VARIANT should be used instead (see below).
The variant of the OS which should be installed. Each OS must support all variants listed under its variants.list file, and may support more. Any more supported variants should be properly documented in the per-os documentation.
The hypervisor of this instance.
The number of disks the instance has. The actual disk defitions are in a set of additional variables. The instance's disk will be numbered from 0 to this value minus one.
The path to the storage for disk N of the
instance. This might be either a block device or a regular
file, in which case the OS scripts should use
losetup (if they need to mount
it). E.g. the first disk of the instance might be exported
as DISK_0_PATH=/dev/drbd0.
This is how the hypervisor will export the instance disks: either read-write (rw) or read-only (ro).
(Optional) If applicable to the current hypervisor type: the type of the device exported by the hypervisor. For example, the Xen HVM hypervisor can export disks as either paravirtual or ioemu.
How files are visible on the node side. This can be either block (when using block devices) or file:type, where type is either loop blktap depending on how the hypervisor will be configured. Note that not all backend types apply to all hypervisors.
Similar to the DISK_COUNT, this
represents the number of NICs of the instance.
The MAC address associated with this interface.
The IP address, if any, associated with the N-th NIC of the instance.
The bridge to which this NIC will be attached to.
(Optional) If applicable, the type of the exported NIC to the instance, this can be one of of: rtl8139, ne2k_pci, ne2k_isa, paravirtual.
If non-zero, this should cause the OS script to generate verbose logs of its execution, for troubleshooting purposes. Currently only 0 and 1 are valid values.
The create command is used for creating a new instance from scratch. It has no additional environment variables bside the common ones.
The INSTANCE_NAME variable denotes the name
of the instance, which is guaranteed to resolve to an IP
address. The create script should configure the instance
according to this name. It can configure the IP statically or
not, depending on the deployment environment.
The INSTANCE_REINSTALL variable is set to '1' when
this create request is reinstalling and existing instance, rather than
creating one anew. This can be used, for example, to preserve some
data in the old instance in an os-specific way.
This command is used in order to make a backup of a given disk of the instance. The command should write to stdout a dump of the given block device. The output of this program will be passed during restore to the import command.
The specific disk to backup is denoted by two additional
environment variables: EXPORT_INDEX which
denotes the index in the instance disks structure (and could
be used for example to skip the second disk if not needed for
backup) and EXPORT_PATH which has the same
value as DISK_N_PATH but is duplicate
here for easier usage by shell scripts (rather than parse the
DISK_... variables).
The import command is used for restoring an instance from a backup as done by export. The arguments are the similar to those passed to export, whose output will be provided on stdin.
The difference in variables is that the current disk is called
by IMPORT_DEVICE and IMPORT_INDEX
(instead of EXPORT_).
This command is used in order to perform a rename at the instance OS level, after the instance has been renamed in Ganeti. The command should do whatever steps are required to ensure that the instance is updated to use the new name, if the operating system supports it.
Note that it is acceptable for the rename script to do nothing at all, however be warned that in this case, there will be a desynchronization between what gnt-instance list shows you and the actual hostname of the instance.
The script will be passed one additional environment
variable called OLD_INSTANCE_NAME which holds the
old instance name. The INSTANCE_NAME variable
holds the new instance name.
A very simple rename script should at least change the hostname and IP address of the instance, leaving the administrator to update the other services.
The ganeti_api_version file is a plain text file containing the version(s) of the guest OS api that this OS definition complies with, one per line. The version documented by this man page is 15, so this file must contain the number 15 followed by a newline if only this version is supported. A script compatible more than one ganeti version should contain the most recent version first (i.e. 15), followed by the old version(s) (in this case 10 and/or 5).
Ganeti 2.1 is compatible with both api version 10, and 15. In api version 10 the variants.list file is ignored and no OS_VARIANT environment variable is passed.
All the scripts should display an usage message when
called with a wrong number of arguments or when the first
argument is -h or
--help.
The variants.list file has been added, so OSes should support at least one variant, declaring it in that file and must be prepared to parse the OS_VARIANT environment variable. OSes are free to support more variants than just the declared ones.
The method os passing data has changed from command line options to environment variables, so scripts should be modified to use these. For an example of how this can be done in a way compatible with both versions, feel free to look at the debootstrap instance's common.sh auxiliary script.
Also, instances can have now a variable number of disks, not only two, and a variable number of NICs (instead of fixed one), so the scripts should deal with this. The biggest change is in the import/export, which are called once per disk, instead of once per instance.
Report bugs to http://code.google.com/p/ganeti/ or contact the developers using the ganeti mailing list <ganeti@googlegroups.com>.
Ganeti overview and specifications: ganeti(7) (general overview), ganeti-os-interface(7) (guest OS definitions).
Ganeti commands: gnt-cluster(8) (cluster-wide commands), gnt-job(8) (job-related commands), gnt-node(8) (node-related commands), gnt-instance(8) (instance commands), gnt-os(8) (guest OS commands), gnt-backup(8) (instance import/export commands), gnt-debug(8) (debug commands).
Ganeti daemons: ganeti-watcher(8) (automatic instance restarter), ganeti-cleaner(8) (job queue cleaner), ganeti-noded(8) (node daemon), ganeti-masterd(8) (master daemon), ganeti-rapi(8) (remote API daemon).
Copyright (C) 2006, 2007, 2008, 2009 Google Inc. Permission is granted to copy, distribute and/or modify under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL.