#Issue63469 Update documentation to include performance impact warnings and workaround

changelog/63610.changed.md

@@ -0,0 +1 @@
+Add performance impact warnings to ``salt-key`` documentation for reject and delete operations that trigger AES key regeneration and mass minion re-authentication.

doc/ref/cli/salt-key.rst

@@ -105,10 +105,25 @@ Actions
     Reject the specified public key (use --include-all to match accepted keys
     in addition to pending keys). Globs are supported.
 
+    .. warning::
+        Rejecting a minion key causes the Salt master to generate a new AES key,
+        which triggers all connected minions to re-authenticate simultaneously.
+        This may degrade Salt master performance. See the
+        `performance guide <https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing>`_
+        for details on performance impacts and possible workarounds.
+
 .. option:: -R, --reject-all
 
     Rejects all pending keys.
 
+    .. warning::
+        Rejecting many minion keys simultaneously causes the Salt master to
+        generate a new AES key for each rejection, which triggers all connected
+        minions to re-authenticate. This may degrade Salt master performance.
+        See the
+        `performance guide <https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing>`_
+        for details on performance impacts and possible workarounds.
+
 .. option:: --include-all
 
     Include non-pending keys when accepting/rejecting.
@@ -125,10 +140,25 @@ Actions
 
     Delete the specified key. Globs are supported.
 
+    .. warning::
+        Deleting a minion key causes the Salt master to generate a new AES key,
+        which triggers all connected minions to re-authenticate simultaneously.
+        This may degrade Salt master performance. See the
+        `performance guide <https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing>`_
+        for details on performance impacts and possible workarounds.
+
 .. option:: -D, --delete-all
 
     Delete all keys.
 
+    .. warning::
+        Deleting many minion keys simultaneously causes the Salt master to
+        generate a new AES key for each deletion, which triggers all connected
+        minions to re-authenticate. This may degrade Salt master performance.
+        See the
+        `performance guide <https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing>`_
+        for details on performance impacts and possible workarounds.
+
 .. option:: -f FINGER, --finger=FINGER
 
     Print the specified key's fingerprint.

doc/topics/tutorials/intro_scale.rst

@@ -76,10 +76,11 @@ and parameters are frequently changed in the Salt Master's configuration
 file(s).
 
 The Salt Master generates a new AES key to encrypt its publications at certain
-events such as a Master restart or the removal of a Minion key.  If you are
-encountering this problem of too many minions re-authing against the Master,
-you will need to recalibrate your setup to reduce the rate of events like a
-Master restart or Minion key removal (``salt-key -d``).
+events, such as a Master restart or the removal/rejection of a Minion key. If
+you are encountering a problem where too many minions are re-authorizing
+against the Master, you need to recalibrate your setup. Try reducing the rate
+of re-authorizing events, such as a Master restart, Minion key removal
+(``salt-key -d``) or Minion key rejection (``salt-key -r``).
 
 When the Master generates a new AES key, the minions aren't notified of this
 but will discover it on the next pub job they receive. When the Minion