Commit d1b1deb4 authored by Iustin Pop's avatar Iustin Pop

Add documentation for OS parameters

Signed-off-by: default avatarIustin Pop <iustin@google.com>
Reviewed-by: default avatarMichael Hanselmann <hansmi@google.com>
parent 996f742d
...@@ -9,15 +9,18 @@ ganeti-os-interface - Specifications for guest OS types ...@@ -9,15 +9,18 @@ ganeti-os-interface - Specifications for guest OS types
DESCRIPTION DESCRIPTION
----------- -----------
The method of supporting guest operating systems in Ganeti is to The method of supporting guest operating systems in Ganeti is to have,
have, for each guest OS type, a directory containing a number of for each guest OS type, a directory containing a number of required
required files. files. This directory must be present across all nodes (Ganeti doesn't
replicate it) in order for the OS to be usable by Ganeti.
REFERENCE REFERENCE
--------- ---------
There are six required files: *create*, *import*, *export*, *rename* There are six required files: *create*, *import*, *export*, *rename*,
(executables), *ganeti_api_version* and *variants.list* (text files). *verify* (executables), *ganeti_api_version*, *variants.list* and
*parameters.list* (text files).
Common environment Common environment
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
...@@ -27,8 +30,6 @@ common set of variables will be exported for all commands, and some ...@@ -27,8 +30,6 @@ common set of variables will be exported for all commands, and some
of them might have extra ones. Note that all counts are of them might have extra ones. Note that all counts are
zero-based. zero-based.
OS_API_VERSION OS_API_VERSION
The OS API version that the rest of the environment conforms to. The OS API version that the rest of the environment conforms to.
...@@ -111,12 +112,21 @@ NIC_%N_FRONTEND_TYPE ...@@ -111,12 +112,21 @@ NIC_%N_FRONTEND_TYPE
instance, this can be one of: ``rtl8139``, ``ne2k_pci``, instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
``ne2k_isa``, ``paravirtual``. ``ne2k_isa``, ``paravirtual``.
OSP_*name*
Each OS parameter (see below) will be exported in its own
variable, prefixed with ``OSP``, and upper-cased. For example, a
``dhcp`` parameter will be exported as ``OSP_DHCP``.
DEBUG_LEVEL DEBUG_LEVEL
If non-zero, this should cause the OS script to generate verbose If non-zero, this should cause the OS script to generate verbose
logs of its execution, for troubleshooting purposes. Currently logs of its execution, for troubleshooting purposes. Currently
only ``0`` and ``1`` are valid values. only ``0`` and ``1`` are valid values.
EXECUTABLE SCRIPTS
------------------
create create
~~~~~~ ~~~~~~
...@@ -194,6 +204,42 @@ A very simple rename script should at least change the hostname and ...@@ -194,6 +204,42 @@ A very simple rename script should at least change the hostname and
IP address of the instance, leaving the administrator to update the IP address of the instance, leaving the administrator to update the
other services. other services.
verify
~~~~~~
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 message in case the validation
fails.
.. highlight:: sh
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
TEXT FILES
----------
ganeti_api_version ganeti_api_version
~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
...@@ -213,15 +259,32 @@ variants.list is a plain text file containing all the declared ...@@ -213,15 +259,32 @@ variants.list is a plain text file containing all the declared
supported variants for this OS, one per line. At least one variant supported variants for this OS, one per line. At least one variant
must be supported. must be supported.
parameters.list
~~~~~~~~~~~~~~~
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 …
NOTES NOTES
----- -----
Backwards compatibility Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~
Ganeti 2.2 is compatible with both API version 10, and 15. In API Ganeti 2.3 and up is compatible with API version 10, 15 and 20. The OS
version 10 the variants.list file is ignored and no OS_VARIANT parameters and related scripts (verify) are only supported in
environment variable is passed. version 20. The variants functionality (variants.list, and OS_VARIANT
env. var) are supported/present only in version 15 and up.
Common behaviour Common behaviour
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
...@@ -233,6 +296,13 @@ wrong number of arguments or when the first argument is ``-h`` or ...@@ -233,6 +296,13 @@ wrong number of arguments or when the first argument is ``-h`` or
Upgrading from old versions Upgrading from old versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 15 to 20
^^^^^^^^^^^^^^^^
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.
Version 10 to 15 Version 10 to 15
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment