Skip to content

docs(auth): explain staged signing-key rotation (FB-4481) - #120

Open
simonzelenskifbio wants to merge 6 commits into
FB-4387-configuration-optionsfrom
FB-4481-signing-key-rotation
Open

simonzelenskifbio wants to merge 6 commits into
FB-4387-configuration-optionsfrom
FB-4481-signing-key-rotation

Conversation

@simonzelenskifbio

@simonzelenskifbio simonzelenskifbio commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

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

  • Helm 3.16.3 strict lint and template rendering passed.
  • Regenerated helm-docs; docs navigation and script checks passed.
  • No runtime test added: only prose and comments change; the signing-key configuration and Certificate spec are unchanged.

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.signingKeys entry” 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.mdx now 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 in helm/values.yaml comments (source for helm-docs), regenerated helm/README.md, helm/AGENTS.md, and comment-only updates in helm/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.

@fireboltdb-docs-integration

fireboltdb-docs-integration Bot commented Oct 2, 2026 •

Copy link
Copy Markdown

Mintlify docs preview

Docs were aggregated into the Firebolt documentation site.

Status Preview Updated (UTC)
🟢 Ready View Preview Oct 02, 2026, 10:47 AM

Mintlify may take a few minutes to finish building. This comment updates on each sync while the source PR is open.

@cursor cursor Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Risk: low. Cursor Bugbot and Cursor Security Agent completed successfully with no findings that need human review. Approved: comment-only documentation of staged signing-key rotation; chart rendering and Certificate spec are unchanged.

Open in Web View Automation 

Sent by Cursor Approval Agent: Infra Reviewer

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.

1 participant