98e7068e48
There are several instances of "Image service" in the upstream documentation. As was recently clarified in the docs mailing list, these should be "Image Service". This patch applies the fix. Change-Id: Iefb63673162ae97b2c0fe1c3ff3fb1ac05e95d83 Partial-Bug: #1217503
250 lines
12 KiB
XML
250 lines
12 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:id="ubuntu-image">
|
|
<title>Example: Ubuntu image</title>
|
|
<para>We'll run through an example of installing an Ubuntu image.
|
|
This will focus mainly on Ubuntu 12.04 (Precise Pangolin)
|
|
server. Because the Ubuntu installation process may change
|
|
across versions, if you are using a different version of
|
|
Ubuntu the installer steps may differ.</para>
|
|
<simplesect>
|
|
<title>Download an Ubuntu install ISO</title>
|
|
<para>In this example, we'll use the network installation ISO,
|
|
since it's a smaller image. The 64-bit 12.04 network
|
|
installer ISO is at <link
|
|
xlink:href="http://archive.ubuntu.com/ubuntu/dists/precise/main/installer-amd64/current/images/netboot/mini.iso"
|
|
>http://archive.ubuntu.com/ubuntu/dists/precise/main/installer-amd64/current/images/netboot/mini.iso</link></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Start the install process</title>
|
|
<para>Start the installation process using either
|
|
<command>virt-manager</command> or
|
|
<command>virt-install</command> as described in the
|
|
previous section. If using
|
|
<command>virt-install</command>, don't forget to connect
|
|
your VNC client to the virtual machine.</para>
|
|
<para>We will assume the name of your virtual machine image is
|
|
<literal>ubuntu-12.04</literal>, which we need to know
|
|
when using <command>virsh</command> commands to manipulate
|
|
the state of the image.</para>
|
|
<para>If you're using virt-manager, the commands should look
|
|
something like
|
|
this:<screen><prompt>#</prompt> <userinput>qemu-img create -f qcow2 /tmp/precise.qcow2 10G</userinput>
|
|
<prompt>#</prompt> <userinput>virt-install --virt-type kvm --name precise --ram 1024 \
|
|
--cdrom=/data/isos/precise-64-mini.iso \
|
|
--disk /tmp/precise.qcow2,format=qcow2 \
|
|
--network network=default \
|
|
--graphics vnc,listen=0.0.0.0 --noautoconsole \
|
|
--os-type=linux --os-variant=ubuntuprecise</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Step through the install</title>
|
|
<para>At the initial Installer boot menu, choose the "Install"
|
|
option. Step through the install prompts, the defaults
|
|
should be fine.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/ubuntu-install.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Hostname</title>
|
|
<para>The installer may ask you to choose a hostname. The
|
|
default (<literal>ubuntu</literal>) is fine. We will
|
|
install the cloud-init package later, which will set the
|
|
hostname on boot when a new instance is provisioned using
|
|
this image.</para>
|
|
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Select a mirror</title>
|
|
<para>The default mirror proposed by the installer should be
|
|
fine.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Step through the install</title>
|
|
<para>Step through the install, using the default options.
|
|
When prompted for a username, the default
|
|
(<literal>ubuntu</literal>) is fine.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Partition the disks</title>
|
|
<para>There are different options for partitioning the disks.
|
|
The default installation will use LVM partitions, and will
|
|
create three partitions (<filename>/boot</filename>,
|
|
<filename>/</filename>, swap), and this will work
|
|
fine. Alternatively, you may wish to create a single ext4
|
|
partition, mounted to "<literal>/</literal>", should also
|
|
work fine.</para>
|
|
<para>If unsure, we recommend you use the installer's default
|
|
partition scheme, since there is no clear advantage to one
|
|
scheme or another.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Automatic updates</title>
|
|
<para>The Ubuntu installer will ask how you want to manage
|
|
upgrades on your system. This option depends on your
|
|
specific use case. If your virtual machine instances will
|
|
be connected to the internet, we recommend "Install
|
|
security updates automatically".</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Software selection: OpenSSH server</title>
|
|
<para>Choose "OpenSSH server"so that you will be able to SSH
|
|
into the virtual machine when it launches inside of an
|
|
OpenStack cloud.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata
|
|
fileref="figures/ubuntu-software-selection.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Install GRUB boot loader</title>
|
|
<para>Select "Yes" when asked about installing the GRUB boot
|
|
loader to the master boot record.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/ubuntu-grub.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Detach the CD-ROM and reboot</title>
|
|
<para>Select the defaults for all of the remaining options.
|
|
When the installation is complete, you will be prompted to
|
|
remove the CD-ROM.</para>
|
|
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/ubuntu-finished.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
<para>
|
|
<note>
|
|
<para>When you hit "Continue" the virtual machine will
|
|
shut down, even though it says it will
|
|
reboot.</para>
|
|
</note>
|
|
</para>
|
|
|
|
<para>To eject a disk using <command>virsh</command>, libvirt
|
|
requires that you attach an empty disk at the same target
|
|
that the CDROM was previously attached, which should be
|
|
<literal>hdc</literal>. You can confirm the
|
|
appropriate target using the <command>dom dumpxml
|
|
<replaceable>vm-image</replaceable></command>
|
|
command.</para>
|
|
<screen><prompt>#</prompt> <userinput>virsh dumpxml precise</userinput>
|
|
<computeroutput><domain type='kvm'>
|
|
<name>precise</name>
|
|
...
|
|
<disk type='block' device='cdrom'>
|
|
<driver name='qemu' type='raw'/>
|
|
<target dev='hdc' bus='ide'/>
|
|
<readonly/>
|
|
<address type='drive' controller='0' bus='1' target='0' unit='0'/>
|
|
</disk>
|
|
...
|
|
</domain>
|
|
</computeroutput></screen>
|
|
|
|
<para>Run the following commands in the host as root to start
|
|
up the machine again as paused, eject the disk and resume.
|
|
If you are using virt-manager, you may use the GUI
|
|
instead.<screen><prompt>#</prompt> <userinput>virsh start precise --paused</userinput>
|
|
<prompt>#</prompt> <userinput>virsh attach-disk --type cdrom --mode readonly precise "" hdc</userinput>
|
|
<prompt>#</prompt> <userinput>virsh resume precise</userinput></screen></para>
|
|
<note>
|
|
<para>In the example above, we start the instance paused,
|
|
eject the disk, and then unpause. In theory, we could
|
|
have ejected the disk at the "Installation complete"
|
|
screen. However, our testing indicates that the Ubuntu
|
|
installer locks the drive so that it cannot be ejected
|
|
at that point.</para>
|
|
</note>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Log in to newly created image</title>
|
|
<para>When you boot for the first time after install, it may ask
|
|
you about authentication tools, you can just choose
|
|
'Exit'. Then, log in as root using the root password you
|
|
specified.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Install cloud-init</title>
|
|
<para>The <command>cloud-init</command> script starts on
|
|
instance boot and will search for a metadata provider to
|
|
fetch a public key from. The public key will be placed in
|
|
the default user account for the image.</para>
|
|
<para>Install the <package>cloud-init</package> package:</para>
|
|
<screen><prompt>#</prompt> <userinput>apt-get install cloud-init</userinput></screen>
|
|
<para>When building Ubuntu images
|
|
<command>cloud-init</command> must be explicitly
|
|
configured for the metadata source in use. The OpenStack
|
|
metadata server emulates the EC2 metadata service used by
|
|
images in Amazon EC2.</para>
|
|
<para>To set the metadata source to be used by the image run
|
|
the <command>dpkg-reconfigure</command> command against
|
|
the <package>cloud-init</package> package. When prompted
|
|
select the <literal>EC2</literal> data source:
|
|
<screen><prompt>#</prompt> <userinput>dpkg-reconfigure cloud-init</userinput></screen>
|
|
</para>
|
|
<para>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".</para>
|
|
<para>You can change the name of the account used by
|
|
cloud-init by editing the
|
|
<filename>/etc/cloud/cloud.cfg</filename> 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 config file so it has the
|
|
line:<programlisting>user: admin</programlisting></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Shut down the instance</title>
|
|
<para>From inside the instance, as
|
|
root:<screen><prompt>#</prompt> <userinput>/sbin/shutdown -h now</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Clean up (remove MAC address details)</title>
|
|
<para>The operating system records the MAC address of the
|
|
virtual ethernet card in locations such as
|
|
<filename>/etc/udev/rules.d/70-persistent-net.rules</filename>
|
|
during the instance process. However, each time the image
|
|
boots up, the virtual ethernet card will have a different
|
|
MAC address, so this information must be deleted from the
|
|
configuration file.</para>
|
|
<para>There is a utility called
|
|
<command>virt-sysprep</command>, that performs various
|
|
cleanup tasks such as removing the MAC address references.
|
|
It will clean up a virtual machine image in
|
|
place:<screen><prompt>#</prompt> <userinput>virt-sysprep -d precise</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Undefine the libvirt domain</title>
|
|
<para>Now that the image is ready to be uploaded to the Image
|
|
Service, we no longer need to have this virtual machine
|
|
image managed by libvirt. Use the <command>virsh undefine
|
|
<replaceable>vm-image</replaceable></command>
|
|
command to inform
|
|
libvirt<screen><prompt>#</prompt> <userinput>virsh undefine precise</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Image is complete</title>
|
|
<para>The underlying image file that you created with
|
|
<command>qemu-img create</command>, such as
|
|
<filename>/tmp/precise.qcow2</filename>, is now ready
|
|
for uploading to the OpenStack Image Service.</para>
|
|
</simplesect>
|
|
</section>
|