diff --git a/doc/image-guide/ch_openstack_images.xml b/doc/image-guide/ch_openstack_images.xml index fb3d5c9a70..ac23385618 100644 --- a/doc/image-guide/ch_openstack_images.xml +++ b/doc/image-guide/ch_openstack_images.xml @@ -1,4 +1,8 @@ + + +]> cloud-init package. You should read this section - before creating your own image to be sure that the image - supports the OpenStack features you plan on using. - - Disk partitions and resize root partition on - boot (cloud-init) - - - No hard-coded MAC address information - - - SSH server running - - - Disable firewall - - - Access instance using ssh public key - (cloud-init) - - - Process user data and other metadata - (cloud-init) - - - Paravirtualized Xen support in Linux kernel (Xen - hypervisor only with Linux kernel version < - 3.0) - - + >cloud-init package. Read + this section before you create your own image to be sure that + the image supports the OpenStack features that you plan on + using. + + + Disk partitions and resize root partition on boot + (cloud-init) + + + No hard-coded MAC address information + + + SSH server running + + + Disable firewall + + + Access instance using ssh public key + (cloud-init) + + + Process user data and other metadata + (cloud-init) + + + Paravirtualized Xen support in Linux kernel (Xen + hypervisor only with Linux kernel version < + 3.0) + +
Disk partitions and resize root partition on boot (cloud-init) - When you create a new Linux image, the first decision - you will need to make is how to partition the disks. The - choice of partition method can affect the resizing - functionality, as described below. + When you create a Linux image, you must decide how to + partition the disks. The choice of partition method can + affect the resizing functionality, as described in the + following sections. The size of the disk in a virtual machine image is determined when you initially create the image. However, OpenStack lets you launch instances with different size drives by specifying different flavors. For example, if - your image was created with a 5 GB disk, and you launch an - instance with a flavor of m1.small. The - resulting virtual machine instance has, by default, - a primary disk size of 10 GB. When an instance's disk is resized - up, zeros are just added to the end. - Your image needs to be able to resize its partitions on - boot to match the size requested by the user. Otherwise, - after the instance boots, you will need to manually resize - the partitions if you want to access the additional - storage you have access to when the disk size associated - with the flavor exceeds the disk size your image was - created with. + your image was created with a 5 GB disk, and you + launch an instance with a flavor of + m1.small. The resulting virtual + machine instance has, by default, a primary disk size of + 10 GB. When the disk for an instance is resized up, + zeros are just added to the end. + Your image must be able to resize its partitions on boot + to match the size requested by the user. Otherwise, after + the instance boots, you must manually resize the + partitions to access the additional storage to which you + have access when the disk size associated with the flavor + exceeds the disk size with which your image was + created. Xen: 1 ext3/ext4 partition (no LVM, no /boot, no swap) - If you are using the OpenStack XenAPI driver, the - Compute service will automatically adjust the - partition and filesystem for your instance on boot. - Automatic resize will occur if the following are all true: - - auto_disk_config=True - is set as a property on the image in the - Image Registry. - - - The disk on the image has only one - partition. - - - The file system on the one partition is - ext3 or ext4. - - - Therefore, if you are using Xen, we recommend that - when you create your images, you create a single ext3 - or ext4 partition (not managed by LVM). Otherwise, - read on. + If you use the OpenStack XenAPI driver, the Compute + service automatically adjusts the partition and file + system for your instance on boot. Automatic resize + occurs if the following conditions are all + true: + + + auto_disk_config=True is + set as a property on the image in the image + registry. + + + The disk on the image has only one + partition. + + + The file system on the one partition is ext3 + or ext4. + + + Therefore, if you use Xen, we recommend that when + you create your images, you create a single ext3 or + ext4 partition (not managed by LVM). Otherwise, read + on. - Non-Xen with cloud-init/cloud-tools: 1 ext3/ext4 + <title>Non-Xen with cloud-init/cloud-tools: One ext3/ext4 partition (no LVM, no /boot, no swap) - Your image must be configured to deal with two issues: - - The image's partition table describes - the original size of the image - - - The image's filesystem fills the - original size of the image - - - Then, during the boot process: - - the partition table must be modified to - be made aware of the additional space - - If you are not using LVM, you - must modify the table to extend the - existing root partition to - encompass this additional - space - - - If you are using LVM, you can - create add a new LVM entry to the - partition table, create a new LVM - physical volume, add it to the - volume group, and extend the - logical partition with the root - volume - - - - - the root volume filesystem must be - resized - - + You must configure these items for your + image: + + + The partition table for the image describes + the original size of the image + + + The file system for the image fills the + original size of the image + + + Then, during the boot process, you must: + + + Modify the partition table to make it aware + of the additional space: + + + If you do not use LVM, you must + modify the table to extend the + existing root partition to encompass + this additional space. + + + If you use LVM, you can add a new + LVM entry to the partition table, + create a new LVM physical volume, add + it to the volume group, and extend the + logical partition with the root + volume. + + + + + Resize the root volume file system. + + The simplest way to support this in your image is to install the growpart tool for extending partitions), the cloud-initramfs-tools package (which will - support resizing root partition on the first boot), + >cloud-initramfs-tools package (which + supports resizing root partition on the first boot), and the cloud-init package into your image. With - these installed, the image will perform the root - partition resize on boot. For example, in the - /etc/rc.local file. These - packages are in the Ubuntu and Debian package - repository, as well as the EPEL repository (for - Fedora/RHEL/CentOS/Scientific Linux guests). - If you are not able to install + >cloud-init package + into your image. With these installed, the image + performs the root partition resize on boot. For + example, in the /etc/rc.local + file. These packages are in the Ubuntu and Debian + package repository, as well as the EPEL repository + (for Fedora/RHEL/CentOS/Scientific Linux + guests). + If you cannot install cloud-initramfs-tools, Robert Plestenjak has a github project called linux-rootfs-resize that contains scripts - that will update a ramdisk using - growpart so that the image will - resize properly on boot. - If you are able to install the cloud-utils and - cloud-init packages, we recommend that when you create - your images, you create a single ext3 or ext4 - partition (not managed by LVM). + that update a ramdisk by using + growpart so that the image + resizes properly on boot. + If you can install the cloud-utils and + cloud-init packages, we + recommend that when you create your images, you create + a single ext3 or ext4 partition (not managed by + LVM). - Non-Xen without cloud-init/cloud-tools: LVM - If you cannot install cloud-init and cloud-tools - inside of your guest, and you want to support resize, - you will need to write a script that your image will - run on boot to modify the partition table. In this - case, we recommend using LVM to manage your - partitions. Due to a limitation in the Linux kernel - (as of this writing), you cannot modify a partition - table of a raw disk that has partition currently - mounted, but you can do this for LVM. - Your script will need to do something like the following: + Non-Xen without + <package>cloud-init</package>/<package>cloud-tools</package>: + LVM + If you cannot install cloud-init + and cloud-tools inside of your + guest, and you want to support resize, you must write + a script that your image runs on boot to modify the + partition table. In this case, we recommend using LVM + to manage your partitions. Due to a limitation in the + Linux kernel (as of this writing), you cannot modify a + partition table of a raw disk that has partitions + currently mounted, but you can do this for LVM. + Your script must do something like the following: Detect if any additional space is available on the disk. For example, parse @@ -210,58 +224,56 @@ /dev/mapper/node-root. - You do not need to have a /boot - partition, unless your image is an older Linux + You do not need a /boot + partition unless your image is an older Linux distribution that requires that - /boot is not managed by LVM. - You may elect to use a swap per + /boot is not managed by LVM.
No hard-coded MAC address information You must remove the network persistence rules in the - image as their presence will result in the network - interface in the instance coming up as an interface other - than eth0. This is because your image has a record of the - MAC address of the network interface card when it was - first installed, and this MAC address will be different - each time the instance boots up. You should alter the - following files: - - Replace - /etc/udev/rules.d/70-persistent-net.rules - with an empty file (contains network - persistence rules, including MAC - address) - - - Replace - /lib/udev/rules.d/75-persistent-net-generator.rules - with an empty file (this generates the file - above) - - - Remove the HWADDR line from - /etc/sysconfig/network-scripts/ifcfg-eth0 - on Fedora-based images - - - If you delete the network persistent rules - files, you may get a udev kernel warning at boot - time, which is why we recommend replacing them - with empty files instead. - - + image because they cause the network interface in the + instance to come up as an interface other than eth0. This + is because your image has a record of the MAC address of + the network interface card when it was first installed, + and this MAC address is different each time that the + instance boots. You should alter the following + files: + + + Replace + /etc/udev/rules.d/70-persistent-net.rules + with an empty file (contains network persistence + rules, including MAC address) + + + Replace + /lib/udev/rules.d/75-persistent-net-generator.rules + with an empty file (this generates the file + above) + + + Remove the HWADDR line from + /etc/sysconfig/network-scripts/ifcfg-eth0 + on Fedora-based images + + + + If you delete the network persistent rules files, + you may get a udev kernel warning at boot time, which + is why we recommend replacing them with empty files + instead. +
Ensure ssh server runs You must install an ssh server into the image and ensure - that it starts up on boot, or you will not be able to - connect to your instance using ssh when it boots inside of - OpenStack. This package is typically called + that it starts up on boot, or you cannot connect to your + instance by using ssh when it boots inside of OpenStack. + This package is typically called openssh-server.
-
Disable firewall In general, we recommend that you disable any firewalls @@ -272,7 +284,7 @@ connect to your instance.
- Access instance using ssh public key + <title>Access instance by using ssh public key (cloud-init) The typical way that users access virtual machines running on OpenStack is to ssh using public key @@ -281,28 +293,32 @@ from the OpenStack metadata service or config drive, at boot time. - Use cloud-init to fetch the public key - The cloud-init package will automatically fetch the - public key from the metadata server and place the key - in an account. The account varies by distribution. On - Ubuntu-based virtual machines, the account is called - "ubuntu". On Fedora-based virtual machines, the - account is called "ec2-user". + Use <package>cloud-init</package> to fetch the + public key + The cloud-init package + automatically fetches the public key from the metadata + server and places the key in an account. The account + varies by distribution. On Ubuntu-based virtual + machines, the account is called + ubuntu. On Fedora-based virtual + machines, the account is called + ec2-user. You can change the name of the account used by - cloud-init by editing the + cloud-init by editing the /etc/cloud/cloud.cfg file and adding a line with a different user. For example, to - configure cloud-init to put the key in an account - named admin, edit the configuration - file so it has the line: + configure cloud-init to put the key + in an account named admin, edit the + configuration file so it has the line: user: admin Write a custom script to fetch the public key - If you are unable or unwilling to install cloud-init - inside the guest, you can write a custom script to - fetch the public key and add it to a user account. + If you are unable or unwilling to install + cloud-init inside the guest, + you can write a custom script to fetch the public key + and add it to a user account. To fetch the ssh public key and add it to the root account, edit the /etc/rc.local file and add the following lines before the line @@ -357,17 +373,16 @@ done
Process user data and other metadata (cloud-init) - In addition to the ssh public key, an image may need to - retrieve additional information from OpenStack, such as - In addition to the ssh public key, an image might need + additional information from OpenStack, such as user data that the user submitted when - requesting the image. For example, you might want to set the - host name of the instance when it is booted. Or, you might - wish to configure your image so that it executes user data - content as a script on boot. - This information is accessible through the metadata service - or the + This information is accessible through the metadata + service or the config drive. As the OpenStack metadata service is compatible with version 2009-04-04 of the @@ -378,9 +393,10 @@ done retrieve user data. The easiest way to support this type of functionality is - to install the cloud-init package into your image, which - is configured by default to treat user data as an - executable script, and will set the host name. + to install the cloud-init package into + your image, which is configured by default to treat user + data as an executable script, and sets the host + name.
Ensure image writes boot log to console @@ -394,11 +410,12 @@ done looks something like this: linux /boot/vmlinuz-3.2.0-49-virtual root=UUID=6d2231e4-0975-4f35-a94f-56738c1a8150 ro console=ttyS0 If console=ttyS0 does not appear, you - will need to modify your grub configuration. In general, - you should not update the grub.cfg directly, since it is - automatically generated. Instead, you should edit - /etc/default/grub and modify the - value of the GRUB_CMDLINE_LINUX_DEFAULT + must modify your grub configuration. In general, you + should not update the grub.cfg + directly, since it is automatically generated. Instead, + you should edit /etc/default/grub and + modify the value of the + GRUB_CMDLINE_LINUX_DEFAULT variable: GRUB_CMDLINE_LINUX_DEFAULT="console=ttyS0" Next, update the grub configuration. On Debian-based @@ -417,8 +434,8 @@ done guests). If you are running the Xen hypervisor with paravirtualization, and you want to create an image for an older Linux distribution that has a pre 3.0 kernel, you - will need to ensure that the image boots a kernel that has - been compiled with Xen support. + must ensure that the image boots a kernel that has been + compiled with Xen support.
Manage the image cache @@ -429,8 +446,8 @@ done compute nodes share one common /var/lib/nova/instances/ directory. - For information about libvirt images in OpenStack, refer - to For information about libvirt images in OpenStack, see + The life of an OpenStack libvirt image from Pádraig Brady. @@ -448,18 +465,29 @@ done preallocate_images=none - (StrOpt) VM image preallocation mode: "none" - => no storage provisioning is done up - front, "space" => storage is fully - allocated at instance start. If this is set to - 'space', the $instance_dir/ images will be  - fallocated to immediately - determine if enough space is available, and to - possibly improve VM I/O performance due to - ongoing allocation avoidance, and better - locality of block allocations. + (StrOpt) VM image preallocation + mode: + + none. No + storage provisioning occurs up + front. + + + space. + Storage is fully allocated at + instance start. The + $instance_dir/ + images are fallocated to immediately + determine if enough space is + available, and to possibly improve + VM I/O performance due to ongoing + allocation avoidance, and better + locality of block + allocations. + + remove_unused_base_images=True @@ -472,13 +500,13 @@ done remove_unused_original_minimum_age_seconds=86400 (IntOpt) Unused unresized base images younger - than this will not be removed. Default is - 86400 seconds, or 24 hours. + than this are not removed. Default is 86400 + seconds, or 24 hours. remove_unused_resized_minimum_age_seconds=3600 (IntOpt) Unused resized base images younger - than this will not be removed. Default is 3600 + than this are not removed. Default is 3600 seconds, or one hour. @@ -494,7 +522,7 @@ a0d1d5d3_20 2012-02-18 04:24:17 41389 INFO nova.virt.libvirt.imagecache [-] Removable base files: /var/lib/nova/instances/_base/06a057b9c7b0b27e3b496f53d1e88810 a0d1d5d3 /var/lib/nova/instances/_base/06a057b9c7b0b27e3b496f53d1e88810a0d1d5d3_20 2012-02-18 04:24:17 41389 INFO nova.virt.libvirt.imagecache [-] Removing base file: /var/lib/nova/instances/_base/06a057b9c7b0b27e3b496f53d1e88810a0d1d5d3 - Since 86400 seconds (24 hours) is the default time for + Because 86400 seconds (24 hours) is the default time for remove_unused_original_minimum_age_seconds, you can either wait for that time interval to see the base image removed, or set the value to a shorter time period