{ "schema_version": 2, "id": "operate/iris/langcache/self-managed/prerequisites", "title": "Self-managed LangCache prerequisites", "url": "https://redis.io/docs/latest/operate/iris/langcache/self-managed/prerequisites/", "summary": "Review software, Redis, network, Secret, image, and sizing prerequisites for self-managed LangCache.", "tags": [ "docs", "operate", "iris" ], "last_updated": "2026-09-10T16:06:39+03:00", "page_type": "content", "content_hash": "5e255d0f7d654d37eac0934be5241c99f398c2c92fa6ee2cde53367fee4b3e48", "sections": [ { "id": "overview", "title": "Overview", "role": "overview", "text": "LangCache self-managed is distributed as container images on Docker Hub plus\nthe `langcache` Helm chart. One `helm install` of the chart deploys the\nLangCache Data Plane, the LangCache Control Plane, and either a bundled\nIdentity Service or a connection to an external Identity Service.\n\nYou provide the Redis databases, embedding provider credentials, Kubernetes\nexposure, and license material used by the deployment.\n\n\nThis guide is for system administrators deploying LangCache on a self-managed\nKubernetes cluster." }, { "id": "what-you-need", "title": "What you need", "role": "content", "text": "| Item | Where it comes from |\n| ---- | ------------------- |\n| Container images | `redislabs/iris-langcache-data`, `redislabs/iris-langcache-control`, and (bundled Identity Service) `redislabs/iris-identity-service` on Docker Hub |\n| Helm chart | `langcache` chart, published to `https://helm.redis.io/ai` (the same repository as the self-managed Redis Agent Memory chart), or a chart package provided by Redis. |\n| Redis databases | You provide Metadata Redis and one or more Cache Redis databases |\n| License key | Contact your Redis representative or [contact sales](https://redis.io/contact/). |\n| Provider credentials | You provide embedding provider credentials (currently an OpenAI-compatible provider) |" }, { "id": "required-software", "title": "Required software", "role": "content", "text": "| Software | Minimum version | Purpose |\n| -------- | --------------- | ------- |\n| Kubernetes | 1.23+ | Orchestration; the chart renders an `autoscaling/v2` HorizontalPodAutoscaler |\n| kubectl | 1.23+ | Kubernetes CLI |\n| Helm | 3.x | Package manager |" }, { "id": "redis-databases", "title": "Redis databases", "role": "content", "text": "The Helm chart does not deploy Redis databases. Provision them outside the\nchart and register them through the Control Plane's and Data Plane's config\noverlays (see [Configuration](https://redis.io/docs/latest/operate/iris/langcache/self-managed/configuration)).\n\nCache Redis must support RediSearch with vector search, because LangCache\ncreates a RediSearch vector index per cache. Metadata Redis does not need\nthat capability.\n\n| Redis database | Required | Registered in | Purpose |\n| --- | --- | --- | --- |\n| Metadata Redis | Always | Both the Data Plane's and Control Plane's config overlays (same URLs, same keyspace) | Cache records written by the Control Plane, read by the Data Plane. |\n| Cache Redis (one or more) | Always | The Control Plane's config overlay only, as a `databases` registry entry keyed by a logical `databaseId` | Cache entry hashes and RediSearch vector indexes. The Data Plane has no database registry of its own — it resolves each cache's Redis URLs from the metadata the Control Plane already persisted at cache-creation time. |\n| Identity Service metadata Redis (bundled mode only) | When `identityService.mode: bundled` | The bundled Identity Service's own config overlay | Agent-key and grant records. Can be the same Redis instance as Metadata Redis, in a separate namespace. |\n\nFor a lab deployment, these Redis roles can point at the same Redis endpoint\nif it has the required modules and capacity. For production, separate them\nso cache data and control metadata can be scaled, backed up, and operated\nindependently." }, { "id": "metadata-redis-durability", "title": "Metadata Redis durability", "role": "content", "text": "Metadata Redis is small compared with Cache Redis, but it is operationally\ncritical. Use persistent storage, Redis authentication, network isolation,\nand TLS where required. Avoid eviction of metadata keys; losing metadata\nremoves Control Plane cache records." }, { "id": "network-access", "title": "Network access", "role": "content", "text": "- **Connected install:** the cluster must be able to pull the LangCache and\n Identity Service images from Docker Hub (or your mirrored registry) and\n reach `https://helm.redis.io/ai`.\n- **Air-gapped install:** mirror the images into an internal registry and\n use a locally downloaded chart package.\n- **Runtime access:** LangCache pods must reach the Redis databases and the\n embedding provider endpoint used by the deployment. The Data Plane must\n also reach the Identity Service (bundled or external); the Control Plane\n must reach Metadata Redis and every registered Cache Redis database.\n- **Data Plane exposure:** use NetworkPolicy, ingress, gateway, service mesh,\n private load balancer, or equivalent controls to restrict API access." }, { "id": "credentials-and-secrets", "title": "Credentials and Secrets", "role": "content", "text": "The chart never puts Redis URLs, the database registry, or the embedding\ncredential in `values.yaml` or a rendered ConfigMap. Each of the Data Plane,\nControl Plane, and bundled Identity Service reads its own pre-created\noverlay Secret, deep-merged over its rendered base config at runtime. See\n[Configuration](https://redis.io/docs/latest/operate/iris/langcache/self-managed/configuration)\nfor the overlay content each component expects.\n\n| Secret | Required when | Default key |\n| --- | --- | --- |\n| LangCache license Secret | Always | `license` |\n| Data Plane config overlay Secret | Always | `overlay.yaml` |\n| Control Plane config overlay Secret | Always | `overlay.yaml` |\n| Identity Service metadata Secret | `identityService.mode: bundled` | `metadata.yaml` |\n| Control Plane admin token | Auto-generated by default, or bring your own | `token` |\n| Control Plane internal (grant-validation) token | Auto-generated by default, or bring your own | `token` |\n| Identity Service control token (bundled mode) | Auto-generated by default, or bring your own | `token` |\n| Data Plane's Identity Service runtime credential (external mode) | `identityService.mode: external` | `token`, minted by the suite-level Identity Service owner |" }, { "id": "release-artifacts-and-image-tags", "title": "Release artifacts and image tags", "role": "content", "text": "LangCache self-managed image tags use the release SemVer value, for example:\n\n[code example]\n\nUse the image tags listed for the release on Docker Hub or provided by\nRedis. Do not use floating image tags in production." }, { "id": "air-gapped-and-private-registry-installs", "title": "Air-gapped and private registry installs", "role": "content", "text": "Mirror the published images into your internal registry:\n\n[code example]\n\nIf the registry requires authentication, create an image pull Secret and\nreference it from `imagePullSecrets` in your values file:\n\n[code example]\n\n[code example]" }, { "id": "system-requirements", "title": "System requirements", "role": "content", "text": "Default chart values:\n\n| Component | Default | Purpose |\n| --------- | ------- | ------- |\n| LangCache Data Plane | 2 replicas with autoscaling enabled (2–10) | Data Plane API traffic |\n| LangCache Control Plane | 1 replica, no autoscaling | Admin API for caches |\n| Identity Service (bundled mode) | 1 replica | Agent-key issuance and introspection |\n\nDuring a rolling update, Kubernetes may temporarily run old and new pods at\nthe same time. A small test cluster can run out of CPU during install or\nupgrade; size for the maximum rolling-update overlap, or reduce replicas\nexplicitly for a lab install." }, { "id": "helm-values-to-review", "title": "Helm values to review", "role": "content", "text": "The walkthroughs in this guide assume the chart's default\n`fullnameOverride: langcache`, which fixes the rendered resource names to\n`langcache` (Data Plane), `langcache-controlplane`, and\n`langcache-identity-service` (bundled mode). If you change it, update the\nrelease-derived names in the verification commands throughout this guide.\n\n| Area | Values | Use when |\n| --- | --- | --- |\n| Images | `dataplane.image.*`, `controlplane.image.*`, `identityService.bundled.image.*`, `imagePullSecrets` | Selecting a release or private registry image. |\n| Data Plane capacity | `dataplane.resources`, `dataplane.autoscaling.*` | Tuning request capacity or memory footprint. |\n| Networking | `dataplane.service.*`, `dataplane.ingress.*` | Exposing LangCache outside the cluster. |\n| Security posture | `security.profile` | Opting into the FIPS-oriented posture. |\n| Identity Service mode | `identityService.mode` (`bundled` or `external`) | Choosing whether this release runs its own Identity Service or joins one the suite already runs. |\n| Config overlays | `dataplane.secrets.*`, `controlplane.secrets.*`, `identityService.bundled.metadata.*` | Pointing the chart at your pre-created overlay Secrets. |\n| Rotation | `*.existingSecretChecksum` fields throughout | Rolling pods after an externally managed Secret changes. |" }, { "id": "next-steps", "title": "Next steps", "role": "content", "text": "Continue to [Configuration](https://redis.io/docs/latest/operate/iris/langcache/self-managed/configuration)\nto prepare the Data Plane, Control Plane, and Identity Service overlay\nSecrets, then [Deploy self-managed LangCache](https://redis.io/docs/latest/operate/iris/langcache/self-managed/deploy)." } ], "examples": [ { "id": "release-artifacts-and-image-tags-ex0", "language": "yaml", "code": "dataplane:\n image:\n repository: redislabs/iris-langcache-data\n tag: \"\"\ncontrolplane:\n image:\n repository: redislabs/iris-langcache-control\n tag: \"\"\nidentityService:\n bundled:\n image:\n repository: redislabs/iris-identity-service\n tag: \"\"", "section_id": "release-artifacts-and-image-tags" }, { "id": "air-gapped-and-private-registry-installs-ex0", "language": "bash", "code": "for image in iris-langcache-data iris-langcache-control iris-identity-service; do\n docker pull redislabs/$image:\n docker tag redislabs/$image: \\\n registry.example.com/redislabs/$image:\n docker push registry.example.com/redislabs/$image:\ndone", "section_id": "air-gapped-and-private-registry-installs" }, { "id": "air-gapped-and-private-registry-installs-ex1", "language": "bash", "code": "kubectl -n create secret docker-registry langcache-registry \\\n --docker-server=registry.example.com \\\n --docker-username= \\\n --docker-password=", "section_id": "air-gapped-and-private-registry-installs" }, { "id": "air-gapped-and-private-registry-installs-ex2", "language": "yaml", "code": "imagePullSecrets:\n - name: langcache-registry", "section_id": "air-gapped-and-private-registry-installs" } ] }