root / doc / design-ovf-support.rst @ a52978c7
History | View | Annotate | Download (16.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 | b3e3813e | Agata Murawska | There are no limitations regarding hard drive images used, as long as |
42 | b3e3813e | Agata Murawska | the description is provided. Any hardware described in a proper |
43 | b3e3813e | Agata Murawska | i.e. CIM - Common Information Model) format is accepted, although |
44 | b3e3813e | Agata Murawska | there is no guarantee that every virtualization software will support |
45 | b3e3813e | Agata Murawska | all types of hardware. |
46 | b3e3813e | Agata Murawska | |
47 | 75932bcf | Agata Murawska | OVF package should contain one file with ``.ovf`` extension, which is an |
48 | b3e3813e | Agata Murawska | 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 | b3e3813e | Agata Murawska | Supported disk formats |
62 | b3e3813e | Agata Murawska | ---------------------- |
63 | b3e3813e | Agata Murawska | |
64 | b3e3813e | Agata Murawska | Although OVF is claimed to support 'any disk format', what we are |
65 | b3e3813e | Agata Murawska | interested in is which of the formats are supported by VM managers |
66 | b3e3813e | Agata Murawska | that currently use OVF. |
67 | b3e3813e | Agata Murawska | |
68 | b3e3813e | Agata Murawska | - VMWare: ``.vmdk`` (which comes in at least 3 different flavours: |
69 | b3e3813e | Agata Murawska | ``sparse``, ``compressed`` and ``streamOptimized``) |
70 | b3e3813e | Agata Murawska | - VirtualBox: ``.vdi`` (VirtualBox's format), ``.vmdk``, ``.vhd`` |
71 | b3e3813e | Agata Murawska | (Microsoft and XenServer); export disk format is always ``.vmdk`` |
72 | b3e3813e | Agata Murawska | - XenServer: ``.vmdk``, ``.vhd``; export disk format is always |
73 | b3e3813e | Agata Murawska | ``.vhd`` |
74 | b3e3813e | Agata Murawska | - Red Hat Enterprise Virtualization: ``.raw`` (raw disk format), |
75 | b3e3813e | Agata Murawska | ``.cow`` (qemu's ``QCOW2``) |
76 | b3e3813e | Agata Murawska | - other: AbiCloud, OpenNode Cloud, SUSE Studio, Morfeo Claudia, |
77 | b3e3813e | Agata Murawska | OpenStack |
78 | b3e3813e | Agata Murawska | |
79 | b3e3813e | Agata Murawska | In our implementation of the OVF we plan to allow a choice between |
80 | 6499c5b8 | Agata Murawska | raw, cow and vmdk disk formats for export. We will not limit the import |
81 | 6499c5b8 | Agata Murawska | formats in any way, but the used format has to be supported by qemu-img. |
82 | 6499c5b8 | Agata Murawska | The justification is the following: |
83 | b3e3813e | Agata Murawska | |
84 | b3e3813e | Agata Murawska | - Raw format is supported as it is the main format of disk images used |
85 | b3e3813e | Agata Murawska | in Ganeti, thus it is effortless to provide support for this format |
86 | 6499c5b8 | Agata Murawska | - Cow is used in Qemu |
87 | b3e3813e | Agata Murawska | - Vmdk is most commonly supported in virtualization software, it also |
88 | b3e3813e | Agata Murawska | has the advantage of producing relatively small disk images, which |
89 | b3e3813e | Agata Murawska | is extremely important advantage when moving instances. |
90 | b3e3813e | Agata Murawska | |
91 | b3e3813e | Agata Murawska | The conversion between RAW and the other formats will be done using |
92 | b3e3813e | Agata Murawska | qemu-img, which transforms, among other, raw disk images to monolithic |
93 | b3e3813e | Agata Murawska | sparse vmdk images. |
94 | b3e3813e | Agata Murawska | |
95 | 75932bcf | Agata Murawska | Import and export - the closer look |
96 | 75932bcf | Agata Murawska | =================================== |
97 | 75932bcf | Agata Murawska | |
98 | 75932bcf | Agata Murawska | This section contains an overview of how different parts of |
99 | 75932bcf | Agata Murawska | Ganeti's export info are included in ``.ovf`` configuration file. |
100 | 75932bcf | Agata Murawska | It also explains how import is designed to work with incomplete |
101 | 75932bcf | Agata Murawska | information. |
102 | 75932bcf | Agata Murawska | |
103 | 75932bcf | Agata Murawska | Ganeti's backup format vs OVF |
104 | 75932bcf | Agata Murawska | ----------------------------- |
105 | 75932bcf | Agata Murawska | .. highlight:: xml |
106 | 75932bcf | Agata Murawska | |
107 | 75932bcf | Agata Murawska | The basic structure of Ganeti ``.ovf`` file is the following:: |
108 | 75932bcf | Agata Murawska | |
109 | 75932bcf | Agata Murawska | <Envelope> |
110 | 75932bcf | Agata Murawska | <References></References> |
111 | 75932bcf | Agata Murawska | <DiskSection></DiskSection> |
112 | 75932bcf | Agata Murawska | <NetworkSection></NetworkSection> |
113 | 75932bcf | Agata Murawska | <VirtualSystem> |
114 | 75932bcf | Agata Murawska | <Name></Name> |
115 | 75932bcf | Agata Murawska | <OperatingSystemSection></OperatingSystemSection> |
116 | 75932bcf | Agata Murawska | <VirtualHardwareSection><VirtualHardwareSection> |
117 | 75932bcf | Agata Murawska | </VirtualSystem> |
118 | 75932bcf | Agata Murawska | <gnt:GanetiSection> |
119 | 75932bcf | Agata Murawska | <gnt:VersionId/> |
120 | 75932bcf | Agata Murawska | <gnt:AutoBalance/> |
121 | 75932bcf | Agata Murawska | <gnt:Tags></gnt:Tags> |
122 | 6499c5b8 | Agata Murawska | <gnt:DiskTemplate</gnt:DiskTemplate> |
123 | 6499c5b8 | Agata Murawska | <gnt:OperatingSystem> |
124 | 6499c5b8 | Agata Murawska | <gnt:Name/> |
125 | 6499c5b8 | Agata Murawska | <gnt:Parameters> |
126 | 6499c5b8 | Agata Murawska | </gnt:Parameters> |
127 | 6499c5b8 | Agata Murawska | </gnt:OperatingSystem> |
128 | 75932bcf | Agata Murawska | <gnt:Hypervisor> |
129 | 6499c5b8 | Agata Murawska | <gnt:Name/> |
130 | 6499c5b8 | Agata Murawska | <gnt:Parameters> |
131 | 6499c5b8 | Agata Murawska | </gnt:Parameters> |
132 | 75932bcf | Agata Murawska | </gnt:Hypervisor> |
133 | 6499c5b8 | Agata Murawska | <gnt:Network> |
134 | 6499c5b8 | Agata Murawska | <gnt:Mode/> |
135 | 6499c5b8 | Agata Murawska | <gnt:MACAddress/> |
136 | 6499c5b8 | Agata Murawska | <gnt:Link/> |
137 | 6499c5b8 | Agata Murawska | <gnt:IPAddress/> |
138 | 6499c5b8 | Agata Murawska | </gnt:Network> |
139 | 75932bcf | Agata Murawska | </gnt:GanetiSection> |
140 | 75932bcf | Agata Murawska | </Envelope> |
141 | 75932bcf | Agata Murawska | |
142 | 75932bcf | Agata Murawska | .. note :: |
143 | 75932bcf | Agata Murawska | Tags with ``gnt:`` prefix are Ganeti-specific and are not a part of |
144 | 75932bcf | Agata Murawska | OVF standard. |
145 | 75932bcf | Agata Murawska | |
146 | 75932bcf | Agata Murawska | .. highlight:: text |
147 | 75932bcf | Agata Murawska | |
148 | 75932bcf | Agata Murawska | Whereas Ganeti's export info is of the following form, ``=>`` showing |
149 | 75932bcf | Agata Murawska | where will the data be in OVF format:: |
150 | 75932bcf | Agata Murawska | |
151 | 75932bcf | Agata Murawska | [instance] |
152 | 6499c5b8 | Agata Murawska | disk0_dump = filename => File in References |
153 | 6499c5b8 | Agata Murawska | disk0_ivname = name => generated automatically |
154 | 6499c5b8 | Agata Murawska | disk0_size = size_in_mb => calculated after conversion to RAW |
155 | 6499c5b8 | Agata Murawska | disk_count = number => generated automatically |
156 | 6499c5b8 | Agata Murawska | disk_template = disk_type => gnt:DiskTemplate |
157 | 6499c5b8 | Agata Murawska | hypervisor = hyp-name => gnt:Name in gnt:Hypervisor |
158 | 75932bcf | Agata Murawska | name = inst-name => Name in VirtualSystem |
159 | 6499c5b8 | Agata Murawska | nic0_ip = ip => gnt:IPAddress in gnt:Network |
160 | 6499c5b8 | Agata Murawska | nic0_link = link => gnt:Link in gnt:Network |
161 | 6499c5b8 | Agata Murawska | nic0_mac = mac => gnt:MACAddress in gnt:Network or |
162 | 6499c5b8 | Agata Murawska | Item in VirtualHardwareSection |
163 | 6499c5b8 | Agata Murawska | nic0_mode = mode => gnt:Mode in gnt:Network |
164 | 6499c5b8 | Agata Murawska | nic_count = number => generated automatically |
165 | 75932bcf | Agata Murawska | tags => gnt:Tags |
166 | 75932bcf | Agata Murawska | |
167 | 75932bcf | Agata Murawska | [backend] |
168 | 75932bcf | Agata Murawska | auto_balanced => gnt:AutoBalance |
169 | 75932bcf | Agata Murawska | memory = mem_in_mb => Item in VirtualHardwareSection |
170 | 75932bcf | Agata Murawska | vcpus = number => Item in VirtualHardwareSection |
171 | 75932bcf | Agata Murawska | |
172 | 75932bcf | Agata Murawska | [export] |
173 | 6499c5b8 | Agata Murawska | compression => ignored |
174 | 6499c5b8 | Agata Murawska | os => gnt:Name in gnt:OperatingSystem |
175 | 75932bcf | Agata Murawska | source => ignored |
176 | 75932bcf | Agata Murawska | timestamp => ignored |
177 | 6499c5b8 | Agata Murawska | version => gnt:VersionId or |
178 | 6499c5b8 | Agata Murawska | constants.EXPORT_VERSION |
179 | 75932bcf | Agata Murawska | |
180 | 6499c5b8 | Agata Murawska | [os] => gnt:Parameters in gnt:OperatingSystem |
181 | 75932bcf | Agata Murawska | |
182 | 6499c5b8 | Agata Murawska | [hypervisor] => gnt:Parameters in gnt:Hypervisor |
183 | 75932bcf | Agata Murawska | |
184 | 75932bcf | Agata Murawska | In case of multiple networks/disks used by an instance, they will |
185 | 75932bcf | Agata Murawska | all be saved in appropriate sections as specified above for the first |
186 | 75932bcf | Agata Murawska | network/disk. |
187 | 75932bcf | Agata Murawska | |
188 | 75932bcf | Agata Murawska | Import from other virtualization software |
189 | 75932bcf | Agata Murawska | ----------------------------------------- |
190 | 75932bcf | Agata Murawska | In case of importing to Ganeti OVF package generated in other software, |
191 | 75932bcf | Agata Murawska | e.g. VirtualBox, some fields required for Ganeti to properly handle |
192 | 75932bcf | Agata Murawska | import may be missing. Most often it will happen that such OVF package |
193 | 75932bcf | Agata Murawska | will lack the ``gnt:GanetiSection``. |
194 | 75932bcf | Agata Murawska | |
195 | 6499c5b8 | Agata Murawska | If this happens you can specify all the missing parameters in |
196 | 6499c5b8 | Agata Murawska | the command line. Please refer to `Command Line`_ section. |
197 | 6499c5b8 | Agata Murawska | |
198 | 6499c5b8 | Agata Murawska | In the `user's manual <TODO: link to manual>`_ we provide examples of |
199 | 6499c5b8 | Agata Murawska | options when converting from VirtualBox, VMWare and OpenSuseStudio. |
200 | 75932bcf | Agata Murawska | |
201 | 75932bcf | Agata Murawska | Export to other virtualization software |
202 | 75932bcf | Agata Murawska | --------------------------------------- |
203 | 75932bcf | Agata Murawska | When exporting to other virtualization software, you may notice that |
204 | 75932bcf | Agata Murawska | there is a section ``gnt:GanetiSection``, containing Ganeti-specific |
205 | 75932bcf | Agata Murawska | information. This may on **rare** cases cause trouble in importing your |
206 | 75932bcf | Agata Murawska | instance. If that is the case please do one of the two: |
207 | 75932bcf | Agata Murawska | |
208 | 75932bcf | Agata Murawska | 1. Export from Ganeti to OVF with ``--external`` option - this will |
209 | 75932bcf | Agata Murawska | cause to skip the non-standard information. |
210 | 75932bcf | Agata Murawska | |
211 | 75932bcf | Agata Murawska | 2. Manually remove the gnt:GanetiSection from the ``.ovf`` file. You |
212 | 6499c5b8 | Agata Murawska | will also have to recompute sha1 sum (``sha1sum`` command) of the .ovf |
213 | 6499c5b8 | Agata Murawska | file and update your ``.mf`` file with new value. |
214 | 75932bcf | Agata Murawska | |
215 | 75932bcf | Agata Murawska | .. note:: |
216 | 75932bcf | Agata Murawska | Manual change option is only recommended when you have exported your |
217 | 75932bcf | Agata Murawska | instance with ``-format`` option other that ``raw`` or selected |
218 | 75932bcf | Agata Murawska | ``--compress``. It saves you the time of converting or compressing |
219 | 75932bcf | Agata Murawska | the disk image. |
220 | b3e3813e | Agata Murawska | |
221 | b3e3813e | Agata Murawska | Planned limitations |
222 | b3e3813e | Agata Murawska | =================== |
223 | b3e3813e | Agata Murawska | |
224 | b3e3813e | Agata Murawska | The limitations regarding import of the OVF instances generated |
225 | b3e3813e | Agata Murawska | outside Ganeti will be (in general) the same, as limitations for |
226 | b3e3813e | Agata Murawska | Ganeti itself. The desired behavior in case of encountering |
227 | 6499c5b8 | Agata Murawska | unsupported element will be to ignore this element's tag without |
228 | 6499c5b8 | Agata Murawska | interruption of the import process. |
229 | b3e3813e | Agata Murawska | |
230 | b3e3813e | Agata Murawska | Package |
231 | b3e3813e | Agata Murawska | ------- |
232 | b3e3813e | Agata Murawska | |
233 | b3e3813e | Agata Murawska | There are no limitations regarding support for multiple files in |
234 | 75932bcf | Agata Murawska | package or packing the OVF package into one OVA (Open Virtual |
235 | 75932bcf | Agata Murawska | Appliance) file. As for certificates and licenses in the package, |
236 | b3e3813e | Agata Murawska | their support will be under discussion after completion of the basic |
237 | b3e3813e | Agata Murawska | features implementation. |
238 | b3e3813e | Agata Murawska | |
239 | b3e3813e | Agata Murawska | Multiple Virtual Systems |
240 | b3e3813e | Agata Murawska | ------------------------ |
241 | b3e3813e | Agata Murawska | |
242 | b3e3813e | Agata Murawska | At first only singular instances (i.e. VirtualSystem, not |
243 | b3e3813e | Agata Murawska | VirtualSystemCollection) will be supported. In the future multi-tiered |
244 | b3e3813e | Agata Murawska | appliances containing whole nodes (or even clusters) are considered an |
245 | b3e3813e | Agata Murawska | option. |
246 | b3e3813e | Agata Murawska | |
247 | b3e3813e | Agata Murawska | Disks |
248 | b3e3813e | Agata Murawska | ----- |
249 | b3e3813e | Agata Murawska | |
250 | b3e3813e | Agata Murawska | As mentioned, Ganeti will allow exporting only ``raw``, ``cow`` and |
251 | b3e3813e | Agata Murawska | ``vmdk`` formats. As for import, we will support all that |
252 | b3e3813e | Agata Murawska | ``qemu-img`` can convert to raw format. At this point this means |
253 | b3e3813e | Agata Murawska | ``raw``, ``cow``, ``qcow``, ``qcow2``, ``vmdk`` and ``cloop``. We do |
254 | b3e3813e | Agata Murawska | not plan for now to support ``vdi`` or ``vhd``. |
255 | b3e3813e | Agata Murawska | |
256 | 75932bcf | Agata Murawska | We plan to support compression both for import and export - in tar.gz |
257 | 75932bcf | Agata Murawska | format. There is also a possibility to provide virtual disk in chunks |
258 | 6499c5b8 | Agata Murawska | of equal size. The latter will not be implemented in the first version, |
259 | 6499c5b8 | Agata Murawska | but we do plan to support it eventually. |
260 | 6499c5b8 | Agata Murawska | |
261 | 6499c5b8 | Agata Murawska | The ``ovf:format`` tag is not used in our case. Instead we use |
262 | 6499c5b8 | Agata Murawska | ``qemu-img info``, which provides enough information for our purposes |
263 | 6499c5b8 | Agata Murawska | and is better standardized. |
264 | b3e3813e | Agata Murawska | |
265 | 6499c5b8 | Agata Murawska | Please note, that due to security reasons we require the disk image to |
266 | 6499c5b8 | Agata Murawska | be in the same directory as the ``.ovf`` description file. |
267 | 6499c5b8 | Agata Murawska | |
268 | 6499c5b8 | Agata Murawska | In order to completely ignore disk-related information in resulting |
269 | 6499c5b8 | Agata Murawska | config file, please use ``--disk-template=diskless`` option. |
270 | b3e3813e | Agata Murawska | |
271 | b3e3813e | Agata Murawska | Network |
272 | b3e3813e | Agata Murawska | ------- |
273 | b3e3813e | Agata Murawska | |
274 | 6499c5b8 | Agata Murawska | Ganeti provides support for routed and bridged mode for the networks. |
275 | 6499c5b8 | Agata Murawska | Since the standard OVF format does not contain any information regarding |
276 | 6499c5b8 | Agata Murawska | used network type, we add our own source of such information in |
277 | 6499c5b8 | Agata Murawska | ``gnt:GanetiSection``. In case this additional information is not |
278 | 6499c5b8 | Agata Murawska | present, we perform a simple check - if network name specified in |
279 | 6499c5b8 | Agata Murawska | ``NetworkSection`` contains words ``bridged`` or ``routed``, we consider |
280 | 6499c5b8 | Agata Murawska | this to be the network type. Otherwise option ``auto`` is chosen, in |
281 | 6499c5b8 | Agata Murawska | which case the clusters' default value for that field will be used when |
282 | 6499c5b8 | Agata Murawska | importing. This provides a safe fallback in case of NAT networks usage, |
283 | 6499c5b8 | Agata Murawska | which are commonly used e.g. in VirtualBox. |
284 | b3e3813e | Agata Murawska | |
285 | b3e3813e | Agata Murawska | Hardware |
286 | b3e3813e | Agata Murawska | -------- |
287 | b3e3813e | Agata Murawska | |
288 | 6499c5b8 | Agata Murawska | The supported hardware is limited to virtual CPUs, RAM memory, disks and |
289 | 6499c5b8 | Agata Murawska | networks. In particular, no USB support is currently provided, as Ganeti |
290 | 6499c5b8 | Agata Murawska | does not support them. |
291 | b3e3813e | Agata Murawska | |
292 | b3e3813e | Agata Murawska | Operating Systems |
293 | b3e3813e | Agata Murawska | ----------------- |
294 | b3e3813e | Agata Murawska | |
295 | 6499c5b8 | Agata Murawska | Support for different operating systems depends solely on their |
296 | 6499c5b8 | Agata Murawska | accessibility for Ganeti instances. List of installed OSes can be |
297 | 6499c5b8 | Agata Murawska | checked using ``gnt-os list`` command. |
298 | b3e3813e | Agata Murawska | |
299 | b3e3813e | Agata Murawska | Other |
300 | b3e3813e | Agata Murawska | ----- |
301 | b3e3813e | Agata Murawska | |
302 | 6499c5b8 | Agata Murawska | The instance name (``gnt:VirtualSystem\gnt:Name``) has to be resolvable |
303 | 6499c5b8 | Agata Murawska | in order for successful import using ``gnt-backup import``. |
304 | 6499c5b8 | Agata Murawska | |
305 | 6499c5b8 | Agata Murawska | _`Command Line` |
306 | 6499c5b8 | Agata Murawska | =============== |
307 | 6499c5b8 | Agata Murawska | |
308 | 6499c5b8 | Agata Murawska | The basic usage of the ovf tool is one of the following:: |
309 | 6499c5b8 | Agata Murawska | |
310 | 6499c5b8 | Agata Murawska | ovfconverter import filename |
311 | 6499c5b8 | Agata Murawska | ovfconverter export filename |
312 | 6499c5b8 | Agata Murawska | |
313 | 6499c5b8 | Agata Murawska | This will result in a conversion based solely on the content of provided |
314 | 6499c5b8 | Agata Murawska | file. In case some information required to make the conversion is |
315 | 6499c5b8 | Agata Murawska | missing, an error will occur. |
316 | 6499c5b8 | Agata Murawska | |
317 | 6499c5b8 | Agata Murawska | If output directory should be different than the standard Ganeti export |
318 | 6499c5b8 | Agata Murawska | directory (usually ``/srv/ganeti/export``), option ``--output-dir`` |
319 | 6499c5b8 | Agata Murawska | can be used. |
320 | 6499c5b8 | Agata Murawska | |
321 | 6499c5b8 | Agata Murawska | If name of resulting entity should be different than the one read from |
322 | 6499c5b8 | Agata Murawska | the file, use ``--name`` option. |
323 | 6499c5b8 | Agata Murawska | |
324 | 6499c5b8 | Agata Murawska | Import options |
325 | 6499c5b8 | Agata Murawska | -------------- |
326 | 6499c5b8 | Agata Murawska | |
327 | 6499c5b8 | Agata Murawska | Import options that ``ovfconverter`` supports include options for |
328 | 6499c5b8 | Agata Murawska | backend, disks, hypervisor, networks and operating system. If an option |
329 | 6499c5b8 | Agata Murawska | is given, it overrides the values provided in the OVF file. |
330 | 6499c5b8 | Agata Murawska | |
331 | 6499c5b8 | Agata Murawska | Backend |
332 | 6499c5b8 | Agata Murawska | ^^^^^^^ |
333 | 6499c5b8 | Agata Murawska | ``--backend=option=value`` can be used to set auto balance, number of |
334 | 6499c5b8 | Agata Murawska | vcpus and amount of RAM memory. |
335 | 6499c5b8 | Agata Murawska | |
336 | 6499c5b8 | Agata Murawska | Please note that when you do not provide full set of options, the |
337 | 6499c5b8 | Agata Murawska | omitted ones will be set to cluster defaults (``auto``). |
338 | 6499c5b8 | Agata Murawska | |
339 | 6499c5b8 | Agata Murawska | Disks |
340 | 6499c5b8 | Agata Murawska | ^^^^^ |
341 | 6499c5b8 | Agata Murawska | ``--disk-template=diskless`` causes the converter to ignore all other |
342 | 6499c5b8 | Agata Murawska | disk option - both from .ovf file and the command line. |
343 | 6499c5b8 | Agata Murawska | |
344 | 6499c5b8 | Agata Murawska | ``--disk=number:size=value`` causes to create disks instead of |
345 | 6499c5b8 | Agata Murawska | converting them from OVF package; numbers should start with ``0`` and be |
346 | 6499c5b8 | Agata Murawska | consecutive. |
347 | 6499c5b8 | Agata Murawska | |
348 | 6499c5b8 | Agata Murawska | Hypervisor |
349 | 6499c5b8 | Agata Murawska | ^^^^^^^^^^ |
350 | 6499c5b8 | Agata Murawska | ``-H hypervisor_name`` and ``-H hypervisor_name:option=value`` |
351 | 6499c5b8 | Agata Murawska | provide options for hypervisor. |
352 | 6499c5b8 | Agata Murawska | |
353 | 6499c5b8 | Agata Murawska | Network |
354 | 6499c5b8 | Agata Murawska | ^^^^^^^ |
355 | 6499c5b8 | Agata Murawska | ``--no-nics`` option causes converter to ignore any network information |
356 | 6499c5b8 | Agata Murawska | provided. |
357 | 6499c5b8 | Agata Murawska | |
358 | 6499c5b8 | Agata Murawska | ``--network=number:option=value`` sets network information according to |
359 | 6499c5b8 | Agata Murawska | provided data, ignoring the OVF package configuration. |
360 | 6499c5b8 | Agata Murawska | |
361 | 6499c5b8 | Agata Murawska | Operating System |
362 | 6499c5b8 | Agata Murawska | ^^^^^^^^^^^^^^^^ |
363 | 6499c5b8 | Agata Murawska | ``--os-type=type`` sets os type accordingly, this option is **required** |
364 | 6499c5b8 | Agata Murawska | when importing from OVF instance not created from Ganeti config file. |
365 | 6499c5b8 | Agata Murawska | |
366 | 6499c5b8 | Agata Murawska | ``--os-parameters`` provides options for chosen operating system. |
367 | 6499c5b8 | Agata Murawska | |
368 | 6499c5b8 | Agata Murawska | Tags |
369 | 6499c5b8 | Agata Murawska | ^^^^ |
370 | 6499c5b8 | Agata Murawska | ``--tags=tag1,tag2,tag3`` is a means of providing tags specific for the |
371 | 6499c5b8 | Agata Murawska | instance. |
372 | 6499c5b8 | Agata Murawska | |
373 | 6499c5b8 | Agata Murawska | After the conversion is completed, you may use ``gnt-backup import`` to |
374 | 6499c5b8 | Agata Murawska | import the instance into Ganeti. |
375 | 6499c5b8 | Agata Murawska | |
376 | 6499c5b8 | Agata Murawska | Example:: |
377 | 6499c5b8 | Agata Murawska | |
378 | 6499c5b8 | Agata Murawska | ovfconverter file.ovf --disk-template=diskless \ |
379 | 6499c5b8 | Agata Murawska | --os-type=lenny-image \ |
380 | 6499c5b8 | Agata Murawska | --backend=vcpus=1,memory=512,auto_balance \ |
381 | 6499c5b8 | Agata Murawska | -H:xen-pvm \ |
382 | 6499c5b8 | Agata Murawska | --net=0:mode=bridged,link=xen-br0 \ |
383 | 6499c5b8 | Agata Murawska | --name=xen.i1 \ |
384 | 6499c5b8 | Agata Murawska | -v |
385 | 6499c5b8 | Agata Murawska | [output] |
386 | 6499c5b8 | Agata Murawska | gnt-backup import xen.i1 |
387 | 6499c5b8 | Agata Murawska | [output] |
388 | 6499c5b8 | Agata Murawska | gnt-instance list |
389 | 6499c5b8 | Agata Murawska | |
390 | 6499c5b8 | Agata Murawska | Export options |
391 | 6499c5b8 | Agata Murawska | -------------- |
392 | 6499c5b8 | Agata Murawska | Export options include choice of disk formats to convert the disk image |
393 | 6499c5b8 | Agata Murawska | (``--format``; default=``raw`` with no conversion) and compression of |
394 | 6499c5b8 | Agata Murawska | the disk into tar.gz format (``--compress``). |
395 | 6499c5b8 | Agata Murawska | User has also the choice of allowing to skip the Ganeti-specific part of |
396 | 6499c5b8 | Agata Murawska | the OVF document (``--external``). |
397 | 6499c5b8 | Agata Murawska | |
398 | 6499c5b8 | Agata Murawska | By default, exported OVF package will not be contained in the OVA |
399 | 6499c5b8 | Agata Murawska | package, but this may be changed by adding ``--ova`` option. |
400 | 6499c5b8 | Agata Murawska | |
401 | 6499c5b8 | Agata Murawska | [TODO: examples of usage] |
402 | 6499c5b8 | Agata Murawska | |
403 | 6499c5b8 | Agata Murawska | Please note that in order to create an OVF package, it is first |
404 | 6499c5b8 | Agata Murawska | required that you export your VM using ``gnt-backup export``. |
405 | 6499c5b8 | Agata Murawska | |
406 | 6499c5b8 | Agata Murawska | [TODO: complete example of export] |
407 | 75932bcf | Agata Murawska | |
408 | b3e3813e | Agata Murawska | Implementation details |
409 | b3e3813e | Agata Murawska | ====================== |
410 | b3e3813e | Agata Murawska | |
411 | 6499c5b8 | Agata Murawska | Disk conversion |
412 | 6499c5b8 | Agata Murawska | --------------- |
413 | 6499c5b8 | Agata Murawska | |
414 | 6499c5b8 | Agata Murawska | Disk conversion for both import and export is done using external tool |
415 | 6499c5b8 | Agata Murawska | called qemu-tools. The same tool is used to determine the type of disks. |
416 | 6499c5b8 | Agata Murawska | |
417 | 6499c5b8 | Agata Murawska | |
418 | 6499c5b8 | Agata Murawska | Import |
419 | 6499c5b8 | Agata Murawska | ------ |
420 | 6499c5b8 | Agata Murawska | |
421 | 6499c5b8 | Agata Murawska | Import functionality is implemented using two classes - OVFReader and |
422 | 6499c5b8 | Agata Murawska | OVFImporter. |
423 | 6499c5b8 | Agata Murawska | |
424 | 6499c5b8 | Agata Murawska | OVFReader class is used to read the contents of the ``.ovf`` file. Every |
425 | 6499c5b8 | Agata Murawska | action that requires ``.ovf`` file access is done through that class. |
426 | 6499c5b8 | Agata Murawska | It also performs validation of manifest, if one is present. |
427 | 6499c5b8 | Agata Murawska | |
428 | 6499c5b8 | Agata Murawska | The result of reading some part of file is typically a dictionary or a |
429 | 6499c5b8 | Agata Murawska | string, containing options which correspond to the ones in |
430 | 6499c5b8 | Agata Murawska | ``config.ini`` file. Only in case of disks, the resulting value is |
431 | 6499c5b8 | Agata Murawska | different - it is then a list of disk names. The reason for that is the |
432 | 6499c5b8 | Agata Murawska | need for conversion. |
433 | 6499c5b8 | Agata Murawska | |
434 | 6499c5b8 | Agata Murawska | OVFImporter class performs all the command-line-like tasks, such as |
435 | 6499c5b8 | Agata Murawska | unpacking OVA package, removing temporary directory, converting disk |
436 | 6499c5b8 | Agata Murawska | file to raw format or saving the configuration file on disk. |
437 | 6499c5b8 | Agata Murawska | It also contains a set of functions that read the options provided in |
438 | 6499c5b8 | Agata Murawska | the command line. |
439 | 6499c5b8 | Agata Murawska | |
440 | 6499c5b8 | Agata Murawska | |
441 | 6499c5b8 | Agata Murawska | Typical workflow for the import is very simple: |
442 | 6499c5b8 | Agata Murawska | |
443 | 6499c5b8 | Agata Murawska | - read the ``.ovf`` file info memory |
444 | 6499c5b8 | Agata Murawska | - verify manifest |
445 | 6499c5b8 | Agata Murawska | - parse each element of the configuration file: name, disk template, |
446 | 6499c5b8 | Agata Murawska | hypervisor, operating system, backend parameters, network and disks |
447 | 6499c5b8 | Agata Murawska | |
448 | 6499c5b8 | Agata Murawska | - check if option for the element can be read from command line |
449 | 6499c5b8 | Agata Murawska | options |
450 | 6499c5b8 | Agata Murawska | |
451 | 6499c5b8 | Agata Murawska | - if yes: parse options from command line |
452 | 6499c5b8 | Agata Murawska | |
453 | 6499c5b8 | Agata Murawska | - otherwise: read the appropriate portion of ``.ovf`` file |
454 | 6499c5b8 | Agata Murawska | |
455 | 6499c5b8 | Agata Murawska | - save gathered information in ``config.ini`` file |
456 | 6499c5b8 | Agata Murawska | |
457 | 6499c5b8 | Agata Murawska | ToDo |
458 | 6499c5b8 | Agata Murawska | ==== |
459 | 6499c5b8 | Agata Murawska | |
460 | 6499c5b8 | Agata Murawska | This lists functionalities for import that are not yet implemented, but |
461 | 6499c5b8 | Agata Murawska | should be before the initial release: |
462 | 6499c5b8 | Agata Murawska | |
463 | 6499c5b8 | Agata Murawska | - Support for compressed disks |
464 | 6499c5b8 | Agata Murawska | |
465 | b3e3813e | Agata Murawska | |
466 | b3e3813e | Agata Murawska | .. vim: set textwidth=72 : |
467 | b3e3813e | Agata Murawska | .. Local Variables: |
468 | b3e3813e | Agata Murawska | .. mode: rst |
469 | b3e3813e | Agata Murawska | .. fill-column: 72 |
470 | b3e3813e | Agata Murawska | .. End: |