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