Skip to content

Docs: mention key rejection as AES rotation trigger (re-auth thundering herd) - #70104

Open
adisivaprasad wants to merge 1 commit into
saltstack:masterfrom
adisivaprasad:fix-63469-docs-key-rejection-aes-rotation
Open

Docs: mention key rejection as AES rotation trigger (re-auth thundering herd)#70104
adisivaprasad wants to merge 1 commit into
saltstack:masterfrom
adisivaprasad:fix-63469-docs-key-rejection-aes-rotation

Conversation

@adisivaprasad

Copy link
Copy Markdown

What does this PR do?

Documents that minion key rejection (salt-key -r) triggers AES key rotation — just like key removal (salt-key -d) — causing all minions to re-authenticate with the master.

Two documentation changes:

  1. Performance guide (doc/topics/tutorials/intro_scale.rst, "Too many minions re-authing" section): now mentions removal/rejection and salt-key -r alongside salt-key -d, as suggested in the issue.
  2. CLI reference (doc/ref/cli/salt-key.rst): adds a prominent warning that deleting/rejecting keys rotates the AES publication key, which can cause a "thundering herd" of minion re-auths on large installations, with a backlink to the performance guide section (new :ref: target too-many-minions-re-authing).

Note: the third location mentioned in the issue, the legacy en/getstarted/system/communication.html page ("Rotating security keys" section), no longer exists in this repository — the get-started docs were migrated to the salt-user-guide / salt-install-guide repos, whose security pages already describe key rotation. Happy to open a companion PR there if maintainers would like.

What issues does this PR fix or reference?

Fixes #63469

Previous Behavior

The performance guide only mentioned master restart and key removal (salt-key -d) as events that rotate the AES key; key rejection was not mentioned, and the salt-key reference carried no warning about the re-auth thundering-herd effect of key deletion/rejection.

New Behavior

Rejection is documented as a rotation trigger in both the performance guide and the salt-key CLI docs (with a warning and cross-link).

Merge requirements satisfied?

Commits signed with GPG?

No

Key rejection (salt-key -r) triggers AES key rotation just like key
removal (salt-key -d), forcing all minions to re-authenticate.

- Mention rejection alongside removal in the 'Too many minions
  re-authing' performance guide section
- Add a warning to the salt-key CLI docs about the re-auth
  'thundering herd' effect, linking back to the performance guide

Fixes saltstack#63469
@adisivaprasad
adisivaprasad requested a review from a team as a code owner August 20, 2026 05:42
@welcome

welcome Bot commented Aug 20, 2026

Copy link
Copy Markdown

Hi there! Welcome to the Salt Community! Thank you for making your first contribution. We have a lengthy process for issues and PRs. Someone from the Core Team will follow up as soon as possible. In the meantime, here's some information that may help as you continue your Salt journey.
Please be sure to review our Code of Conduct. Also, check out some of our community resources including:

There are lots of ways to get involved in our community. Every month, there are around a dozen opportunities to meet with other contributors and the Salt Core team and collaborate in real time. The best way to keep track is by subscribing to the Salt Community Events Calendar.
If you have additional questions, email us at saltproject.pdl@broadcom.com. We're glad you've joined our community and look forward to doing awesome things with you!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[DOCS] key rejection is not mentioned in the guides when AES key rotation situations happens

1 participant