docs: review manual image creation

* Add TOCs
* Divide Examples and Tools (make it easier to add others such as VBox,
	VMware etc.)
* Merge all libvirt related content as a tool
* Modify headers as per Contributor Guide [1]
* Move pages to clarify hierarchy
Note: further work will be needed to update examples

[1] https://docs.openstack.org/doc-contrib-guide/rst-conv/titles.html

Change-Id: I78970ef578020c7df7e35ca59a1c7b8aed19bb6f

doc/image-guide/source/create-images-manually-example-centos-image.rst

@@ -7,8 +7,10 @@ mainly on CentOS 7. Because the CentOS installation process
 might differ across versions, the installation steps might
 differ if you use a different version of CentOS.
 
+.. contents:: :depth: 2
+
 Download a CentOS install ISO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 #. Navigate to the `CentOS mirrors
    <https://www.centos.org/download/mirrors/>`_ page.
@@ -24,7 +26,7 @@ Download a CentOS install ISO
    packages from the Internet during installation.
 
 Start the installation process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Start the installation process using either the :command:`virt-manager`
 or the :command:`virt-install` command as described previously.
@@ -52,7 +54,7 @@ something like this:
      --location=/data/isos/CentOS-7-x86_64-NetInstall-1611.iso
 
 Step through the installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 At the initial Installer boot menu, choose the
 :guilabel:`Install CentOS 7` option. After the installation program starts,
@@ -63,7 +65,7 @@ installation summary. Accept the defaults.
    :width: 100%
 
 Change the Ethernet status
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The default Ethernet setting is ``OFF``. Change the setting of
 the Ethernet form ``OFF`` to ``ON``. In particular, ensure that
@@ -74,7 +76,7 @@ default.
    :width: 100%
 
 Hostname
---------
+~~~~~~~~
 
 The installer allows you to choose a host name.
 The default (``localhost.localdomain``) is fine.
@@ -83,7 +85,7 @@ which sets the host name on boot when a new instance
 is provisioned using this image.
 
 Point the installer to a CentOS web server
-------------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Depending on the version of CentOS, the net installer requires
 the user to specify either a URL or the web site and
@@ -109,13 +111,13 @@ to get a full list of mirrors, click on the ``HTTP`` link
 of a mirror to retrieve the web site name of a mirror.
 
 Storage devices
----------------
+~~~~~~~~~~~~~~~
 
 If prompted about which type of devices your installation uses,
 choose :guilabel:`Virtio Block Device`.
 
 Partition the disks
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 There are different options for partitioning the disks.
 The default installation uses LVM partitions, and creates
@@ -130,19 +132,19 @@ list will allow it to grow without crossing another
 partition's boundary.
 
 Select installation option
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Step through the installation, using the default options.
 The simplest thing to do is to choose the ``Minimal Install``
 install, which installs an SSH server.
 
 Set the root password
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 During the installation, remember to set the root password when prompted.
 
 Detach the CD-ROM and reboot
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Wait until the installation is complete.
 
@@ -181,7 +183,7 @@ and reboot it by manually stopping and starting.
    # virsh reboot centos
 
 Install the ACPI service
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 To enable the hypervisor to reboot or shutdown an instance,
 you must install and run the ``acpid`` service on the guest system.
@@ -196,7 +198,7 @@ system boots:
    # systemctl enable acpid
 
 Configure to fetch metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 An instance must interact with the metadata service to perform
 several tasks on start up. For example, the instance must get
@@ -210,7 +212,7 @@ the instance performs these tasks, use one of these methods:
   the metadata service, as described in the next section.
 
 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.
@@ -237,7 +239,7 @@ syntax in the configuration file:
        (...)
 
 Install cloud-utils-growpart to allow partitions to resize
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------------
 
 In order for the root partition to properly resize, install the
 ``cloud-utils-growpart`` package, which contains the proper tools
@@ -248,7 +250,7 @@ to allow the disk to resize using cloud-init.
    # yum install cloud-utils-growpart
 
 Write a script to fetch the public key (if no cloud-init)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------------------------------------
 
 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,
