{
  "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-09-10T16:06:39+03:00",
  "page_type": "content",
  "content_hash": "2d81fa81533868c1c1abea1407333878a85224c8ee33ddfafcfd4995b2cdbba8",
  "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)."
    },
    {
      "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": "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 <chart-version>` 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\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  image:\n    repository: redislabs/iris-langcache-data\n    tag: \"<langcache-version>\"\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  image:\n    repository: redislabs/iris-langcache-control\n    tag: \"<langcache-version>\"\n  secrets:\n    secretName: cp-overlay\n  configData:\n    profile: prod\n\nidentityService:\n  mode: bundled\n  bundled:\n    image:\n      repository: redislabs/iris-identity-service\n      tag: \"<langcache-version>\"\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 <chart-version> \\\n  --namespace <namespace-name> \\\n  --create-namespace \\\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": "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"
    }
  ]
}