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