@@ -303,7 +305,7 @@ before the line ``touch /var/lock/subsys/local``:
    AESDG-chapter-instancedata.html>`_ for details on how to get user data.
 
 Disable the zeroconf route
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 For the instance to access the metadata service,
 you must disable the default zeroconf route:
@@ -313,7 +315,7 @@ you must disable the default zeroconf route:
    # echo "NOZEROCONF=yes" >> /etc/sysconfig/network
 
 Configure console
-~~~~~~~~~~~~~~~~~
+-----------------
 
 For the :command:`nova console-log` command to work properly
 on CentOS 7, you might need to do the following steps:
@@ -346,7 +348,7 @@ on CentOS 7, you might need to do the following steps:
      done
 
 Shut down the instance
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 From inside the instance, run as root:
 
@@ -355,7 +357,7 @@ From inside the instance, run as root:
    # poweroff
 
 Clean up (remove MAC address details)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The operating system records the MAC address of the virtual Ethernet
 card in locations such as ``/etc/sysconfig/network-scripts/ifcfg-eth0``
@@ -372,7 +374,7 @@ It will clean up a virtual machine image in place:
    # virt-sysprep -d centos
 
 Undefine the libvirt domain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 Now that you can upload the image to the Image service, you no
 longer need to have this virtual machine image managed by libvirt.
@@ -383,7 +385,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt:
    # virsh undefine centos
 
 Image is complete
-~~~~~~~~~~~~~~~~~
+-----------------
 
 The underlying image file that you created with the
 :command:`qemu-img create` command is ready to be uploaded.

doc/image-guide/source/create-images-manually-example-fedora-image.rst

@@ -7,8 +7,10 @@ mainly on Fedora 25. Because the Fedora installation process
 might differ across versions, the installation steps might
 differ if you use a different version of Fedora.
 
+.. contents:: :depth: 2
+
 Download a Fedora install ISO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 #. Visit the `Fedora download site <https://getfedora.org/>`_.
 
@@ -23,7 +25,7 @@ Download a Fedora install ISO
    installation.
 
 Start the installation process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Start the installation process using either the :command:`virt-manager`
 or the :command:`virt-install` command as described previously.
@@ -51,19 +53,19 @@ something like this:
      --location=/tmp/Fedora-Server-netinst-x86_64-25-1.3.iso
 
 Step through the installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 After the installation program starts, choose your preferred language and click
 :guilabel:`Continue` to get to the installation summary. Accept the defaults.
 
 Review the Ethernet status
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Ensure that the Ethernet setting is ``ON``. Additionally, make sure that
 ``IPv4 Settings' Method`` is ``Automatic (DHCP)``, which is the default.
 
 Hostname
---------
+~~~~~~~~
 
 The installer allows you to choose a host name.
 The default (``localhost.localdomain``) is fine.
@@ -72,7 +74,7 @@ which sets the host name on boot when a new instance
 is provisioned using this image.
 
 Partition the disks
--------------------
+~~~~~~~~~~~~~~~~~~~
 
 There are different options for partitioning the disks.
 The default installation uses LVM partitions, and creates
@@ -87,19 +89,19 @@ list will allow it to grow without crossing another
 partition's boundary.
 
 Select software to install
---------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Step through the installation, using the default options.
 The simplest thing to do is to choose the ``Minimal Install``
 install, which installs an SSH server.
 
 Set the root password
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 During the installation, remember to set the root password when prompted.
 
 Detach the CD-ROM and reboot
-----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Wait until the installation is complete.
 
@@ -138,7 +140,7 @@ and reboot it by manually stopping and starting.
    # virsh reboot fedora
 
 Install the ACPI service
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
 
 To enable the hypervisor to reboot or shutdown an instance,
 you must install and run the ``acpid`` service on the guest system.
@@ -153,7 +155,7 @@ system boots:
    # systemctl enable acpid
 
 Configure cloud-init to fetch metadata
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------------------
 
 An instance must interact with the metadata service to perform
 several tasks on start up. For example, the instance must get
@@ -186,7 +188,7 @@ syntax in the configuration file:
        (...)
 
 Install cloud-utils-growpart to allow partitions to resize
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------------
 
 In order for the root partition to properly resize, install the
 ``cloud-utils-growpart`` package, which contains the proper tools
