From 4e782d37eea73bb10ac716cbd82e016c55a69786 Mon Sep 17 00:00:00 2001
From: Jay Faulkner <jay@jvf.cc>
Date: Thu, 23 Jan 2025 09:19:57 -0800
Subject: [PATCH] [doc] Add node history to admin guide

Node history previously was only documented in our troubleshooting faq
and API reference.

Change-Id: I84c32f657d420c9f02458347a318a67bff14e981
---
 doc/source/admin/features.rst     |  1 +
 doc/source/admin/node-history.rst | 46 +++++++++++++++++++++++++++++++
 2 files changed, 47 insertions(+)
 create mode 100644 doc/source/admin/node-history.rst

diff --git a/doc/source/admin/features.rst b/doc/source/admin/features.rst
index d6dad3976e..1281996832 100644
--- a/doc/source/admin/features.rst
+++ b/doc/source/admin/features.rst
@@ -25,3 +25,4 @@ Bare Metal Service Features
    Deploying without BMC Credentials <agent-power>
    Layer 3 or DHCP-less Ramdisk Booting <dhcp-less>
    Deploying with Anaconda <anaconda-deploy-interface>
+   Node History <node-history>
diff --git a/doc/source/admin/node-history.rst b/doc/source/admin/node-history.rst
new file mode 100644
index 0000000000..54455d952d
--- /dev/null
+++ b/doc/source/admin/node-history.rst
@@ -0,0 +1,46 @@
+.. _node-history:
+
+============
+Node History
+============
+
+Overview
+========
+Ironic keeps a record of node error events in node history. This allows
+operators to track frequent failures and get additional context when
+troubleshooting failures.
+
+How it works
+============
+
+Anytime a node would have it's ``last_error`` populated, an entry is added
+to the history of the node containing severity of and details about the
+failure.
+
+Node history can be completely disabled by setting
+:oslo.config:option:`conductor.node_history` to ``False``; it is enabled
+by default.
+
+Since node history can grow unbounded over time, by default Ironic
+is configured to prune the data; this behavior is configurable with
+the following settings:
+
+- :oslo.config:option:`conductor.node_history_max_entries`
+- :oslo.config:option:`conductor.node_history_cleanup_interval`
+- :oslo.config:option:`conductor.node_history_cleanup_batch_count`
+- :oslo.config:option:`conductor.node_history_minimum_days`
+
+Client usage
+============
+The baremetal CLI has full support for node history.
+
+To view the list of entries in history for a node:
+``baremetal node history list $node``.
+
+To see a specific node history entry you want to see in detail:
+``baremetal node history get $node $eventId``.
+
+Node history entries cannot be removed manually. Use the configuration
+options listed in the previous section to control the automatic pruning
+behavior of Ironic.
+