MOD-17747: Add self-managed LangCache documentation - #3925
Merged
Conversation
|
|
Contributor
🧠 Redis MemoryFound 11 related items from repository history (1 new this commit):
Memory updated at 2a7e460 |
Contributor
mich-elle-luna
requested changes
Sep 4, 2026
mich-elle-luna
left a comment
mich-elle-luna
left a comment
Collaborator
There was a problem hiding this comment.
Thank you! This is looking good so far, just a few small suggestions.
tptodorov
added a commit
that referenced
this pull request
Sep 10, 2026
Applied all 22 inline review suggestions from PR #3925: - _index.md: wording fixes ("faster", "either returns a", "no lighter-weight install of only the Data Plane", period instead of em-dash). - authentication.md: reworded the admin/internal-token-mismatch sentence and the bundled-mode intro; renamed "### Bundled" to "### Bundled Identity Service" (matching "### External Identity Service") with an explicit "choose either ... or ..." lead-in; added the missing article to the external credential sentence; added a "Next steps" section. - configuration.md: split the overlay-mechanism sentence for clarity, reworded the `authorized: true` rule and the bundled Identity Service metadata intro; added a "Next steps" section. - deploy.md: dropped "(by default)"/"(default)" qualifiers now that bundled vs. external is chosen explicitly one section down; added a "Next steps" section. - operations.md: added a "See also" section. - prerequisites.md: dropped the same "(by default)"/"(bundled)" qualifiers; added a "Next steps" section. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
Author
|
Addressed all 22 review comments in ea4ff94:
Ready for another look, @mich-elle-luna 🙏 |
Document LangCache on-prem (self-managed) deployment and usage, based on the self-managed Redis Agent Memory (RAM) docs and verified against the LangCache ADR/TDD, Helm chart, and controlplane-onprem/dataplane source. Adds content/operate/iris/langcache/self-managed/: - _index.md, plan-deployment.md, prerequisites.md - deploy-static.md, deploy-control-plane.md, data-plane-configuration.md - authentication.md - control-plane-api-reference.md + generated openapi-control-plane.json - operations.md, reference.md, api-examples.md Also adds one link from the existing LangCache Cloud index page (content/operate/iris/langcache/_index.md) to the new self-managed section, mirroring the Agent Memory index's "Deployment options" pattern. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- _index.md: split the single Data Plane port entry into static-caches (8080) vs. Control Plane managed caches (9000) — they're different binaries with different defaults, and the single row was misleading. - data-plane-configuration.md: add the required embedding.endpoint.base_url to the Control Plane managed caches example; pkg/inference.Config.Validate requires it for non-noop providers, so the example would fail startup without it. - operations.md: correct the FIPS posture claim. The on-prem-hardened binaries are FIPS-*capable* (GOFIPS140), but ship with runtime FIPS mode off by default (GODEBUG=fips140=off); the strict rediss:// checks are opt-in, not automatic just from using the hardened image. - deploy-control-plane.md: add the missing Secret-mount steps (license, Identity Service introspection token) for the Data Plane, since the config example referenced mount paths the chart doesn't wire up on its own; uses the chart's existing generic volumes/volumeMounts passthrough. - authentication.md: strengthen the Identity Service caveat to note it needs its own control credential, a per-Data-Plane introspection credential, and product wiring — not just one extra container. Found via a Codex content/meaning review of the rendered staging pages, cross-checked against the actual Go source in the iris monorepo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The langcache chart takes dataplane.config.yaml inline as the `config` value, rendered into a ConfigMap — it has no existingSecret/ existingSecretChecksum option for it (that's an RS-Agent-Memory-chart convention I'd copied without checking against this chart's actual values.yaml/configmap.yaml). Corrected across deploy-static.md, deploy-control-plane.md, prerequisites.md, reference.md, and operations.md: - Config is now shown inline under `config:` in the Helm values examples, with an explicit callout that this renders to a ConfigMap (not a Secret) so the values file itself should be treated as sensitive. - License and Identity Service introspection-token files (which the chart doesn't support at all) are now mounted via the chart's generic volumes/volumeMounts passthrough, using dedicated directories (/etc/license, /etc/introspection) instead of subPath mounts into /etc/langcache — subPath mounts don't pick up Secret updates without a pod restart, whole-directory mounts do. - Removed the SHA-256-checksum-based rollout pattern for config/license (it assumed a chart field, existingSecretChecksum, that doesn't exist); replaced with explicit `kubectl rollout restart` guidance for license and introspection-token rotation in operations.md. - Added `nameOverride`/`fullnameOverride: langcache` to the values examples so the chart's actual default resource names (derived from nameOverride=langcache-app) don't silently mismatch the `svc/langcache`, `deploy/langcache`, and `app.kubernetes.io/name=langcache` used throughout the verification commands. - deploy-control-plane.md: added `service.port: 9000` since the managed-cache Data Plane binary's default port doesn't match the chart's default service.port (8080); fixed the intro note, which claimed the page deploys the Identity Service when it doesn't. - authentication.md: `full` grant wording corrected to not imply it grants Control Plane admin API access. - api-examples.md: noted the 8080/9000 port split for static vs. Control-Plane-managed Data Plane calls. Found via a second Codex content/meaning review pass, cross-checked against the actual Go source, Helm chart, and Kubernetes subPath semantics. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…m chart
Static caches / "Data Plane only" self-managed LangCache is no longer a
thing: since MOD-17459 ("Evolve langcache/helm into the canonical LangCache
on-prem chart") and MOD-17460 (removing the on-prem Data Plane's own
database registry), the langcache chart always installs the Data Plane,
Control Plane, and a bundled-or-external Identity Service together. There
is no deployment-mode choice anymore and no supported no-Control-Plane
path — the previous docs described an earlier, now-superseded shape of the
product (a DP-only chart, a hand-rolled CP manifest, no public images).
Rewritten against langcache/helm/{values.yaml,README.md,Chart.yaml},
controlplane-onprem/dataplane on-prem config structs, and
development/langcache/onprem/*.config.yaml at origin/main (HEAD's checkout
of this reference repo was 15 commits behind and missing all of this):
- Removed plan-deployment.md and deploy-static.md — no modes to choose.
- Renamed deploy-control-plane.md -> deploy.md: one `helm install` now
stands up DP+CP+IdS together; no more manual Control Plane Deployment
manifest, the chart templates it.
- Renamed data-plane-configuration.md -> configuration.md: config is now a
values.yaml (non-secret structure) + per-component overlay Secret
(Redis URLs, database registry, embedding credential) split, chart-native
end to end, replacing the old hand-mounted subPath workarounds.
- authentication.md: agent-key auth via Identity Service (bundled or
external) is the only Data Plane auth mode; dropped the legacy
static-cache-token material entirely, since static caches aren't part of
this product's self-managed shape anymore.
- operations.md: rotation now uses the chart's real
`*.existingSecretChecksum` mechanism; added the chart's own FIPS posture,
support bundle, and preflight features, all newly chart-native.
- _index.md/reference.md: updated component list, ports, and images
(redislabs/iris-langcache-data, iris-langcache-control,
iris-identity-service — now published to public Docker Hub, closing the
"no public registry" gap noted in the previous revision).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Verified against the real release: RedisLabs/redis-enterprise-helm now carries ai/charts/langcache (chart v0.0.1, synced from langcache/helm at origin/main — content is byte-identical except default image tags now pinned to 0.0.1 instead of empty), and https://helm.redis.io/ai/index.yaml actually serves a "langcache" entry as of today. This confirms, rather than just infers by analogy with RAM, the chart's public distribution channel. - prerequisites.md/reference.md: state the chart is published to https://helm.redis.io/ai (same repo as self-managed Redis Agent Memory) instead of "contact your Redis representative for exact coordinates." Split the reference.md "contact your rep" row so it only covers the license key now, not chart/image access (both of which are public). - deploy.md/operations.md: install/upgrade/helm-test commands now use `helm repo add redis-ai https://helm.redis.io/ai` + `helm install/upgrade langcache redis-ai/langcache --version <chart-version>`, matching the real, now-public flow, with a note for anyone still installing from a local chart checkout or package instead. No other content changed — the chart's actual config schema, ports, overlay mechanism, and image names documented in the previous revision all matched the published release exactly. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Applied all 22 inline review suggestions from PR #3925: - _index.md: wording fixes ("faster", "either returns a", "no lighter-weight install of only the Data Plane", period instead of em-dash). - authentication.md: reworded the admin/internal-token-mismatch sentence and the bundled-mode intro; renamed "### Bundled" to "### Bundled Identity Service" (matching "### External Identity Service") with an explicit "choose either ... or ..." lead-in; added the missing article to the external credential sentence; added a "Next steps" section. - configuration.md: split the overlay-mechanism sentence for clarity, reworded the `authorized: true` rule and the bundled Identity Service metadata intro; added a "Next steps" section. - deploy.md: dropped "(by default)"/"(default)" qualifiers now that bundled vs. external is chosen explicitly one section down; added a "Next steps" section. - operations.md: added a "See also" section. - prerequisites.md: dropped the same "(by default)"/"(bundled)" qualifiers; added a "Next steps" section. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
tptodorov
force-pushed
the
MOD-17747-langcache-onprem-docs
branch
from
September 10, 2026 12:20
ea4ff94 to
1cdc3aa
Compare
Downloaded the actual published chart tarball (langcache-0.0.1.tgz from the helm.redis.io/ai release) and cross-checked every technical claim in the PR against its templates/_helpers.tpl, values.yaml, and NOTES.txt, plus the identity-service, controlplane-onprem, and dataplane Smithy/Go source at origin/main. Everything else held up exactly as documented (ports, resource names, secret keys, overlay mount paths, FIPS validation messages, the Identity Service's Grant/CreateAPIKey shapes, the internal grant-validation path, and the /health endpoints all matched byte-for-byte or field-for-field). One place was more hedged than it needed to be: operations.md's auto-generated-token rotation guidance said to "confirm which behavior your chart version implements" because I hadn't verified the underlying mechanism. controlplane-secrets.yaml and identity-service-secrets.yaml both show the real mechanism directly: a lookup-or-generate helper that re-reads the existing Secret on every helm upgrade (keeping it stable) plus a helm.sh/resource-policy: keep annotation, so deleting the Secret and re-running helm upgrade does mint a fresh token. Replaced the hedge with that confirmed explanation. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- _index.md: split "Cache entries" table row so flush's real path
(/v1/caches/{cacheId}/flush) isn't implied to live under /entries; added
a note that the shared LangCache API reference doesn't yet cover
conversational search or cache health (confirmed: content/develop/ai/
context-engine/langcache/api-reference/api.yaml only has entries/search,
entries, entries/{entryId}, and flush — both endpoints are real on the
actual Data Plane per the Smithy source, just missing from that shared
spec, which is out of scope to edit here).
- api-examples.md: added a real "Search using conversation history"
example (verified against ConversationalSearchBody/-Output in the DP
Smithy source: prompt, context as chronological turns, actualPrompt in
the response) instead of just claiming conversational search was
covered by a reference that doesn't include it.
- reference.md: replaced a troubleshooting row describing a 400 for
"per-cache embedding fields" on CreateCache — CreateCacheRequestContent
has no embedding-related field at all, so that scenario can't occur as
described. Replaced with the request fields that actually exist and can
fail validation.
- authentication.md: added the missing Secret name and retrieval command
for the Data Plane's own auto-generated Identity Service runtime
credential (langcache-identity-service-dp-credential) — previously
mentioned as existing but never given a name, unlike the other three
auto-generated tokens.
Not changed: the generated openapi-control-plane.json's PATCH /v1/caches
returning 201 with no body. Verified directly against the Smithy source
(@http(method: "PATCH", ..., code: 201), no output) — that's what the real
API does, however unusual; "fixing" it to 200 would misrepresent it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
teoparvanov
approved these changes
Sep 10, 2026
Collaborator
|
Looks good, with the one additional change from Teo and please also sign the license agreement. |
Per teoparvanov's review: conversational search isn't fully supported yet, so remove its coverage from the self-managed LangCache docs for now (_index.md's API surfaces table and component summary, and the api-examples.md endpoint example and its cross-reference note). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Contributor
Author
|
Addressed in 2a7e460: dropped conversational search from the self-managed docs per @teoparvanov's comment — removed it from _index.md's component summary and API surfaces table, and removed the @mich-elle-luna re: the CLA — that's on Todor to sign directly, not something I can do on his behalf. |
Contributor
Author
|
@mich-elle-luna I addressed the comments. Could you please proceed with publishing. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents LangCache on-prem (self-managed) deployment and usage, per MOD-17747, based on the self-managed Redis Agent Memory (RAM) docs and verified against the LangCache Helm chart and source in the
irismonorepo (read-only reference, not part of this repo).Adds
content/operate/iris/langcache/self-managed/:_index.md,prerequisites.md,deploy.md,configuration.mdauthentication.mdcontrol-plane-api-reference.md+ a generatedopenapi-control-plane.json(built from the LangCache Control Plane's own Smithy API via the repo's own Smithy build, not hand-written)operations.md,reference.md,api-examples.mdAlso adds one link from the existing LangCache Cloud index page to the new self-managed section, mirroring the "Deployment options" pattern already used on Agent Memory's index page.
Latest update
Pushed
a64b87d47to address the 2026-09-10 deep-review findings:controlplane.configData.embeddersexamples and documenteddataplane.embedding.*as the Helm source of truth for provider, model, and dimensionsdefaultTtlMillis: 0Validation:
git diff --checkjq empty content/operate/iris/langcache/self-managed/control-plane-api-reference/openapi-control-plane.jsonhugois not installed on this PATH; GitHubbuild_docsis re-running on the pushed branch.Structural decision: where the docs live
The ticket's recommended default was
content/operate/iris/langcache/self-managed/*, mirroring Agent Memory's current (post-move) location. While investigating, I found the LangCache Cloud page had already been moved tocontent/operate/iris/langcache/_index.md(the oldrc/context-engine/langcachepath is now just a redirect stub) — so I used that clearer, already-established precedent: the new docs sit atcontent/operate/iris/langcache/self-managed/*, a sibling of the migrated Cloud page, exactly mirroringcontent/operate/iris/agent-memory/self-managed/*.What this product actually looks like today (verified against the real 0.0.1 release)
The self-managed LangCache product moved fast underneath this PR — twice. My first pass documented a Data-Plane-only Helm chart with a hand-rolled Control Plane manifest and no public registry; that was accurate for the code at the time, but superseded within the same work window by MOD-17459 ("Evolve
langcache/helminto the canonical LangCache on-prem chart") and MOD-17460 (removing the on-prem Data Plane's own database registry). I rewrote the docs against that.Then an actual chart release shipped (
langcachechart v0.0.1), and I re-verified everything against the real, live artifacts rather than the reference repo alone:https://helm.redis.io/ai/index.yamlnow genuinely serveslangcache(confirmed live, not inferred) — same public Helm repository as self-managed Redis Agent Memory.deploy.mdandoperations.mdnow use the realhelm repo add redis-ai https://helm.redis.io/ai/helm install langcache redis-ai/langcache --version <chart-version>flow instead of a "contact your Redis rep for coordinates" placeholder.RedisLabs/redis-enterprise-helm(ai/charts/langcache) is byte-identical to what's in theirismonorepo'slangcache/helm/, except default image tags are now pinned to0.0.1— so everything else I'd already documented (config schema, overlay-Secret mechanism, ports, image names, FIPS/support-bundle/preflight behavior) needed no changes.redislabs/iris-langcache-data,-control, andiris-identity-service) — confirmed via Docker Hub's public API, no auth needed. Splitreference.md's "contact your Redis representative" row so it only covers the license key now, not chart/image access.One deliberate simplification, per explicit instruction mid-review: static caches / "Data Plane only" self-managed LangCache isn't a real deployment shape for this product (the chart always installs Data Plane + Control Plane + Identity Service together), so that material was dropped entirely rather than kept as a stale "also supported" path — including the legacy per-cache token auth mode, which doesn't exist for this product's self-managed form.
Verification approach
Every config key, endpoint, port, and Secret/resource name in these docs was checked against
langcache/helm/values.yamlandREADME.md, the Go config-validation source for the Control Plane and Data Plane, the Control Plane's Smithy API (and its generated OpenAPI, shipped as-is rather than hand-written), the real dev-stack config files underdevelopment/langcache/onprem/, and — for this latest revision — the actual published chart and Docker Hub images. Two rounds of a Codex content/meaning review against the rendered staging pages also caught and fixed several bugs earlier in this PR (wrong default port, a missing required config field, an incorrect FIPS claim, and a Helm chart-value convention copied from RAM that didn't actually exist in LangCache's chart at the time).🤖 Generated with Claude Code
Note
Low Risk
Documentation-only changes with no application code, auth, or data-path modifications.
Overview
Adds a full self-managed LangCache doc tree under
content/operate/iris/langcache/self-managed/, mirroring the Redis Agent Memory on-prem pattern. The LangCache on Redis Cloud index now links to this section as an alternative deployment path.The new guides cover the canonical
langcacheHelm chart install (Data Plane, Control Plane, and bundled or external Identity Service), overlay Secrets for Redis and embeddings, agent-key auth via Identity Service, Helm deploy/upgrade fromhttps://helm.redis.io/ai, operations (backups, secret rotation, FIPS posture, support bundles), curl API examples, and a Control Plane OpenAPI reference (openapi-control-plane.json). Docs state that embedding provider/model/dimensions come fromdataplane.embedding.*, not per-cache Control Plane fields, and that there is no Data-Plane-only self-managed install.Reviewed by Cursor Bugbot for commit 2a7e460. Bugbot is set up for automated code reviews on this repo. Configure here.