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 impact; the new REST field description may need engineering confirmation of name and default.

Overview
Documents smart client handoffs (SCH) for Redis Software on Kubernetes, replacing the prior “not supported” stance in the client overview.

Adds smart-client-handoffs.md with end-to-end guidance: version prerequisites, enabling clientMaintenanceNotifications on the REC (proxyMode / ossMode), how the operator owns those settings, in-cluster client connectivity (including internal-ip vs none), and how to verify SCH via client debug logs and during a rolling upgrade.

Updates the Kubernetes networking index with a SCH section and links, and extends the cluster REST API reference with oss_cluster_client_maint_notifications. External TLS / name-based access is explicitly out of scope on the new page.

^{Reviewed by Cursor Bugbot for commit f412d94. 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.

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.

zcahana · 2026-07-29T06:57:29Z

+
+You can also observe the handshake server-side with the [`MONITOR`]({{< relref "/commands/monitor" >}}) command.
+
+## Validate SCH during an upgrade


For validation purposes, I think it's better to initiate an endpoint rebind via rladmin, and not go through a full rolling upgrade - at least not as a first validation step.
@dmaier-redislabs can you please confirm whether this is a sufficient validation approach?

To add a rebind as the first check, which rladmin bind endpoint form should the docs use: exclude, include, or policy? exclude forces the endpoint to move but leaves a persistent configuration change.

zcahana · 2026-07-29T07:09:59Z

+
+[Smart client handoffs]({{< relref "/develop/clients/sch" >}}) (SCH) let a Redis Enterprise cluster notify clients about planned maintenance shortly before it happens, so clients can reconnect or otherwise respond gracefully without significant interruptions in service. SCH is primarily useful during server software or hardware upgrades, where it provides *relaxed timeouts* and transparent *pre-handoffs* to new endpoints. See [Smart client handoffs]({{< relref "/develop/clients/sch" >}}) for a full description of the feature.
+
+This page describes how to enable SCH for a Redis Enterprise cluster (REC) running on Kubernetes when your application and the cluster run within the same Kubernetes pod network, using IP-based access without TLS. External access over TLS with name-based addressing is not yet covered.


Beyond describing how to enable SCH, I think it would be useful if we include usage guidelines, and particularly with the aspects that are specific to K8s - connecting (seed address) via a ClusterIP or Headless service, or just directly using pod IPs (less common I suppose, and not recommended); how to use the different endpoint types (none vs internal-ip) and what SCH will provide with each type.

Unfortunately, I'm not an SME on that topic, and hopefully @dmaier-redislabs can chime in about what would be important to document. There's also this doc describing testing that was done, probably a good starting point.

github-actions · 2026-10-15T19:47:43Z

🧠 Redis Memory

Found 5 related items from repository history:

PR — DOC-7027 Document StackExchange.Redis smart client handoffs (3.3.0)

Summary
PR — DOC-7177 Document ioredis smart client handoffs (SCH) [PARKED]

Documents smart client handoffs (SCH) for ioredis, added in v6.1.0-beta.1 by
Commit — DOC-7177 Document ioredis smart client handoffs (SCH)

DOC-7177 Document ioredis smart client handoffs (SCH)
PR — K8s: Document disconnectClientsOnPasswordRemoval (RED-197499)

Summary
PR — DOC-6564 updated RS SCH support info

Updated the info about RS support for Smart client handoffs for consistency.

Memory updated at f412d94

cursor

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, have a team admin enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e491471. Configure here.}

cursor · 2026-10-15T20:13:19Z

+
+[Smart client handoffs]({{< relref "/develop/clients/sch" >}}) (SCH) let a Redis Enterprise cluster notify clients about planned maintenance shortly before it happens, so clients can reconnect or otherwise respond gracefully without significant interruptions in service. SCH is primarily useful during server software or hardware upgrades, where it provides *relaxed timeouts* and transparent *pre-handoffs* to new endpoints. See [Smart client handoffs]({{< relref "/develop/clients/sch" >}}) for a full description of the feature.
+
+This page describes how to enable SCH for a Redis Enterprise cluster (REC) running on Kubernetes when your application and the cluster run within the same Kubernetes pod network, using IP-based access without TLS. External access over TLS with name-based addressing is not yet covered.


Scope note forecasts later TLS support

Low Severity

The scope sentence says external TLS and name-based access is not yet covered, which implies later support. This violates the Kubernetes AGENTS.md rule to document current behavior only and not foreshadow planned support.

^{Reviewed by Cursor Bugbot for commit e491471. Configure here.}

kaitlynmichael

I've added a few commits with Rachel and Zvi's suggestions and I think its ready to merge into the release-k8s-eden branch for next week's release.

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

zcahana reviewed Jul 29, 2026

View reviewed changes

kaitlynmichael added do not merge yet next release labels Sep 11, 2026

github-actions Bot mentioned this pull request Sep 18, 2026

DOC-7027 Document StackExchange.Redis smart client handoffs (3.3.0) #4047

Merged

1 of 2 tasks

This was referenced Oct 13, 2026

DOC-7177 Document ioredis smart client handoffs (SCH) [PARKED] #4252

Open

K8s: Gateway API routing (eden release) #4277

Open

Merge remote-tracking branch 'origin/main' into DOC-6816-sch-k-8-s-docs

0db2c8c

Enable K8s SCH with the REC CRD field instead of the REST API

e491471

cursor Bot reviewed Oct 15, 2026

View reviewed changes

Rename to Redis Software and cut unverified MONITOR check

f412d94

kaitlynmichael changed the base branch from main to release-k8s-eden October 15, 2026 20:30

kaitlynmichael approved these changes Oct 15, 2026

View reviewed changes


		You can also observe the handshake server-side with the [`MONITOR`]({{< relref "/commands/monitor" >}}) command.

		## Validate SCH during an upgrade


		[Smart client handoffs]({{< relref "/develop/clients/sch" >}}) (SCH) let a Redis Enterprise cluster notify clients about planned maintenance shortly before it happens, so clients can reconnect or otherwise respond gracefully without significant interruptions in service. SCH is primarily useful during server software or hardware upgrades, where it provides relaxed timeouts and transparent pre-handoffs to new endpoints. See [Smart client handoffs]({{< relref "/develop/clients/sch" >}}) for a full description of the feature.

		This page describes how to enable SCH for a Redis Enterprise cluster (REC) running on Kubernetes when your application and the cluster run within the same Kubernetes pod network, using IP-based access without TLS. External access over TLS with name-based addressing is not yet covered.

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!

Uh oh!

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!

zcahana Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

kaitlynmichael Oct 15, 2026

Choose a reason for hiding this comment

Uh oh!

zcahana Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

🧠 Redis Memory

Summary

Summary

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cursor Bot Oct 15, 2026

Choose a reason for hiding this comment

Scope note forecasts later TLS support

Uh oh!

kaitlynmichael left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 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

github-actions Bot commented Oct 15, 2026 •

edited

Loading