DOC-6816 Document smart client handoffs (SCH) for Redis Enterprise on Kubernetes by andy-stark-redis · Pull Request #3597 · redis/docs

andy-stark-redis · 2026-07-07T13:12:47Z

Summary

Documents Smart client handoffs (SCH) support for Redis Enterprise on Kubernetes (DOC-6816), based on David Maier's input.

New page content/operate/kubernetes/networking/smart-client-handoffs.md — enables SCH on a K8s REC for the same-pod-network / IP-based / no-TLS scenario: prerequisites and version gates (RS 8.0.2-17 standalone, 8.0.16-29 OSS Cluster API), get cluster credentials, enable via the PUT /v1/cluster REST API request, verify the MONITOR handshake, and validate during an operator upgrade. Includes port-forward guidance for reaching the ClusterIP REST service.
content/develop/clients/sch.md — the Kubernetes section now says SCH is supported (was "not currently supported") and links to the new page.
content/operate/kubernetes/networking/_index.md — adds a Smart client handoffs section.
content/operate/rs/references/rest-api/objects/cluster/_index.md — adds the oss_cluster_client_maint_notifications field row.

Reviewer questions (need eng sign-off)

oss_cluster_client_maint_notifications is undocumented upstream. It's absent from the release notes and (before this PR) the REST API reference. Please confirm the exact name and default.
Two-flag enablement. The enable step sets both client_maint_notifications and oss_cluster_client_maint_notifications. Please confirm whether a standalone-only cluster on 8.0.2-17 accepts the OSS flag, and whether OSS Cluster API mode requires both flags or only the OSS-specific one. If it matters, the command should be split by mode.

Deferred (intentional)

The external / TLS / name-based access scenario is a TODO in the source doc, so it's out of scope here. A scope note in the page and overview says so. Worth a follow-up ticket.

Notes

Authored in the current (top-level) networking/; not mirrored into the 8.0/networking/ snapshot — leave to release-branch sync unless we want it now.
hugo --renderToMemory builds clean (exit 0, no relref errors).

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only changes with no runtime or security behavior changes in this repo.

Overview
Documents Smart client handoffs (SCH) for Redis Enterprise on Kubernetes when apps and the REC share the same pod network (IP-based, no TLS).

Adds smart-client-handoffs.md with version gates, secret-based REST auth, enabling client_maint_notifications and oss_cluster_client_maint_notifications via PUT /v1/cluster, kubectl port-forward for the ClusterIP API, verification via client debug logs and CLIENT MAINT_NOTIFICATIONS handshakes, and validation during a rolling upgrade.

sch.md now states K8s SCH is supported (replacing “not currently supported”) and links to the new page. The Kubernetes networking index gets a SCH section. The cluster REST API reference documents oss_cluster_client_maint_notifications (default false).

External TLS / name-based access is explicitly out of scope.

^{Reviewed by Cursor Bugbot for commit 2d736de. Bugbot is set up for automated code reviews on this repo. Configure here.}

… Kubernetes Add a networking page for enabling SCH on a K8s REC, plus supporting edits to the SCH overview, the networking index, and the REST API cluster-object reference. The enablement steps, the MONITOR-handshake verification, and the two notification flags come from David Maier's Slack/Google doc rather than any released reference. The load-bearing surprise: oss_cluster_client_maint_notifications does not appear in the release notes or the REST API cluster object docs, so I documented it from the source doc and added the reference row myself. Enablement is via the REST API on purpose (a temporary workaround) because the REC cluster spec does not yet expose these settings. The page is deliberately scoped to the same-pod-network / IP-based / no-TLS case; the external/TLS/name-based scenario is a TODO in the source doc, not an oversight. Learned: SCH-for-K8s config sourced from David's doc; the key OSS flag is undocumented upstream Gaps: oss_cluster_client_maint_notifications absent from release notes and REST API reference before this change; unconfirmed whether standalone on 8.0.2-17 accepts it, or whether OSS mode needs both flags — needs eng sign-off Recheck: when the REC cluster spec exposes SCH settings, replace the REST API enablement workaround Directive: external/TLS/name-based SCH is intentionally deferred (source doc TODO) — do not treat its absence as a gap Ticket: DOC-6816 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CLAassistant · 2026-07-07T13:12:58Z

All committers have signed the CLA.

github-actions · 2026-07-07T13:13:01Z

