From 3bb9d0ae21da5bf8552e661667ea5efd94490c84 Mon Sep 17 00:00:00 2001
From: Alex Welsh <alex@stackhpc.com>
Date: Mon, 17 Nov 2025 15:41:29 +0000
Subject: [PATCH] Add removing a hypervisor doc section

---
 .../bifrost-hardware-inventory-management.rst | 47 +++++++++++++++++++
 1 file changed, 47 insertions(+)

diff --git a/doc/source/operations/bifrost-hardware-inventory-management.rst b/doc/source/operations/bifrost-hardware-inventory-management.rst
index eb900721ba..21bfc8a456 100644
--- a/doc/source/operations/bifrost-hardware-inventory-management.rst
+++ b/doc/source/operations/bifrost-hardware-inventory-management.rst
@@ -102,6 +102,53 @@ To deprovision an existing hypervisor, run:
    system. Running this command without a limit will deprovision all overcloud
    hosts.
 
+Removing a Hypervisor
+---------------------
+
+To remove a hypervisor without replacing it, proceed as follows:
+
+#. :ref:`Disable the hypervisor to avoid scheduling any new instance on it <taking-a-hypervisor-out-of-service>`
+#. :ref:`Evacuate all instances <evacuating-all-instances>`
+#. (optionally) Deprovision the hypervisor
+
+   .. code-block:: console
+
+      kayobe overcloud deprovision --limit <Hypervisor hostname>
+
+   .. warning::
+
+      Always use ``--limit`` with ``kayobe overcloud deprovision`` on a production
+      system. Running this command without a limit will deprovision all overcloud
+      hosts.
+
+#. Physically remove the node from the deployment
+#. Delete the compute service in OpenStack:
+
+   .. code-block:: console
+
+      openstack compute service list | grep <Hypervisor hostname>
+      openstack compute service delete <Service ID>
+
+#. Delete the network agents in OpenStack:
+
+   .. code-block:: console
+
+      openstack network agent list | grep <Hypervisor hostname>
+      openstack network agent delete <Agent IDs>
+
+#. Delete the node in Bifrost:
+
+   .. code-block:: console
+
+      docker exec -it bifrost_deploy bash
+      (bifrost-deploy)[root@seed bifrost-base]# export OS_CLOUD=bifrost
+      (bifrost-deploy)[root@seed bifrost-base]# openstack baremetal node delete <Hostname>
+
+#. Remove the node from the Kayobe configuration. Ensure the node is removed
+   from the inventory and ``network-allocation.yml``. Other configuration files
+   may also be removed, but this is dependent on the deployment. Recursive
+   ``grep`` can help here.
+
 .. _evacuating-all-instances:
 
 Evacuating all instances