Langfuse Operator

Appearance

LangfuseInstance ​

langfuseinstances.langfuse.palena.ai/v1alpha1

Deploys and manages the complete Langfuse stack: Web, Worker, and all dependent services.

Spec ​

FieldTypeDefaultDescription
imageImageSpecContainer image configuration
webWebSpecWeb component configuration
workerWorkerSpecWorker component configuration
authAuthSpecAuthentication configuration
tlsTLSSpecTrusted CA for encrypted datastore connections; see Datastore TLS
eeLicenseKey*SecretValueLANGFUSE_EE_LICENSE_KEY reference. Required for the LangfuseOrganization/LangfuseProject CRDs (EE/Pro-gated org-management API); see Multi-Tenancy
secretsSecretManagementSpecSecret generation and rotation
databaseDatabaseSpecPostgreSQL configuration
clickhouseClickHouseSpecClickHouse configuration
redisRedisSpecRedis configuration
blobStorageBlobStorageSpecBlob storage configuration
llmLLMSpecLLM integration
ingressIngressSpecKubernetes Ingress
routeRouteSpecOpenShift Route
gatewayAPIGatewayAPISpecGateway API HTTPRoute
securitySecuritySpecSecurity settings
observabilityObservabilitySpecMonitoring and tracing
circuitBreakerCircuitBreakerSpecDependency circuit breaking
upgradeUpgradeSpecUpgrade strategy

Status ​

FieldTypeDescription
readyboolWhether the instance is fully operational
phasestringPending, Migrating, Running, Degraded, or Error
webComponentStatusWeb component state: replicas, readyReplicas, endpoint, and issues
workerWorkerComponentStatusWorker component state: as above plus queueDepth, circuitBreakerActive
databaseDatabaseStatusDatabase connection and migration state
migrationMigrationStatusMigration Job state, including pod-level failures
clickhouseClickHouseStatusClickHouse state including storage
redisConnectionStatusRedis connection state
blobStorageBlobStorageStatusBlob storage state
secretsSecretsStatusSecret management state
versionstringCurrently running Langfuse version
publicUrlstringPublic URL of the instance
conditions[]ConditionStandard Kubernetes conditions

Conditions ​

TypeDescription
ReadyAll components are operational
DatabaseReadyPostgreSQL is connected and migrated
ClickHouseReadyClickHouse is connected
RedisReadyRedis is connected
BlobStorageReadyBlob storage is accessible
MigrationsCompleteAll migrations have finished
SecretsReadyAll secrets are generated/available
ClickHouseRetentionAppliedTTL policies are active
ClickHouseSchemaDriftSchema drift detected
CircuitBreakerActiveA circuit breaker is tripped

Type Reference ​

ImageSpec ​

FieldTypeDefaultDescription
repositorystringlangfuse/langfuseContainer image repository
tagstringrequiredImage tag
pullPolicystringIfNotPresentAlways, IfNotPresent, or Never
pullSecrets[]LocalObjectReferenceImage pull secrets

WebSpec ​

FieldTypeDefaultDescription
replicas*int321Number of Web pod replicas
autoscaling*AutoscalingSpecHPA configuration
resources*ResourceRequirementsCPU/memory requests and limits
podDisruptionBudget*PDBSpecPDB configuration
topologySpreadConstraints*TopologySpreadSpecTopology spread
extraEnv[]EnvVarAdditional environment variables
extraVolumeMounts[]VolumeMountAdditional volume mounts
extraVolumes[]VolumeAdditional volumes
nodeSelectormap[string]stringNode selector
tolerations[]TolerationTolerations
affinity*AffinityAffinity rules

WorkerSpec ​

