From 6f798cf52e1154ab1e851353e5f98d74ab49903e Mon Sep 17 00:00:00 2001 From: shashwatpandeyvns <107537202+shashwatpandeyvns@users.noreply.github.com> Date: Thu, 2 Feb 2023 21:11:07 +0530 Subject: [PATCH 1/4] #Issue63469 update Docs --- doc/ref/cli/salt-key.rst | 12 ++++++++++++ doc/topics/tutorials/intro_scale.rst | 8 ++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/doc/ref/cli/salt-key.rst b/doc/ref/cli/salt-key.rst index f51a6cbbeaaf..71eaf553279d 100644 --- a/doc/ref/cli/salt-key.rst +++ b/doc/ref/cli/salt-key.rst @@ -104,10 +104,16 @@ Actions Reject the specified public key (use --include-all to match accepted keys in addition to pending keys). Globs are supported. + .. Warning:: + It may cause dramatic performance salt-master degradation. + See `performance guide`_ for details. .. option:: -R, --reject-all Rejects all pending keys. + .. Warning:: + It may cause dramatic performance salt-master degradation. + See `performance guide`_ for details. .. option:: --include-all @@ -124,10 +130,16 @@ Actions .. option:: -d DELETE, --delete=DELETE Delete the specified key. Globs are supported. + .. Warning:: + It may cause dramatic performance salt-master degradation. + See `performance guide`_ for details. .. option:: -D, --delete-all Delete all keys. + .. Warning:: + It may cause dramatic performance salt-master degradation. + See `performance guide`_ for details. .. option:: -f FINGER, --finger=FINGER diff --git a/doc/topics/tutorials/intro_scale.rst b/doc/topics/tutorials/intro_scale.rst index a4824b3f9f85..41f8a6768f28 100644 --- a/doc/topics/tutorials/intro_scale.rst +++ b/doc/topics/tutorials/intro_scale.rst @@ -76,10 +76,10 @@ 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 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, +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 From 63b39d7555038d0772930eaad4487431256b5d2b Mon Sep 17 00:00:00 2001 From: shashwatpandeyvns <107537202+shashwatpandeyvns@users.noreply.github.com> Date: Tue, 7 Feb 2023 04:05:14 +0530 Subject: [PATCH 2/4] #63610 Suggested changes --- doc/ref/cli/salt-key.rst | 32 +++++++++++++++++----------- doc/topics/tutorials/intro_scale.rst | 6 +++--- 2 files changed, 23 insertions(+), 15 deletions(-) diff --git a/doc/ref/cli/salt-key.rst b/doc/ref/cli/salt-key.rst index 71eaf553279d..0a3edba9c162 100644 --- a/doc/ref/cli/salt-key.rst +++ b/doc/ref/cli/salt-key.rst @@ -104,16 +104,20 @@ Actions Reject the specified public key (use --include-all to match accepted keys in addition to pending keys). Globs are supported. - .. Warning:: - It may cause dramatic performance salt-master degradation. - See `performance guide`_ for details. + .. warning:: + Using globs to reject the specified public key may cause performance issues + because of a Salt master degredation dramatic performance salt-master degradation. + See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) + for more information about performance impacts and workarounds. .. option:: -R, --reject-all Rejects all pending keys. - .. Warning:: - It may cause dramatic performance salt-master degradation. - See `performance guide`_ for details. + .. warning:: + Using globs to reject the specified public key may cause performance issues + because of a Salt master degredation dramatic performance salt-master degradation. + See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) + for more information about performance impacts and workarounds. .. option:: --include-all @@ -130,16 +134,20 @@ Actions .. option:: -d DELETE, --delete=DELETE Delete the specified key. Globs are supported. - .. Warning:: - It may cause dramatic performance salt-master degradation. - See `performance guide`_ for details. + .. warning:: + Using globs to reject the specified public key may cause performance issues + because of a Salt master degredation dramatic performance salt-master degradation. + See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) + for more information about performance impacts and workarounds. .. option:: -D, --delete-all Delete all keys. - .. Warning:: - It may cause dramatic performance salt-master degradation. - See `performance guide`_ for details. + .. warning:: + Using globs to reject the specified public key may cause performance issues + because of a Salt master degredation dramatic performance salt-master degradation. + See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) + for more information about performance impacts and workarounds. .. option:: -f FINGER, --finger=FINGER diff --git a/doc/topics/tutorials/intro_scale.rst b/doc/topics/tutorials/intro_scale.rst index 41f8a6768f28..3f8a439fb4a0 100644 --- a/doc/topics/tutorials/intro_scale.rst +++ b/doc/topics/tutorials/intro_scale.rst @@ -76,9 +76,9 @@ 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/rejection 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, +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 From f2b3f6991807000c9fb8652df8679accc551b2a3 Mon Sep 17 00:00:00 2001 From: "Daniel A. Wozniak" Date: Mon, 15 Jun 2026 15:41:44 -0700 Subject: [PATCH 3/4] Fix warning wording and rST formatting in salt-key.rst - Replace broken English and duplicated 'degradation' phrase in all 4 warning blocks with accurate, idiomatic text - Fix markdown link syntax to rST hyperlink syntax so Sphinx renders clickable links - Add blank line before each .. warning:: directive so Sphinx parses the admonition correctly - Tailor each warning to its specific operation: reject vs reject-all, delete vs delete-all (per twangboy review 2025-04-02) - Wrap long lines in intro_scale.rst to fit within 80 characters Fixes #63469 --- doc/ref/cli/salt-key.rst | 42 +++++++++++++++++----------- doc/topics/tutorials/intro_scale.rst | 9 +++--- 2 files changed, 31 insertions(+), 20 deletions(-) diff --git a/doc/ref/cli/salt-key.rst b/doc/ref/cli/salt-key.rst index 0a3edba9c162..45212969f0b4 100644 --- a/doc/ref/cli/salt-key.rst +++ b/doc/ref/cli/salt-key.rst @@ -104,20 +104,25 @@ Actions Reject the specified public key (use --include-all to match accepted keys in addition to pending keys). Globs are supported. + .. warning:: - Using globs to reject the specified public key may cause performance issues - because of a Salt master degredation dramatic performance salt-master degradation. - See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) - for more information about performance impacts and workarounds. + 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:: - Using globs to reject the specified public key may cause performance issues - because of a Salt master degredation dramatic performance salt-master degradation. - See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) - for more information about performance impacts and workarounds. + 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 @@ -134,20 +139,25 @@ Actions .. option:: -d DELETE, --delete=DELETE Delete the specified key. Globs are supported. + .. warning:: - Using globs to reject the specified public key may cause performance issues - because of a Salt master degredation dramatic performance salt-master degradation. - See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) - for more information about performance impacts and workarounds. + 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:: - Using globs to reject the specified public key may cause performance issues - because of a Salt master degredation dramatic performance salt-master degradation. - See [`performance guide`](https://docs.saltproject.io/en/latest/topics/tutorials/intro_scale.html#too-many-minions-re-authing) - for more information about performance impacts and workarounds. + 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 diff --git a/doc/topics/tutorials/intro_scale.rst b/doc/topics/tutorials/intro_scale.rst index 3f8a439fb4a0..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/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``). +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 From 30a9379c5343dd4ff7bd5097f72c3634f28195bd Mon Sep 17 00:00:00 2001 From: "Daniel A. Wozniak" Date: Fri, 26 Jun 2026 04:10:17 -0700 Subject: [PATCH 4/4] Add changelog entry for PR #63610 --- changelog/63610.changed.md | 1 + 1 file changed, 1 insertion(+) create mode 100644 changelog/63610.changed.md 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.