Langfuse Kubernetes Deployment

Version 2.0.0 of the Helm chart introduces significant changes by replacing Bitnami sub-charts with OSS-licensed alternatives and using the ClickHouse/clickhouse-operator for ClickHouse deployments.

Component Changes:

Credential Management: On first install, the chart auto-generates Secrets for Postgres, ClickHouse, Valkey, SeaweedFS, and three Langfuse application secrets (salt, encryptionKey, nextauth.secret). These are persisted across upgrades via lookup. These Secrets are marked with helm.sh/resource-policy: keep, meaning they survive helm uninstall and must be deleted manually for a clean slate.

Upgrading from Langfuse Helm Chart v1.x to v2.0 involves a migration process to handle changes in how data stores (PostgreSQL, ClickHouse) are managed. The migration can be performed using an automated script or manually depending on your storage architecture.

Migration Strategies

1. In-place Upgrade (All stores external): Use this if your PostgreSQL and ClickHouse instances are managed externally to the Helm chart. This is the simplest path as it only involves updating the application configuration.
2. Sibling + Traffic Shift (Bundled stores): Use this if you are using the bundled stores provided by the chart. This method involves deploying a 'sibling' installation (a new version alongside the old one) and then shifting traffic to the new version to minimize downtime.

Automated Migration Tools

The repository provides scripts to automate the transformation of Helm values and the migration process:

• scripts/migrate-v1-to-v2.sh: The main interactive migration driver. Use the --yes flag to skip interactive prompts (it will still print the migration plan).
• scripts/migrate-values.py: A Python script that transforms v1 values.yaml into v2 formats using one of three modes: sibling, cutover, or inplace.
• scripts/ch-online-sync.sh: A helper script for performing incremental synchronization of ClickHouse data.

Requirements

To run the automated migration, you must have the following installed:

• kubectl
• helm >= 3.17
• jq
• python3
• A YAML parser: yq (mikefarah version), PyYAML, or Ruby.

Example Files for Reference

• v1-values.yaml: A representative example of v1 source values (includes wal_level=logical).
• v2-values.yaml: An example of a sibling overlay (Ingress is turned off, uses shared app secrets).
• v2-app-values.yaml: An example of a cutover overlay (Ingress is turned on, uses the same hosts as the original).

Before installing Langfuse, you must ensure cert-manager and the ClickHouse operator are installed in your cluster. These are required because the Langfuse chart renders ClickHouseCluster and KeeperCluster Custom Resources (CRs). Install them in the following order:

1. cert-manager: Required for certificate management.
2. ClickHouse operator: Required for managing ClickHouse clusters.

Wait for the CRDs to be established before proceeding to the Langfuse installation.

# 1. Install cert-manager
helm install \
  cert-manager oci://quay.io/jetstack/charts/cert-manager \
  --version v1.20.2 \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

kubectl wait --for=condition=Established \
  crd/certificates.cert-manager.io \
  crd/issuers.cert-manager.io \
  --timeout=120s

# 2. Install ClickHouse operator
helm install clickhouse-operator oci://ghcr.io/clickhouse/clickhouse-operator-helm \
  --version 0.0.5 \
  --namespace clickhouse-operator --create-namespace

kubectl wait --for=condition=Established \
  crd/clickhouseclusters.clickhouse.com \
  crd/keeperclusters.clickhouse.com \
  --timeout=120s

When upgrading from Langfuse Helm Chart v0.13 to v1.0, you must restructure your values.yaml. Most core configurations have moved under a top-level langfuse key.

Required Migration Steps:

1. Restructure Core Config: Move global settings (resources, affinity, nodeSelector, etc.) under the langfuse key.
2. Update Image Config: Use the new langfuse.image structure. You can now override images per component (web or worker).
3. Update Secrets:
   • For salt, use langfuse.salt.value or langfuse.salt.secretKeyRef.
   • For encryptionKey, use langfuse.encryptionKey.value or langfuse.encryptionKey.existingSecret / existingSecretKey.
4. Migrate Integrated Services:
   • Redis: Move from valkey or additionalEnv to the redis section. Use nameOverride: valkey to keep the old name.
   • Clickhouse: Move from clickhouse or additionalEnv to the clickhouse section. Warning: clickhouse configuration and langfuse.additionalEnv ClickHouse variables are mutually exclusive.
   • S3/MinIO: Move from minio or additionalEnv to the s3 section. Use nameOverride: minio to keep the old name.
5. Update Feature Flags: Move flags to langfuse.features (e.g., telemetryEnabled, signUpDisabled, experimentalFeaturesEnabled).

# Example of the new v1.0 structure
langfuse:
  replicas: 1
  image:
    tag: 3
  features:
    telemetryEnabled: true
  salt:
    value: "your-salt"
  encryptionKey:
    value: "your-key"

redis:
  nameOverride: valkey
  host: <host>
  port: <port>
  auth:
    username: <username>
    password: <password>

clickhouse:
  host: <host>
  auth:
    username: "<username>"
    password: "<password>"

s3:
  nameOverride: minio
  bucket: <bucket>
  region: <region>
  endpoint: <endpoint>