{
  "schema_version": 2,
  "id": "operate/iris/langcache/self-managed/configuration",
  "title": "Configuration",
  "url": "https://redis.io/docs/latest/operate/iris/langcache/self-managed/configuration/",
  "summary": "Configure the LangCache Data Plane, Control Plane, and Identity Service through Helm values and config overlay Secrets.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-09-10T16:06:39+03:00",
  "page_type": "content",
  "content_hash": "3bc3ce7c560a2ddbbb294b8db9447ed08d3a80767132faa8aa0b1e6fd9eead34",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "The `langcache` chart splits configuration into two layers for the Data\nPlane, the Control Plane, and (in bundled mode) the Identity Service:\n\n- **Non-secret structure**, set as Helm values (`dataplane.configData`,\n  `controlplane.configData`, `identityService.bundled.configData`) and\n  rendered into a ConfigMap by default.\n- **Redis URLs, the database registry, and the embedding credential**,\n  which never go in `values.yaml` or a rendered ConfigMap. Each component\n  reads its own pre-created overlay Secret, deep-merged over its rendered\n  base config at container startup. The chart passes each overlay as an\n  additional `--config` flag, so later files win.\n\nYou always create the overlay Secrets yourself; the chart only tells each\ncomponent where to mount and read them."
    },
    {
      "id": "data-plane-overlay",
      "title": "Data Plane overlay",
      "role": "content",
      "text": "Create `dp-overlay.yaml`. Provide Metadata Redis and, when\n`dataplane.embedding.credentials.type: static`, the embedding credential.\nThe Data Plane has no database registry of its own — it resolves each\ncache's Cache Redis target from the `databaseUrls` the Control Plane already\npersisted in Metadata Redis at cache-creation time.\n\n[code example]\n\n[code example]\n\nPoint the chart at it, alongside the public (non-secret) embedding facts:\n\n[code example]"
    },
    {
      "id": "control-plane-overlay",
      "title": "Control Plane overlay",
      "role": "content",
      "text": "Create `cp-overlay.yaml`. Provide the same Metadata Redis as the Data Plane,\nplus the `databases` registry — one entry per Cache Redis target, keyed by a\nlogical ID you choose. The Control Plane never receives an embedding\ncredential; it only needs the public provider/model/dimensions contract\nthat the chart renders from `dataplane.embedding.*`.\n\n[code example]\n\n[code example]\n\n[code example]\n\nThe `databases` map must use the same logical IDs your operators will pass\nas `databaseId` when creating caches through the Control Plane API. The\nchart derives the Control Plane's `embedders` config from\n`dataplane.embedding.provider` and `dataplane.embedding.models.*`. On-prem\ncache creation uses that single provider/model/dimensions contract and\ndoes not accept per-cache embedding credentials."
    },
    {
      "id": "identity-service-metadata-bundled-mode-only",
      "title": "Identity Service metadata (bundled mode only)",
      "role": "content",
      "text": "When `identityService.mode: bundled` is set, the bundled Identity\nService needs its own Metadata Redis connection. This connection can be the same Redis\ninstance as the Control Plane's Metadata Redis, in a separate namespace.\n\n[code example]\n\n[code example]\n\n[code example]\n\nIf you use `identityService.mode: external` instead, there is no Identity\nService overlay to create here; see\n[Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication)."
    },
    {
      "id": "multiple-overlay-secrets",
      "title": "Multiple overlay Secrets",
      "role": "content",
      "text": "`dataplane.secrets.additionalSecrets` and\n`controlplane.secrets.additionalSecrets` accept a list of extra pre-created\nSecret names, layered in order after the primary overlay (later wins). Use\nthis to split, for example, Redis connection details from the embedding\ncredential across separately rotated Secrets."
    },
    {
      "id": "treat-overlay-content-as-sensitive",
      "title": "Treat overlay content as sensitive",
      "role": "content",
      "text": "Store `dp-overlay.yaml`, `cp-overlay.yaml`, and `ids-metadata.yaml` outside\nyour values files and outside git, the same as any other credential\nmaterial."
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "With your overlay Secrets and values ready, continue to\n[Deploy self-managed LangCache](https://redis.io/docs/latest/operate/iris/langcache/self-managed/deploy)."
    }
  ],
  "examples": [
    {
      "id": "data-plane-overlay-ex0",
      "language": "yaml",
      "code": "metadata:\n  urls:\n    - rediss://default:<password>@metadata-redis:6380\n\nembedding:\n  credentials:\n    api_key: \"<embedding-api-key>\"",
      "section_id": "data-plane-overlay"
    },
    {
      "id": "data-plane-overlay-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic dp-overlay \\\n  --from-file=overlay.yaml=./dp-overlay.yaml",
      "section_id": "data-plane-overlay"
    },
    {
      "id": "data-plane-overlay-ex2",
      "language": "yaml",
      "code": "dataplane:\n  secrets:\n    secretName: dp-overlay\n  embedding:\n    provider: openai\n    endpoint:\n      baseURL: https://api.openai.com/v1\n    credentials:\n      type: static\n    models:\n      defaultEmbeddingModel: text-embedding-3-small\n      dimensions: 1536",
      "section_id": "data-plane-overlay"
    },
    {
      "id": "control-plane-overlay-ex0",
      "language": "yaml",
      "code": "metadata:\n  urls:\n    - rediss://default:<password>@metadata-redis:6380\n\ndatabases:\n  cache-primary:\n    name: cache-primary\n    urls:\n      - rediss://default:<password>@cache-primary:6380",
      "section_id": "control-plane-overlay"
    },
    {
      "id": "control-plane-overlay-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic cp-overlay \\\n  --from-file=overlay.yaml=./cp-overlay.yaml",
      "section_id": "control-plane-overlay"
    },
    {
      "id": "control-plane-overlay-ex2",
      "language": "yaml",
      "code": "controlplane:\n  secrets:\n    secretName: cp-overlay\n  configData:\n    profile: prod",
      "section_id": "control-plane-overlay"
    },
    {
      "id": "identity-service-metadata-bundled-mode-only-ex0",
      "language": "yaml",
      "code": "metadata:\n  urls:\n    - rediss://default:<password>@metadata-redis:6380",
      "section_id": "identity-service-metadata-bundled-mode-only"
    },
    {
      "id": "identity-service-metadata-bundled-mode-only-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic ids-metadata \\\n  --from-file=metadata.yaml=./ids-metadata.yaml",
      "section_id": "identity-service-metadata-bundled-mode-only"
    },
    {
      "id": "identity-service-metadata-bundled-mode-only-ex2",
      "language": "yaml",
      "code": "identityService:\n  mode: bundled\n  bundled:\n    metadata:\n      existingSecret: ids-metadata",
      "section_id": "identity-service-metadata-bundled-mode-only"
    }
  ]
}