Merge "[image-guide] Convert OpenStack images to RST"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
a106988d4a
@ -1,3 +1,405 @@
|
||||
==================================
|
||||
OpenStack Linux image requirements
|
||||
==================================
|
||||
|
||||
For a Linux-based image to have full functionality in an
|
||||
OpenStack Compute cloud, there are a few requirements.
|
||||
For some of these, you can fulfill the requirements by installing the
|
||||
`cloud-init <https://cloudinit.readthedocs.org/en/latest/>`_ package.
|
||||
Read this section before you create your own image to be sure that
|
||||
the image supports the OpenStack features that you plan to use.
|
||||
|
||||
* 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 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 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: one ext3/ext4 partition (no LVM)
|
||||
-------------------------------------
|
||||
|
||||
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: one ext3/ext4 partition (no LVM)
|
||||
---------------------------------------------------------------------
|
||||
|
||||
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 is to install in your image the:
|
||||
|
||||
* `cloud-utils <https://launchpad.net/cloud-utils>`_ package,
|
||||
which contains the ``growpart`` tool for extending partitions.
|
||||
* `cloud-initramfs-growroot <https://launchpad.net/cloud-initramfs-tools>`_
|
||||
package for Ubuntu, Debian and Fedora, which supports resizing
|
||||
root partition on the first boot.
|
||||
* ``cloud-initramfs-growroot`` package for CentOS and RHEL.
|
||||
* `cloud-init <https://launchpad.net/cloud-init>`__ package.
|
||||
|
||||
With these packages 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
|
||||
<https://github.com/flegmatik/linux-rootfs-resize>`_
|
||||
that contains scripts 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 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 the output of
|
||||
``parted /dev/sda --script "print free"``.
|
||||
#. Create a new LVM partition with the additional space.
|
||||
For example, ``parted /dev/sda --script "mkpart lvm ..."``.
|
||||
#. Create a new physical volume. For example, ``pvcreate /dev/sda6``.
|
||||
#. Extend the volume group with this physical partition.
|
||||
For example, ``vgextend vg00 /dev/sda6``.
|
||||
#. Extend the logical volume contained the root partition by
|
||||
the amount of space. For example,
|
||||
``lvextend /dev/mapper/node-root /dev/sda6``.
|
||||
#. Resize the root file system. For example,
|
||||
``resize2fs /dev/mapper/node-root``.
|
||||
|
||||
You do not need a ``/boot`` partition unless your image is an older
|
||||
Linux distribution that requires that ``/boot`` is not managed by LVM.
|
||||
|
||||
No hard-coded MAC address information
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must remove the network persistence rules in the
|
||||
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 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.
|
||||
|
||||
.. note::
|
||||
|
||||
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 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
|
||||
inside of your image and use OpenStack security groups to
|
||||
restrict access to instances.
|
||||
The reason is that having a firewall installed on your
|
||||
instance can make it more difficult to troubleshoot
|
||||
networking issues if you cannot connect to your instance.
|
||||
|
||||
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 authentication.
|
||||
For this to work, your virtual machine image must be configured
|
||||
to download the ssh public key from the OpenStack metadata
|
||||
service or config drive, at boot time.
|
||||
|
||||
If both the XenAPI agent and ``cloud-init`` are present
|
||||
in an image, ``cloud-init`` handles ssh-key injection.
|
||||
The system assumes ``cloud-init`` is present when the image
|
||||
has the ``cloud_init_installed`` property.
|
||||
|
||||
Use cloud-init 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 ``/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:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
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.
|
||||
|
||||
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 "touch /var/lock/subsys/local".
|
||||
This code fragment is taken from the
|
||||
`rackerjoe oz-image-build CentOS 6 template <https://github.com/
|
||||
rackerjoe/oz-image-build/blob/master/templates/centos60_x86_64.tdl>`_.
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
if [ ! -d /root/.ssh ]; then
|
||||
mkdir -p /root/.ssh
|
||||
chmod 700 /root/.ssh
|
||||
fi
|
||||
|
||||
# Fetch public key using HTTP
|
||||
ATTEMPTS=30
|
||||
FAILED=0
|
||||
while [ ! -f /root/.ssh/authorized_keys ]; do
|
||||
curl -f http://169.254.169.254/latest/meta-data/public-keys/0/openssh-key > /tmp/metadata-key 2>/dev/null
|
||||
if [ $? -eq 0 ]; then
|
||||
cat /tmp/metadata-key >> /root/.ssh/authorized_keys
|
||||
chmod 0600 /root/.ssh/authorized_keys
|
||||
restorecon /root/.ssh/authorized_keys
|
||||
rm -f /tmp/metadata-key
|
||||
echo "Successfully retrieved public key from instance metadata"
|
||||
echo "*****************"
|
||||
echo "AUTHORIZED KEYS"
|
||||
echo "*****************"
|
||||
cat /root/.ssh/authorized_keys
|
||||
echo "*****************"
|
||||
else
|
||||
FAILED=`expr $FAILED + 1`
|
||||
if [ $FAILED -ge $ATTEMPTS ]; then
|
||||
echo "Failed to retrieve public key from instance metadata after $FAILED attempts, quitting"
|
||||
break
|
||||
fi
|
||||
echo "Could not retrieve public key from instance metadata (attempt #$FAILED/$ATTEMPTS), retrying in 5 seconds..."
|
||||
sleep 5
|
||||
fi
|
||||
done
|
||||
|
||||
.. note::
|
||||
|
||||
Some VNC clients replace : (colon) with ; (semicolon) and
|
||||
_ (underscore) with - (hyphen).
|
||||
If editing a file over a VNC session, make sure it is
|
||||
http: not http; and authorized_keys not authorized-keys.
|
||||
|
||||
Process user data and other metadata (cloud-init)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
In addition to the ssh public key, an image might need
|
||||
additional information from OpenStack, such as
|
||||
`Provide user data to instances <http://docs.openstack.org/
|
||||
user-guide/cli_provide_user_data_to_instances.html>`_,
|
||||
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.
|
||||
|
||||
You can access this information through the metadata
|
||||
service or referring to `Store metadata on the configuration drive
|
||||
<http://docs.openstack.org/user-guide/cli_config_drive.html>`_.
|
||||
As the OpenStack metadata service is compatible with version
|
||||
2009-04-04 of the Amazon EC2 metadata service, consult the
|
||||
Amazon EC2 documentation on
|
||||
`Using Instance Metadata <http://docs.amazonwebservices.com/
|
||||
AWSEC2/2009-04-04/UserGuide/AESDG-chapter-instancedata.html>`_
|
||||
for details on how to 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 sets the host name.
|
||||
|
||||
Ensure image writes boot log to console
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You must configure the image so that the kernel writes
|
||||
the boot log to the ``ttyS0`` device. In particular, the
|
||||
``console=ttyS0`` argument must be passed to the kernel on boot.
|
||||
|
||||
If your image uses grub2 as the boot loader,
|
||||
there should be a line in the grub configuration file.
|
||||
For example, ``/boot/grub/grub.cfg``, which 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 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:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
GRUB_CMDLINE_LINUX_DEFAULT="console=ttyS0"
|
||||
|
||||
Next, update the grub configuration. On Debian-based
|
||||
operating-systems such as Ubuntu, run this command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# update-grub
|
||||
|
||||
On Fedora-based systems, such as RHEL and CentOS,
|
||||
and on openSUSE, run this command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# grub2-mkconfig -o /boot/grub2/grub.cfg
|
||||
|
||||
Paravirtualized Xen support in the kernel (Xen hypervisor only)
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Prior to Linux kernel version 3.0, the mainline branch of
|
||||
the Linux kernel did not have support for paravirtualized
|
||||
Xen virtual machine instances (what Xen calls DomU 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 must ensure that the image
|
||||
boots a kernel that has been compiled with Xen support.
|
||||
|
||||
Manage the image cache
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Use options in ``nova.conf`` to control whether, and for how long,
|
||||
unused base images are stored in ``/var/lib/nova/instances/_base/``.
|
||||
If you have configured live migration of instances, all your compute
|
||||
nodes share one common ``/var/lib/nova/instances/`` directory.
|
||||
|
||||
For information about libvirt images in OpenStack, see
|
||||
`The life of an OpenStack libvirt image from Pádraig Brady
|
||||
<http://www.pixelbeat.org/docs/openstack_libvirt_images/>`_.
|
||||
|
||||
.. list-table:: Image cache management configuration options
|
||||
:widths: 50 50
|
||||
:header-rows: 1
|
||||
|
||||
* - Configuration option=Default value
|
||||
- (Type) Description
|
||||
* - preallocate_images=none
|
||||
- (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 <http://www.kernel.org/doc/man-pages/online/pages/man2/fallocate.2.html>`_
|
||||
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
|
||||
- (BoolOpt) Should unused base images be removed?
|
||||
When set to True, the interval at which base images are
|
||||
removed are set with the following two settings.
|
||||
If set to False base images are never removed by Compute.
|
||||
* - remove_unused_original_minimum_age_seconds=86400
|
||||
- (IntOpt) Unused unresized base images younger 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 are
|
||||
not removed. Default is 3600 seconds, or one hour.
|
||||
|
||||
To see how the settings affect the deletion of a running instance,
|
||||
check the directory where the images are stored:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
# ls -lash /var/lib/nova/instances/_base/
|
||||
|
||||
In the ``/var/log/compute/compute.log`` file, look for the identifier:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
2012-02-18 04:24:17 41389 WARNING nova.virt.libvirt.imagecache [-] Unknown base file: /var/lib/nova/instances/_base/06a057b9c7b0b27e3b496f53d1e88810a0d1d5d3_20
|
||||
2012-02-18 04:24:17 41389 INFO nova.virt.libvirt.imagecache [-] Removable base files: /var/lib/nova/instances/_base/06a057b9c7b0b27e3b496f53d1e88810a0d1d5d3 /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
|
||||
|
||||
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 in ``nova.conf``.
|
||||
Restart all nova services after changing a setting in ``nova.conf``.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user