---
title: Kubernetes (Helm) (self-hosted)
description: Step-by-step guide to run Langfuse on Kubernetes via Helm.
label: "Version: v4"
sidebarTitle: "Kubernetes (Helm)"
---

# Kubernetes (Helm)

This guide will walk you through the steps to deploy Langfuse on Kubernetes using the Helm package manager.
You will need access to a Kubernetes cluster and Helm installed on your local machine.
For the purposes of this guide, we will use a local minikube instance, but each step should extend to a managed Kubernetes service like GKE, EKS, or AKS.

By default, the chart will deploy the Langfuse application containers and data stores ([architecture overview](/self-hosting#architecture)).
You can optionally point to an existing PostgreSQL, Clickhouse and Redis instance.
See [Readme](https://github.com/langfuse/langfuse-k8s/blob/main/README.md) for more details.

  If you are interested in contributing to our Kubernetes deployment guide or
  Helm chart, please create an issue on the [GitHub
  Discussion](https://github.com/orgs/langfuse/discussions/1902).

Alternatively, you can use one of the following cloud-specific deployment guides:

- [AWS (Terraform)](/self-hosting/deployment/aws)
- [Azure (Terraform)](/self-hosting/deployment/azure)
- [GCP (Terraform)](/self-hosting/deployment/gcp)
- [Render](/self-hosting/deployment/render) (community)
- [Railway](/self-hosting/deployment/railway) (community)

## Prerequisites [#prerequisites]

- **Kubernetes `v1.28` or newer**, as required by the [ClickHouse Kubernetes Operator](/self-hosting/deployment/infrastructure/clickhouse#clickhouse-kubernetes-operator).
- **cert-manager and the ClickHouse operator, installed once per cluster.** From chart version `v2.0.0` onwards, `clickhouse.deploy: true` (the default) renders `ClickHouseCluster` and `KeeperCluster` resources, and the operator creates cert-manager resources for its webhooks. Both CRD sets must exist before `helm install`; the chart preflights the ClickHouse CRDs and fails fast if they are missing. The [Readme](#readme) below lists the exact install commands.

Deployments that point every data store at an external service (`*.deploy: false`) do not need the operator.

## Fetch the Helm chart and customize values

Fetch the `langfuse-k8s` Helm chart.

```bash
helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
```

For local experimentation, the pre-configured variables in the values.yaml file are usually sufficient.

If you send _any_ kind of sensitive data to the application or intend to keep it up for longer, we recommend that
you modify the values.yaml file according to your needs

For a comprehensive overview of all available environment variables and configuration options, please refer to the [configuration guide](/self-hosting/configuration) and the [Readme](https://github.com/langfuse/langfuse-k8s/blob/main/README.md).

## Deploy the helm chart

Create a new namespace for the Langfuse deployment (optional), e.g.:

```bash
kubectl create namespace langfuse
```

Install the Helm chart into your namespace:

```bash
helm install langfuse langfuse/langfuse -n langfuse
```

Our chart assumes that it's installed as `langfuse`.
If you want to install it with a different name, you will have to adjust the Redis hostname in the `values.yaml` accordingly.

At this point, Kubernetes will start to deploy the Langfuse application and its dependencies.
This can take up to 5 minutes.
You can monitor the progress by checking `kubectl get pods -n langfuse` - we expect all pods to be running eventually.
The langfuse-web and langfuse-worker container will restart a couple of times while the databases are being provisioned.

## Smoke test UI

The Langfuse UI will be served on a ClusterIP service by default.
Use `kubectl get services -n langfuse` and search for `langfuse-web` to see the port mapping.
Create a port-forward via `kubectl port-forward svc/langfuse-web -n langfuse <local-port>:<nodeport>` and access the UI via `http://localhost:<local-port>` in your browser.
Go ahead and register, create a new organization, project, and explore Langfuse.

## Readme [#readme]

Source: [langfuse/langfuse-k8s](https://github.com/langfuse/langfuse-k8s)

  

## Features

Langfuse supports many configuration options and self-hosted features.
For more details, please refer to the [configuration guide](/self-hosting/configuration).

<Cards num={3}>
  <Cards.Card
    icon={}
    title="Authentication & SSO"
    href="/self-hosting/security/authentication-and-sso"
    arrow
  />
  <Cards.Card
    icon={}
    title="Automated Access Provisioning"
    href="/self-hosting/administration/automated-access-provisioning"
    arrow
  />
  <Cards.Card
    icon={}
    title="Caching"
    href="/self-hosting/configuration/caching"
    arrow
  />
  <Cards.Card
    icon={}
    title="Code evaluators"
    href="/self-hosting/configuration/code-evaluators"
    arrow
  />
  <Cards.Card
    icon={}
    title="Custom Base Path"
    href="/self-hosting/configuration/custom-base-path"
    arrow
  />
  <Cards.Card
    icon={}
    title="Encryption"
    href="/self-hosting/configuration/encryption"
    arrow
  />
  <Cards.Card
    icon={}
    title="Headless Initialization"
    href="/self-hosting/administration/headless-initialization"
    arrow
  />
  <Cards.Card
    icon={}
    title="Data Masking"
    href="/self-hosting/security/data-masking"
    arrow
  />
  <Cards.Card
    icon={}
    title="Networking"
    href="/self-hosting/security/networking"
    arrow
  />
  <Cards.Card
    icon={}
    title="Organization Creators (EE)"
    href="/self-hosting/administration/organization-creators"
    arrow
  />
  <Cards.Card
    icon={}
    title="Instance Management API (EE)"
    href="/self-hosting/administration/instance-management-api"
    arrow
  />
  <Cards.Card
    icon={}
    title="Health and Readiness Check"
    href="/self-hosting/configuration/health-readiness-endpoints"
    arrow
  />
  <Cards.Card
    icon={}
    title="Observability via OpenTelemetry"
    href="/self-hosting/configuration/observability"
    arrow
  />
  <Cards.Card
    icon={}
    title="Transactional Emails"
    href="/self-hosting/configuration/transactional-emails"
    arrow
  />
  <Cards.Card
    icon={}
    title="UI Customization (EE)"
    href="/self-hosting/administration/ui-customization"
    arrow
  />
</Cards>

## Shutdown

You can delete the Helm release and the namespace to clean up the resources:

```bash
helm uninstall langfuse -n langfuse
kubectl delete namespace langfuse
```

## How to Upgrade

Run the following commands to upgrade the Helm chart within a chart major version:

```bash
helm repo update
helm upgrade langfuse langfuse/langfuse -n langfuse
```

For more details on upgrading Langfuse itself, please refer to the [upgrade guide](/self-hosting/upgrade).

### Upgrade the chart from v1 to v2 [#chart-v1-to-v2]

Chart `v2.0.0` is a major version of the Helm chart: it replaces every bundled Bitnami sub-chart with an OSS-licensed alternative. ClickHouse now runs through the [ClickHouse Kubernetes Operator](/self-hosting/deployment/infrastructure/clickhouse#clickhouse-kubernetes-operator), PostgreSQL through `groundhog2k/postgres`, Valkey through `valkey-io/valkey`, and bundled object storage through SeaweedFS. Because StatefulSet identities and PVC layouts change, a plain `helm upgrade` from a v1 release that deploys any of these stores is blocked by the chart.

Follow the [v1 to v2 chart upgrade guide](https://github.com/langfuse/langfuse-k8s/tree/main/examples/upgrade-v1-to-v2). It covers both paths: releases that point to external stores (`*.deploy: false`) upgrade in place, while releases with bundled stores install a sibling v2 release, copy the data over, and then shift traffic. Your deployment must run at least Langfuse v3.224.1 before you start.

If you run the bundled ClickHouse (`clickhouse.deploy: true`), **complete the chart v1 to v2 upgrade before you upgrade Langfuse to v4**. The v1 chart cannot bring its bundled ClickHouse to the version that [Langfuse v4 requires](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4#step-1); the v2 chart can. Deployments that connect to an external ClickHouse are not affected and can upgrade Langfuse to v4 independently of the chart.

Chart `v2.0.0` ships Langfuse v4 as its default `appVersion`. To keep the chart migration and the Langfuse v4 upgrade as two separate steps, pin `langfuse.image.tag` to your current Langfuse v3 image while you move to the v2 chart, then follow the [v3 to v4 upgrade guide](/self-hosting/upgrade/upgrade-guides/upgrade-v3-to-v4). To stay on the v1 chart for now, pass a `1.x` chart version explicitly via `helm upgrade --version`.

If you experience any issues when self-hosting Langfuse, please:

1. Check out [Troubleshooting & FAQ](/self-hosting/troubleshooting-and-faq) page.
2. Use [Ask AI](/ask-ai) to get instant answers to your questions.
3. Ask the maintainers on [GitHub Discussions](/gh-support).
4. Create a bug report or feature request on [GitHub](/issues).

  Enterprise-grade support is available when self-hosting Langfuse. Learn more on
  our [pricing page](/pricing-self-host).

<!-- agent-instructions -->

---

## Agent Instructions

This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/self-hosting/deployment/kubernetes-helm.md`.

### Querying these docs

If the answer is not on this page, query the documentation instead of guessing:

- **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question:

  ```bash
  curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?"
  ```

- **Index of every page**: <https://langfuse.com/llms.txt>, with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt).

### Before writing Langfuse code

- **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results.
- **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application.
- **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples.
- **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api <resource> <action>`) to read or write traces, prompts, datasets, and scores from the terminal.

Found an error in these docs? Please open an issue at <https://github.com/langfuse/langfuse-docs/issues>.