Langfuse Operator

A Kubernetes operator for deploying and managing production-ready Langfuse LLM observability instances.

---

Overview

The Langfuse Operator manages the full Langfuse v3 stack on Kubernetes through a declarative API. Define a LangfuseInstance custom resource and the operator handles deployments, services, configuration, and lifecycle management.

Key Features

• Full stack deployment -- Web, Worker, PostgreSQL, ClickHouse, Redis, and Blob Storage from a single CR
• Automated upgrades -- zero-downtime rollouts with database migration orchestration
• Secret management -- auto-generation and rotation with rolling restarts
• Networking -- Kubernetes Ingress (with TLS/cert-manager), OpenShift Routes, Gateway API HTTPRoute, and per-component NetworkPolicies
• Multi-tenancy -- manage organizations, projects, and API keys via LangfuseOrganization and LangfuseProject CRDs
• Observability -- Prometheus ServiceMonitor, OpenTelemetry integration, and operator metrics
• Namespace scoping -- restrict the operator to specific namespaces via WATCH_NAMESPACE or Helm watchNamespaces
• Platform support -- Kubernetes, OpenShift, EKS, GKE, and AKS

Quick Start

Prerequisites

• Kubernetes v1.26+
• kubectl
• OLM (for OLM-based install) or Helm v3

Install with Helm

helm install langfuse-operator deploy/charts/langfuse-operator \
  -n langfuse-operator-system --create-namespace \
  --set image.tag=0.6.0

This installs the CRDs, RBAC, and operator deployment. See the chart values for all configuration options.

Install CRDs only (manual deploy)

kubectl apply -f https://raw.githubusercontent.com/PalenaAI/langfuse-operator/main/config/crd/bases/langfuse.palena.ai_langfuseinstances.yaml
kubectl apply -f https://raw.githubusercontent.com/PalenaAI/langfuse-operator/main/config/crd/bases/langfuse.palena.ai_langfuseorganizations.yaml
kubectl apply -f https://raw.githubusercontent.com/PalenaAI/langfuse-operator/main/config/crd/bases/langfuse.palena.ai_langfuseprojects.yaml

Deploy a Langfuse Instance

apiVersion: langfuse.palena.ai/v1alpha1
kind: LangfuseInstance
metadata:
  name: langfuse
  namespace: langfuse
spec:
  image:
    tag: "3"
  auth:
    nextAuthUrl: "https://langfuse.example.com"

kubectl apply -f langfuse-instance.yaml

The operator creates and manages the Web and Worker deployments, Services, managed data stores (ClickHouse, Redis), database migrations, secrets, networking, and observability resources.

Verify

kubectl get langfuseinstances -n langfuse

NAME       PHASE     READY   VERSION   AGE
langfuse   Running   true    3         2m

Custom Resources

CRD	Purpose
LangfuseInstance	Deploys and manages a full Langfuse stack
LangfuseOrganization	Manages organizations and member access
LangfuseProject	Manages projects and API key Secrets

Documentation

Full documentation is available at the Langfuse Operator Docs site, covering:

• Installation -- OLM, Helm, and manual methods
• Architecture -- how the operator works
• Database, ClickHouse, Redis, Blob Storage -- data store configuration
• Authentication -- OIDC, email/password, init user
• Networking -- Ingress, OpenShift Routes, NetworkPolicies
• Upgrades -- zero-downtime upgrade strategy
• Secret Management -- auto-generation and rotation
• Multi-Tenancy -- organizations and projects
• CRD Reference -- full spec documentation

Contributing

See CONTRIBUTING.md for development setup, coding conventions, and how to submit changes.

License

Copyright 2026 bitkaio LLC. Licensed under the Apache License 2.0.