root / doc / design-ovf-support.rst @ 5cbf7832
History | View | Annotate | Download (18.5 kB)
1 | b3e3813e | Agata Murawska | ============================================================== |
---|---|---|---|
2 | b3e3813e | Agata Murawska | Ganeti Instance Import/Export using Open Virtualization Format |
3 | b3e3813e | Agata Murawska | ============================================================== |
4 | b3e3813e | Agata Murawska | |
5 | b3e3813e | Agata Murawska | Background |
6 | b3e3813e | Agata Murawska | ========== |
7 | b3e3813e | Agata Murawska | |
8 | b3e3813e | Agata Murawska | Open Virtualization Format is an open standard for packaging |
9 | b3e3813e | Agata Murawska | information regarding virtual machines. It is used, among other, by |
10 | b3e3813e | Agata Murawska | VMWare, VirtualBox and XenServer. OVF allows users to migrate between |
11 | b3e3813e | Agata Murawska | virtualization software without the need of reconfiguring hardware, |
12 | b3e3813e | Agata Murawska | network or operating system. |
13 | b3e3813e | Agata Murawska | |
14 | b3e3813e | Agata Murawska | Currently, exporting instance in Ganeti results with a configuration |
15 | b3e3813e | Agata Murawska | file that is readable only for Ganeti. It disallows the users to |
16 | b3e3813e | Agata Murawska | change the platform they use without loosing all the machine's |
17 | b3e3813e | Agata Murawska | configuration. Import function in Ganeti is also currently limited to |
18 | b3e3813e | Agata Murawska | the previously prepared instances. |
19 | b3e3813e | Agata Murawska | |
20 | b3e3813e | Agata Murawska | Implementation of OVF support allows users to migrate to Ganeti from |
21 | b3e3813e | Agata Murawska | other platforms, thus potentially increasing the usage. It also |
22 | b3e3813e | Agata Murawska | enables virtual machine end-users to create their own machines |
23 | b3e3813e | Agata Murawska | (e.g. in VirtualBox or SUSE Studio) and then add them to Ganeti |
24 | b3e3813e | Agata Murawska | cluster, thus providing better personalization. |
25 | b3e3813e | Agata Murawska | |
26 | b3e3813e | Agata Murawska | Overview |
27 | b3e3813e | Agata Murawska | ======== |
28 | b3e3813e | Agata Murawska | |
29 | b3e3813e | Agata Murawska | Open Virtualization Format description |
30 | b3e3813e | Agata Murawska | -------------------------------------- |
31 | b3e3813e | Agata Murawska | |
32 | b3e3813e | Agata Murawska | According to the DMTF document introducing the standard: "The Open |
33 | b3e3813e | Agata Murawska | Virtualization Format (OVF) Specification describes an open, secure, |
34 | b3e3813e | Agata Murawska | portable, efficient and extensible format for the packaging and |
35 | b3e3813e | Agata Murawska | distribution of software to be run in virtual machines." OVF supports |
36 | b3e3813e | Agata Murawska | both single and multiple- configurations of VMs in one package, is |
37 | b3e3813e | Agata Murawska | host- and virtualization platform-independent and optimized for |
38 | b3e3813e | Agata Murawska | distribution (e.g. by allowing usage of public key infrastructure and |
39 | b3e3813e | Agata Murawska | providing tools for management of basic software licensing). |
40 | b3e3813e | Agata Murawska | |
41 | 97c60815 | Agata Murawska | There are no limitations regarding disk images used, as long as the |
42 | 97c60815 | Agata Murawska | description is provided. Any hardware described in a proper format |
43 | 97c60815 | Agata Murawska | (i.e. CIM - Common Information Model) is accepted, although there is no |
44 | 97c60815 | Agata Murawska | guarantee that every virtualization software will support all types of |
45 | 97c60815 | Agata Murawska | hardware. |
46 | b3e3813e | Agata Murawska | |
47 | 97c60815 | Agata Murawska | OVF package should contain exactly one file with ``.ovf`` extension, |
48 | 97c60815 | Agata Murawska | which is an XML file specifying the following (per virtual machine): |
49 | b3e3813e | Agata Murawska | |
50 | b3e3813e | Agata Murawska | - virtual disks |
51 | b3e3813e | Agata Murawska | - network description |
52 | b3e3813e | Agata Murawska | - list of virtual hardware |
53 | b3e3813e | Agata Murawska | - operating system, if any |
54 | b3e3813e | Agata Murawska | |
55 | 75932bcf | Agata Murawska | Each of the elements in ``.ovf`` file may, if desired, contain a |
56 | b3e3813e | Agata Murawska | human-readable description to every piece of information given. |
57 | b3e3813e | Agata Murawska | |
58 | b3e3813e | Agata Murawska | Additionally, the package may have some disk image files and other |
59 | b3e3813e | Agata Murawska | additional resources (e.g. ISO images). |
60 | b3e3813e | Agata Murawska | |
61 | 97c60815 | Agata Murawska | In order to provide secure means of distribution for OVF packages, the |
62 | 97c60815 | Agata Murawska | manifest and certificate are provided. Manifest (``.mf`` file) contains |
63 | 97c60815 | Agata Murawska | checksums for all the files in OVF package, whereas certificate |
64 | 97c60815 | Agata Murawska | (``.cert`` file) contains X.509 certificate and a checksum of manifest |
65 | 97c60815 | Agata Murawska | file. Both files are not compulsory, but certificate requires manifest |
66 | 97c60815 | Agata Murawska | to be present. |
67 | 97c60815 | Agata Murawska | |
68 | b3e3813e | Agata Murawska | Supported disk formats |
69 | b3e3813e | Agata Murawska | ---------------------- |
70 | b3e3813e | Agata Murawska | |
71 | b3e3813e | Agata Murawska | Although OVF is claimed to support 'any disk format', what we are |
72 | 97c60815 | Agata Murawska | interested in is which formats are supported by VM managers that |
73 | 97c60815 | Agata Murawska | currently use OVF. |
74 | b3e3813e | Agata Murawska | |
75 | b3e3813e | Agata Murawska | - VMWare: ``.vmdk`` (which comes in at least 3 different flavours: |
76 | b3e3813e | Agata Murawska | ``sparse``, ``compressed`` and ``streamOptimized``) |
77 | b3e3813e | Agata Murawska | - VirtualBox: ``.vdi`` (VirtualBox's format), ``.vmdk``, ``.vhd`` |
78 | b3e3813e | Agata Murawska | (Microsoft and XenServer); export disk format is always ``.vmdk`` |
79 | b3e3813e | Agata Murawska | - XenServer: ``.vmdk``, ``.vhd``; export disk format is always |
80 | b3e3813e | Agata Murawska | ``.vhd`` |
81 | b3e3813e | Agata Murawska | - Red Hat Enterprise Virtualization: ``.raw`` (raw disk format), |
82 | b3e3813e | Agata Murawska | ``.cow`` (qemu's ``QCOW2``) |
83 | b3e3813e | Agata Murawska | - other: AbiCloud, OpenNode Cloud, SUSE Studio, Morfeo Claudia, |
84 | 97c60815 | Agata Murawska | OpenStack: mostly ``.vmdk`` |
85 | b3e3813e | Agata Murawska | |
86 | 97c60815 | Agata Murawska | In our implementation of the OVF we allow a choice between raw, cow and |
87 | 97c60815 | Agata Murawska | vmdk disk formats for both import and export. Other formats covertable |
88 | a17deeab | Agata Murawska | using ``qemu-img`` are allowed in import mode, but not tested. |
89 | 6499c5b8 | Agata Murawska | The justification is the following: |
90 | b3e3813e | Agata Murawska | |
91 | b3e3813e | Agata Murawska | - Raw format is supported as it is the main format of disk images used |
92 | b3e3813e | Agata Murawska | in Ganeti, thus it is effortless to provide support for this format |
93 | 6499c5b8 | Agata Murawska | - Cow is used in Qemu |
94 | b3e3813e | Agata Murawska | - Vmdk is most commonly supported in virtualization software, it also |
95 | b3e3813e | Agata Murawska | has the advantage of producing relatively small disk images, which |
96 | b3e3813e | Agata Murawska | is extremely important advantage when moving instances. |
97 | b3e3813e | Agata Murawska | |
98 | 75932bcf | Agata Murawska | Import and export - the closer look |
99 | 75932bcf | Agata Murawska | =================================== |
100 | 75932bcf | Agata Murawska | |
101 | 75932bcf | Agata Murawska | This section contains an overview of how different parts of |
102 | 75932bcf | Agata Murawska | Ganeti's export info are included in ``.ovf`` configuration file. |
103 | 75932bcf | Agata Murawska | It also explains how import is designed to work with incomplete |
104 | 75932bcf | Agata Murawska | information. |
105 | 75932bcf | Agata Murawska | |
106 | 75932bcf | Agata Murawska | Ganeti's backup format vs OVF |
107 | 75932bcf | Agata Murawska | ----------------------------- |
108 | 75932bcf | Agata Murawska | .. highlight:: xml |
109 | 75932bcf | Agata Murawska | |
110 | 75932bcf | Agata Murawska | The basic structure of Ganeti ``.ovf`` file is the following:: |
111 | 75932bcf | Agata Murawska | |
112 | 75932bcf | Agata Murawska | <Envelope> |
113 | 75932bcf | Agata Murawska | <References></References> |
114 | 75932bcf | Agata Murawska | <DiskSection></DiskSection> |
115 | 75932bcf | Agata Murawska | <NetworkSection></NetworkSection> |
116 | 75932bcf | Agata Murawska | <VirtualSystem> |
117 | 75932bcf | Agata Murawska | <Name></Name> |
118 | 75932bcf | Agata Murawska | <OperatingSystemSection></OperatingSystemSection> |
119 | 75932bcf | Agata Murawska | <VirtualHardwareSection><VirtualHardwareSection> |
120 | 75932bcf | Agata Murawska | </VirtualSystem> |
121 | 75932bcf | Agata Murawska | <gnt:GanetiSection> |
122 | 75932bcf | Agata Murawska | <gnt:VersionId/> |
123 | 75932bcf | Agata Murawska | <gnt:AutoBalance/> |
124 | 75932bcf | Agata Murawska | <gnt:Tags></gnt:Tags> |
125 | 6499c5b8 | Agata Murawska | <gnt:DiskTemplate</gnt:DiskTemplate> |
126 | 6499c5b8 | Agata Murawska | <gnt:OperatingSystem> |
127 | 6499c5b8 | Agata Murawska | <gnt:Name/> |
128 | 97c60815 | Agata Murawska | <gnt:Parameters></gnt:Parameters> |
129 | 6499c5b8 | Agata Murawska | </gnt:OperatingSystem> |
130 | 75932bcf | Agata Murawska | <gnt:Hypervisor> |
131 | 6499c5b8 | Agata Murawska | <gnt:Name/> |
132 | 97c60815 | Agata Murawska | <gnt:Parameters></gnt:Parameters> |
133 | 75932bcf | Agata Murawska | </gnt:Hypervisor> |
134 | 6499c5b8 | Agata Murawska | <gnt:Network> |
135 | 6499c5b8 | Agata Murawska | <gnt:Mode/> |
136 | 6499c5b8 | Agata Murawska | <gnt:MACAddress/> |
137 | 6499c5b8 | Agata Murawska | <gnt:Link/> |
138 | 6499c5b8 | Agata Murawska | <gnt:IPAddress/> |
139 | 6499c5b8 | Agata Murawska | </gnt:Network> |
140 | 75932bcf | Agata Murawska | </gnt:GanetiSection> |
141 | 75932bcf | Agata Murawska | </Envelope> |
142 | 75932bcf | Agata Murawska | |
143 | 75932bcf | Agata Murawska | .. note :: |
144 | 75932bcf | Agata Murawska | Tags with ``gnt:`` prefix are Ganeti-specific and are not a part of |
145 | 75932bcf | Agata Murawska | OVF standard. |
146 | 75932bcf | Agata Murawska | |
147 | 75932bcf | Agata Murawska | .. highlight:: text |
148 | 75932bcf | Agata Murawska | |
149 | 75932bcf | Agata Murawska | Whereas Ganeti's export info is of the following form, ``=>`` showing |
150 | 75932bcf | Agata Murawska | where will the data be in OVF format:: |
151 | 75932bcf | Agata Murawska | |
152 | 75932bcf | Agata Murawska | [instance] |
153 | 6499c5b8 | Agata Murawska | disk0_dump = filename => File in References |
154 | 6499c5b8 | Agata Murawska | disk0_ivname = name => generated automatically |
155 | 97c60815 | Agata Murawska | disk0_size = size_in_mb => calculated after disk conversion |
156 | 6499c5b8 | Agata Murawska | disk_count = number => generated automatically |
157 | 6499c5b8 | Agata Murawska | disk_template = disk_type => gnt:DiskTemplate |
158 | 6499c5b8 | Agata Murawska | hypervisor = hyp-name => gnt:Name in gnt:Hypervisor |
159 | 75932bcf | Agata Murawska | name = inst-name => Name in VirtualSystem |
160 | 6499c5b8 | Agata Murawska | nic0_ip = ip => gnt:IPAddress in gnt:Network |
161 | 6499c5b8 | Agata Murawska | nic0_link = link => gnt:Link in gnt:Network |
162 | 6499c5b8 | Agata Murawska | nic0_mac = mac => gnt:MACAddress in gnt:Network or |
163 | 6499c5b8 | Agata Murawska | Item in VirtualHardwareSection |
164 | 6499c5b8 | Agata Murawska | nic0_mode = mode => gnt:Mode in gnt:Network |
165 | 6499c5b8 | Agata Murawska | nic_count = number => generated automatically |
166 | 75932bcf | Agata Murawska | tags => gnt:Tags |
167 | 75932bcf | Agata Murawska | |
168 | 75932bcf | Agata Murawska | [backend] |
169 | 75932bcf | Agata Murawska | auto_balanced => gnt:AutoBalance |
170 | 75932bcf | Agata Murawska | memory = mem_in_mb => Item in VirtualHardwareSection |
171 | 75932bcf | Agata Murawska | vcpus = number => Item in VirtualHardwareSection |
172 | 75932bcf | Agata Murawska | |
173 | 75932bcf | Agata Murawska | [export] |
174 | 6499c5b8 | Agata Murawska | compression => ignored |
175 | 6499c5b8 | Agata Murawska | os => gnt:Name in gnt:OperatingSystem |
176 | 75932bcf | Agata Murawska | source => ignored |
177 | 75932bcf | Agata Murawska | timestamp => ignored |
178 | 6499c5b8 | Agata Murawska | version => gnt:VersionId or |
179 | 6499c5b8 | Agata Murawska | constants.EXPORT_VERSION |
180 | 75932bcf | Agata Murawska | |
181 | 6499c5b8 | Agata Murawska | [os] => gnt:Parameters in gnt:OperatingSystem |
182 | 75932bcf | Agata Murawska | |
183 | 6499c5b8 | Agata Murawska | [hypervisor] => gnt:Parameters in gnt:Hypervisor |
184 | 75932bcf | Agata Murawska | |
185 | 75932bcf | Agata Murawska | In case of multiple networks/disks used by an instance, they will |
186 | 75932bcf | Agata Murawska | all be saved in appropriate sections as specified above for the first |
187 | 75932bcf | Agata Murawska | network/disk. |
188 | 75932bcf | Agata Murawska | |
189 | 75932bcf | Agata Murawska | Import from other virtualization software |
190 | 75932bcf | Agata Murawska | ----------------------------------------- |
191 | 75932bcf | Agata Murawska | In case of importing to Ganeti OVF package generated in other software, |
192 | 75932bcf | Agata Murawska | e.g. VirtualBox, some fields required for Ganeti to properly handle |
193 | 75932bcf | Agata Murawska | import may be missing. Most often it will happen that such OVF package |
194 | 75932bcf | Agata Murawska | will lack the ``gnt:GanetiSection``. |
195 | 75932bcf | Agata Murawska | |
196 | 6499c5b8 | Agata Murawska | If this happens you can specify all the missing parameters in |
197 | 6499c5b8 | Agata Murawska | the command line. Please refer to `Command Line`_ section. |
198 | 6499c5b8 | Agata Murawska | |
199 | 97c60815 | Agata Murawska | In the :doc:`ovfconverter` we provide examples of |
200 | 6499c5b8 | Agata Murawska | options when converting from VirtualBox, VMWare and OpenSuseStudio. |
201 | 75932bcf | Agata Murawska | |
202 | 75932bcf | Agata Murawska | Export to other virtualization software |
203 | 75932bcf | Agata Murawska | --------------------------------------- |
204 | 75932bcf | Agata Murawska | When exporting to other virtualization software, you may notice that |
205 | 75932bcf | Agata Murawska | there is a section ``gnt:GanetiSection``, containing Ganeti-specific |
206 | 75932bcf | Agata Murawska | information. This may on **rare** cases cause trouble in importing your |
207 | 75932bcf | Agata Murawska | instance. If that is the case please do one of the two: |
208 | 75932bcf | Agata Murawska | |
209 | 75932bcf | Agata Murawska | 1. Export from Ganeti to OVF with ``--external`` option - this will |
210 | 75932bcf | Agata Murawska | cause to skip the non-standard information. |
211 | 75932bcf | Agata Murawska | |
212 | 75932bcf | Agata Murawska | 2. Manually remove the gnt:GanetiSection from the ``.ovf`` file. You |
213 | 6499c5b8 | Agata Murawska | will also have to recompute sha1 sum (``sha1sum`` command) of the .ovf |
214 | 6499c5b8 | Agata Murawska | file and update your ``.mf`` file with new value. |
215 | 75932bcf | Agata Murawska | |
216 | 75932bcf | Agata Murawska | .. note:: |
217 | 75932bcf | Agata Murawska | Manual change option is only recommended when you have exported your |
218 | 75932bcf | Agata Murawska | instance with ``-format`` option other that ``raw`` or selected |
219 | 75932bcf | Agata Murawska | ``--compress``. It saves you the time of converting or compressing |
220 | 75932bcf | Agata Murawska | the disk image. |
221 | b3e3813e | Agata Murawska | |
222 | b3e3813e | Agata Murawska | Planned limitations |
223 | b3e3813e | Agata Murawska | =================== |
224 | b3e3813e | Agata Murawska | |
225 | b3e3813e | Agata Murawska | The limitations regarding import of the OVF instances generated |
226 | b3e3813e | Agata Murawska | outside Ganeti will be (in general) the same, as limitations for |
227 | b3e3813e | Agata Murawska | Ganeti itself. The desired behavior in case of encountering |
228 | 6499c5b8 | Agata Murawska | unsupported element will be to ignore this element's tag without |
229 | 6499c5b8 | Agata Murawska | interruption of the import process. |
230 | b3e3813e | Agata Murawska | |
231 | b3e3813e | Agata Murawska | Package |
232 | b3e3813e | Agata Murawska | ------- |
233 | b3e3813e | Agata Murawska | |
234 | b3e3813e | Agata Murawska | There are no limitations regarding support for multiple files in |
235 | 75932bcf | Agata Murawska | package or packing the OVF package into one OVA (Open Virtual |
236 | 75932bcf | Agata Murawska | Appliance) file. As for certificates and licenses in the package, |
237 | b3e3813e | Agata Murawska | their support will be under discussion after completion of the basic |
238 | b3e3813e | Agata Murawska | features implementation. |
239 | b3e3813e | Agata Murawska | |
240 | b3e3813e | Agata Murawska | Multiple Virtual Systems |
241 | b3e3813e | Agata Murawska | ------------------------ |
242 | b3e3813e | Agata Murawska | |
243 | b3e3813e | Agata Murawska | At first only singular instances (i.e. VirtualSystem, not |
244 | b3e3813e | Agata Murawska | VirtualSystemCollection) will be supported. In the future multi-tiered |
245 | b3e3813e | Agata Murawska | appliances containing whole nodes (or even clusters) are considered an |
246 | b3e3813e | Agata Murawska | option. |
247 | b3e3813e | Agata Murawska | |
248 | b3e3813e | Agata Murawska | Disks |
249 | b3e3813e | Agata Murawska | ----- |
250 | b3e3813e | Agata Murawska | |
251 | 97c60815 | Agata Murawska | As mentioned, Ganeti will allow export in ``raw``, ``cow`` and ``vmdk`` |
252 | 97c60815 | Agata Murawska | formats. This means i.e. that the appropriate ``ovf:format`` |
253 | a17deeab | Agata Murawska | will be provided. |
254 | 97c60815 | Agata Murawska | As for import, we will support all formats that ``qemu-img`` can convert |
255 | 97c60815 | Agata Murawska | to ``raw``. At this point this means ``raw``, ``cow``, ``qcow``, |
256 | 97c60815 | Agata Murawska | ``qcow2``, ``vmdk`` and ``cloop``. We do not plan for now to support |
257 | 97c60815 | Agata Murawska | ``vdi`` or ``vhd`` unless they become part of qemu-img supported formats. |
258 | b3e3813e | Agata Murawska | |
259 | 97c60815 | Agata Murawska | We plan to support compression both for import and export - in gzip |
260 | 75932bcf | Agata Murawska | format. There is also a possibility to provide virtual disk in chunks |
261 | 6499c5b8 | Agata Murawska | of equal size. The latter will not be implemented in the first version, |
262 | 6499c5b8 | Agata Murawska | but we do plan to support it eventually. |
263 | 6499c5b8 | Agata Murawska | |
264 | 97c60815 | Agata Murawska | |
265 | 97c60815 | Agata Murawska | The ``ovf:format`` tag is not used in our case when importing. Instead |
266 | 97c60815 | Agata Murawska | we use ``qemu-img info``, which provides enough information for our |
267 | 97c60815 | Agata Murawska | purposes and is better standardized. |
268 | b3e3813e | Agata Murawska | |
269 | 6499c5b8 | Agata Murawska | Please note, that due to security reasons we require the disk image to |
270 | a17deeab | Agata Murawska | be in the same directory as the ``.ovf`` description file for both |
271 | a17deeab | Agata Murawska | import and export. |
272 | 6499c5b8 | Agata Murawska | |
273 | 6499c5b8 | Agata Murawska | In order to completely ignore disk-related information in resulting |
274 | 6499c5b8 | Agata Murawska | config file, please use ``--disk-template=diskless`` option. |
275 | b3e3813e | Agata Murawska | |
276 | b3e3813e | Agata Murawska | Network |
277 | b3e3813e | Agata Murawska | ------- |
278 | b3e3813e | Agata Murawska | |
279 | 6499c5b8 | Agata Murawska | Ganeti provides support for routed and bridged mode for the networks. |
280 | 6499c5b8 | Agata Murawska | Since the standard OVF format does not contain any information regarding |
281 | 6499c5b8 | Agata Murawska | used network type, we add our own source of such information in |
282 | 6499c5b8 | Agata Murawska | ``gnt:GanetiSection``. In case this additional information is not |
283 | 6499c5b8 | Agata Murawska | present, we perform a simple check - if network name specified in |
284 | 6499c5b8 | Agata Murawska | ``NetworkSection`` contains words ``bridged`` or ``routed``, we consider |
285 | 6499c5b8 | Agata Murawska | this to be the network type. Otherwise option ``auto`` is chosen, in |
286 | 97c60815 | Agata Murawska | which case the cluster's default value for that field will be used when |
287 | 97c60815 | Agata Murawska | importing. |
288 | 97c60815 | Agata Murawska | This provides a safe fallback in case of NAT networks usage, which are |
289 | 97c60815 | Agata Murawska | commonly used e.g. in VirtualBox. |
290 | b3e3813e | Agata Murawska | |
291 | b3e3813e | Agata Murawska | Hardware |
292 | b3e3813e | Agata Murawska | -------- |
293 | b3e3813e | Agata Murawska | |
294 | 6499c5b8 | Agata Murawska | The supported hardware is limited to virtual CPUs, RAM memory, disks and |
295 | 6499c5b8 | Agata Murawska | networks. In particular, no USB support is currently provided, as Ganeti |
296 | 6499c5b8 | Agata Murawska | does not support them. |
297 | b3e3813e | Agata Murawska | |
298 | b3e3813e | Agata Murawska | Operating Systems |
299 | b3e3813e | Agata Murawska | ----------------- |
300 | b3e3813e | Agata Murawska | |
301 | 6499c5b8 | Agata Murawska | Support for different operating systems depends solely on their |
302 | 6499c5b8 | Agata Murawska | accessibility for Ganeti instances. List of installed OSes can be |
303 | 6499c5b8 | Agata Murawska | checked using ``gnt-os list`` command. |
304 | b3e3813e | Agata Murawska | |
305 | a17deeab | Agata Murawska | References |
306 | a17deeab | Agata Murawska | ---------- |
307 | a17deeab | Agata Murawska | |
308 | a17deeab | Agata Murawska | Files listed in ``ovf:References`` section cannot be hyperlinks. |
309 | a17deeab | Agata Murawska | |
310 | b3e3813e | Agata Murawska | Other |
311 | b3e3813e | Agata Murawska | ----- |
312 | b3e3813e | Agata Murawska | |
313 | 97c60815 | Agata Murawska | The instance name (``gnt:VirtualSystem\gnt:Name`` or command line's |
314 | 97c60815 | Agata Murawska | ``--name`` option ) has to be resolvable in order for successful import |
315 | 97c60815 | Agata Murawska | using ``gnt-backup import``. |
316 | 97c60815 | Agata Murawska | |
317 | 6499c5b8 | Agata Murawska | |
318 | 6499c5b8 | Agata Murawska | _`Command Line` |
319 | 6499c5b8 | Agata Murawska | =============== |
320 | 6499c5b8 | Agata Murawska | |
321 | 6499c5b8 | Agata Murawska | The basic usage of the ovf tool is one of the following:: |
322 | 6499c5b8 | Agata Murawska | |
323 | 6499c5b8 | Agata Murawska | ovfconverter import filename |
324 | 97c60815 | Agata Murawska | ovfconverter export --format=<format> filename |
325 | 6499c5b8 | Agata Murawska | |
326 | 6499c5b8 | Agata Murawska | This will result in a conversion based solely on the content of provided |
327 | 6499c5b8 | Agata Murawska | file. In case some information required to make the conversion is |
328 | 6499c5b8 | Agata Murawska | missing, an error will occur. |
329 | 6499c5b8 | Agata Murawska | |
330 | 6499c5b8 | Agata Murawska | If output directory should be different than the standard Ganeti export |
331 | 6499c5b8 | Agata Murawska | directory (usually ``/srv/ganeti/export``), option ``--output-dir`` |
332 | 6499c5b8 | Agata Murawska | can be used. |
333 | 6499c5b8 | Agata Murawska | |
334 | 6499c5b8 | Agata Murawska | If name of resulting entity should be different than the one read from |
335 | 6499c5b8 | Agata Murawska | the file, use ``--name`` option. |
336 | 6499c5b8 | Agata Murawska | |
337 | 6499c5b8 | Agata Murawska | Import options |
338 | 6499c5b8 | Agata Murawska | -------------- |
339 | 6499c5b8 | Agata Murawska | |
340 | 6499c5b8 | Agata Murawska | Import options that ``ovfconverter`` supports include options for |
341 | 6499c5b8 | Agata Murawska | backend, disks, hypervisor, networks and operating system. If an option |
342 | 6499c5b8 | Agata Murawska | is given, it overrides the values provided in the OVF file. |
343 | 6499c5b8 | Agata Murawska | |
344 | 6499c5b8 | Agata Murawska | Backend |
345 | 6499c5b8 | Agata Murawska | ^^^^^^^ |
346 | 6499c5b8 | Agata Murawska | ``--backend=option=value`` can be used to set auto balance, number of |
347 | 6499c5b8 | Agata Murawska | vcpus and amount of RAM memory. |
348 | 6499c5b8 | Agata Murawska | |
349 | 6499c5b8 | Agata Murawska | Please note that when you do not provide full set of options, the |
350 | 6499c5b8 | Agata Murawska | omitted ones will be set to cluster defaults (``auto``). |
351 | 6499c5b8 | Agata Murawska | |
352 | 6499c5b8 | Agata Murawska | Disks |
353 | 6499c5b8 | Agata Murawska | ^^^^^ |
354 | 6499c5b8 | Agata Murawska | ``--disk-template=diskless`` causes the converter to ignore all other |
355 | 97c60815 | Agata Murawska | disk option - both from .ovf file and the command line. Other disk |
356 | 97c60815 | Agata Murawska | template options include ``plain``, ``drdb``, ``file``, ``sharedfile`` |
357 | 97c60815 | Agata Murawska | and ``blockdev``. |
358 | 6499c5b8 | Agata Murawska | |
359 | 6499c5b8 | Agata Murawska | ``--disk=number:size=value`` causes to create disks instead of |
360 | 6499c5b8 | Agata Murawska | converting them from OVF package; numbers should start with ``0`` and be |
361 | 6499c5b8 | Agata Murawska | consecutive. |
362 | 6499c5b8 | Agata Murawska | |
363 | 6499c5b8 | Agata Murawska | Hypervisor |
364 | 6499c5b8 | Agata Murawska | ^^^^^^^^^^ |
365 | 6499c5b8 | Agata Murawska | ``-H hypervisor_name`` and ``-H hypervisor_name:option=value`` |
366 | 6499c5b8 | Agata Murawska | provide options for hypervisor. |
367 | 6499c5b8 | Agata Murawska | |
368 | 6499c5b8 | Agata Murawska | Network |
369 | 6499c5b8 | Agata Murawska | ^^^^^^^ |
370 | 6499c5b8 | Agata Murawska | ``--no-nics`` option causes converter to ignore any network information |
371 | 6499c5b8 | Agata Murawska | provided. |
372 | 6499c5b8 | Agata Murawska | |
373 | 6499c5b8 | Agata Murawska | ``--network=number:option=value`` sets network information according to |
374 | 6499c5b8 | Agata Murawska | provided data, ignoring the OVF package configuration. |
375 | 6499c5b8 | Agata Murawska | |
376 | 6499c5b8 | Agata Murawska | Operating System |
377 | 6499c5b8 | Agata Murawska | ^^^^^^^^^^^^^^^^ |
378 | 6499c5b8 | Agata Murawska | ``--os-type=type`` sets os type accordingly, this option is **required** |
379 | 6499c5b8 | Agata Murawska | when importing from OVF instance not created from Ganeti config file. |
380 | 6499c5b8 | Agata Murawska | |
381 | 6499c5b8 | Agata Murawska | ``--os-parameters`` provides options for chosen operating system. |
382 | 6499c5b8 | Agata Murawska | |
383 | 6499c5b8 | Agata Murawska | Tags |
384 | 6499c5b8 | Agata Murawska | ^^^^ |
385 | 6499c5b8 | Agata Murawska | ``--tags=tag1,tag2,tag3`` is a means of providing tags specific for the |
386 | 6499c5b8 | Agata Murawska | instance. |
387 | 6499c5b8 | Agata Murawska | |
388 | 97c60815 | Agata Murawska | |
389 | 6499c5b8 | Agata Murawska | After the conversion is completed, you may use ``gnt-backup import`` to |
390 | 6499c5b8 | Agata Murawska | import the instance into Ganeti. |
391 | 6499c5b8 | Agata Murawska | |
392 | 6499c5b8 | Agata Murawska | Example:: |
393 | 6499c5b8 | Agata Murawska | |
394 | 97c60815 | Agata Murawska | ovfconverter import file.ovf --disk-template=diskless \ |
395 | 97c60815 | Agata Murawska | --os-type=lenny-image \ |
396 | 97c60815 | Agata Murawska | --backend=vcpus=1,memory=512,auto_balance \ |
397 | 97c60815 | Agata Murawska | -H:xen-pvm \ |
398 | 97c60815 | Agata Murawska | --net=0:mode=bridged,link=xen-br0 \ |
399 | 97c60815 | Agata Murawska | --name=xen.i1 |
400 | 97c60815 | Agata Murawska | [...] |
401 | 6499c5b8 | Agata Murawska | gnt-backup import xen.i1 |
402 | 97c60815 | Agata Murawska | [...] |
403 | 6499c5b8 | Agata Murawska | gnt-instance list |
404 | 6499c5b8 | Agata Murawska | |
405 | 6499c5b8 | Agata Murawska | Export options |
406 | 6499c5b8 | Agata Murawska | -------------- |
407 | 6499c5b8 | Agata Murawska | Export options include choice of disk formats to convert the disk image |
408 | 97c60815 | Agata Murawska | (``--format``) and compression of the disk into gzip format |
409 | 97c60815 | Agata Murawska | (``--compress``). User has also the choice of allowing to skip the |
410 | 97c60815 | Agata Murawska | Ganeti-specific part of the OVF document (``--external``). |
411 | 6499c5b8 | Agata Murawska | |
412 | 6499c5b8 | Agata Murawska | By default, exported OVF package will not be contained in the OVA |
413 | 6499c5b8 | Agata Murawska | package, but this may be changed by adding ``--ova`` option. |
414 | 6499c5b8 | Agata Murawska | |
415 | 6499c5b8 | Agata Murawska | Please note that in order to create an OVF package, it is first |
416 | 6499c5b8 | Agata Murawska | required that you export your VM using ``gnt-backup export``. |
417 | 6499c5b8 | Agata Murawska | |
418 | 97c60815 | Agata Murawska | Example:: |
419 | 97c60815 | Agata Murawska | |
420 | 97c60815 | Agata Murawska | gnt-backup export -n node1.xen xen.i1 |
421 | 97c60815 | Agata Murawska | [...] |
422 | 97c60815 | Agata Murawska | ovfconverter export --format=vmdk --ova --external \ |
423 | 97c60815 | Agata Murawska | --output-dir=~/xen.i1 \ |
424 | 97c60815 | Agata Murawska | /srv/ganeti/export/xen.i1.node1.xen/config.ini |
425 | 75932bcf | Agata Murawska | |
426 | b3e3813e | Agata Murawska | Implementation details |
427 | b3e3813e | Agata Murawska | ====================== |
428 | b3e3813e | Agata Murawska | |
429 | 6499c5b8 | Agata Murawska | Disk conversion |
430 | 6499c5b8 | Agata Murawska | --------------- |
431 | 6499c5b8 | Agata Murawska | |
432 | 6499c5b8 | Agata Murawska | Disk conversion for both import and export is done using external tool |
433 | a17deeab | Agata Murawska | called ``qemu-img``. The same tool is used to determine the type of |
434 | a17deeab | Agata Murawska | disk, as well as its virtual size. |
435 | 6499c5b8 | Agata Murawska | |
436 | 6499c5b8 | Agata Murawska | |
437 | 6499c5b8 | Agata Murawska | Import |
438 | 6499c5b8 | Agata Murawska | ------ |
439 | 6499c5b8 | Agata Murawska | |
440 | 6499c5b8 | Agata Murawska | Import functionality is implemented using two classes - OVFReader and |
441 | 6499c5b8 | Agata Murawska | OVFImporter. |
442 | 6499c5b8 | Agata Murawska | |
443 | 6499c5b8 | Agata Murawska | OVFReader class is used to read the contents of the ``.ovf`` file. Every |
444 | 6499c5b8 | Agata Murawska | action that requires ``.ovf`` file access is done through that class. |
445 | 6499c5b8 | Agata Murawska | It also performs validation of manifest, if one is present. |
446 | 6499c5b8 | Agata Murawska | |
447 | 6499c5b8 | Agata Murawska | The result of reading some part of file is typically a dictionary or a |
448 | 6499c5b8 | Agata Murawska | string, containing options which correspond to the ones in |
449 | 6499c5b8 | Agata Murawska | ``config.ini`` file. Only in case of disks, the resulting value is |
450 | 6499c5b8 | Agata Murawska | different - it is then a list of disk names. The reason for that is the |
451 | 6499c5b8 | Agata Murawska | need for conversion. |
452 | 6499c5b8 | Agata Murawska | |
453 | 6499c5b8 | Agata Murawska | OVFImporter class performs all the command-line-like tasks, such as |
454 | 6499c5b8 | Agata Murawska | unpacking OVA package, removing temporary directory, converting disk |
455 | 6499c5b8 | Agata Murawska | file to raw format or saving the configuration file on disk. |
456 | 6499c5b8 | Agata Murawska | It also contains a set of functions that read the options provided in |
457 | 6499c5b8 | Agata Murawska | the command line. |
458 | 6499c5b8 | Agata Murawska | |
459 | 6499c5b8 | Agata Murawska | |
460 | 6499c5b8 | Agata Murawska | Typical workflow for the import is very simple: |
461 | 6499c5b8 | Agata Murawska | |
462 | 54f834df | Agata Murawska | - read the ``.ovf`` file into memory |
463 | 6499c5b8 | Agata Murawska | - verify manifest |
464 | 6499c5b8 | Agata Murawska | - parse each element of the configuration file: name, disk template, |
465 | 6499c5b8 | Agata Murawska | hypervisor, operating system, backend parameters, network and disks |
466 | 6499c5b8 | Agata Murawska | |
467 | 6499c5b8 | Agata Murawska | - check if option for the element can be read from command line |
468 | 6499c5b8 | Agata Murawska | options |
469 | 6499c5b8 | Agata Murawska | |
470 | 6499c5b8 | Agata Murawska | - if yes: parse options from command line |
471 | 6499c5b8 | Agata Murawska | |
472 | 6499c5b8 | Agata Murawska | - otherwise: read the appropriate portion of ``.ovf`` file |
473 | 6499c5b8 | Agata Murawska | |
474 | 6499c5b8 | Agata Murawska | - save gathered information in ``config.ini`` file |
475 | 6499c5b8 | Agata Murawska | |
476 | 54f834df | Agata Murawska | Export |
477 | 54f834df | Agata Murawska | ------ |
478 | 54f834df | Agata Murawska | |
479 | 54f834df | Agata Murawska | Similar to import, export functionality also uses two classes - |
480 | 54f834df | Agata Murawska | OVFWriter and OVFExporter. |
481 | 54f834df | Agata Murawska | |
482 | 54f834df | Agata Murawska | OVFWriter class produces XML output based on the information given. Its |
483 | 54f834df | Agata Murawska | sole role is to separate the creation of ``.ovf`` file content. |
484 | 54f834df | Agata Murawska | |
485 | 54f834df | Agata Murawska | OVFExporter class gathers information from ``config.ini`` file or |
486 | 54f834df | Agata Murawska | command line and performs necessary operations like disk conversion, disk |
487 | 54f834df | Agata Murawska | compression, manifest creation and OVA package creation. |
488 | 54f834df | Agata Murawska | |
489 | 54f834df | Agata Murawska | Typical workflow for the export is even simpler, than for the import: |
490 | 54f834df | Agata Murawska | |
491 | 54f834df | Agata Murawska | - read the ``config.ini`` file into memory |
492 | 54f834df | Agata Murawska | - gather information about certain parts of the instance, convert and |
493 | 54f834df | Agata Murawska | compress disks if desired |
494 | 54f834df | Agata Murawska | - save each of these elements as a fragment of XML tree |
495 | 54f834df | Agata Murawska | - save the XML tree as ``.ovf`` file |
496 | 54f834df | Agata Murawska | - create manifest file and fill it with appropriate checksums |
497 | 54f834df | Agata Murawska | - if ``--ova`` option was chosen, pack the results into ``.ova`` tarfile |
498 | 54f834df | Agata Murawska | |
499 | b3e3813e | Agata Murawska | |
500 | a17deeab | Agata Murawska | Work in progress |
501 | a17deeab | Agata Murawska | ---------------- |
502 | a17deeab | Agata Murawska | |
503 | a17deeab | Agata Murawska | - conversion to/from raw disk should be quicker |
504 | a17deeab | Agata Murawska | - add graphic card memory to export information (12 MB of memory) |
505 | a17deeab | Agata Murawska | - space requirements for conversion + compression + ova are currently |
506 | a17deeab | Agata Murawska | enormous |
507 | a17deeab | Agata Murawska | - add support for disks in chunks |
508 | a17deeab | Agata Murawska | - add support for certificates |
509 | a17deeab | Agata Murawska | - investigate why VMWare's ovftool does not work with ovfconverter's |
510 | a17deeab | Agata Murawska | compression and ova packaging -- maybe noteworty: if OVA archive does |
511 | a17deeab | Agata Murawska | not have a disk (i.e. in OVA package there is only .ovf ad .mf file), |
512 | a17deeab | Agata Murawska | then the ovftool works |
513 | a17deeab | Agata Murawska | - investigate why new versions of VirtualBox have problems with OVF |
514 | a17deeab | Agata Murawska | created by ovfconverter (everything works fine with 3.16 version, but |
515 | a17deeab | Agata Murawska | not with 4.0) |
516 | a17deeab | Agata Murawska | |
517 | a17deeab | Agata Murawska | |
518 | b3e3813e | Agata Murawska | .. vim: set textwidth=72 : |
519 | b3e3813e | Agata Murawska | .. Local Variables: |
520 | b3e3813e | Agata Murawska | .. mode: rst |
521 | b3e3813e | Agata Murawska | .. fill-column: 72 |
522 | b3e3813e | Agata Murawska | .. End: |