MOD-17747: Add self-managed LangCache documentation - #3925
Open
tptodorov wants to merge 4 commits into
Open
Conversation
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>
|
|
Contributor
🧠 Redis MemoryFound 8 related items from repository history (1 new this commit):
Memory updated at ad5c284 |
Contributor
- _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>
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.
| hideListLinks: true | ||
| --- | ||
|
|
||
| LangCache is a semantic caching service that stores LLM responses for fast, |
Collaborator
There was a problem hiding this comment.
Suggested change
| LangCache is a semantic caching service that stores LLM responses for fast, | |
| LangCache is a semantic caching service that stores LLM responses for faster, |
| --- | ||
|
|
||
| LangCache is a semantic caching service that stores LLM responses for fast, | ||
| cheaper retrieval. Applications send prompts to LangCache, which returns a |
Collaborator
There was a problem hiding this comment.
Suggested change
| cheaper retrieval. Applications send prompts to LangCache, which returns a | |
| cheaper retrieval. Applications send prompts to LangCache, which either returns a |
|
|
||
| One `helm install` of the `langcache` chart always creates the Data Plane and | ||
| the Control Plane, plus either a bundled or an external Identity Service. | ||
| There is no lighter-weight "Data Plane only" install for self-managed |
Collaborator
There was a problem hiding this comment.
Suggested change
| There is no lighter-weight "Data Plane only" install for self-managed | |
| There is no lighter-weight install of only the Data Plane for self-managed |
| One `helm install` of the `langcache` chart always creates the Data Plane and | ||
| the Control Plane, plus either a bundled or an external Identity Service. | ||
| There is no lighter-weight "Data Plane only" install for self-managed | ||
| LangCache — every cache is created and managed through the Control Plane, and |
Collaborator
There was a problem hiding this comment.
Suggested change
| LangCache — every cache is created and managed through the Control Plane, and | |
| LangCache. Every cache is created and managed through the Control Plane, and |
| (see [External Identity Service](#external-identity-service)). | ||
|
|
||
| The admin token and internal token must always be different values; the | ||
| Control Plane rejects config where they match. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Control Plane rejects config where they match. | |
| Control Plane rejects a configuration where admin token and internal token match. |
| --namespace <namespace-name> \ | ||
| -f langcache-values.yaml \ | ||
| --atomic --wait | ||
| ``` |
Collaborator
There was a problem hiding this comment.
add a next steps section
| directly. Write a NetworkPolicy for your cluster's CNI that default-denies | ||
| ingress to the `langcache`, `langcache-controlplane`, and (bundled mode) | ||
| `langcache-identity-service` Services, then allow TCP traffic on their | ||
| respective ports (`9000`, `9100`, `9200`) from approved callers only. |
Collaborator
There was a problem hiding this comment.
maybe a see also section here for links to info about backups how tos?
|
|
||
| LangCache self-managed is distributed as container images on Docker Hub plus | ||
| the `langcache` Helm chart. One `helm install` of the chart deploys the | ||
| LangCache Data Plane, the LangCache Control Plane, and (by default) a |
Collaborator
There was a problem hiding this comment.
Suggested change
| LangCache Data Plane, the LangCache Control Plane, and (by default) a | |
| LangCache Data Plane, the LangCache Control Plane, and a |
|
|
||
| The chart never puts Redis URLs, the database registry, or the embedding | ||
| credential in `values.yaml` or a rendered ConfigMap. Each of the Data Plane, | ||
| Control Plane, and (bundled) Identity Service reads its own pre-created |
Collaborator
There was a problem hiding this comment.
Suggested change
| Control Plane, and (bundled) Identity Service reads its own pre-created | |
| Control Plane, and bundled Identity Service reads its own pre-created |
| | Identity Service mode | `identityService.mode` (`bundled` or `external`) | Choosing whether this release runs its own Identity Service or joins one the suite already runs. | | ||
| | Config overlays | `dataplane.secrets.*`, `controlplane.secrets.*`, `identityService.bundled.metadata.*` | Pointing the chart at your pre-created overlay Secrets. | | ||
| | Rotation | `*.existingSecretChecksum` fields throughout | Rolling pods after an externally managed Secret changes. | | ||
| {{< /table-scrollable >}} |
Collaborator
There was a problem hiding this comment.
add the next steps here
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
3 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.
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 (this took two passes to get right)
The self-managed LangCache product moved fast underneath this PR. My first pass (based on the state of the
irisreference repo when I started) documented a Data-Plane-only Helm chart with a hand-rolled Control Plane Kubernetes manifest, a legacy per-cache token auth mode, and no public image/chart registry — all accurate at the time, but superseded within the same work window by two upstream changes: MOD-17459 ("Evolvelangcache/helminto the canonical LangCache on-prem chart") and MOD-17460 (removing the on-prem Data Plane's own database registry).The docs now reflect the current shape, verified against
langcache/helm/{values.yaml,README.md,Chart.yaml}, the on-prem config structs incontrolplane-onprem/dataplane, and the real example configs indevelopment/langcache/onprem/*.config.yaml:helm installdeploys everything. The chart always installs the Data Plane, Control Plane, and either a bundled or an external Identity Service — there's no lighter-weight "Data Plane only" mode anymore, and no manual Kubernetes manifest needed for the Control Plane (the chart templates it now).subPath-mount workarounds entirely.redislabs/iris-langcache-data,redislabs/iris-langcache-control, andredislabs/iris-identity-servicepublish to Docker Hub, and the chart syncs to the Redis Enterprise Helm chart repo (ai/charts/langcache) the same way RAM's chart does. This closes the "no public registry" gap flagged in my first pass.security.profile: fips,supportPackage.enabled,preflight.enabled) — documented inoperations.md.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), and the real dev-stack config files underdevelopment/langcache/onprem/. Two rounds of a Codex content/meaning review against the rendered staging pages also caught and fixed several bugs before this rewrite superseded them (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 then-current chart).One inference I couldn't directly verify: the published Helm chart's exact repository coordinates (
prerequisites.mdsays "contact your Redis representative" rather than guessing a specifichelm repo addURL) — the sync target isRedisLabs/redis-enterprise-helmatai/charts/langcache, and by analogy with RAM'sredis-ai/redis-agent-memoryfromhttps://helm.redis.io/ai, it's very likelyredis-ai/langcachefrom the same repo, but I didn't have a way to confirm the live Helm repo index from this environment, so I left it as a contact-your-rep pointer rather than asserting a specific chart ref.🤖 Generated with Claude Code