Skip to content

Add Redis Sentinel storage documentation for auth server#3824

Merged
tgrunnagle merged 3 commits intomainfrom
issue_3790_as-redis-docs
Mar 3, 2026
Merged

Add Redis Sentinel storage documentation for auth server#3824
tgrunnagle merged 3 commits intomainfrom
issue_3790_as-redis-docs

Conversation

@tgrunnagle
Copy link
Contributor

@tgrunnagle tgrunnagle commented Feb 13, 2026

Closes #3790

Summary

Adds comprehensive documentation for configuring Redis Sentinel as the storage backend for the embedded authorization server. This completes Phase 3 (Documentation) of the Redis storage implementation plan, covering a user-facing configuration guide, architecture documentation, and example Kubernetes manifests.

Changes Made

User-Facing Guide (docs/redis-storage.md)

  • Complete Redis Sentinel configuration guide with CRD and RunConfig examples
  • Step-by-step Spotahome Redis Operator deployment instructions
  • Redis ACL user setup with minimum required commands
  • Data model reference: key schema, secondary indexes, TTL values
  • Atomicity and consistency model documentation
  • Troubleshooting section for connection, authentication, permission, and failover issues
  • Full CRD configuration reference tables

Architecture Documentation (docs/arch/11-auth-server-storage.md)

  • Storage interface design covering fosite OAuth 2.0 interfaces and ToolHive extensions
  • Memory vs Redis Sentinel backend comparison with architecture diagram
  • Multi-tenancy via Redis hash tags with forward-compatibility rationale
  • Consistency model: Lua scripts, pipelines, and best-effort individual commands
  • TTL management, serialization, and security considerations

Example Manifests (examples/operator/redis-storage/)

  • redis-failover.yaml — Spotahome RedisFailover CRD with ACL file support and provisioning guidance
  • sentinel-service.yaml — Manual Sentinel Service + StatefulSet with init container for writable config
  • redis-credentials.yaml — Kubernetes Secret template for Redis ACL credentials
  • mcpexternalauthconfig-redis-storage.yaml — Complete MCPExternalAuthConfig with Redis storage and Sentinel Service discovery

Existing Architecture Docs

Additional Notes

  • Documentation-only PR — no Go code changes
  • All YAML examples validated against CRD type definitions in mcpexternalauthconfig_types.go

Large PR Justification

  • Documentation updates only, all related to Authz server redis token storage

@github-actions github-actions bot added the size/L Large PR: 600-999 lines changed label Feb 13, 2026
@codecov
Copy link

codecov bot commented Feb 13, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.92%. Comparing base (1b87777) to head (70f574c).
⚠️ Report is 17 commits behind head on main.

Additional details and impacted files
@@            Coverage Diff             @@
##             main    #3824      +/-   ##
==========================================
- Coverage   68.03%   67.92%   -0.11%     
==========================================
  Files         438      438              
  Lines       44000    44033      +33     
==========================================
- Hits        29936    29911      -25     
- Misses      11722    11779      +57     
- Partials     2342     2343       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copy link
Contributor

@jhrozek jhrozek left a comment

Choose a reason for hiding this comment

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

Documentation review — 4 inline suggestions below. Overall the docs are thorough, accurate, and well cross-referenced. All code file paths, CRD field names, interface names, key patterns, and TTL values were verified against the implementation. Nice work.

Add comprehensive documentation for configuring Redis Sentinel as the
storage backend for the embedded authorization server, enabling
horizontal scaling across multiple auth server replicas.

New files:
- docs/redis-storage.md: User-facing configuration guide with CRD
  examples, Spotahome Redis Operator deployment steps, data model
  reference, troubleshooting, and configuration reference tables
- docs/arch/11-auth-server-storage.md: Architecture documentation
  covering storage interface design, memory and Redis backends,
  multi-tenancy via key prefixes, and atomic Lua script operations
- examples/operator/redis-storage/: Example manifests for Redis
  Failover, Sentinel Service, credentials Secret, and
  MCPExternalAuthConfig with Redis storage

Updated architecture docs (README, overview, operator) to reference
the new storage documentation.

Closes #3790
@tgrunnagle tgrunnagle force-pushed the issue_3790_as-redis-docs branch from 29846a9 to cedda09 Compare March 2, 2026 16:31
@github-actions github-actions bot added size/L Large PR: 600-999 lines changed and removed size/L Large PR: 600-999 lines changed labels Mar 2, 2026
@github-actions github-actions bot added size/XL Extra large PR: 1000+ lines changed and removed size/L Large PR: 600-999 lines changed labels Mar 2, 2026
Copy link
Contributor

@github-actions github-actions bot left a comment

Choose a reason for hiding this comment

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

Large PR Detected

This PR exceeds 1000 lines of changes and requires justification before it can be reviewed.

How to unblock this PR:

Add a section to your PR description with the following format:

## Large PR Justification

[Explain why this PR must be large, such as:]
- Generated code that cannot be split
- Large refactoring that must be atomic
- Multiple related changes that would break if separated
- Migration or data transformation

Alternative:

Consider splitting this PR into smaller, focused changes (< 1000 lines each) for easier review and reduced risk.

See our Contributing Guidelines for more details.


This review will be automatically dismissed once you add the justification section.

@tgrunnagle tgrunnagle dismissed github-actions[bot]’s stale review March 3, 2026 15:08

Added large PR justification and request re-review not working.

@tgrunnagle tgrunnagle merged commit d57b70b into main Mar 3, 2026
33 checks passed
@tgrunnagle tgrunnagle deleted the issue_3790_as-redis-docs branch March 3, 2026 15:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

size/XL Extra large PR: 1000+ lines changed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Auth Server: Add Redis Storage Documentation

2 participants