Debian Codegraph @

doc/source/building_images/build_simple_disk.rst

raw
1 .. _simple_disk:
2
3 Build a Virtual Disk Image
4 ==========================
5
6 .. sidebar:: Abstract
7
8 This page explains how to build a simple disk image.
9 It covers the following topics:
10
11 - defines a simple disk image in the image description
12 - builds a simple disk image
13 - runs it with QEMU
14
15 A simple virtual disk image is a compressed system disk with additional
16 metadata useful for cloud frameworks like Amazon EC2, Google Compute Engine,
17 or Microsoft Azure. It is used as the native disk of a system, and it does
18 not require an additional installation workflow or a complex first-boot setup
19 procedure.
20
21 To enable {kiwi} to build a simple disk image, add a `type` element with
22 `image="oem"` in :file:`config.xml`, where the `oem-resize` option is
23 disabled. An example configuration for a 42-GB large VMDK image with
24 512 MB of RAM, an IDE controller, and a bridged network interface is shown
25 below:
26
27 .. code:: xml
28
29 <image schemaversion="{schema_version}" name="Tumbleweed_appliance">
30 <!-- snip -->
31 <preferences>
32 <type image="oem" filesystem="ext4" format="vmdk">
33 <bootloader name="grub2" timeout="0"/>
34 <size unit="G">42</size>
35 <oemconfig>
36 <oem-resize>false</oem-resize>
37 </oemconfig>
38 <machine memory="512" guestOS="suse" HWversion="4">
39 <vmdisk id="0" controller="ide"/>
40 <vmnic driver="e1000" interface="0" mode="bridged"/>
41 </machine>
42 </type>
43 <!-- additional preferences -->
44 </preferences>
45 <!-- snip -->
46 </image>
47
48 The following attributes of the `type` element deserve attention
49 when building simple disk images:
50
51 - `format`: Specifies the format of the virtual disk. Possible values are
52 `gce`, `ova`, `qcow2`, `vagrant`, `vmdk`, `vdi`, `vhd`, `vhdx`, and
53 `vhd-fixed`.
54
55 - `formatoptions`: Specifies additional format options passed to
56 :command:`qemu-img`. `formatoptions` is a comma-separated list of format-
57 specific options in a `name=value` format, as expected by
58 :command:`qemu-img`. {kiwi} forwards the settings from the attribute as a
59 parameter to the `-o` option in the :command:`qemu-img` call.
60
61 The `bootloader`, `size`, and `machine` child elements of `type` can be
62 used to customize the virtual machine image. These elements are described in
63 the following sections: :ref:`disk-bootloader`, :ref:`disk-the-size-element`,
64 and :ref:`disk-the-machine-element`.
65
66 Once your image description is finished, you can build the image using the
67 following {kiwi} command:
68
69 .. code:: bash
70
71 $ sudo kiwi-ng system build \
72 --description kiwi/build-tests/{exc_description_disk_simple} \
73 --set-repo {exc_repo_leap} \
74 --target-dir /tmp/myimage
75
76 The resulting :file:`.raw` image is stored in :file:`/tmp/myimage`.
77
78 You can test the image using QEMU:
79
80 .. code:: bash
81
82 $ sudo qemu \
83 -drive file={exc_image_base_name_disk_simple}.x86_64-{exc_image_version}.raw,format=raw,if=virtio \
84 -m 4096
85
86 For further information on how to configure the image to work within a cloud
87 framework, see:
88
89 * :ref:`setup_for_ec2`
90 * :ref:`setup_for_azure`
91 * :ref:`setup_for_gce`
92
93 For information on how to set up a Vagrant system, see :ref:`setup_vagrant`.
94
95 .. _disk-bootloader:
96
97 Setting up the Bootloader in the Image
98 --------------------------------------
99
100 .. code:: xml
101
102 <preferences>
103 <type>
104 <bootloader name="grub2"/>
105 </type>
106 </preferences>
107
108 The `bootloader` element defines which bootloader to use in the
109 image, and the element offers several options for customizing its configuration.
110
111 For details, see :ref:`preferences-type-bootloader`.
112
113 .. _disk-the-size-element:
114
115 Modifying the Size of the Image
116 -------------------------------
117
118 The `size` child element of `type` specifies the size of the resulting
119 disk image. The following example shows an image description where 20 GB are
120 added to the virtual machine image, of which 5 GB are left unpartitioned:
121
122 .. code:: xml
123
124 <preferences>
125 <type image="oem" format="vmdk">
126 <size unit="G" additive="true" unpartitioned="5">20</size>
127 <oemconfig>
128 <oem-resize>false</oem-resize>
129 </oemconfig>
130 </type>
131 </preferences>
132
133 The following optional attributes can be used to further customize the image size:
134
135 - `unit`: Defines the unit used for the provided numerical value. Possible
136 values are `M` for megabytes and `G` for gigabytes. The default unit
137 is megabytes.
138
139 - `additive`: A boolean value that determines whether the provided value is added
140 to the current image size (`additive="true"`) or whether it is the total size
141 (`additive="false"`). The default value is `false`.
142
143 - `unpartitioned`: Specifies the image space in the image that is not
144 partitioned. The attribute uses either the same unit as defined in the attribute
145 `unit` or the default value.
146
147
148 .. _disk-the-machine-element:
149
150 Customizing the Virtual Machine
151 -------------------------------
152
153 The `machine` child element of `type` can be used to customize the virtual
154 machine configuration, including the number of CPUs and the connected network
155 interfaces.
156
157 The following attributes are supported by the `machine` element:
158
159 - `ovftype`: The OVF configuration type. The Open Virtualization Format is a
160 standard for describing virtual appliances and distributing them in an archive
161 called an Open Virtual Appliance (OVA). The standard describes the major
162 components associated with a disk image. The exact specification depends on
163 the product using the format. Supported value is `vmware`.
164
165 - `HWversion`: The virtual machine's hardware version (`vmdk` and `ova`
166 formats only); refer to VMware documentation for further
167 information on the supported values.
168
169 - `arch`: the VM architecture (`vmdk` format only). Valid values are
170 `ix86` (= `i585` and `i686`) and `x86_64`.
171
172 - `xen_loader`: the Xen target loader that is expected to load the guest.
173 Valid values are `hvmloader`, `pygrub`, and `pvgrub`.
174
175 - `guestOS`: The virtual guest OS' identification string for the VM (only
176 applicable for `vmdk` and `ova` formats. Note that the name designation
177 is different for the two formats).
178 Note: For vmware ovftools, guestOS is a VMX GuestOS, but not a VIM GuestOS.
179 For instance, the correct value for Ubuntu 64-bit is "ubuntu-64", but not
180 "ubuntu64Guest". See GUEST_OS_KEY_MAP in guest_os_tables.h at
181 https://github.com/vmware/open-vm-tools for another guestOS values.
182
183 - `min_memory`: The virtual machine's minimum memory in MB (`ova` format
184 only).
185
186 - `max_memory`: The virtual machine's maximum memory in MB (`ova` format
187 only).
188
189 - `min_cpu`: The virtual machine's minimum CPU count (`ova` format only).
190
191 - `max_cpu`: The virtual machine's maximum CPU count (`ova` format only).
192
193 - `memory`: The virtual machine's memory in MB (all formats).
194
195 - `ncpus`: The number of virtual CPUs available to the virtual machine (all
196 formats).
197
198 `machine` also supports additional child elements that are covered in the following
199 subsections.
200
201 Modifying the VM Configuration Directly
202 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
203
204 The `vmconfig-entry` element is used to add entries directly into the
205 virtual machine's configuration file. This is currently only supported for
206 the `vmdk` format, where the provided strings are directly pasted into the
207 :file:`.vmx` file.
208
209 The `vmconfig-entry` element has no attributes and can appear multiple
210 times. The entries are added to the configuration file in the provided
211 order. Note that {kiwi} does not check the entries for correctness.
212
213 The following example adds the two entries `numvcpus = "4"` and
214 `cpuid.coresPerSocket = "2"` into the VM configuration file:
215
216 .. code:: xml
217
218 <preferences>
219 <type image="oem" filesystem="ext4" format="vmdk">
220 <machine memory="512" guestOS="suse" HWversion="4">
221 <vmconfig-entry>numvcpus = "4"</vmconfig-entry>
222 <vmconfig-entry>cpuid.coresPerSocket = "2"</vmconfig-entry>
223 </machine>
224 </type>
225 </preferences>
226
227 Adding Network Interfaces to the VM
228 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
229
230 Network interfaces can be explicitly specified for the VM when required via
231 the `vmnic` element. This makes it possible to add another bridged interface or
232 to specify the driver to be used.
233
234 Note that this element is used for the `vmdk` image format only.
235
236 The following example adds a bridged network interface that uses the `e1000`
237 driver:
238
239 .. code:: xml
240
241 <preferences>
242 <type image="oem" filesystem="ext4" format="vmdk">
243 <machine memory="4096" guestOS="suse" HWversion="4">
244 <vmnic driver="e1000" interface="0" mode="bridged"/>
245 </machine>
246 </type>
247 </preferences>
248
249 The `vmnic` element supports the following attributes:
250
251 - `interface`: **Mandatory** interface ID for the VM's network interface.
252
253 - `driver`: An optional driver.
254
255 - `mac`: The MAC address of the specified interface.
256
257 - `mode`: The mode of the interface.
258
259 Note that {kiwi} does **not** verify the values of the
260 attributes; it only inserts them into the appropriate configuration
261 files.
262
263
264 Specifying Disks and Disk Controllers
265 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
266
267 The `vmdisk` element can be used to customize the disks and disk controllers for
268 the virtual machine. This element can be specified for each disk or disk
269 controller present.
270
271 Note that this element is used for `vmdk` and `ova` image formats only.
272
273 The following example adds a disk with the ID 0 that uses an IDE controller:
274
275 .. code:: xml
276
277 <preferences>
278 <type image="oem" filesystem="ext4" format="vmdk">
279 <machine memory="512" guestOS="suse" HWversion="4">
280 <vmdisk id="0" controller="ide"/>
281 </machine>
282 </type>
283 </preferences>
284
285 Each `vmdisk` element can be further customized using optional
286 attributes:
287
288 - `controller`: The disk controller used for the VM guest (`vmdk` format
289 only). Supported values are `ide`, `buslogic`, `lsilogic`, `lsisas1068`,
290 `legacyESX`, and `pvscsi`.
291
292 - `device`: The disk device to appear in the guest (`xen` format only).
293
294 - `diskmode`: The disk mode (`vmdk` format only). Valid values are
295 `monolithicSparse`, `monolithicFlat`, `twoGbMaxExtentSparse`,
296 `twoGbMaxExtentFlat`, and `streamOptimized` (see also
297 https://vdc-download.vmware.com/vmwb-repository/dcr-public/6335f27c-c6e9-4804-95b0-ea9449958403/c7798a8b-4c73-41d9-84e8-db5453de7b17/doc/vddkDataStruct.5.3.html).
298
299 - `disktype`: The type of the disk handled internally by the VM
300 (`ova` format only). This attribute is currently unused.
301
302 - `id`: The disk ID of the VM disk (`vmdk` format only).
303
304 Adding CD/DVD Drives
305 ^^^^^^^^^^^^^^^^^^^^
306
307 {kiwi} supports adding IDE and SCSCI CD/DVD drives to the virtual
308 machine using the `vmdvd` element for the `vmdk` image format. The
309 following example adds two drives: one with a SCSCI and another with an
310 IDE controller:
311
312 .. code:: xml
313
314 <preferences>
315 <type image="oem" filesystem="ext4">
316 <machine memory="512" xen_loader="hvmloader">
317 <vmdvd id="0" controller="scsi"/>
318 <vmdvd id="1" controller="ide"/>
319 </machine>
320 </type>
321 </preferences>
322
323 The `vmdvd` element features two **mandatory** attributes:
324
325 - `id`: The CD/DVD ID of the drive.
326
327 - `controller`: The CD/DVD controller used for the VM guest. Valid
328 values are `ide` and `scsi`.