DOC-6816

github-actions · 2026-07-07T13:13:02Z

Staging links:
https://redis.io/docs/staging/DOC-6816-sch-k-8-s-docs/develop/clients/sch/
https://redis.io/docs/staging/DOC-6816-sch-k-8-s-docs/operate/kubernetes/networking/
https://redis.io/docs/staging/DOC-6816-sch-k-8-s-docs/operate/kubernetes/networking/smart-client-handoffs/
https://redis.io/docs/staging/DOC-6816-sch-k-8-s-docs/operate/rs/references/rest-api/objects/cluster/

rrelledge

Thank you! Looks good to me. I just left a couple of comments, but I would ultimately follow Kaitlyn's advice after she has time to review this.

rrelledge · 2026-07-07T15:21:46Z

+You need a RedisEnterpriseCluster (REC) running a version of Redis Enterprise Software that supports SCH:
+
+- Redis Enterprise Software 8.0.2-17 or later for standalone (Enterprise cluster mode) connections.
+- Redis Enterprise Software 8.0.16-29 or later for [OSS Cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}) connections.


On the Redis Software side, we dropped "Enterprise" from the name. But I would go with whatever Kaitlyn thinks is appropriate for the k8s section.

Suggested change

You need a RedisEnterpriseCluster (REC) running a version of Redis Enterprise Software that supports SCH:

- Redis Enterprise Software 8.0.2-17 or later for standalone (Enterprise cluster mode) connections.

- Redis Enterprise Software 8.0.16-29 or later for [OSS Cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}) connections.

You need a RedisEnterpriseCluster (REC) running a version of Redis Software that supports SCH:

- Redis Software 8.0.2-17 or later for standalone (Enterprise cluster mode) connections.

- Redis Software 8.0.16-29 or later for [OSS Cluster API]({{< relref "/operate/rs/databases/configure/oss-cluster-api" >}}) connections.

rrelledge · 2026-07-07T15:22:26Z

+
+To confirm that SCH reduces disruption during maintenance, [upgrade the Redis Enterprise cluster]({{< relref "/operate/kubernetes/upgrade" >}}), which adds and removes nodes as the operator performs a rolling upgrade of the pods.
+
+1. Make sure both the source and target Redis Enterprise Software versions support SCH.


Suggested change

1. Make sure both the source and target Redis Enterprise Software versions support SCH.

1. Make sure both the source and target Redis Software versions support SCH.

rrelledge · 2026-07-07T15:23:16Z