FieldTypeDefaultDescription
replicas*int321Number of Worker pod replicas
autoscaling*AutoscalingSpecHPA configuration
resources*ResourceRequirementsCPU/memory requests and limits
concurrency*int3210LANGFUSE_WORKER_CONCURRENCY
extraEnv[]EnvVarAdditional environment variables
extraVolumeMounts[]VolumeMountAdditional volume mounts on the Worker container
extraVolumes[]VolumeAdditional volumes on the Worker pod
nodeSelectormap[string]stringNode selector
tolerations[]TolerationTolerations
affinity*AffinityAffinity rules

AuthSpec ​

FieldTypeDescription
nextAuthUrlstringCanonical URL for NextAuth (NEXTAUTH_URL)
nextAuthSecret*SecretValueSecret reference or auto-generate
salt*SecretValueEncryption salt reference or auto-generate
emailPassword*EmailPasswordSpecEmail/password auth settings
oidc*OIDCSpecOpenID Connect settings
initUser*InitUserSpecInitial admin user
adminApiKey*SecretValueADMIN_API_KEY reference or auto-generate; used by the Organization/Project controllers (see Multi-Tenancy)

DatabaseSpec ​

FieldTypeDescription
cloudnativepg*CloudNativePGSpecReference a CNPG Cluster (recommended for production)
external*ExternalDatabaseSpecExternal PostgreSQL (recommended for production)
managed*ManagedDatabaseSpecNot implemented — reserved for a future release
migration*MigrationSpecMigration behavior

ClickHouseSpec ​

FieldTypeDescription
external*ExternalClickHouseSpecExternal ClickHouse (recommended for production)
managed*ManagedClickHouseSpecSingle-node StatefulSet (dev / preview only — no replication, no backups)
databasestringDatabase Langfuse stores its tables in (CLICKHOUSE_DB). Defaults to default. Must match ^[A-Za-z_][A-Za-z0-9_]*$. Must already exist for external; created automatically for managed. Also used by retention and schema drift checks.
encryption*ClickHouseEncryptionSpecEncryption settings
retention*RetentionSpecData retention policies
schemaDrift*SchemaDriftSpecSchema drift detection

RedisSpec ​

FieldTypeDescription
external*ExternalRedisSpecExternal Redis (recommended for production)
managed*ManagedRedisSpecSingle-pod StatefulSet (dev / preview only — no HA, no backups)

BlobStorageSpec ​

FieldTypeDescription
providerstrings3, azure, or gcs
s3*S3SpecS3-compatible storage config
azure*AzureBlobSpecAzure Blob Storage config
gcs*GCSSpecGoogle Cloud Storage config

SecuritySpec ​

FieldTypeDefaultDescription
readOnlyRootFilesystem*booltrueRead-only root filesystem
runAsNonRoot*booltrueRun containers as non-root
networkPolicy.enabled*booltrueCreate NetworkPolicy
telemetry.enabled*booltrueLangfuse telemetry

CircuitBreakerSpec ​

FieldTypeDefaultDescription
enabled*booltrueEnable circuit breakers
clickhouse*ComponentCircuitBreakerSpecClickHouse circuit breaker
redis*ComponentCircuitBreakerSpecRedis circuit breaker
database*ComponentCircuitBreakerSpecDatabase circuit breaker

UpgradeSpec ​

FieldTypeDefaultDescription
strategystringrollingUpgrade strategy
preUpgrade*PreUpgradeSpecActions before upgrade
rollingUpdate*RollingUpdateSpecRolling update parameters
postUpgrade*PostUpgradeSpecActions after upgrade

Nested types ​

The remaining *Spec types referenced above. Field defaults marked *T mean the field is a pointer (omitting it falls back to the default; setting it explicitly to the zero value sticks).

SecretValue ​

FieldTypeDescription
secretRef*SecretKeyRefReference to an existing Secret key. When nil and auto-generation is enabled, the operator generates the value.

AutoscalingSpec ​

FieldTypeDefaultDescription
enabledboolfalseToggle HPA creation
minReplicas*int321Lower bound
maxReplicasint3210Upper bound
targetCPUUtilization*int3280Target CPU utilization (%)
customMetrics[]CustomMetricAdditional scaling metrics (type, threshold)

