diff --git a/changelog/63610.changed.md b/changelog/63610.changed.md new file mode 100644 index 000000000000..e8983a6d23ee --- /dev/null +++ b/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. diff --git a/doc/ref/cli/salt-key.rst b/doc/ref/cli/salt-key.rst index f51a6cbbeaaf..45212969f0b4 100644 --- a/doc/ref/cli/salt-key.rst +++ b/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 `_ + 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 `_ + 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 `_ + 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 `_ + for details on performance impacts and possible workarounds. + .. option:: -f FINGER, --finger=FINGER Print the specified key's fingerprint. diff --git a/doc/topics/tutorials/intro_scale.rst b/doc/topics/tutorials/intro_scale.rst index a4824b3f9f85..d8e0eb917926 100644 --- a/doc/topics/tutorials/intro_scale.rst +++ b/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