From 76c10acb33f309d11ee043e909909271c842b38e Mon Sep 17 00:00:00 2001
From: melanie witt <melwittt@gmail.com>
Date: Fri, 6 Sep 2024 00:19:30 +0000
Subject: [PATCH] docs: Show the recommended way to PXE boot an instance

Someone asked about this in the #openstack-nova channel today and I
found some artifacts: an abandoned patch [1] and spec [2] where the
conclusion of the discussion was a recommendation to use iPXE and
rescue to PXE boot an instance.

This adds a small high level doc about how to do it to help others who
may want to do the same thing.

[1] https://review.opendev.org/c/openstack/nova/+/434549
[2] https://review.opendev.org/c/openstack/nova-specs/+/435052

Change-Id: I78f097b9e280fc2bcc14655042b844d3d5977b07
---
 doc/source/user/boot-instance-using-PXE.rst | 61 +++++++++++++++++++++
 doc/source/user/launch-instances.rst        |  1 +
 2 files changed, 62 insertions(+)
 create mode 100644 doc/source/user/boot-instance-using-PXE.rst

diff --git a/doc/source/user/boot-instance-using-PXE.rst b/doc/source/user/boot-instance-using-PXE.rst
new file mode 100644
index 0000000000..fd149812f8
--- /dev/null
+++ b/doc/source/user/boot-instance-using-PXE.rst
@@ -0,0 +1,61 @@
+==========================
+Boot an instance using PXE
+==========================
+
+Follow the steps below to boot an existing instance using PXE.
+
+Create an image with iPXE
+=========================
+
+iPXE is open source boot firmware. See the documentation for more details:
+https://ipxe.org/docs
+
+Use the iPXE image as a rescue image
+====================================
+
+Boot the instance from the iPXE image using rescue.
+
+Legacy instance rescue
+----------------------
+
+The ordering of disks is not guaranteed to be consistent.
+
+.. code-block:: console
+
+   $ openstack server rescue --image IPXE_IMAGE INSTANCE_NAME
+
+Stable device instance rescue
+-----------------------------
+
+To preserve the ordering of disks when booting, use `stable device rescue`_.
+
+#. Ensure that the ``hw_rescue_device`` (``cdrom`` | ``disk`` | ``floppy``)
+   and/or the ``hw_rescue_bus`` (``scsi`` | ``virtio`` | ``ide`` | ``usb``) image
+   properties are set on the image. For example:
+
+   .. code-block:: console
+
+      $ openstack image set --property hw_rescue_device=disk IPXE_IMAGE
+
+   or:
+
+   .. code-block:: console
+
+      $ openstack image set --property hw_rescue_bus=virtio IPXE_IMAGE
+
+   or:
+
+   .. code-block:: console
+
+      $ openstack image set --property hw_rescue_device=disk \
+        --property hw_rescue_bus=virtio IPXE_IMAGE
+
+#. Run the rescue using the API microversion 2.87 or later:
+
+   .. code-block:: console
+
+      $ openstack --os-compute-api-version 2.87 server rescue \
+        --image IPXE_IMAGE INSTANCE_NAME
+
+
+.. _stable device rescue: https://docs.openstack.org/nova/latest/user/rescue.html#stable-device-instance-rescue
diff --git a/doc/source/user/launch-instances.rst b/doc/source/user/launch-instances.rst
index 0073852161..73f113e67a 100644
--- a/doc/source/user/launch-instances.rst
+++ b/doc/source/user/launch-instances.rst
@@ -165,4 +165,5 @@ You can launch an instance from various sources.
    launch-instance-from-image
    launch-instance-from-volume
    launch-instance-using-ISO-image
+   boot-instance-using-PXE