From f2418d75fa2e8322378cf78409dd6da636a96ab6 Mon Sep 17 00:00:00 2001 From: Dmitry Tantsur Date: Tue, 3 Mar 2020 11:26:51 +0100 Subject: [PATCH] Docs: split away user image building and highlight whole disk images The user image documentation applies to both standalone and glance usage, but we keep it in the glance section. This change creates a new page to talk about user images. We also don't emphasize the difference between partition and whole disk images enough, resulting in users trying whole disk images with kernel/ramdisk set. Make the difference clearer. Conflicts: doc/source/install/standalone.rst Change-Id: I7185679203e0f9aa7ebe9c69971009cd59271b89 (cherry picked from commit 530ec9d0b133fad5c05ebf988320394358fe4ff4) --- .../install/configure-glance-images.rst | 69 ++++--------------- doc/source/install/creating-images.rst | 65 +++++++++++++++++ doc/source/install/index.rst | 3 +- doc/source/install/standalone.rst | 11 ++- 4 files changed, 91 insertions(+), 57 deletions(-) create mode 100644 doc/source/install/creating-images.rst diff --git a/doc/source/install/configure-glance-images.rst b/doc/source/install/configure-glance-images.rst index f5a373de13..67d18aaa66 100644 --- a/doc/source/install/configure-glance-images.rst +++ b/doc/source/install/configure-glance-images.rst @@ -1,54 +1,9 @@ .. _image-requirements: -Create and add images to the Image service -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Add images to the Image service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Bare Metal provisioning requires two sets of images: the deploy images -and the user images. The deploy images are used by the Bare Metal service -to prepare the bare metal server for actual OS deployment. Whereas the -user images are installed on the bare metal server to be used by the -end user. Below are the steps to create the required images and add -them to the Image service: - -#. Build the user images - - The `disk-image-builder`_ can be used to create user images required for - deployment and the actual OS which the user is going to run. - - .. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/ - - - Install diskimage-builder package (use virtualenv, if you don't - want to install anything globally): - - .. code-block:: console - - # pip install diskimage-builder - - - Build the image your users will run (Ubuntu image has been taken as - an example): - - - Partition images - - .. code-block:: console - - $ disk-image-create ubuntu baremetal dhcp-all-interfaces grub2 -o my-image - - - - Whole disk images - - .. code-block:: console - - $ disk-image-create ubuntu vm dhcp-all-interfaces -o my-image - - The partition image command creates ``my-image.qcow2``, - ``my-image.vmlinuz`` and ``my-image.initrd`` files. The ``grub2`` element - in the partition image creation command is only needed if local boot will - be used to deploy ``my-image.qcow2``, otherwise the images - ``my-image.vmlinuz`` and ``my-image.initrd`` will be used for PXE booting - after deploying the bare metal with ``my-image.qcow2``. - - If you want to use Fedora image, replace ``ubuntu`` with ``fedora`` in the - chosen command. +#. Build or download the user images as described in :doc:`creating-images`. #. Add the user images to the Image service @@ -56,6 +11,8 @@ them to the Image service: and note the image UUIDs in the Image service for each one as it is generated. + For *partition images*: + - Add the kernel and ramdisk images to the Image service: .. code-block:: console @@ -84,14 +41,18 @@ them to the Image service: kernel_id=$MY_VMLINUZ_UUID --property \ ramdisk_id=$MY_INITRD_UUID --file my-image.qcow2 - .. note:: To deploy a whole disk image, a kernel_id and a ramdisk_id - shouldn't be associated with the image. For example, + For *whole disk images*, skip uploading and configuring kernel and ramdisk + images completely, proceed directly to uploading the main image: - .. code-block:: console + .. code-block:: console - $ openstack image create my-whole-disk-image --public \ - --disk-format qcow2 --container-format bare \ - --file my-whole-disk-image.qcow2 + $ openstack image create my-whole-disk-image --public \ + --disk-format qcow2 --container-format bare \ + --file my-whole-disk-image.qcow2 + + .. warning:: + The kernel/initramfs pair must not be set for whole disk images, + otherwise they'll be mistaken for partition images. #. Build or download the deploy images diff --git a/doc/source/install/creating-images.rst b/doc/source/install/creating-images.rst new file mode 100644 index 0000000000..f6155142f6 --- /dev/null +++ b/doc/source/install/creating-images.rst @@ -0,0 +1,65 @@ +Create user images for the Bare Metal service +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Bare Metal provisioning requires two sets of images: the deploy images +and the user images. The :ref:`deploy images ` are used by the +Bare Metal service to prepare the bare metal server for actual OS deployment. +Whereas the user images are installed on the bare metal server to be used by +the end user. There are two types of user images: + +*partition images* + contain only the contents of the root partition. Additionally, two more + images are used together with them: an image with a kernel and with + an initramfs. + + .. warning:: + To use partition images with local boot, Grub2 must be installed on + them. + +*whole disk images* + contain a complete partition table with one or more partitions. + + .. warning:: + The kernel/initramfs pair must not be used with whole disk images, + otherwise they'll be mistaken for partition images. + +Building user images +^^^^^^^^^^^^^^^^^^^^ + +The `disk-image-builder`_ can be used to create user images required for +deployment and the actual OS which the user is going to run. + +- Install diskimage-builder package (use virtualenv, if you don't + want to install anything globally): + + .. code-block:: console + + # pip install diskimage-builder + +- Build the image your users will run (Ubuntu image has been taken as + an example): + + - Partition images + + .. code-block:: console + + $ disk-image-create ubuntu baremetal dhcp-all-interfaces grub2 -o my-image + + - Whole disk images + + .. code-block:: console + + $ disk-image-create ubuntu vm dhcp-all-interfaces -o my-image + +The partition image command creates ``my-image.qcow2``, +``my-image.vmlinuz`` and ``my-image.initrd`` files. The ``grub2`` element +in the partition image creation command is only needed if local boot will +be used to deploy ``my-image.qcow2``, otherwise the images +``my-image.vmlinuz`` and ``my-image.initrd`` will be used for PXE booting +after deploying the bare metal with ``my-image.qcow2``. For whole disk images +only the main image is used. + +If you want to use Fedora image, replace ``ubuntu`` with ``fedora`` in the +chosen command. + +.. _disk-image-builder: https://docs.openstack.org/diskimage-builder/latest/ diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 7fb04cada3..63041923b7 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -15,8 +15,9 @@ It contains the following sections: get_started.rst refarch/index install.rst - configure-integration.rst + creating-images.rst deploy-ramdisk.rst + configure-integration.rst setup-drivers.rst enrollment.rst standalone.rst diff --git a/doc/source/install/standalone.rst b/doc/source/install/standalone.rst index 8a90c69d27..c7bda06ce9 100644 --- a/doc/source/install/standalone.rst +++ b/doc/source/install/standalone.rst @@ -110,7 +110,8 @@ Steps to start a deployment are pretty similar to those when using Compute: openstack baremetal port create $MAC_ADDRESS --node $NODE_UUID -#. You also need to specify some fields in the node's ``instance_info``: +#. You also need to specify image information in the node's ``instance_info`` + (see :doc:`creating-images`): * ``image_source`` - URL of the whole disk or root partition image, mandatory. For :ref:`direct-deploy` only HTTP(s) links are accepted, @@ -141,7 +142,7 @@ Steps to start a deployment are pretty similar to those when using Compute: md5sum *.img > checksums * ``kernel``, ``ramdisk`` - HTTP(s) or file URLs of the kernel and - initramfs of the target OS, only required for partition images. + initramfs of the target OS. Must be added **only** for partition images. For example:: @@ -152,6 +153,12 @@ Steps to start a deployment are pretty similar to those when using Compute: --instance-info ramdisk=$RAMDISK \ --instance-info root_gb=10 + With a whole disk image:: + + openstack baremetal node set $NODE_UUID \ + --instance-info image_source=$IMG \ + --instance-info image_checksum=$MD5HASH + #. Validate that all parameters are correct:: openstack baremetal node validate $NODE_UUID