root / man / ganeti-os-interface.rst @ a317d77a
History | View | Annotate | Download (12.6 kB)
1 |
ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@ |
---|---|
2 |
======================================================== |
3 |
|
4 |
Name |
5 |
---- |
6 |
|
7 |
ganeti-os-interface - Specifications for guest OS types |
8 |
|
9 |
DESCRIPTION |
10 |
----------- |
11 |
|
12 |
The method of supporting guest operating systems in Ganeti is to have, |
13 |
for each guest OS type, a directory containing a number of required |
14 |
files. This directory must be present across all nodes (Ganeti doesn't |
15 |
replicate it) in order for the OS to be usable by Ganeti. |
16 |
|
17 |
|
18 |
REFERENCE |
19 |
--------- |
20 |
|
21 |
There are eight required files: *create*, *import*, *export*, *rename*, |
22 |
*verify* (executables), *ganeti_api_version*, *variants.list* and |
23 |
*parameters.list* (text files). |
24 |
|
25 |
Common environment |
26 |
~~~~~~~~~~~~~~~~~~ |
27 |
|
28 |
All commands will get their input via environment variables. A |
29 |
common set of variables will be exported for all commands, and some |
30 |
of them might have extra ones. Note that all counts are |
31 |
zero-based. |
32 |
|
33 |
Since Ganeti version 2.5, the environment will be cleaned up before |
34 |
being passed to scripts, therefore they will not inherit the environment |
35 |
in with which the ganeti node daemon was started. If you depend on any |
36 |
environment variables (non-Ganeti), then you will need to define or |
37 |
source them appropriately. |
38 |
|
39 |
OS_API_VERSION |
40 |
The OS API version that the rest of the environment conforms to. |
41 |
|
42 |
INSTANCE_NAME |
43 |
The instance name the script should operate on. |
44 |
|
45 |
INSTANCE_OS, OS_NAME |
46 |
Both names point to the name of the instance's OS as Ganeti knows |
47 |
it. This can simplify the OS scripts by providing the same scripts |
48 |
under multiple names, and then the scripts can use this name to |
49 |
alter their behaviour. |
50 |
|
51 |
With OS API 15 changing the script behavior based on this variable |
52 |
is deprecated: OS_VARIANT should be used instead (see below). |
53 |
|
54 |
OS_VARIANT |
55 |
The variant of the OS which should be installed. Each OS must |
56 |
support all variants listed under its variants.list file, and may |
57 |
support more. Any more supported variants should be properly |
58 |
documented in the per-OS documentation. |
59 |
|
60 |
HYPERVISOR |
61 |
The hypervisor of this instance. |
62 |
|
63 |
DISK_COUNT |
64 |
The number of disks the instance has. The actual disk definitions are |
65 |
in a set of additional variables. The instance's disk will be |
66 |
numbered from 0 to this value minus one. |
67 |
|
68 |
DISK_%N_PATH |
69 |
The path to the storage for disk N of the instance. This might be |
70 |
either a block device or a regular file, in which case the OS |
71 |
scripts should use ``losetup`` (if they need to mount it). E.g. the |
72 |
first disk of the instance might be exported as |
73 |
``DISK_0_PATH=/dev/drbd0``. |
74 |
|
75 |
DISK_%N_ACCESS |
76 |
This is how the hypervisor will export the instance disks: either |
77 |
read-write (``rw``) or read-only (``ro``). |
78 |
|
79 |
DISK_%N_UUID |
80 |
The uuid associated with the N-th disk of the instance. |
81 |
|
82 |
DISK_%N_NAME |
83 |
(Optional) The name, if any, associated with the N-th disk of the instance. |
84 |
|
85 |
DISK_%N_FRONTEND_TYPE |
86 |
(Optional) If applicable to the current hypervisor type: the type |
87 |
of the device exported by the hypervisor. For example, the Xen HVM |
88 |
hypervisor can export disks as either ``paravirtual`` or |
89 |
``ioemu``. |
90 |
|
91 |
DISK_%N_BACKEND_TYPE |
92 |
How files are visible on the node side. This can be either |
93 |
``block`` (when using block devices) or ``file:type``, where |
94 |
``type`` is either ``loop``, ``blktap`` or ``blktap2``, depending on how the |
95 |
hypervisor will be configured. Note that not all backend types apply to all |
96 |
hypervisors. |
97 |
|
98 |
NIC_COUNT |
99 |
Similar to the ``DISK_COUNT``, this represents the number of NICs |
100 |
of the instance. |
101 |
|
102 |
NIC_%N_MAC |
103 |
The MAC address associated with this interface. |
104 |
|
105 |
NIC_%N_UUID |
106 |
The uuid associated with the N-th NIC of the instance. |
107 |
|
108 |
NIC_%N_NAME |
109 |
(Optional) The name, if any, associated with the N-th NIC of the instance. |
110 |
|
111 |
NIC_%N_IP |
112 |
The IP address, if any, associated with the N-th NIC of the |
113 |
instance. |
114 |
|
115 |
NIC_%N_MODE |
116 |
The NIC mode, routed, bridged or openvswitch |
117 |
|
118 |
NIC_%N_BRIDGE |
119 |
The bridge to which this NIC will be attached. This variable is |
120 |
defined only when the NIC is in bridged mode. |
121 |
|
122 |
NIC_%N_LINK |
123 |
In bridged or openvswitch mode, this is the interface to which the |
124 |
NIC will be attached (same as ``NIC_%N_BRIDGE`` for bridged). In |
125 |
routed mode it is the routing table which will be used by the |
126 |
hypervisor to insert the appropriate routes. |
127 |
|
128 |
NIC_%N_FRONTEND_TYPE |
129 |
(Optional) If applicable, the type of the exported NIC to the |
130 |
instance, this can be one of: ``rtl8139``, ``ne2k_pci``, |
131 |
``ne2k_isa``, ``paravirtual``. |
132 |
|
133 |
NIC_%d_NETWORK_NAME |
134 |
(Optional) If a NIC network is specified, the network's name. |
135 |
|
136 |
NIC_%d_NETWORK_UUID |
137 |
(Optional) If a NIC network is specified, the network's uuid. |
138 |
|
139 |
NIC_%d_NETWORK_FAMILY |
140 |
(Optional) If a NIC network is specified, the network's family. |
141 |
|
142 |
NIC_%d_NETWORK_SUBNET |
143 |
(Optional) If a NIC network is specified, the network's IPv4 subnet. |
144 |
|
145 |
NIC_%d_NETWORK_GATEWAY |
146 |
(Optional) If a NIC network is specified, the network's IPv4 |
147 |
gateway. |
148 |
|
149 |
NIC_%d_NETWORK_SUBNET6 |
150 |
(Optional) If a NIC network is specified, the network's IPv6 subnet. |
151 |
|
152 |
NIC_%d_NETWORK_GATEWAY6 |
153 |
(Optional) If a NIC network is specified, the network's IPv6 |
154 |
gateway. |
155 |
|
156 |
NIC_%d_NETWORK_MAC_PREFIX |
157 |
(Optional) If a NIC network is specified, the network's mac prefix. |
158 |
|
159 |
NIC_%d_NETWORK_TAGS |
160 |
(Optional) If a NIC network is specified, the network's tags, space |
161 |
separated. |
162 |
|
163 |
OSP_*name* |
164 |
Each OS parameter (see below) will be exported in its own |
165 |
variable, prefixed with ``OSP_``, and upper-cased. For example, a |
166 |
``dhcp`` parameter will be exported as ``OSP_DHCP``. |
167 |
|
168 |
DEBUG_LEVEL |
169 |
If non-zero, this should cause the OS script to generate verbose |
170 |
logs of its execution, for troubleshooting purposes. Currently |
171 |
only ``0`` and ``1`` are valid values. |
172 |
|
173 |
|
174 |
EXECUTABLE SCRIPTS |
175 |
------------------ |
176 |
|
177 |
|
178 |
create |
179 |
~~~~~~ |
180 |
|
181 |
The **create** command is used for creating a new instance from |
182 |
scratch. It has no additional environment variables bside the |
183 |
common ones. |
184 |
|
185 |
The ``INSTANCE_NAME`` variable denotes the name of the instance, |
186 |
which is guaranteed to resolve to an IP address. The create script |
187 |
should configure the instance according to this name. It can |
188 |
configure the IP statically or not, depending on the deployment |
189 |
environment. |
190 |
|
191 |
The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create |
192 |
request is reinstalling an existing instance, rather than creating |
193 |
a new one. This can be used, for example, to preserve some data in the |
194 |
old instance in an OS-specific way. |
195 |
|
196 |
export |
197 |
~~~~~~ |
198 |
|
199 |
This command is used in order to make a backup of a given disk of |
200 |
the instance. The command should write to stdout a dump of the |
201 |
given block device. The output of this program will be passed |
202 |
during restore to the **import** command. |
203 |
|
204 |
The specific disk to backup is denoted by two additional environment |
205 |
variables: ``EXPORT_INDEX`` which denotes the index in the instance |
206 |
disks structure (and could be used for example to skip the second disk |
207 |
if not needed for backup) and ``EXPORT_DEVICE`` which has the same value |
208 |
as ``DISK_N_PATH`` but is duplicated here for easier usage by shell |
209 |
scripts (rather than parse the ``DISK_...`` variables). |
210 |
|
211 |
To provide the user with an estimate on how long the export will take, |
212 |
a predicted size can be written to the file descriptor passed in the |
213 |
variable ``EXP_SIZE_FD``. The value is in bytes and must be terminated |
214 |
by a newline character (``\n``). Older versions of Ganeti don't |
215 |
support this feature, hence the variable should be checked before |
216 |
use. Example:: |
217 |
|
218 |
if test -n "$EXP_SIZE_FD"; then |
219 |
blockdev --getsize64 $blockdev >&$EXP_SIZE_FD |
220 |
fi |
221 |
|
222 |
import |
223 |
~~~~~~ |
224 |
|
225 |
The **import** command is used for restoring an instance from a |
226 |
backup as done by **export**. The arguments are the similar to |
227 |
those passed to **export**, whose output will be provided on |
228 |
stdin. |
229 |
|
230 |
The difference in variables is that the current disk is denoted by |
231 |
``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``). |
232 |
|
233 |
rename |
234 |
~~~~~~ |
235 |
|
236 |
This command is used in order to perform a rename at the instance |
237 |
OS level, after the instance has been renamed in Ganeti. The |
238 |
command should do whatever steps are required to ensure that the |
239 |
instance is updated to use the new name, if the operating system |
240 |
supports it. |
241 |
|
242 |
Note that it is acceptable for the rename script to do nothing at |
243 |
all, however be warned that in this case, there will be a |
244 |
desynchronization between what gnt-instance list shows you and the |
245 |
actual hostname of the instance. |
246 |
|
247 |
The script will be passed one additional environment variable |
248 |
called ``OLD_INSTANCE_NAME`` which holds the old instance name. The |
249 |
``INSTANCE_NAME`` variable holds the new instance name. |
250 |
|
251 |
A very simple rename script should at least change the hostname and |
252 |
IP address of the instance, leaving the administrator to update the |
253 |
other services. |
254 |
|
255 |
verify |
256 |
~~~~~~ |
257 |
|
258 |
The *verify* script is used to verify consistency of the OS parameters |
259 |
(see below). The command should take one or more arguments denoting |
260 |
what checks should be performed, and return a proper exit code |
261 |
depending on whether the validation failed or succeeded. |
262 |
|
263 |
Currently (API version 20), only one parameter is supported: |
264 |
``parameters``. This should validate the ``OSP_`` variables from the |
265 |
environment, and output diagnostic messages in case the validation |
266 |
fails. |
267 |
|
268 |
For the ``dhcp`` parameter given as example above, a verification |
269 |
script could be: |
270 |
|
271 |
.. code-block:: bash |
272 |
|
273 |
#!/bin/sh |
274 |
|
275 |
case $OSP_DHCP in |
276 |
""|yes|no) |
277 |
;; |
278 |
*) |
279 |
echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2 |
280 |
exit 1; |
281 |
;; |
282 |
esac |
283 |
|
284 |
exit 0 |
285 |
|
286 |
|
287 |
TEXT FILES |
288 |
---------- |
289 |
|
290 |
|
291 |
ganeti_api_version |
292 |
~~~~~~~~~~~~~~~~~~ |
293 |
|
294 |
The ganeti_api_version file is a plain text file containing the |
295 |
version(s) of the guest OS API that this OS definition complies |
296 |
with, one per line. The version documented by this man page is 20, |
297 |
so this file must contain the number 20 followed by a newline if |
298 |
only this version is supported. A script compatible with more than |
299 |
one Ganeti version should contain the most recent version first |
300 |
(i.e. 20), followed by the old version(s) (in this case 15 and/or |
301 |
10). |
302 |
|
303 |
variants.list |
304 |
~~~~~~~~~~~~~ |
305 |
|
306 |
variants.list is a plain text file containing all the declared supported |
307 |
variants for this OS, one per line. If this file is missing or empty, |
308 |
then the OS won't be considered to support variants. |
309 |
|
310 |
Empty lines and lines starting with a hash (``#``) are ignored. |
311 |
|
312 |
parameters.list |
313 |
~~~~~~~~~~~~~~~ |
314 |
|
315 |
This file declares the parameters supported by the OS, one parameter |
316 |
per line, with name and description (space and/or tab separated). For |
317 |
example:: |
318 |
|
319 |
dhcp Whether to enable (yes) or disable (no) dhcp |
320 |
root_size The size of the root partition, in GiB |
321 |
|
322 |
The parameters can then be used in instance add or modification, as |
323 |
follows:: |
324 |
|
325 |
# gnt-instance add -O dhcp=no,root_size=8 ... |
326 |
|
327 |
|
328 |
NOTES |
329 |
----- |
330 |
|
331 |
Backwards compatibility |
332 |
~~~~~~~~~~~~~~~~~~~~~~~ |
333 |
|
334 |
Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS |
335 |
parameters and related scripts (verify) are only supported in |
336 |
version 20. The variants functionality (variants.list, and OS_VARIANT |
337 |
env. var) are supported/present only in version 15 and up. |
338 |
|
339 |
Common behaviour |
340 |
~~~~~~~~~~~~~~~~ |
341 |
|
342 |
All the scripts should display an usage message when called with a |
343 |
wrong number of arguments or when the first argument is ``-h`` or |
344 |
``--help``. |
345 |
|
346 |
Upgrading from old versions |
347 |
~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
348 |
|
349 |
Version 15 to 20 |
350 |
^^^^^^^^^^^^^^^^ |
351 |
|
352 |
The ``parameters.list`` file and ``verify`` script have been |
353 |
added. For no parameters, an empty parameters file and an empty verify |
354 |
script which returns success can be used. |
355 |
|
356 |
Version 10 to 15 |
357 |
^^^^^^^^^^^^^^^^ |
358 |
|
359 |
The ``variants.list`` file has been added, so OSes should support at |
360 |
least one variant, declaring it in that file and must be prepared to |
361 |
parse the OS_VARIANT environment variable. OSes are free to support more |
362 |
variants than just the declared ones. Note that this file is optional; |
363 |
without it, the variants functionality is disabled. |
364 |
|
365 |
Version 5 to 10 |
366 |
^^^^^^^^^^^^^^^ |
367 |
|
368 |
The method for passing data has changed from command line options |
369 |
to environment variables, so scripts should be modified to use |
370 |
these. For an example of how this can be done in a way compatible |
371 |
with both versions, feel free to look at the debootstrap instance's |
372 |
common.sh auxiliary script. |
373 |
|
374 |
Also, instances can have now a variable number of disks, not only |
375 |
two, and a variable number of NICs (instead of fixed one), so the |
376 |
scripts should deal with this. The biggest change is in the |
377 |
import/export, which are called once per disk, instead of once per |
378 |
instance. |
379 |
|
380 |
Version 4 to 5 |
381 |
^^^^^^^^^^^^^^ |
382 |
|
383 |
The rename script has been added. If you don't want to do any |
384 |
changes on the instances after a rename, you can migrate the OS |
385 |
definition to version 5 by creating the rename script simply as: |
386 |
|
387 |
.. code-block:: bash |
388 |
|
389 |
#!/bin/sh |
390 |
|
391 |
exit 0 |
392 |
|
393 |
Note that the script must be executable. |
394 |
|
395 |
.. vim: set textwidth=72 : |
396 |
.. Local Variables: |
397 |
.. mode: rst |
398 |
.. fill-column: 72 |
399 |
.. End: |