{
  "schema_version": 2,
  "id": "operate/iris/langcache/self-managed/deploy",
  "title": "Deploy self-managed LangCache",
  "url": "https://redis.io/docs/latest/operate/iris/langcache/self-managed/deploy/",
  "summary": "Deploy self-managed LangCache with the langcache Helm chart.",
  "tags": [
    "docs",
    "operate",
    "iris"
  ],
  "last_updated": "2026-10-06T12:03:53+03:00",
  "page_type": "content",
  "content_hash": "3f4b77bd94c6bcc54dff16fd9257e6bf28d05d268c4b2b14257feb847af20112",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "One `helm install` of the `langcache` chart deploys the Data Plane, the\nControl Plane, and either a bundled Identity Service or a connection to an\nexternal Identity Service. There is no separate lighter-weight install\npath; every self-managed LangCache deployment uses the Data Plane, Control\nPlane, and one Identity Service mode.\n\nBefore you begin, review [prerequisites](https://redis.io/docs/latest/operate/iris/langcache/self-managed/prerequisites)\nand prepare the config overlays described in\n[Configuration](https://redis.io/docs/latest/operate/iris/langcache/self-managed/configuration).\n\nYou use three credentials along the way: the Control Plane admin token, the Identity Service\ncontrol token, and an agent key. The chart generates the first two. For what each credential\nunlocks, see [Credentials](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication#credentials)."
    },
    {
      "id": "choose-an-identity-service-mode",
      "title": "Choose an Identity Service mode",
      "role": "content",
      "text": "Decide before you install:\n\n| Mode | Use when | Values |\n| --- | --- | --- |\n| Bundled | This is your first LangCache install, or your suite doesn't already run an Identity Service. | `identityService.mode: bundled` |\n| External | Your suite already runs an Identity Service (for example, alongside self-managed Redis Agent Memory) and you want LangCache to share it. | `identityService.mode: external` |\n\nThis guide uses bundled mode. For external mode, see\n[Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication#external-identity-service)\nfor the values and the coordination required with the Identity Service's\nowner."
    },
    {
      "id": "create-the-namespace",
      "title": "Create the namespace",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "create-the-required-secrets",
      "title": "Create the required Secrets",
      "role": "content",
      "text": "Create the license Secret, shared by the Data Plane and Control Plane:\n\n[code example]\n\nCreate the config overlay Secrets described in\n[Configuration](https://redis.io/docs/latest/operate/iris/langcache/self-managed/configuration):\n\n[code example]"
    },
    {
      "id": "create-helm-values",
      "title": "Create Helm values",
      "role": "content",
      "text": "Create `langcache-values.yaml`:\n\n[code example]\n\nThis is a minimal complete install. `controlplane.adminToken`,\n`controlplane.internalToken`, and `identityService.bundled.controlToken`\nall default to `autoGenerate: true`, so the chart mints those tokens for\nyou on first install; see\n[Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication)\nto retrieve them, or set `existingSecret` to bring your own.\n\nThe chart renders the Control Plane's embedding contract from\n`dataplane.embedding.*`, so set the provider, model, and dimensions only\nunder `dataplane.embedding`."
    },
    {
      "id": "before-you-install-check-your-values",
      "title": "Before you install: check your values",
      "role": "content",
      "text": "Check each item before you install and before you mint a key. If one is wrong, you see the symptom\nin its row. The rows are checklist items LC-CL-1 to LC-CL-3.\n\n| Row | Check | Symptom | Fix |\n| --- | --- | --- | --- |\n| <a id=\"lc-cl-1\"></a>LC-CL-1 | No image tag is set, or it exists on Docker Hub (`0.0.1` is the only published tag) | With `--atomic --wait`: `Error: INSTALLATION FAILED: release langcache failed, and has been uninstalled due to atomic being set: context deadline exceeded` after the wait times out; `kubectl get events` keeps `Failed to pull image \"redislabs/iris-langcache-data:1.0.0\": … not found` (also `-control`, `iris-identity-service`) | Remove `*.image.tag` |\n| <a id=\"lc-cl-2\"></a>LC-CL-2 | The Identity Service is reachable before you mint a key | `curl: (7) Failed to connect to localhost port 9200 after 0 ms: Couldn't connect to server` | Port-forward `svc/langcache-identity-service 9200:9200`, as in [Verify the deployment](#verify-the-deployment) |\n| <a id=\"lc-cl-3\"></a>LC-CL-3 | Every attribute you send was listed in `attributes` when the cache was created | `400`, `\"detail\":\"attributes: no attributes are configured for this cache.\"` | Create the cache with the attribute names, for example `\"attributes\": [\"topic\"]` |"
    },
    {
      "id": "install-the-chart",
      "title": "Install the chart",
      "role": "setup",
      "text": "Add the Helm repository when installing from the public repository:\n\n[code example]\n\nInstall with `langcache` as the Helm release name:\n\n[code example]\n\nIf you installed from a chart package or a local checkout instead, replace\n`redis-ai/langcache --version 0.0.1` with the chart path (for\nexample `.` from the chart's own root directory).\n\nOn small clusters, install without `--atomic --wait`, then watch pod\nstatus:\n\n[code example]"
    },
    {
      "id": "verify-the-deployment",
      "title": "Verify the deployment",
      "role": "content",
      "text": "[code example]\n\nPort-forward the Data Plane:\n\n[code example]\n\n[code example]\n\nPort-forward the Control Plane:\n\n[code example]\n\nRetrieve the auto-generated admin token, then create your first cache:\n\n[code example]\n\n[code example]\n\nPort-forward the Identity Service (bundled mode):\n\n[code example]\n\nRetrieve the auto-generated Identity Service control token:\n\n[code example]\n\nFor the full self-managed admin API schema, see the\n[Control Plane API reference](https://redis.io/docs/latest/operate/iris/langcache/self-managed/control-plane-api-reference).\n\nNext, mint an agent key through the Identity Service and start calling the\nData Plane; see\n[Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication)\nand [API examples](https://redis.io/docs/latest/operate/iris/langcache/self-managed/api-examples)."
    },
    {
      "id": "update",
      "title": "Update",
      "role": "content",
      "text": "[code example]"
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "- [Authentication and authorization](https://redis.io/docs/latest/operate/iris/langcache/self-managed/authentication) to mint agent keys and configure the Identity Service mode you chose.\n- [API examples](https://redis.io/docs/latest/operate/iris/langcache/self-managed/api-examples) to start calling the Data Plane.\n- [Operations](https://redis.io/docs/latest/operate/iris/langcache/self-managed/operations) for backups, secret rotation, and FIPS posture."
    }
  ],
  "examples": [
    {
      "id": "create-the-namespace-ex0",
      "language": "bash",
      "code": "kubectl create namespace <namespace-name>",
      "section_id": "create-the-namespace"
    },
    {
      "id": "create-the-required-secrets-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic langcache-license \\\n  --from-file=license=./langcache.key",
      "section_id": "create-the-required-secrets"
    },
    {
      "id": "create-the-required-secrets-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> create secret generic dp-overlay \\\n  --from-file=overlay.yaml=./dp-overlay.yaml\nkubectl -n <namespace-name> create secret generic cp-overlay \\\n  --from-file=overlay.yaml=./cp-overlay.yaml\nkubectl -n <namespace-name> create secret generic ids-metadata \\\n  --from-file=metadata.yaml=./ids-metadata.yaml",
      "section_id": "create-the-required-secrets"
    },
    {
      "id": "create-helm-values-ex0",
      "language": "yaml",
      "code": "dataplane:\n  license:\n    existingSecret: langcache-license\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\n\ncontrolplane:\n  secrets:\n    secretName: cp-overlay\n  configData:\n    profile: prod\n\nidentityService:\n  mode: bundled\n  bundled:\n    metadata:\n      existingSecret: ids-metadata",
      "section_id": "create-helm-values"
    },
    {
      "id": "install-the-chart-ex0",
      "language": "bash",
      "code": "helm repo add redis-ai https://helm.redis.io/ai\nhelm repo update redis-ai\nhelm search repo redis-ai/langcache --versions",
      "section_id": "install-the-chart"
    },
    {
      "id": "install-the-chart-ex1",
      "language": "bash",
      "code": "helm install langcache redis-ai/langcache \\\n  --version 0.0.1 \\\n  --namespace <namespace-name> \\\n  -f langcache-values.yaml \\\n  --atomic --wait",
      "section_id": "install-the-chart"
    },
    {
      "id": "install-the-chart-ex2",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get pods -w",
      "section_id": "install-the-chart"
    },
    {
      "id": "verify-the-deployment-ex0",
      "language": "bash",
      "code": "kubectl -n <namespace-name> rollout status deployment/langcache\nkubectl -n <namespace-name> rollout status deployment/langcache-controlplane\nkubectl -n <namespace-name> rollout status deployment/langcache-identity-service",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex1",
      "language": "bash",
      "code": "kubectl -n <namespace-name> port-forward svc/langcache 9000:9000",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex2",
      "language": "bash",
      "code": "curl http://localhost:9000/health",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex3",
      "language": "bash",
      "code": "kubectl -n <namespace-name> port-forward svc/langcache-controlplane 9100:9100",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex4",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret langcache-controlplane-admin-token \\\n  -o jsonpath=\"{.data.token}\" | base64 -d",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex5",
      "language": "bash",
      "code": "curl -sS -X POST http://localhost:9100/v1/caches \\\n  -H \"Authorization: Bearer <admin-token>\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"my-cache\",\n    \"databaseId\": \"cache-primary\",\n    \"defaultSearchThreshold\": 0.9,\n    \"defaultTtlMillis\": -1,\n    \"attributes\": []\n  }'",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex6",
      "language": "bash",
      "code": "kubectl -n <namespace-name> port-forward svc/langcache-identity-service 9200:9200",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "verify-the-deployment-ex7",
      "language": "bash",
      "code": "kubectl -n <namespace-name> get secret langcache-identity-service-control-token -o jsonpath=\"{.data.token}\" | base64 -d",
      "section_id": "verify-the-deployment"
    },
    {
      "id": "update-ex0",
      "language": "bash",
      "code": "helm upgrade langcache redis-ai/langcache \\\n  --version <chart-version> \\\n  --namespace <namespace-name> \\\n  -f langcache-values.yaml \\\n  --atomic --wait",
      "section_id": "update"
    }
  ]
}