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
386 lines
18 KiB
XML
386 lines
18 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="centos-image">
|
|
<title>Example: CentOS image</title>
|
|
<para>We'll run through an example of installing a CentOS image.
|
|
This will focus mainly on CentOS 6.4. Because the CentOS
|
|
installation process may change across versions, if you are
|
|
using a different version of CentOS the installer steps may
|
|
differ.</para>
|
|
<simplesect>
|
|
<title>Download a CentOS install ISO</title>
|
|
<para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Navigate to the <link
|
|
xlink:href="http://www.centos.org/modules/tinycontent/index.php?id=30"
|
|
>CentOS mirrors</link> page.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Click one of the <literal>HTTP</literal>
|
|
links in the right-hand column next to one of
|
|
the mirrors.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Click the folder link of the CentOS version
|
|
you want to use. For example,
|
|
<literal>6.4/</literal>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Click the <literal>isos/</literal> folder
|
|
link.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Click the <literal>x86_64/</literal> folder
|
|
link for 64-bit images.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Click the ISO image you want to download.
|
|
The netinstall ISO. For example,
|
|
<filename>CentOS-6.4-x86_64-netinstall.iso</filename>
|
|
is a good choice since it's a smaller image
|
|
that will download missing packages from the
|
|
Internet during the install process.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</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>centos-6.4</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/centos-6.4.qcow2 10G</userinput>
|
|
<prompt>#</prompt> <userinput>virt-install --virt-type kvm --name centos-6.4 --ram 1024 \
|
|
--cdrom=/data/isos/CentOS-6.4-x86_64-netinstall.iso \
|
|
--disk /tmp/centos-6.4.qcow2,format=qcow2 \
|
|
--network network=default \
|
|
--graphics vnc,listen=0.0.0.0 --noautoconsole \
|
|
--os-type=linux --os-variant=rhel6</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Step through the install</title>
|
|
<para>At the initial Installer boot menu, choose the "Install
|
|
or upgrade an existing system" option. Step through the
|
|
install prompts, the defaults should be fine.</para>
|
|
<mediaobject>
|
|
<imageobject role="fo">
|
|
<imagedata fileref="figures/centos-install.png"
|
|
format="PNG" scale="60"/>
|
|
</imageobject>
|
|
<imageobject role="html">
|
|
<imagedata fileref="figures/centos-install.png"
|
|
format="PNG"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Configure TCP/IP</title>
|
|
<para>The default TCP/IP settings are fine. In particular,
|
|
ensure that Enable IPv4 support is enabled with DHCP,
|
|
which is the default.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/centos-tcpip.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Point the installer to a CentOS web server</title>
|
|
<para>Choose URL as the installation method.</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/install-method.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
<para>Depending on the version of CentOS, the net installer
|
|
requires that the user specify either a URL, or the web
|
|
site and a CentOS directory that corresponds to one of the
|
|
CentOS mirrors. If the installer asks for a single URL, an
|
|
example of a valid URL would be:
|
|
<literal>http://mirror.umd/centos/6/os/x86_64</literal>.<note>
|
|
<para>Consider using other mirrors as an alternative
|
|
to mirror.umd.edu.</para>
|
|
</note></para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/url-setup.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<para>If the installer asks for web site name and CentOS
|
|
directory separately, an example would be:</para>
|
|
<para>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Web site name:
|
|
<literal>mirror.umd.edu</literal>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>CentOS directory:
|
|
<literal>centos/6/os/x86_64</literal></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
<para>See <link
|
|
xlink:href="http://www.centos.org/modules/tinycontent/index.php?id=30"
|
|
>CentOS mirror page</link> to get a full list of
|
|
mirrors, click on the "HTTP" link of a mirror to retrieve
|
|
the web site name of a mirror.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Storage devices</title>
|
|
<para>If asked about what type of devices your installation
|
|
involves, choose "Basic Storage Devices".</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Hostname</title>
|
|
<para>The installer may ask you to choose a hostname. The
|
|
default (<literal>localhost.localdomain</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>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>Step through the install</title>
|
|
<para>Step through the install, using the default options. The
|
|
simplest thing to do is to choose the "Basic Server"
|
|
install (may be called "Server" install on older versions
|
|
of CentOS), which will install an SSH server.</para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Detach the CD-ROM and reboot</title>
|
|
<para>Once the install completes, you will see the screen
|
|
"Congratulations, your CentOS installation is
|
|
complete".</para>
|
|
<mediaobject>
|
|
<imageobject>
|
|
<imagedata fileref="figures/centos-complete.png"
|
|
format="PNG" contentwidth="6in"/>
|
|
</imageobject>
|
|
</mediaobject>
|
|
|
|
<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 centos-6.4</userinput>
|
|
<computeroutput><domain type='kvm'>
|
|
<name>centos-6.4</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 from the host to eject the
|
|
disk and reboot using virsh, as root. If you are using
|
|
virt-manager, the commands below will work, but you can
|
|
also use the GUI to detach and reboot it by manually
|
|
stopping and
|
|
starting.<screen><prompt>#</prompt> <userinput>virsh attach-disk --type cdrom --mode readonly centos-6.4 "" hdc</userinput>
|
|
<prompt>#</prompt> <userinput>virsh destroy centos-6.4</userinput>
|
|
<prompt>#</prompt> <userinput>virsh start centos-6.4</userinput></screen></para>
|
|
<note>
|
|
<para>In theory, the <command>virsh reboot
|
|
centos-6.4</command> command can be used instead
|
|
of using destroy and start commands. However, in our
|
|
testing we were unable to reboot successfully using
|
|
the <command>virsh reboot</command> command.</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>Configure to fetch metadata</title>
|
|
<para>An instance must perform several steps on start up by
|
|
interacting with the metadata service. For example,
|
|
retrieve ssh public key and execute user data script.
|
|
There are several ways to implement this functionality, including:<itemizedlist>
|
|
<listitem>
|
|
<para>Install a cloud-init RPM, which is a port of
|
|
the Ubuntu <link
|
|
xlink:href="https://launchpad.net/cloud-init"
|
|
>cloud-init</link> package. This is the
|
|
recommended approach.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>Modify <filename>/etc/rc.local</filename> to
|
|
fetch desired information from the metadata
|
|
service, as described below.</para>
|
|
</listitem>
|
|
</itemizedlist></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Use cloud-init to fetch the public key</title>
|
|
<para>The cloud-init package will automatically fetch the
|
|
public key from the metadata server and place the key in
|
|
an account. You can install cloud-init inside the CentOS
|
|
guest by adding the EPEL
|
|
repo:<screen><prompt>#</prompt> <userinput>rpm -Uvh http://download.fedoraproject.org/pub/epel/6/x86_64/epel-release-6-8.noarch.rpm</userinput>
|
|
<prompt>#</prompt> <userinput>yum install 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
|
|
<literal>admin</literal>, edit the configuration file
|
|
so it has the line:</para>
|
|
<programlisting>user: admin</programlisting>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Write a script to fetch the public key (if no
|
|
cloud-init)</title>
|
|
<para>If you are not able to install the cloud-init package in
|
|
your image, to fetch the ssh public key and add it to the
|
|
root account, edit the <filename>/etc/rc.local</filename>
|
|
file and add the following lines before the line
|
|
“<literal>touch
|
|
/var/lock/subsys/local</literal>”</para>
|
|
<programlisting language="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 "*****************"
|
|
done</programlisting>
|
|
<note>
|
|
<para>Some VNC clients replace : (colon) with ;
|
|
(semicolon) and _ (underscore) with - (hyphen). Make
|
|
sure it's http: not http; and authorized_keys not
|
|
authorized-keys.</para>
|
|
</note>
|
|
<note>
|
|
<para>The above script only retrieves the ssh public key
|
|
from the metadata server. It does not retrieve
|
|
<emphasis role="italic">user data</emphasis>,
|
|
which is optional data that can be passed by the user
|
|
when requesting a new instance. User data is often
|
|
used for running a custom script when an instance
|
|
comes up.</para>
|
|
<para>As the OpenStack metadata service is compatible with
|
|
version 2009-04-04 of the Amazon EC2 metadata service,
|
|
consult the Amazon EC2 documentation on <link
|
|
xlink:href="http://docs.amazonwebservices.com/AWSEC2/2009-04-04/UserGuide/AESDG-chapter-instancedata.html"
|
|
>Using Instance Metadata</link> for details on how
|
|
to retrieve user data.</para>
|
|
</note>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Disable the zeroconf route</title>
|
|
<para>In order for the instance to access the metadata service, disable
|
|
the default zeroconf route:</para>
|
|
<screen><prompt>#</prompt> <userinput>echo "NOZEROCONF=yes" >> /etc/sysconfig/network</userinput></screen>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Configure console</title>
|
|
<para>In order for <command>nova console-log</command> to work
|
|
properly on CentOS 6.x, guests you may need to add the
|
|
following lines to
|
|
<filename>/boot/grub/menu.lst</filename><programlisting>serial --unit=0 --speed=115200
|
|
terminal --timeout=10 console serial
|
|
# Edit the kernel line to add the console entries
|
|
kernel <replaceable>...</replaceable> console=tty0 console=ttyS0,115200n8</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/sysconfig/network-scripts/ifcfg-eth0</filename>
|
|
and
|
|
<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 centos-6.4</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, you 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 centos-6.4</userinput></screen></para>
|
|
</simplesect>
|
|
<simplesect>
|
|
<title>Image is complete</title>
|
|
<para>The underlying image file you created with
|
|
<command>qemu-img create</command>. For example,
|
|
<filename>/tmp/centos-6.4.qcow2</filename> is now
|
|
ready for uploading to the OpenStack Image Service.</para>
|
|
</simplesect>
|
|
</section>
|