root / doc / design-2.0-os-interface.rst @ ef79eb82
History | View | Annotate | Download (8.5 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 |
- Number of calls: export scripts will be called once for each device the |
105 |
instance has, and import scripts once for every exported disk. Imported |
106 |
instances will be forced to have a number of disks greater or equal to the |
107 |
one of the export. |
108 |
- Some scripts are not compulsory: if such a script is missing the relevant |
109 |
operations will be forbidden for instances of that os. This makes it easier |
110 |
to distinguish between unsupported operations and no-op ones (if any). |
111 |
|
112 |
|
113 |
Input |
114 |
~~~~~ |
115 |
|
116 |
Rather than using command line flags, as they do now, scripts will accept |
117 |
inputs from environment variables. We expect the following input values: |
118 |
|
119 |
OS_API_VERSION |
120 |
The version of the OS api that the following parameters comply with; |
121 |
this is used so that in the future we could have OSes supporting |
122 |
multiple versions and thus Ganeti send the proper version in this |
123 |
parameter |
124 |
INSTANCE_NAME |
125 |
Name of the instance acted on |
126 |
HYPERVISOR |
127 |
The hypervisor the instance should run on (eg. 'xen-pvm', 'xen-hvm', 'kvm') |
128 |
DISK_COUNT |
129 |
The number of disks this instance will have |
130 |
NIC_COUNT |
131 |
The number of nics this instance will have |
132 |
DISK_<N>_PATH |
133 |
Path to the Nth disk. |
134 |
DISK_<N>_ACCESS |
135 |
W if read/write, R if read only. OS scripts are not supposed to touch |
136 |
read-only disks, but will be passed them to know. |
137 |
DISK_<N>_FRONTEND_TYPE |
138 |
Type of the disk as seen by the instance. Can be 'scsi', 'ide', 'virtio' |
139 |
DISK_<N>_BACKEND_TYPE |
140 |
Type of the disk as seen from the node. Can be 'block', 'file:loop' or |
141 |
'file:blktap' |
142 |
NIC_<N>_MAC |
143 |
Mac address for the Nth network interface |
144 |
NIC_<N>_IP |
145 |
Ip address for the Nth network interface, if available |
146 |
NIC_<N>_BRIDGE |
147 |
Node bridge the Nth network interface will be connected to |
148 |
NIC_<N>_FRONTEND_TYPE |
149 |
Type of the Nth nic as seen by the instance. For example 'virtio', 'rtl8139', etc. |
150 |
DEBUG_LEVEL |
151 |
Whether more out should be produced, for debugging purposes. Currently the |
152 |
only valid values are 0 and 1. |
153 |
|
154 |
These are only the basic variables we are thinking of now, but more may come |
155 |
during the implementation and they will be documented in the ganeti-os-api man |
156 |
page. All these variables will be available to all scripts. |
157 |
|
158 |
Some scripts will need a few more information to work. These will have |
159 |
per-script variables, such as for example: |
160 |
|
161 |
OLD_INSTANCE_NAME |
162 |
rename: the name the instance should be renamed from. |
163 |
EXPORT_DEVICE |
164 |
export: device to be exported, a snapshot of the actual device. The data must be exported to stdout. |
165 |
EXPORT_INDEX |
166 |
export: sequential number of the instance device targeted. |
167 |
IMPORT_DEVICE |
168 |
import: device to send the data to, part of the new instance. The data must be imported from stdin. |
169 |
IMPORT_INDEX |
170 |
import: sequential number of the instance device targeted. |
171 |
|
172 |
(Rationale for INSTANCE_NAME as an environment variable: the instance name is |
173 |
always needed and we could pass it on the command line. On the other hand, |
174 |
though, this would force scripts to both access the environment and parse the |
175 |
command line, so we'll move it for uniformity.) |
176 |
|
177 |
|
178 |
Output/Behaviour |
179 |
~~~~~~~~~~~~~~~~ |
180 |
|
181 |
As discussed scripts should only send user-targeted information to stderr. The |
182 |
create and import scripts are supposed to format/initialise the given block |
183 |
devices and install the correct instance data. The export script is supposed to |
184 |
export instance data to stdout in a format understandable by the the import |
185 |
script. The data will be compressed by ganeti, so no compression should be |
186 |
done. The rename script should only modify the instance's knowledge of what |
187 |
its name is. |
188 |
|
189 |
Other declarative style features |
190 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
191 |
|
192 |
Similar to Ganeti 1.2, OS specifications will need to provide a |
193 |
'ganeti_api_version' containing list of numbers matching the version(s) of the |
194 |
api they implement. Ganeti itself will always be compatible with one version of |
195 |
the API and may maintain retrocompatibility if it's feasible to do so. The |
196 |
numbers are one-per-line, so an OS supporting both version 5 and version 20 |
197 |
will have a file containing two lines. This is different from Ganeti 1.2, which |
198 |
only supported one version number. |
199 |
|
200 |
In addition to that an OS will be able to declare that it does support only a |
201 |
subset of the ganeti hypervisors, by declaring them in the 'hypervisors' file. |
202 |
|
203 |
|
204 |
Caveats/Notes |
205 |
------------- |
206 |
|
207 |
We might want to have a "default" import/export behaviour that just dumps all |
208 |
disks and restores them. This can save work as most systems will just do this, |
209 |
while allowing flexibility for different systems. |
210 |
|
211 |
Environment variables are limited in size, but we expect that there will be |
212 |
enough space to store the information we need. If we discover that this is not |
213 |
the case we may want to go to a more complex API such as storing those |
214 |
information on the filesystem and providing the OS script with the path to a |
215 |
file where they are encoded in some format. |