root / doc / design-2.0-os-interface.rst @ 43f30ee6
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 |
|
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 |
- Scripts are not compulsory: if a script is missing the relevant operations |
111 |
will be forbidden for instances of that os. This makes it easier to |
112 |
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 |
INSTANCE_NAME |
122 |
Name of the instance acted on |
123 |
HYPERVISOR |
124 |
The hypervisor the instance should run on (eg. 'xen-pvm', 'xen-hvm', 'kvm') |
125 |
DISK_COUNT |
126 |
The number of disks this instance will have |
127 |
NIC_COUNT |
128 |
The number of nics this instance will have |
129 |
DISK_<N>_PATH |
130 |
Path to the Nth disk. |
131 |
DISK_<N>_ACCESS |
132 |
W if read/write, R if read only. OS scripts are not supposed to touch |
133 |
read-only disks, but will be passed them to know. |
134 |
DISK_<N>_FRONTEND_TYPE |
135 |
Type of the disk as seen by the instance. Can be 'scsi', 'ide', 'virtio' |
136 |
DISK_<N>_BACKEND_TYPE |
137 |
Type of the disk as seen from the node. Can be 'block', 'file:loop' or |
138 |
'file:blktap' |
139 |
NIC_<N>_MAC |
140 |
Mac address for the Nth network interface |
141 |
NIC_<N>_IP |
142 |
Ip address for the Nth network interface, if available |
143 |
NIC_<N>_BRIDGE |
144 |
Node bridge the Nth network interface will be connected to |
145 |
NIC_<N>_FRONTEND_TYPE |
146 |
Type of the Nth nic as seen by the instance. For example 'virtio', 'rtl8139', etc. |
147 |
DEBUG_LEVEL |
148 |
Whether more out should be produced, for debugging purposes. Currently the |
149 |
only valid values are 0 and 1. |
150 |
|
151 |
These are only the basic variables we are thinking of now, but more may come |
152 |
during the implementation and they will be documented in the ganeti-os-api man |
153 |
page. All these variables will be available to all scripts. |
154 |
|
155 |
Some scripts will need a few more information to work. These will have |
156 |
per-script variables, such as for example: |
157 |
|
158 |
NEW_INSTANCE_NAME |
159 |
rename: the name the instance should be renamed to. |
160 |
EXPORT_NODE |
161 |
import/export: node where the export should be saved to or sourced from. |
162 |
EXPORT_PATH |
163 |
import/export: the place where exports are/should be saved to. |
164 |
EXPORT_COMPRESSION |
165 |
import/export: the type of compression for the exports. |
166 |
|
167 |
(Rationale for the EXPORT_NODE, EXPORT_PATH decision: giving always a local |
168 |
path would require either copying exports around, which takes a lot of |
169 |
time/resources or depending on some type of remote filesystem to mount |
170 |
resources on different nodes, which would add even more complexity to the |
171 |
ganeti code, and can be added later, if really needed.) |
172 |
|
173 |
(Rationale for INSTANCE_NAME as an environment variable: the instance name is |
174 |
always needed and we could pass it on the command line. On the other hand, |
175 |
though, this would force scripts to both access the environment and parse the |
176 |
command line, so we'll move it for uniformity.) |
177 |
|
178 |
|
179 |
Output/Behaviour |
180 |
~~~~~~~~~~~~~~~~ |
181 |
|
182 |
As discussed scripts should only send user-targeted information to stdout. The |
183 |
create and import scripts are supposed to format/initialise the given block |
184 |
devices and install the correct instance data. The export script is supposed to |
185 |
export instance data to a target node in a format understandable by the the |
186 |
import script. The rename script should only modify the instance's knowledge of |
187 |
what its name is. |
188 |
|
189 |
Other declarative style features |
190 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
191 |
|
192 |
As for Ganeti 1.2 OS specifications will need to provide a 'ganeti_api_version' |
193 |
with a number matching the version of the api they implement. Ganeti itself |
194 |
will always be compatible with one version of the API and may maintain |
195 |
retrocompatibility if it's feasible to do so. |
196 |
|
197 |
In addition to that an OS will be able to declare that it does support only a |
198 |
subset of the ganeti hypervisors, by declaring them in the 'hypervisors' file. |
199 |
|
200 |
|
201 |
Caveats/Notes |
202 |
------------- |
203 |
|
204 |
We might want to have a "default" import/export behaviour that just dumps all |
205 |
disks and restores them. This can save work as most systems will just do this, |
206 |
while allowing flexibility for different systems. |
207 |
|
208 |
Environment variables are limited in size, but we expect that there will be |
209 |
enough space to store the information we need. If we discover that this is not |
210 |
the case we may want to go to a more complex API such as storing those |
211 |
information on the filesystem and providing the OS script with the path to a |
212 |
file where they are encoded in some format. |