@@ -197,7 +199,7 @@ to allow the disk to resize using cloud-init.
    # dnf install cloud-utils-growpart
 
 Disable the zeroconf route
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
 
 For the instance to access the metadata service,
 you must disable the default zeroconf route:
@@ -207,7 +209,7 @@ you must disable the default zeroconf route:
    # echo "NOZEROCONF=yes" >> /etc/sysconfig/network
 
 Configure console
-~~~~~~~~~~~~~~~~~
+-----------------
 
 For the :command:`nova console-log` command to work properly
 on Fedora, you might need to do the following steps:
@@ -235,7 +237,7 @@ on Fedora, you might need to do the following steps:
      done
 
 Shut down the instance
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 From inside the instance, run as root:
 
@@ -244,7 +246,7 @@ From inside the instance, run as root:
    # poweroff
 
 Clean up (remove MAC address details)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The operating system records the MAC address of the virtual Ethernet
 card in locations such as ``/etc/sysconfig/network-scripts/ifcfg-eth0``
@@ -261,7 +263,7 @@ It will clean up a virtual machine image in place:
    # virt-sysprep -d fedora
 
 Undefine the libvirt domain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 Now that you can upload the image to the Image service, you no
 longer need to have this virtual machine image managed by libvirt.
@@ -272,7 +274,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt:
    # virsh undefine fedora
 
 Image is complete
-~~~~~~~~~~~~~~~~~
+-----------------
 
 The underlying image file that you created with the
 :command:`qemu-img create` command is ready to be uploaded.

doc/image-guide/source/create-images-manually-example-freebsd-image.rst

@@ -17,7 +17,10 @@ use that same platform in the image creation step.
 This example shows how to create a FreeBSD 10 image. To create
 a FreeBSD 9.2 image, follow these steps with the noted differences.
 
-**To create a FreeBSD image**
+.. contents:: :depth: 2
+
+Prerequisites
+-------------
 
 #. Make a virtual drive:
 
@@ -71,6 +74,9 @@ a FreeBSD 9.2 image, follow these steps with the noted differences.
    You now have a VM that boots from the downloaded install ISO and
    is connected to the blank virtual disk that you created previously.
 
+Installation
+------------
+
 #. To install the operating system, complete the following
    steps inside the VM:
 

doc/image-guide/source/create-images-manually-example-ubuntu-image.rst

@@ -6,8 +6,10 @@ This example installs an Ubuntu 18.04 (Bionic Beaver) image.
 To create an image for a different version of Ubuntu,
 follow these steps with the noted differences.
 
+.. contents:: :depth: 2
+
 Download an Ubuntu installation ISO
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
 
 Because the goal is to make the smallest possible base image,
 this example uses the network installation ISO.
@@ -15,7 +17,7 @@ The Ubuntu 64-bit 18.04 network installation ISO is at the `Ubuntu download
 page <http://archive.ubuntu.com/ubuntu/dists/bionic/main/installer-amd64/current/images/netboot/mini.iso>`_.
 
 Start the installation process
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------
 
 Start the installation process by using either :command:`virt-manager`
 or :command:`virt-install` as described in the previous section.
@@ -44,7 +46,7 @@ the commands should look something like this:
      --os-type=linux --os-variant=ubuntu18.04
 
 Step through the installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 At the initial Installer boot menu, choose the :guilabel:`Install` option.
 Step through the installation prompts, the defaults should be fine.
@@ -112,14 +114,14 @@ For more information on configuring Grub, see the section
 called ":ref:`write-to-console`".
 
 Log in to newly created image
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------
 
 When you boot for the first time after install, it may ask
 you about authentication tools, you can just choose :guilabel:`Exit`.
 Then, log in as admin user using the password you specified.
 
 Install cloud-init
-~~~~~~~~~~~~~~~~~~
+------------------
 
 The :command:`cloud-init` script starts on instance boot and
 will search for a metadata provider to fetch a public key from.
@@ -161,7 +163,7 @@ syntax in the configuration file:
        (...)
 
 Shut down the instance
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
 
 From inside the instance, as root:
 
@@ -170,7 +172,7 @@ From inside the instance, as root:
    # /sbin/shutdown -h now
 
 Clean up (remove MAC address details)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------
 
 The operating system records the MAC address of the virtual Ethernet
 card in locations such as ``/etc/udev/rules.d/70-persistent-net.rules``
