code.grnet.gr Git - ganeti-local/blob - doc/design-2.0-os-interface.rst

   1 Ganeti 2.0 OS Interface
   2 =======================
   3
   4 .. contents::
   5
   6 Objective
   7 ---------
   8
   9 We want to update the Ganeti OS Interface, which allows different operating
  10 systems to be installed on instances in a Ganeti cluster. This interface has
  11 been designed for Ganeti 1.2, and needs some changes to be compatible with the
  12 changes introduced in Ganeti 2.0 (for a more through discussion of those please
  13 check the Cluster Parameters design doc).
  14
  15
  16 Background
  17 ----------
  18
  19 The current Ganeti OS interface, version 5, is tailored for Ganeti 1.2. The
  20 interface is composed by a series of scripts which get called with certain
  21 parameters to perform OS-dependent operations on the cluster. The current
  22 scripts are:
  23
  24 create
  25   called when a new instance is added to the cluster
  26 export
  27   called to export an instance disk to a stream
  28 import
  29   called to import from a stream to a new instance
  30 rename
  31   called to perform the os-specific operations necessary for renaming an
  32   instance
  33
  34 Currently these scripts suffer from the limitations of Ganeti 1.2: for example
  35 they accept exactly one block and one swap devices to operate on, rather than
  36 any amount of generic block devices, they blindly assume that an instance will
  37 have just one network interface to operate, they can not be configured to
  38 optimise the instance for a particular hypervisor.
  39
  40 Since in Ganeti 2.0 we want to support multiple hypervisors, and a non-fixed
  41 number of network and disks the OS interface need to change to transmit the
  42 appropriate amount of information about an instance to its managing operating
  43 system, when operating on it. Moreover since some old assumptions usually used
  44 in OS scripts are no longer valid we need to re-establish a common knowledge on
  45 what can be assumed and what cannot be regarding Ganeti environment.
  46
  47
  48 Overview
  49 --------
  50
  51 When designing the new OS API our priorities are:
  52 - ease of use
  53 - future extensibility
  54 - ease of porting from the old api
  55 - modularity
  56
  57 As such we want to limit the number of scripts that must be written to support
  58 an OS, and make it easy to share code between them by uniforming their input.
  59 We also will leave the current script structure unchanged, as far as we can,
  60 and make a few of the scripts (import, export and rename) optional. Most
  61 information will be passed to the script through environment variables, for
  62 ease of access and at the same time ease of using only the information a script
  63 needs.
  64
  65
  66 Detailed Design
  67 ---------------
  68
  69 The Scripts
  70 ~~~~~~~~~~~
  71
  72 As in Ganeti 1.2, every OS which wants to be installed in Ganeti needs to
  73 support the following functionality, through scripts:
  74
  75 create:
  76   used to create a new instance running that OS. This script should prepare the
  77   block devices, and install them so that the new OS can boot under the
  78   specified hypervisor.
  79 export (optional):
  80   used to export an installed instance using the given OS to a format which can
  81   be used to import it back into a new instance.
  82 import (optional):
  83   used to import an exported instance into a new one. This script is similar to
  84   create, but the new instance should have the content of the export, rather
  85   than contain a pristine installation.
  86 rename (optional):
  87   used to perform the internal OS-specific operations needed to rename an
  88   instance.
  89
  90 If any optional script is not implemented Ganeti will refuse to perform the
  91 given operation on instances using the non-implementing OS. Of course the
  92 create script is mandatory, and it doesn't make sense to support the either the
  93 export or the import operation but not both.
  94
  95 Incompatibilities with 1.2
  96 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  97
  98 We expect the following incompatibilities between the OS scripts for 1.2 and
  99 the ones for 2.0:
 100
 101 - Input parameters: in 1.2 those were passed on the command line, in 2.0 we'll
 102   use environment variables, as there will be a lot more information and not
 103   all OSes may care about all of it.
 104 - Input/Output: in 1.2 import scripts accepted the instance contents from
 105   standard input, and export scripts exported it to standard output. This can't
 106   be done in 2.0 as we can have more than one disk and so we wouldn't have a
 107   way to distinguish them. A target/source node and directory will be instead
 108   passed, for the import script to do the correct job. All scripts will get
 109   nothing in input and are supposed to output only user-relevant messages.
 110 - Some scripts are not compulsory: if such a script is missing the relevant
 111   operations will be forbidden for instances of that os. This makes it easier
 112   to distinguish between unsupported operations and no-op ones (if any).
 113
 114
 115 Input
 116 ~~~~~
 117
 118 Rather than using command line flags, as they do now, scripts will accept
 119 inputs from environment variables.  We expect the following input values:
 120
 121 OS_API_VERSION
 122   The version of the OS api that the following parameters comply with;
 123   this is used so that in the future we could have OSes supporting
 124   multiple versions and thus Ganeti send the proper version in this
 125   parameter
 126 INSTANCE_NAME
 127   Name of the instance acted on
 128 HYPERVISOR
 129   The hypervisor the instance should run on (eg. 'xen-pvm', 'xen-hvm', 'kvm')
 130 DISK_COUNT
 131   The number of disks this instance will have
 132 NIC_COUNT
 133   The number of nics this instance will have
 134 DISK_<N>_PATH
 135   Path to the Nth disk.
 136 DISK_<N>_ACCESS
 137   W if read/write, R if read only. OS scripts are not supposed to touch
 138   read-only disks, but will be passed them to know.
 139 DISK_<N>_FRONTEND_TYPE
 140   Type of the disk as seen by the instance. Can be 'scsi', 'ide', 'virtio'
 141 DISK_<N>_BACKEND_TYPE
 142   Type of the disk as seen from the node. Can be 'block', 'file:loop' or
 143   'file:blktap'
 144 NIC_<N>_MAC
 145   Mac address for the Nth network interface
 146 NIC_<N>_IP
 147   Ip address for the Nth network interface, if available
 148 NIC_<N>_BRIDGE
 149   Node bridge the Nth network interface will be connected to
 150 NIC_<N>_FRONTEND_TYPE
 151   Type of the Nth nic as seen by the instance. For example 'virtio', 'rtl8139', etc.
 152 DEBUG_LEVEL
 153   Whether more out should be produced, for debugging purposes. Currently the
 154   only valid values are 0 and 1.
 155
 156 These are only the basic variables we are thinking of now, but more may come
 157 during the implementation and they will be documented in the ganeti-os-api man
 158 page. All these variables will be available to all scripts.
 159
 160 Some scripts will need a few more information to work. These will have
 161 per-script variables, such as for example:
 162
 163 OLD_INSTANCE_NAME
 164   rename: the name the instance should be renamed from.
 165 EXPORT_NODE
 166   import/export: node where the export should be saved to or sourced from.
 167 EXPORT_PATH
 168   import/export: the place where exports are/should be saved to.
 169 EXPORT_COMPRESSION
 170   import/export: the type of compression for the exports.
 171
 172 (Rationale for the EXPORT_NODE, EXPORT_PATH decision: giving always a local
 173 path would require either copying exports around, which takes a lot of
 174 time/resources or depending on some type of remote filesystem to mount
 175 resources on different nodes, which would add even more complexity to the
 176 ganeti code, and can be added later, if really needed.)
 177
 178 (Rationale for INSTANCE_NAME as an environment variable: the instance name is
 179 always needed and we could pass it on the command line. On the other hand,
 180 though, this would force scripts to both access the environment and parse the
 181 command line, so we'll move it for uniformity.)
 182
 183
 184 Output/Behaviour
 185 ~~~~~~~~~~~~~~~~
 186
 187 As discussed scripts should only send user-targeted information to stdout. The
 188 create and import scripts are supposed to format/initialise the given block
 189 devices and install the correct instance data. The export script is supposed to
 190 export instance data to a target node in a format understandable by the the
 191 import script. The rename script should only modify the instance's knowledge of
 192 what its name is.
 193
 194 Other declarative style features
 195 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 196
 197 Similar to Ganeti 1.2, OS specifications will need to provide a
 198 'ganeti_api_version' containing list of numbers matching the version(s) of the
 199 api they implement. Ganeti itself will always be compatible with one version of
 200 the API and may maintain retrocompatibility if it's feasible to do so. The
 201 numbers are one-per-line, so an OS supporting both version 5 and version 20
 202 will have a file containing two lines. This is different from Ganeti 1.2, which
 203 only supported one version number.
 204
 205 In addition to that an OS will be able to declare that it does support only a
 206 subset of the ganeti hypervisors, by declaring them in the 'hypervisors' file.
 207
 208
 209 Caveats/Notes
 210 -------------
 211
 212 We might want to have a "default" import/export behaviour that just dumps all
 213 disks and restores them. This can save work as most systems will just do this,
 214 while allowing flexibility for different systems.
 215
 216 Environment variables are limited in size, but we expect that there will be
 217 enough space to store the information we need. If we discover that this is not
 218 the case we may want to go to a more complex API such as storing those
 219 information on the filesystem and providing the OS script with the path to a
 220 file where they are encoded in some format.