Langfuse - Control Plane

Overview

Langfuse is an open-source LLM observability and evaluation platform. This template deploys the full Langfuse stack on Control Plane — UI, background worker, and all required data stores — ready to receive traces from any LLM application.

Architecture

Langfuse Web — Next.js application serving the UI and public API. Autoscales between 2 and 5 replicas.
Langfuse Worker — Background processor for trace ingestion, automated evaluations, and third-party integrations.
PostgreSQL — Stores all configuration data: users, projects, API keys, prompts, datasets, and evaluation configs.
Redis — BullMQ ingestion queue and short-lived cache for API keys and prompts.
ClickHouse — Columnar store for all traces, observations, and scores. Powers all dashboard queries. Data files are written directly to object storage.
Object Storage — AWS S3 or GCS. Shared between ClickHouse (data files) and Langfuse (raw event buffer and media uploads) using separate key prefixes (clickhouse/, events/, media/).

What Gets Created

Standard Langfuse Web Workload — The Next.js UI and public API with autoscaling enabled.
Standard Langfuse Worker Workload — Background trace ingestion and evaluation processor.
Stateful PostgreSQL Workload — Single-replica Postgres with a persistent volume set.
Stateful Redis Workload — Single-replica Redis for the BullMQ queue and cache.
Stateful ClickHouse Workload — Single-node ClickHouse with a persistent volume set for local metadata.
Volume Sets — One persistent volume set each for PostgreSQL and ClickHouse.
Identity & Policy — An identity bound to all workloads with reveal access to all secrets, and cloud storage access for the object store.
Secrets — Opaque secrets for all component credentials and Langfuse auth keys.

This template does not create a GVC. You must deploy it into an existing GVC.

Prerequisites

Object storage must be configured before deploying. Both ClickHouse and Langfuse use the same bucket with separate key prefixes — create the bucket and credentials as described below, then fill in the objectStore section of values.yaml.

AWS S3

Create a bucket

Create an S3 bucket. Set objectStore.aws.bucket to its name and objectStore.aws.region to its region.

Set up a Cloud Account

If you do not have one, create a Cloud Account. Set objectStore.aws.cloudAccountName to its name.

Create an IAM policy

Create an IAM policy with the following JSON (replace YOUR_BUCKET_NAME) and set objectStore.aws.policyName to its name:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject",
                "s3:ListBucket",
                "s3:GetObjectVersion",
                "s3:DeleteObjectVersion"
            ],
            "Resource": [
                "arn:aws:s3:::YOUR_BUCKET_NAME",
                "arn:aws:s3:::YOUR_BUCKET_NAME/*"
            ]
        }
    ]
}

GCS

GCS uses S3-compatible HMAC authentication for this template. A Control Plane Cloud Account is not required.

Create a bucket

Create a GCS bucket. Set objectStore.gcp.bucket to its name.

Create a service account and HMAC key

In the GCP console, go to Settings → Interoperability and click Create a key for a service account → Create new account. Name the service account, assign the Storage Object Admin role, and click Done. Copy the provided HMAC access key and secret into objectStore.gcp.accessKeyId and objectStore.gcp.secretAccessKey.Or use the CLI:

gcloud config set project YOUR_PROJECT_ID

gcloud storage buckets create gs://YOUR_BUCKET_NAME

gcloud iam service-accounts create langfuse-storage

gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
  --member="serviceAccount:langfuse-storage@$(gcloud config get-value project).iam.gserviceaccount.com" \
  --role="roles/storage.objectAdmin"

gsutil hmac create langfuse-storage@$(gcloud config get-value project).iam.gserviceaccount.com

Installation

Once object storage is ready, install using your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

The default values.yaml for this template:

# Object store - used by both ClickHouse (data files) and Langfuse (raw event buffer + media)
# Both services share the same bucket using separate key prefixes
objectStore:
  provider: aws # Options: aws, gcp
  aws:
    bucket: my-langfuse-bucket
    region: us-east-1
    cloudAccountName: my-cloudaccount
    policyName: my-custom-policy
  gcp:
    bucket: my-langfuse-bucket
    accessKeyId: my-gcs-key        # GCS HMAC key ID
    secretAccessKey: my-gcs-secret # GCS HMAC secret key

# Langfuse application
langfuse:
  web:
    image: langfuse/langfuse:3
    minReplicas: 2  # Keep at 2+ for zero-downtime rolling deploys
    maxReplicas: 5
    resources:
      minCpu: 500m
      maxCpu: 1000m
      minMemory: 1Gi
      maxMemory: 2Gi

  worker:
    image: langfuse/langfuse-worker:3
    replicas: 1
    resources:
      minCpu: 250m
      maxCpu: 500m
      minMemory: 512Mi
      maxMemory: 1Gi

  auth:
    nextAuthSecret: ""    # Required: openssl rand -base64 32
    encryptionKey: ""     # Required: openssl rand -hex 32 (must be exactly 64 hex characters)
    salt: ""              # Required: openssl rand -base64 32

  firewall:
    inboundAllowCIDR:
      - 0.0.0.0/0  # Restrict to specific IPs in production