@@ -187,7 +189,7 @@ It will clean up a virtual machine image in place:
    # virt-sysprep -d bionic
 
 Undefine the libvirt domain
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
 
 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.
@@ -198,7 +200,7 @@ Use the :command:`virsh undefine vm-image` command to inform libvirt:
    # virsh undefine bionic
 
 Image is complete
-~~~~~~~~~~~~~~~~~
+-----------------
 
 The underlying image file that you created with the
 :command:`qemu-img create` command, such as

doc/image-guide/source/create-images-manually-example-windows-image.rst

@@ -2,9 +2,14 @@
 Example: Microsoft Windows image
 ================================
 
+.. contents:: :depth: 2
+
 This example creates a Windows Server 2012 qcow2 image,
 using the :command:`virt-install` command and the KVM hypervisor.
 
+Prerequisites
+-------------
+
 #. Follow these steps to prepare the installation:
 
    #. Download a Windows Server 2012 installation ISO.
@@ -19,6 +24,9 @@ using the :command:`virt-install` command and the KVM hypervisor.
 
          $ qemu-img create -f qcow2 ws2012.qcow2 15G
 
+Installation
+------------
+
 #. Start the Windows Server 2012 installation with the
    :command:`virt-install` command:
 
@@ -94,6 +102,9 @@ using the :command:`virt-install` command and the KVM hypervisor.
 
    Wait for the machine shutdown.
 
+Image ready
+-----------
+
 Your image is ready to upload to the Image service:
 
 .. code-block:: console

doc/image-guide/source/create-images-manually-tools-libvirt.rst

@@ -1,6 +1,93 @@
-========================================================
+=====================================
+Tools: libvirt and virsh/virt-manager
+=====================================
+
+.. contents:: :depth: 3
+
+Prerequisites
+-------------
+
+Verify the libvirt default network is running
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Before starting a virtual machine with libvirt, verify
+that the libvirt ``default`` network has started.
+This network must be active for your virtual machine
+to be able to connect out to the network.
+Starting this network will create a Linux bridge (usually
+called ``virbr0``), iptables rules, and a dnsmasq process
+that will serve as a DHCP server.
+
+To verify that the libvirt ``default`` network is enabled,
+use the :command:`virsh net-list` command and verify
+that the ``default`` network is active:
+
+.. code-block:: console
+
+   # virsh net-list
+   Name                 State      Autostart
+   -----------------------------------------
+   default              active     yes
+
+If the network is not active, start it by doing:
+
+.. code-block:: console
+
+   # virsh net-start default
+
+Use the virt-manager X11 GUI
+----------------------------
+
+If you plan to create a virtual machine image on a machine that
+can run X11 applications, the simplest way to do so is to use
+the :command:`virt-manager` GUI, which is installable as the
+``virt-manager`` package on both Fedora-based and Debian-based systems.
+This GUI has an embedded VNC client that will let you view and
+interact with the guest's graphical console.
+
+If you are building the image on a headless server, and
+you have an X server on your local machine, you can launch
+:command:`virt-manager` using ssh X11 forwarding to access the GUI.
+Since virt-manager interacts directly with libvirt, you typically
+need to be root to access it. If you can ssh directly in as root
+(or with a user that has permissions to interact with libvirt), do:
+
+.. code-block:: console
+
+   $ ssh -X root@server virt-manager
+
+If the account you use to ssh into your server does not have
+permissions to run libvirt, but has sudo privileges, do:
+
+.. code-block:: console
+
+   $ ssh -X user@server
+   $ sudo virt-manager
+
+.. note::
+
+   The ``-X`` flag passed to ssh will enable X11 forwarding over ssh.
+   If this does not work, try replacing it with the ``-Y`` flag.
+
+Click the :guilabel:`Create a new virtual machine` button at the top-left,
+or go to :menuselection:`File --> New Virtual Machine`. Then, follow the
+instructions.
+
+.. figure:: figures/virt-manager.png
+   :width: 100%
+
+You will be shown a series of dialog boxes that will allow you
+to specify information about the virtual machine.
+
+.. note::
+
+   When using qcow2 format images, you should check the option
+   ``Customize configuration before install``, go to disk properties and
+   explicitly select the :guilabel:`qcow2` format.
+   This ensures the virtual machine disk size will be correct.
+
 Use virt-install and connect by using a local VNC client