+
+Use the [`/v1/cluster`]({{< relref "/operate/rs/references/rest-api/requests/cluster#put-cluster" >}}) REST API request to enable SCH for both Enterprise cluster mode and OSS Cluster API mode. Set `client_maint_notifications` and `oss_cluster_client_maint_notifications` to `true`.
+
+The following example uses [`curl`](https://curl.se/) and addresses the cluster REST API on port `9443` of the REC service (for example, `rec` in a cluster named `rec`):


Maybe this is just a k8s thing that I'm unfamiliar with, but "for example, rec in a cluster named rec" seems a bit confusing to me.

andy-stark-redis · 2026-07-07T15:26:25Z

Thanks @rrelledge !

kaitlynmichael · 2026-07-17T21:20:18Z

I will have to run this past engineering SMEs. I haven't heard anything about this or if we are supporting it.

The CAE "SCH on Kubernetes - Status of Record" page shows the MONITOR handshake capture was never actually done: the expected handshake strings were inferred from client-side rebind/DEBUG logs (Lettuce INTERNAL_IP, redis-py notification logs), not observed server-side via MONITOR. Reframe the verify section to lead with the confirmed client-log evidence and present the MONITOR handshake as expected behaviour, with MONITOR demoted to a secondary server-side option. Learned: MONITOR handshake was never captured in K8s SCH testing; only client-side DEBUG/rebind evidence exists Gaps: exact MONITOR handshake strings remain unconfirmed server-side (per CAE status-of-record, 2026-07-18) Ticket: DOC-6816 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

andy-stark-redis · 2026-07-20T14:11:55Z

Cross-referenced against the CAE SCH on Kubernetes - Status of Record page (compiled 2026-07-18, evidence-linked to the CAE test pages, #sch-k8s, and Jira). It largely corroborates this PR. Notes for review:

Applied in this PR (commit reframing the verification section): the status-of-record marks both MONITOR handshake captures as NOT DONE — the expected strings were inferred from client-side rebind/DEBUG logs (Lettuce INTERNAL_IP, redis-py notification logs), never observed server-side. The "Verify SCH is active" section now leads with the confirmed client-log evidence and presents the MONITOR handshake as expected behaviour.

Corroborated (raises confidence on an earlier open question): enabling both client_maint_notifications and oss_cluster_client_maint_notifications in one PUT /v1/cluster was tested and both returned true. Still worth an eng confirm on the exact field name/default of oss_cluster_client_maint_notifications and whether a standalone-only cluster on 8.0.2-17 accepts the OSS flag.

Scenario 2 deferral confirmed as correct: external/TLS/name-based is "INVESTIGATED, BLOCKED BY PRODUCT GAPS", not merely unwritten — hostname certs lack IP SANs while CLUSTER SLOTS/SMIGRATED return pod IPs, and DMC hardcodes a nodeN.* prefix (RED-197931, TO DO). Keep it out of scope here.

Follow-up trigger for the REST API workaround: operator PR redis-enterprise-operator#6560 (David Maier) exposes the flags via the REC CRD as maintenanceNotifications.* (epic RED-203631, in review). When that ships, switch the enablement steps from the REST API to the CRD spec.

andy-stark-redis requested review from kaitlynmichael, mortensi and rrelledge July 7, 2026 13:13

andy-stark-redis self-assigned this Jul 7, 2026

andy-stark-redis added k8s clients Client library docs rs Redis Software labels Jul 7, 2026

andy-stark-redis requested review from kaitlynmichael and rrelledge and removed request for kaitlynmichael, mortensi and rrelledge July 7, 2026 14:16

rrelledge approved these changes Jul 7, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

DOC-6816 Document smart client handoffs (SCH) for Redis Enterprise on Kubernetes#3597

DOC-6816 Document smart client handoffs (SCH) for Redis Enterprise on Kubernetes#3597
andy-stark-redis wants to merge 2 commits into
mainfrom
DOC-6816-sch-k-8-s-docs

andy-stark-redis commented Jul 7, 2026 •

edited by cursor Bot

Loading

Uh oh!

CLAassistant commented Jul 7, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 7, 2026 •

edited by atlassian Bot

Loading

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

rrelledge left a comment

Uh oh!

rrelledge Jul 7, 2026

Uh oh!

rrelledge Jul 7, 2026

Uh oh!

rrelledge Jul 7, 2026

Uh oh!

andy-stark-redis commented Jul 7, 2026

Uh oh!

kaitlynmichael commented Jul 17, 2026

Uh oh!

andy-stark-redis commented Jul 20, 2026 •

edited by atlassian Bot

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants


		To confirm that SCH reduces disruption during maintenance, [upgrade the Redis Enterprise cluster]({{< relref "/operate/kubernetes/upgrade" >}}), which adds and removes nodes as the operator performs a rolling upgrade of the pods.

		1. Make sure both the source and target Redis Enterprise Software versions support SCH.


		Use the [`/v1/cluster`]({{< relref "/operate/rs/references/rest-api/requests/cluster#put-cluster" >}}) REST API request to enable SCH for both Enterprise cluster mode and OSS Cluster API mode. Set `client_maint_notifications` and `oss_cluster_client_maint_notifications` to `true`.

		The following example uses [`curl`](https://curl.se/) and addresses the cluster REST API on port `9443` of the REC service (for example, `rec` in a cluster named `rec`):

Uh oh!

Conversation

andy-stark-redis commented Jul 7, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Reviewer questions (need eng sign-off)

Deferred (intentional)

Notes

Uh oh!

CLAassistant commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

rrelledge left a comment

Choose a reason for hiding this comment

Uh oh!

rrelledge Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

rrelledge Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

rrelledge Jul 7, 2026

Choose a reason for hiding this comment

Uh oh!

andy-stark-redis commented Jul 7, 2026

Uh oh!

kaitlynmichael commented Jul 17, 2026

Uh oh!

andy-stark-redis commented Jul 20, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

andy-stark-redis commented Jul 7, 2026 •

edited by cursor Bot

Loading

CLAassistant commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited by atlassian Bot

Loading

andy-stark-redis commented Jul 20, 2026 •

edited by atlassian Bot

Loading