Repository navigation
docs(auth): explain staged signing-key rotation (FB-4481) - #120
Open
simonzelenskifbio wants to merge 6 commits into
Open
simonzelenskifbio wants to merge 6 commits into
simonzelenskifbio wants to merge 6 commits into
Conversation
Mintlify docs previewDocs were aggregated into the Firebolt documentation site.
Mintlify may take a few minutes to finish building. This comment updates on each sync while the source PR is open. |
…nto FB-4481-signing-key-rotation
simonzelenskifbio
changed the base branch from
main
to
FB-4387-configuration-options
October 2, 2026 09:30
This was referenced Oct 2, 2026
simonzelenskifbio
marked this pull request as ready for review
October 2, 2026 09:32
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.


Background
FB-4481: promoting a new signing key before every Engine can verify it can break cross-node token validation during a rollout.
Summary
Document separate distribution, promotion, retention, and removal upgrades. Append the new verifier and complete every Engine rollout before making it the active signer. Retain the outgoing verifier for the maximum old-token lifetime plus clock-skew tolerance after the last old signer stops.
Update authentication documentation, values annotations, the generated chart README, and related maintainer/template comments consistently. This is documentation only; it does not add automated rotation or promise uninterrupted queries during Engine restarts.
Stack 6/6 for FB-4382, based on #117. No runtime template behavior changes.
Stack navigation: #111 → #112 → #113 → #114 → #117 → #120. Merge in this order.
Test Plan
Note
Low Risk
Prose and comment updates only; JWT signing key configuration and cert-manager Certificate behavior are unchanged.
Overview
Documentation-only update (FB-4481) that replaces “prepend a new
auth.signingKeysentry” rotation guidance with a staged Helm upgrade flow so multi-node engines do not mint tokens other nodes cannot verify mid-rollout.User-facing
docs/usage/authentication.mdxnow documents append → full Engine rollout → promote to first position → another rollout → retain old key through token lifetime (plus skew) → remove, including the[old]→[old, new]→[new, old]→[new]sequence, restart requirements, and an optional maintenance-window shortcut. The same wording is mirrored inhelm/values.yamlcomments (source forhelm-docs), regeneratedhelm/README.md,helm/AGENTS.md, and comment-only updates inhelm/templates/certificates.yaml. No chart rendering or Certificate spec behavior changes—only prose and comments.Reviewed by Cursor Bugbot for commit 076ba1c. Bugbot is set up for automated code reviews on this repo. Configure here.