PDBSpec ​

FieldTypeDescription
enabledboolToggle PDB creation
minAvailable*int32Minimum pods that must remain available

TopologySpreadSpec ​

FieldTypeDefaultDescription
enabledboolfalseToggle topology spread constraints
maxSkew*int321Maximum spread skew
topologyKeystringtopology.kubernetes.io/zoneTopology domain key

EmailPasswordSpec ​

FieldTypeDefaultDescription
enabled*booltrueToggle email/password auth
disableSignupboolfalseBlock new user registration

OIDCSpec ​

Configures Langfuse's generic custom OIDC provider (mapped to the upstream AUTH_CUSTOM_* variables). The IdP must whitelist the callback URL <NEXTAUTH_URL>/api/auth/callback/custom.

FieldTypeDescription
enabledboolToggle OIDC
issuerstringOIDC issuer URL → AUTH_CUSTOM_ISSUER
clientId*SecretKeyRefReference to OIDC client ID → AUTH_CUSTOM_CLIENT_ID
clientSecret*SecretKeyRefReference to OIDC client secret → AUTH_CUSTOM_CLIENT_SECRET
namestringLogin button label → AUTH_CUSTOM_NAME (default SSO)
scope[]stringRequested OAuth scopes → AUTH_CUSTOM_SCOPE, space-joined (default openid email profile)
ssoEnforcedDomains[]stringDomains forced to sign in via SSO → AUTH_DOMAINS_WITH_SSO_ENFORCEMENT, comma-joined (password login disabled for them)

InitUserSpec ​

FieldTypeDefaultDescription
enabledboolfalseCreate the initial admin user on first boot
emailstringInitial user email
password*SecretKeyRefReference to the initial password
orgNamestringDefaultDefault organization name
projectNamestringDefaultDefault project name

SecretManagementSpec ​

FieldTypeDescription
autoGenerate*AutoGenerateSpecAuto-generation of NEXTAUTH_SECRET, SALT, etc.
rotation*RotationSpecSecret-rotation detection and restart

AutoGenerateSpec ​

FieldTypeDefaultDescription
enabled*booltrueToggle auto-generation of operator-owned secrets

RotationSpec ​

FieldTypeDefaultDescription
enabled*booltrueDetect secret changes and trigger component restarts
customMappings[]SecretRestartMappingMap a Secret name → components to restart (secretName, restartComponents: [web, worker])

CloudNativePGSpec ​

FieldTypeDefaultDescription
clusterRefObjectReferenceReference to an existing CNPG Cluster
databasestringlangfuseDatabase name within the cluster

ManagedDatabaseSpec ​

FieldTypeDefaultDescription
instances*int321Number of PostgreSQL instances
storageSizestring10GiPVC size for each instance
storageClassstringStorage class for PVCs
backup*DatabaseBackupSpecAutomated backup configuration

DatabaseBackupSpec ​

FieldTypeDefaultDescription
enabledboolfalseToggle automated backups
schedulestring0 2 * * *Cron schedule

ExternalDatabaseSpec ​

