Document necessary delay in master key rolllover

During master key rollover, if the old master key is purged
immediately after updating principal encryption, running processes may
not successfully update their in-memory copies of the master key.
Document that the administrator should delay purging the master key
until after propagation and some daemon activity.

ticket: 8744
tags: pullup
target_version: 1.17

diff --git a/doc/admin/database.rst b/doc/admin/database.rst
index 14c145b24dd81abe70bccdd48af4458fcaf5dc17..2b02af3a01686b8764f908a2fff3dac584944ebb 100644 (file)
--- a/doc/admin/database.rst
+++ b/doc/admin/database.rst
@@ -535,6 +535,10 @@ availability.  To roll over the master key, follow these steps:
    use unlocked iteration; this variant will take longer, but will
    keep the database available to the KDC and kadmind while it runs.
 
+#. Wait until the above changes have propagated to all replica KDCs
+   and until all running KDC and kadmind processes have serviced
+   requests using updated principal entries.
+
 #. On the master KDC, run ``kdb5_util purge_mkeys`` to clean up the
    old master key.