# PostgreSQL - stores users, projects, API keys, prompts, datasets, eval configs
postgres:
  image: postgres:18
  resources:
    minCpu: 250m
    maxCpu: 1
    minMemory: 512Mi
    maxMemory: 1Gi
  config:
    username: langfuse
    password: mypassword
    database: langfuse
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

# Redis - BullMQ ingestion queue and API key/prompt cache
redis:
  image: redis:7.4
  resources:
    minCpu: 100m
    maxCpu: 400m
    minMemory: 256Mi
    maxMemory: 512Mi
  auth:
    password: mypassword

# ClickHouse - stores all traces, observations, and scores; powers dashboards
# Data files are stored in the object store above; volumeset holds local metadata only
clickhouse:
  image: clickhouse/clickhouse-server:25.10
  resources:
    minCpu: 1
    maxCpu: 2
    minMemory: 2Gi
    maxMemory: 4Gi
  config:
    password: mypassword
    database: langfuse
  volumeset:
    capacity: 10 # initial capacity in GiB (minimum is 10)

Required Auth Secrets

Three auth values must be generated and set in values.yaml before deploying:

# nextAuthSecret and salt — any base64 string
openssl rand -base64 32

# encryptionKey — must be exactly 64 hex characters (32 bytes)
openssl rand -hex 32

encryptionKey encrypts LLM API keys and other sensitive project data stored in PostgreSQL. It must be generated with openssl rand -hex 32 — a base64 value will fail validation on startup. Run each command separately and copy the output into the corresponding field.

Passwords

Change all component passwords before deploying to production:

postgres.config.password — PostgreSQL admin password
redis.auth.password — Redis password
clickhouse.config.password — ClickHouse password

Firewall

The Langfuse web UI and API are publicly accessible by default (0.0.0.0/0). To restrict access to specific IP ranges, update langfuse.firewall.inboundAllowCIDR:

langfuse:
  firewall:
    inboundAllowCIDR:
      - 203.0.113.0/24  # restrict to your office or application IPs

Object Store

Both ClickHouse and Langfuse share one bucket with separate key prefixes:

Prefix	Used by
`clickhouse/`	ClickHouse data files (tables, parts, metadata)
`events/`	Langfuse raw event ingestion buffer
`media/`	Langfuse media uploads (screenshots, attachments)

Set objectStore.provider to aws or gcp and fill in the corresponding block. Leave the unused provider block empty.

Accessing Langfuse

Once deployed, the Langfuse UI is accessible via the Control Plane external endpoint for the {release-name}-langfuse-web workload. Navigate to the endpoint in your browser to create an account and log in.

Sending Traces via API

After creating a project and generating API keys (Settings → API Keys), send traces using the public API:

curl -X POST https://YOUR_LANGFUSE_ENDPOINT/api/public/traces \
  -H "Content-Type: application/json" \
  -u "YOUR_PUBLIC_KEY:YOUR_SECRET_KEY" \
  -d '{
    "name": "my-first-trace",
    "input": "Hello",
    "output": "Hello back"
  }'

Or integrate using the Langfuse SDK for Python, TypeScript, and other languages.

LLM Connections (Playground and Evaluations)

The Langfuse playground and LLM-as-a-Judge evaluations require LLM API keys configured through the UI. These keys are stored encrypted in PostgreSQL using your encryptionKey. To configure:

In the Langfuse UI, go to Settings → LLM API Keys (for the playground) or Evaluation → Set up default model (for automated evals).
Click Add LLM Connection, choose your provider (OpenAI, Anthropic, etc.), and enter your API key.

Backups

PostgreSQL

Stores all critical config: users, projects, API keys, prompts, datasets, and eval configs. Most important to back up. Enable snapshot policies on the PostgreSQL volume set via the Control Plane console — snapshots capture the full disk state and restore quickly.

ClickHouse

Data files are stored directly in your object store (S3 or GCS) and are inherently durable — the volume set only holds local metadata. A full restore is performed by redeploying and pointing ClickHouse at the existing bucket.

Redis

Holds only the transient BullMQ ingestion queue and short-lived cache. Backup is not required.

External References

Langfuse Documentation

Full Langfuse product documentation

Langfuse SDK Reference

Python, TypeScript, and other language SDK guides

Langfuse Self-Hosting Guide

Self-hosting architecture and configuration reference

Create a Cloud Account

Set up a Control Plane Cloud Account for S3 access

​Overview

​Architecture

​What Gets Created

​Prerequisites

​AWS S3

​GCS

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Required Auth Secrets

​Passwords

​Firewall

​Object Store

​Accessing Langfuse

​Sending Traces via API

​LLM Connections (Playground and Evaluations)

​Backups

PostgreSQL

ClickHouse

Redis

​External References

Langfuse Documentation

Langfuse SDK Reference

Langfuse Self-Hosting Guide

Create a Cloud Account

Overview

Architecture

What Gets Created

Prerequisites

AWS S3

GCS

Installation

Configuration

Required Auth Secrets

Passwords

Firewall

Object Store

Accessing Langfuse

Sending Traces via API

LLM Connections (Playground and Evaluations)

Backups

External References