From cb98f4a28ecbb1ca4f3366494038572ed8929e7d 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 | 50 ++++++++++++++++++-
 1 file changed, 49 insertions(+), 1 deletion(-)

diff --git a/doc/source/operations/bifrost-hardware-inventory-management.rst b/doc/source/operations/bifrost-hardware-inventory-management.rst
index eb900721ba..6e2b332994 100644
--- a/doc/source/operations/bifrost-hardware-inventory-management.rst
+++ b/doc/source/operations/bifrost-hardware-inventory-management.rst
@@ -83,7 +83,7 @@ Replacing a Failing Hypervisor
 
 To replace a failing hypervisor, proceed as follows:
 
-* :ref:`Disable the hypervisor to avoid scheduling any new instance on it <taking-a-hypervisor-out-of-service>`
+* :ref:`Disable the hypervisor to avoid scheduling any new instances on it <taking-a-hypervisor-out-of-service>`
 * :ref:`Evacuate all instances <evacuating-all-instances>`
 * :ref:`Set the node to maintenance mode in Bifrost <set-bifrost-maintenance-mode>`
 * Physically fix or replace the node
@@ -102,6 +102,54 @@ 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 instances 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 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>
+
+#. 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>
+
+#. 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