-========================================================
+--------------------------------------------------------
 
 If you do not wish to use :command:`virt-manager` (for example,
 you do not want to install the dependencies on your server, you do

doc/image-guide/source/create-images-manually.rst

@@ -2,18 +2,6 @@
 Create images manually
 ======================
 
-.. toctree::
-   :maxdepth: 1
-
-   net-running.rst
-   virt-manager.rst
-   virt-install.rst
-   centos-image.rst
-   ubuntu-image.rst
-   fedora-image.rst
-   windows-image.rst
-   freebsd-image.rst
-
 Creating a new image is a step done outside of your
 OpenStack installation. You create the new image manually on
 your own system and then upload the image to your cloud.
@@ -39,3 +27,23 @@ to find a VNC client that works on your local desktop.
 To create an image for the Database service,
 see `Building Guest Images for OpenStack Trove
 <https://docs.openstack.org/trove/latest/admin/building_guest_images.html>`_.
+
+Tools
+-----
+
+.. toctree::
+   :maxdepth: 1
+
+   create-images-manually-tools-libvirt.rst
+
+Examples
+--------
+
+.. toctree::
+   :maxdepth: 1
+
+   create-images-manually-example-centos-image.rst
+   create-images-manually-example-fedora-image.rst
+   create-images-manually-example-freebsd-image.rst
+   create-images-manually-example-windows-image.rst
+   create-images-manually-example-ubuntu-image.rst

doc/image-guide/source/net-running.rst

@@ -1,28 +0,0 @@
-=============================================
-Verify the libvirt default network is running
-=============================================
-
-Before starting a virtual machine with libvirt, verify
-that the libvirt ``default`` network has started.
-This network must be active for your virtual machine
-to be able to connect out to the network.
-Starting this network will create a Linux bridge (usually
-called ``virbr0``), iptables rules, and a dnsmasq process
-that will serve as a DHCP server.
-
-To verify that the libvirt ``default`` network is enabled,
-use the :command:`virsh net-list` command and verify
-that the ``default`` network is active:
-
-.. code-block:: console
-
-   # virsh net-list
-   Name                 State      Autostart
-   -----------------------------------------
-   default              active     yes
-
-If the network is not active, start it by doing:
-
-.. code-block:: console
-
-   # virsh net-start default

doc/image-guide/source/virt-manager.rst

@@ -1,51 +0,0 @@
-============================
-Use the virt-manager X11 GUI
-============================
-
-If you plan to create a virtual machine image on a machine that
-can run X11 applications, the simplest way to do so is to use
-the :command:`virt-manager` GUI, which is installable as the
-``virt-manager`` package on both Fedora-based and Debian-based systems.
-This GUI has an embedded VNC client that will let you view and
-interact with the guest's graphical console.
-
-If you are building the image on a headless server, and
-you have an X server on your local machine, you can launch
-:command:`virt-manager` using ssh X11 forwarding to access the GUI.
-Since virt-manager interacts directly with libvirt, you typically
-need to be root to access it. If you can ssh directly in as root
-(or with a user that has permissions to interact with libvirt), do:
-
-.. code-block:: console
-
-   $ ssh -X root@server virt-manager
-
-If the account you use to ssh into your server does not have
-permissions to run libvirt, but has sudo privileges, do:
-
-.. code-block:: console
-
-   $ ssh -X user@server
-   $ sudo virt-manager
-
-.. note::
-
-   The ``-X`` flag passed to ssh will enable X11 forwarding over ssh.
-   If this does not work, try replacing it with the ``-Y`` flag.
-
-Click the :guilabel:`Create a new virtual machine` button at the top-left,
-or go to :menuselection:`File --> New Virtual Machine`. Then, follow the
-instructions.
-
-.. figure:: figures/virt-manager.png
-   :width: 100%
-
-You will be shown a series of dialog boxes that will allow you
-to specify information about the virtual machine.
-
-.. note::
-
-   When using qcow2 format images, you should check the option
-   ``Customize configuration before install``, go to disk properties and
-   explicitly select the :guilabel:`qcow2` format.
-   This ensures the virtual machine disk size will be correct.