diff --git a/doc/image-guide/source/centos-image.rst b/doc/image-guide/source/create-images-manually-example-centos-image.rst similarity index 95% rename from doc/image-guide/source/centos-image.rst rename to doc/image-guide/source/create-images-manually-example-centos-image.rst index 99a9edefd9..0ada6c2957 100644 --- a/doc/image-guide/source/centos-image.rst +++ b/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 `_ 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. diff --git a/doc/image-guide/source/fedora-image.rst b/doc/image-guide/source/create-images-manually-example-fedora-image.rst similarity index 94% rename from doc/image-guide/source/fedora-image.rst rename to doc/image-guide/source/create-images-manually-example-fedora-image.rst index 70db3b4119..e9ff67ac8b 100644 --- a/doc/image-guide/source/fedora-image.rst +++ b/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 `_. @@ -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. diff --git a/doc/image-guide/source/freebsd-image.rst b/doc/image-guide/source/create-images-manually-example-freebsd-image.rst similarity index 99% rename from doc/image-guide/source/freebsd-image.rst rename to doc/image-guide/source/create-images-manually-example-freebsd-image.rst index 67f0cf1dbd..9b956deff9 100644 --- a/doc/image-guide/source/freebsd-image.rst +++ b/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: diff --git a/doc/image-guide/source/ubuntu-image.rst b/doc/image-guide/source/create-images-manually-example-ubuntu-image.rst similarity index 96% rename from doc/image-guide/source/ubuntu-image.rst rename to doc/image-guide/source/create-images-manually-example-ubuntu-image.rst index 5eec05d741..f26316ff6f 100644 --- a/doc/image-guide/source/ubuntu-image.rst +++ b/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 `_. 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 diff --git a/doc/image-guide/source/windows-image.rst b/doc/image-guide/source/create-images-manually-example-windows-image.rst similarity index 97% rename from doc/image-guide/source/windows-image.rst rename to doc/image-guide/source/create-images-manually-example-windows-image.rst index 79d3c93e21..0dbc887447 100644 --- a/doc/image-guide/source/windows-image.rst +++ b/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 diff --git a/doc/image-guide/source/virt-install.rst b/doc/image-guide/source/create-images-manually-tools-libvirt.rst similarity index 52% rename from doc/image-guide/source/virt-install.rst rename to doc/image-guide/source/create-images-manually-tools-libvirt.rst index c32365b027..5d082d301d 100644 --- a/doc/image-guide/source/virt-install.rst +++ b/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 diff --git a/doc/image-guide/source/create-images-manually.rst b/doc/image-guide/source/create-images-manually.rst index 20e9f45097..663ab2c7ea 100644 --- a/doc/image-guide/source/create-images-manually.rst +++ b/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 `_. + +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 diff --git a/doc/image-guide/source/net-running.rst b/doc/image-guide/source/net-running.rst deleted file mode 100644 index 8f6093cc4a..0000000000 --- a/doc/image-guide/source/net-running.rst +++ /dev/null @@ -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 diff --git a/doc/image-guide/source/virt-manager.rst b/doc/image-guide/source/virt-manager.rst deleted file mode 100644 index d235115c80..0000000000 --- a/doc/image-guide/source/virt-manager.rst +++ /dev/null @@ -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.