Add platform-wide Redis defaults callouts to operator guides

[claude]

Requested by Daniel Barr · Slack thread

Before / After

Before: the Kubernetes operator deployment guides explain how to configure Redis for horizontal scaling session storage at the OSS level (per-CR spec.sessionStorage and the operator-wide operator.defaultRedis), but they don't point full-platform users to the umbrella-level platform-wide defaults. Someone running the full Stacklok Enterprise platform has no signal that they can set this once at the umbrella level instead of per component.

After: each relevant operator guide carries a short enterprise-context callout that tells full-platform users to set this once at the umbrella level via global.redis, and links to the platform-wide Redis/Valkey defaults on the platform deployment page. The underlying OSS feature descriptions are unchanged and remain accurate.

How

This mirrors the :::enterprise admonition idiom (per CLAUDE.md): a brief, OSS-neutral callout that routes full-platform users to the canonical supported path without implying the feature is Enterprise-gated. No <EnterpriseBadge /> is added to any feature heading. Each callout cross-links to the existing #global-redisvalkey-defaults section on docs/platform/enterprise-platform/deployment.mdx (anchor verified with github-slugger).

Files touched and which global.* each covers:

• docs/toolhive/guides-k8s/deploy-operator.mdx (global.redis) - callout at the end of the "Set a cluster-wide default Redis" section, the OSS analog of the umbrella default that global.redis overrides.
• docs/toolhive/guides-k8s/redis-session-storage.mdx (global.redis) - callout in the "Horizontal scaling session storage" section, alongside the existing cluster-wide-default tip.

This is the companion to PR #979's pattern: #979 establishes the global.postgres callout on the registry server's deploy-helm.mdx and adds the "Global PostgreSQL defaults" section to the platform deployment page; this PR extends the same idiom to the global.redis defaults that the operator subchart honors.

Scope / skipped

Deliberately left out, because the global.* fallback does not genuinely apply or is handled elsewhere:

• docs/toolhive/guides-registry/deploy-helm.mdx - the global.postgres callout is being handled in PR Update stacklok/toolhive-registry-server to v1.4.11 #979; not duplicated here.
• docs/toolhive/guides-registry/deploy-operator.mdx - uses the deprecated MCPRegistry CRD. The global.postgres fallback is a feature of the registry-server Helm subchart, not the CRD, so the CRD-based path does not honor it.
• docs/toolhive/guides-registry/database.mdx, deploy-manual.mdx - standalone/manual registry deployments, not umbrella-subchart context.
• Embedded auth server Redis sections (in redis-session-storage.mdx and auth-k8s.mdx) - the platform deployment page states embedded auth token storage is configured separately via MCPExternalAuthConfig and does not inherit global.redis, so no callout there.
• rate-limiting.mdx and the vMCP scaling page - neither references the operator-level/umbrella default; the two operator deploy pages above are the canonical, conservative spots (one callout per page).

For Daniel's judgment: global.postgres genuinely applies to only the registry server, which PR #979 already covers, so there was no additional postgres page to add here. global.redis is the only platform-wide default with extra OSS guide surface, and the two pages above are the accurate targets.

🤖 Generated with Claude Code

https://claude.ai/code/session_014pdgd5wypAXDCqR4zFk7Gj

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Jun 25, 2026 10:13pm

[claude]

Automated editorial review (docs-review skill)

This is an automated editorial pass produced by running the repo's .claude/skills/docs-review skill against the two files changed in this PR (deploy-operator.mdx, redis-session-storage.mdx), the diff vs. main, and cross-checked against AGENTS.md/STYLE-GUIDE.md and the cross-linked platform page. It is advisory; a human should make the final call.

Summary

A clean, conservative change: two short :::enterprise callouts that route full-platform users to the umbrella-level global.redis default without implying the OSS feature is Enterprise-gated. The construct choice, placement, length, and cross-links all align with the repo's enterprise-content conventions. The technical claims match the cross-linked platform deployment page. No primary (merge-blocking) issues found.

Verification performed

• Enterprise construct usage - Correct. Per AGENTS.md ("Enterprise content constructs"), :::enterprise is the right construct for a 2-4 sentence callout that routes to an Enterprise capability; one per page (two max) is the guidance. This PR adds exactly one per page, each 3-4 sentences. No <EnterpriseBadge /> is (correctly) added to any feature heading, so no feature is mislabeled as Enterprise-gated.
• Cross-link anchor - Valid. Both callouts link to ../../platform/enterprise-platform/deployment.mdx#global-redisvalkey-defaults. The target heading #### Global Redis/Valkey defaults exists (deployment.mdx line 238) and github-slugger renders it as global-redisvalkey-defaults (the / and case are stripped) - matches.
• Relative path - Valid. Both source files live in docs/toolhive/guides-k8s/; ../../platform/... resolves to docs/platform/....
• Technical accuracy - Claims match the canonical platform page. The toolhiveOperator row of the components table (deployment.mdx line 275) confirms global.redis is the default session storage for MCPServer, MCPRemoteProxy, and VirtualMCPServer workloads with no explicit spec.sessionStorage. The "a local operator.defaultRedis still wins when set" claim in the deploy-operator callout matches the precedence note on deployment.mdx (lines 283-290).
• LLM-pattern scan - No em/en dashes, no hedging language, no placeholder examples, no buried lede. Prose is direct and active.
• Placement - Each callout sits at the end of its relevant section (the "cluster-wide default Redis" / "horizontal scaling session storage" context), adjacent to the existing OSS guidance it complements. Appropriate.

Secondary observations (non-blocking, for human judgment)

Observation	Note
Slight wording divergence between the two callouts	The deploy-operator.mdx callout adds "A local operator.defaultRedis still wins when set." while the redis-session-storage.mdx callout omits the precedence sentence and instead qualifies with "that have no explicit spec.sessionStorage." Both are individually accurate and each fits its local context (the operator page is already discussing operator.defaultRedis; the session-storage page is discussing per-CR spec.sessionStorage). This is a reasonable context-sensitive difference, not an inconsistency to "fix" - flagged only so a reviewer can confirm the intent is deliberate.
"set this once at the umbrella level instead"	"instead" reads naturally in context (instead of the per-component OSS approach just described). Clear; no change needed.

What works well

• Both callouts are OSS-neutral: they describe where to set a default for full-platform users without removing or weakening the existing OSS instructions, so the underlying feature docs remain accurate and complete for OSS readers.
• Single source of truth is respected - the callouts link to the canonical global.redis documentation rather than duplicating the YAML block.
• Conservative scope (the PR description's "skipped" rationale is sound: embedded auth token storage is correctly excluded since it does not inherit global.redis).

Recommendation: No merge-blocking changes. The two secondary observations are for reviewer awareness only.