ganeti-os-interface - Specifications for guest OS types
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. This directory must be present across all nodes (Ganeti doesn’t replicate it) in order for the OS to be usable by Ganeti.
There are eight required files: create, import, export, rename, verify (executables), ganeti_api_version, variants.list and parameters.list (text files).
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.
Since Ganeti version 2.5, the environment will be cleaned up before being passed to scripts, therefore they will not inherit the environment in with which the ganeti node daemon was started. If you depend on any environment variables (non-Ganeti), then you will need to define or source them appropriately.
Both names point to the name of 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.
With OS API 15 changing the script behavior based on this variable is deprecated: OS_VARIANT should be used instead (see below).
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 an existing instance, rather than creating a new one. 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_DEVICE which has the same value as DISK_N_PATH but is duplicated here for easier usage by shell scripts (rather than parse the DISK_... variables).
To provide the user with an estimate on how long the export will take, a predicted size can be written to the file descriptor passed in the variable EXP_SIZE_FD. The value is in bytes and must be terminated by a newline character (\n). Older versions of Ganeti don’t support this feature, hence the variable should be checked before use. Example:
if test -n "$EXP_SIZE_FD"; then
blockdev --getsize64 $blockdev >&$EXP_SIZE_FD
fi
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 denoted 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 verify script is used to verify consistency of the OS parameters (see below). The command should take one or more arguments denoting what checks should be performed, and return a proper exit code depending on whether the validation failed or succeeded.
Currently (API version 20), only one parameter is supported: parameters. This should validate the OSP_ variables from the environment, and output diagnostic messages in case the validation fails.
For the dhcp parameter given as example above, a verification script could be:
#!/bin/sh
case $OSP_DHCP in
""|yes|no)
;;
*)
echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
exit 1;
;;
esac
exit 0
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 20, so this file must contain the number 20 followed by a newline if only this version is supported. A script compatible with more than one Ganeti version should contain the most recent version first (i.e. 20), followed by the old version(s) (in this case 15 and/or 10).
variants.list is a plain text file containing all the declared supported variants for this OS, one per line. If this file is missing or empty, then the OS won’t be considered to support variants.
Empty lines and lines starting with a hash (#) are ignored.
This file declares the parameters supported by the OS, one parameter per line, with name and description (space and/or tab separated). For example:
dhcp Whether to enable (yes) or disable (no) dhcp
root_size The size of the root partition, in GiB
The parameters can then be used in instance add or modification, as follows:
# gnt-instance add -O dhcp=no,root_size=8 ...
Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS parameters and related scripts (verify) are only supported in version 20. The variants functionality (variants.list, and OS_VARIANT env. var) are supported/present only in version 15 and up.
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 parameters.list file and verify script have been added. For no parameters, an empty parameters file and an empty verify script which returns success can be used.
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. Note that this file is optional; without it, the variants functionality is disabled.
The method for 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.
The rename script has been added. If you don’t want to do any changes on the instances after a rename, you can migrate the OS definition to version 5 by creating the rename script simply as:
#!/bin/sh
exit 0
Note that the script must be executable.