FieldTypeDescription
secretRefSecretKeysRefReference to a Secret with connection details. Recognised keys: url (required, postgres://…), directUrl (optional, bypasses pooling). With a tls block the url must not contain a query string.
tlsDatabaseTLSSpecTLS for the PostgreSQL connection.

MigrationSpec ​

FieldTypeDefaultDescription
runOnDeploy*booltrueRun migrations on every deployment
backgroundMigrations*BackgroundMigrationSpecBackground-migration handling

BackgroundMigrationSpec ​

FieldTypeDefaultDescription
enabled*booltrueMonitor background migrations via /api/public/background-migrations
timeoutstring3600sMaximum wait

ManagedClickHouseSpec ​

FieldTypeDefaultDescription
shards*int321Number of shards
replicas*int321Replicas per shard
storageSizestring50GiPVC size
storageClassstringStorage class
resources*ClickHouseResourceSpecResource preset or custom
auth*ClickHouseAuthSpecCredentials reference

ClickHouseResourceSpec ​

FieldTypeDescription
presetstringOne of small, medium, large, custom
custom*ResourceRequirementsUsed when preset: custom

ClickHouseAuthSpec ​

FieldTypeDescription
secretRef*SecretKeysRefReference to a Secret with username and password keys. Omit to let the operator auto-generate.

ExternalClickHouseSpec ​

FieldTypeDescription
secretRefSecretKeysRefReference to a Secret with connection details. Recognised keys: url (HTTP, e.g. http://ch:8123), migrationUrl (native, e.g. clickhouse://ch:9000), username, password. With a tls block, use the TLS scheme/port (https://…:8443, clickhouse://…:9440).
tlsClickHouseTLSSpecTLS for the ClickHouse connection.

ClickHouseEncryptionSpec ​

FieldTypeDescription
enabledboolEncryption at rest
blobStorageboolBlob-storage encryption

RetentionSpec ​

FieldTypeDescription
traces*TableRetentionSpecTTL for trace data
observations*TableRetentionSpecTTL for observation data
scores*TableRetentionSpecTTL for score data
storagePressure*StoragePressureSpecAuto-retention under disk pressure

TableRetentionSpec ​

FieldTypeDescription
ttlDaysint32Days to retain data; 0 = infinite

StoragePressureSpec ​

FieldTypeDefaultDescription
enabledboolfalseMonitor ClickHouse storage pressure
warningThresholdPercentint3275Emit a warning event above this
criticalThresholdPercentint3290Begin pruning above this
pruneOldestPartitionsboolfalseDrop oldest partitions when critical
minRetainDaysint327Floor for retention even under pressure

SchemaDriftSpec ​

FieldTypeDefaultDescription
enabledboolfalsePeriodic schema drift detection
checkIntervalMinutesint3260Interval between checks
autoRepairboolfalseAutomatically repair detected drift

ManagedRedisSpec ​

FieldTypeDefaultDescription
replicas*int321Number of Redis replicas
storageSizestring5GiPVC size

ExternalRedisSpec ​

FieldTypeDescription
secretRefSecretKeysRefReference to a Secret with connection details. Recognised keys: host, port, password, tls (legacy boolean; prefer the tls block).
tlsRedisTLSSpecTLS for the Redis connection.

TLSSpec ​

Trust configuration for encrypted datastore connections. See Datastore TLS.

FieldTypeDescription
trustedCASecretRefCACertSecretRefCA mounted into Web + Worker and exported as NODE_EXTRA_CA_CERTS. Covers ClickHouse HTTPS, and is the default CA for Redis/PostgreSQL.

DatabaseTLSSpec ​

FieldTypeDefaultDescription
sslModestringrequiredisable, require, verify-ca, or verify-full. Mapped to Prisma's sslmode/sslaccept parameters (Prisma has no CA-only mode, so verify-ca ≡ verify-full).
caSecretRefCACertSecretRefCA used as Prisma's sslcert. Defaults to spec.tls.trustedCASecretRef.

The operator composes DATABASE_URL as $(DATABASE_URL_BASE)?<params> via env interpolation, so the url in the Secret must not contain its own query string.

ClickHouseTLSSpec ​

FieldTypeDefaultDescription
enabledboolfalseSets CLICKHOUSE_MIGRATION_SSL=true. The runtime HTTPS client trusts the CA via NODE_EXTRA_CA_CERTS. URLs in the Secret must use the TLS scheme/port.

RedisTLSSpec ​

FieldTypeDefaultDescription
enabledboolfalseSets REDIS_TLS_ENABLED=true on Web + Worker.
caSecretRefCACertSecretRefCA for REDIS_TLS_CA_PATH. Defaults to spec.tls.trustedCASecretRef (ioredis ignores NODE_EXTRA_CA_CERTS).
clientCertSecretRefClientCertSecretRefClient cert/key for mutual TLS (REDIS_TLS_CERT_PATH / REDIS_TLS_KEY_PATH).
serverNamestringTLS SNI/hostname override (REDIS_TLS_SERVERNAME).

CACertSecretRef ​

FieldTypeDefaultDescription
namestringSecret name.
keystringca.crtSecret key holding the PEM CA certificate.

ClientCertSecretRef ​

FieldTypeDefaultDescription
namestringSecret name.
certKeystringtls.crtSecret key holding the PEM client certificate.
keyKeystringtls.keySecret key holding the PEM client private key.

PodIssue ​

A pod-level failure surfaced into status.web.issues, status.worker.issues, or status.migration.issues, so a stuck component can be diagnosed without inspecting pods by hand. Populated only while a component is not ready.

FieldTypeDescription
podstringName of the affected pod.
containerstringContainer that reported the problem. Empty for pod-level problems such as scheduling failures.
reasonstringKubernetes reason, e.g. CrashLoopBackOff, ImagePullBackOff, CreateContainerConfigError, Unschedulable, OOMKilled.
messagestringHuman-readable detail. For a crash loop this includes the previous run's exit code and captured output.
restartCountint32Container restart count.
fatalboolThe failure cannot self-heal and needs human action. Any fatal issue moves the instance to phase: Error instead of Degraded.

Fatal reasons are those that never resolve on their own: ImagePullBackOff, ErrImagePull, InvalidImageName, ErrImageNeverPull, CreateContainerConfigError, CreateContainerError. CrashLoopBackOff is deliberately not fatal — Langfuse containers legitimately crash-loop while waiting for Postgres or ClickHouse during a cold start.

MigrationStatus ​

FieldTypeDescription
jobNamestringName of the migration Job.
failedint32Number of failed migration pod attempts.
issues[]PodIssuePod-level problems from the migration Job's pods.

S3Spec ​

FieldTypeDescription
endpointstringS3 endpoint URL (set for MinIO; omit for AWS)
regionstringS3 region
bucketstringBucket name (required)
forcePathStyleboolPath-style addressing (MinIO)
credentials*S3CredentialsSpecCredentials reference

S3CredentialsSpec ​

FieldTypeDescription
secretRefSecretKeysRefReference to a Secret with accessKeyId and secretAccessKey

AzureBlobSpec ​

FieldTypeDescription
storageAccountNamestringAzure storage account name (used as the access key ID and to derive the default endpoint)
containerNamestringBlob container name (Langfuse's upload "bucket")
endpointstringBlob service endpoint override. Defaults to https://<storageAccountName>.blob.core.windows.net
credentials*AzureCredentialsSpecCredentials reference

AzureCredentialsSpec ​

FieldTypeDescription
secretRefSecretKeysRefReference to a Secret holding the storage account key under the accountKey key (override via the Keys map). Langfuse does not support Azure connection strings.

GCSSpec ​

FieldTypeDescription
bucketNamestringGCS bucket name
projectIdstringGCP project ID
credentials*GCSCredentialsSpecCredentials reference

GCSCredentialsSpec ​

FieldTypeDescription
secretRefSecretKeysRefReference to a Secret containing the GCP service-account JSON

LLMSpec ​

FieldTypeDescription
apiBasestringLLM API base URL
apiKey*SecretKeyRefReference to the LLM API key
modelstringLLM model name

IngressSpec ​

FieldTypeDescription
enabledboolToggle Ingress creation
classNamestringIngressClass name
hoststringIngress hostname
annotationsmap[string]stringAdditional Ingress annotations
tls*IngressTLSSpecTLS configuration

IngressTLSSpec ​

FieldTypeDescription
enabledboolToggle TLS
secretNamestringExisting TLS Secret name
certManager*CertManagerSpeccert-manager integration

CertManagerSpec ​

FieldTypeDescription
issuerRef.namestringIssuer name
issuerRef.kindstringIssuer or ClusterIssuer (default ClusterIssuer)

RouteSpec ​

FieldTypeDescription
enabledboolToggle OpenShift Route creation
hoststringRoute hostname
annotationsmap[string]stringAdditional Route annotations

GatewayAPISpec ​

FieldTypeDescription
enabledboolToggle HTTPRoute creation
gatewayRef.namestringGateway name (required)
gatewayRef.namespacestringGateway namespace (default: HTTPRoute namespace)
gatewayRef.sectionNamestringListener name on the Gateway
hostnamestringHTTP hostname to match
annotationsmap[string]stringAdditional HTTPRoute annotations

NetworkPolicySpec ​

FieldTypeDefaultDescription
enabled*booltrueCreate per-component NetworkPolicies
extraEgressPorts[]NetworkPolicyPortAdditional destination ports to allow. The defaults cover the well-known datastore ports (plaintext and TLS); use this for non-standard ports such as a connection pooler. See Networking.

NetworkPolicyPort ​

FieldTypeDefaultDescription
portint32Destination port (1–65535).
protocolstringTCPTCP or UDP.

TelemetrySpec ​

FieldTypeDefaultDescription
enabled*booltrueToggle Langfuse's built-in telemetry (TELEMETRY_ENABLED)

ObservabilitySpec ​

FieldTypeDescription
serviceMonitor*ServiceMonitorSpecPrometheus ServiceMonitor
otel*OTELSpecOpenTelemetry integration

ServiceMonitorSpec ​

FieldTypeDefaultDescription
enabledboolfalseCreate a Prometheus ServiceMonitor
intervalstring30sScrape interval
labelsmap[string]stringAdditional ServiceMonitor labels

OTELSpec ​

FieldTypeDefaultDescription
enabledboolfalseToggle OTEL
endpointstringOTEL collector endpoint
protocolstringgrpcgrpc or http

ComponentCircuitBreakerSpec ​

FieldTypeDefaultDescription
actionstringscaleWorkerToZero, emitCriticalEvent, or none
probeIntervalSecondsint3215Health probe interval
failureThresholdint323Failures before opening the circuit
recoveryActionstringrestoreScale or none

PreUpgradeSpec ​

FieldTypeDefaultDescription
runMigrations*booltrueRun migrations before upgrade
backupDatabaseboolfalseTrigger a CNPG backup

RollingUpdateSpec ​

FieldTypeDefaultDescription
maxUnavailable*int320Max unavailable pods during update
maxSurge*int321Max extra pods during update

PostUpgradeSpec ​

FieldTypeDefaultDescription
runBackgroundMigrations*booltrueMonitor background migrations after upgrade
healthCheckTimeoutstring120sTimeout for post-upgrade health checks
autoRollbackboolfalseRevert on health failure

Example ​

yaml
apiVersion: langfuse.palena.ai/v1alpha1
kind: LangfuseInstance
metadata:
  name: production
  namespace: langfuse
spec:
  image:
    tag: "3"
  auth:
    nextAuthUrl: "https://langfuse.example.com"
  web:
    replicas: 3
  worker:
    replicas: 2
  database:
    external:
      secretRef:
        name: langfuse-db
        keys:
          url: database_url
  clickhouse:
    external:
      secretRef:
        name: langfuse-clickhouse
        keys:
          url: url
          username: username
          password: password
  redis:
    external:
      secretRef:
        name: langfuse-redis
        keys:
          host: host
          port: port
          password: password
NAME         PHASE     READY   VERSION   AGE
production   Running   true    3         5d

Released under the Apache 2.0 License.

Copyright 2026 bitkaio LLC