PalenaObservability

A PalenaObservability deploys a LangfuseInstance tied to an existing PalenaGateway and wires a Langfuse callback into the gateway's LiteLLMInstance so every request is traced automatically.

Short name: pobsAPI group: operator.palena.ai/v1alpha1Scope: Namespaced

spec

Field	Type	Required	Description
gatewayRef	LocalObjectReference	Yes	Target PalenaGateway.
langfuse	LangfuseSpec	Yes	Langfuse configuration.

LangfuseSpec

Field	Type	Required	Description
image	ImageSpec	No	Langfuse image override.
web.replicas	int32	No	Web component replicas. Default 1.
web.resources	corev1.ResourceRequirements	No	Web resource requests/limits.
worker.replicas	int32	No	Worker replicas. Default 1.
worker.resources	corev1.ResourceRequirements	No	Worker resources.
auth	LangfuseAuthSpec	No	NextAuth / OIDC / seed user config.
database	LangfuseDatabaseSpec	No	Postgres backend. When nil, reuses the gateway's CNPG cluster.
clickhouse	LangfuseClickHouseSpec	Yes	ClickHouse backend.
redis	LangfuseRedisSpec	No	Redis/Valkey backend. Defaults to managed.
blobStorage	LangfuseBlobStorageSpec	Yes	Object store for traces.
ingress	IngressSpec	No	Ingress configuration.
route	RouteSpec	No	OpenShift Route.

LangfuseAuthSpec

Field	Type	Required	Description
nextAuthUrl	string	No	NextAuth canonical URL. Auto-derived from Ingress when empty.
disableSignup	bool	No	Disable public signups.
oidc	OIDCSpec	No	OIDC provider config.
initUser.email	string	When initUser set	Seed admin email.
initUser.password	SecretKeyRef	When initUser set	Seed admin password.
initUser.orgName	string (default Default)	No	Seed organization name.
initUser.projectName	string (default Default)	No	Seed project name.

LangfuseDatabaseSpec

Exactly one of cloudnativepg or external may be set. Omit entirely to reuse the gateway's CNPG cluster with database langfuse.

Field	Type	Default	Description
cloudnativepg.name	string	—	CNPG Cluster name.
cloudnativepg.namespace	string	current namespace	CNPG Cluster namespace.
cloudnativepg.database	string	langfuse	Target database inside the cluster.
external.secretRef	SecretKeysRef	—	Secret with connection parameter keys.

LangfuseClickHouseSpec

Exactly one of managed or external must be set.

Field	Type	Default	Description
managed.shards	int32	1	Shard count.
managed.replicas	int32	1	Replica count.
managed.storageSize	string	50Gi	PVC size.
managed.storageClass	string	—	Optional StorageClass.
external.secretRef	SecretKeysRef	—	External ClickHouse credentials.

LangfuseBlobStorageSpec

provider must be one of s3, azure, gcs; exactly one matching sub-block must be set.

Field	Type	Description
provider	string	s3, azure, gcs.
s3.endpoint	string	Custom S3 endpoint (for MinIO etc.).
s3.region	string	AWS region.
s3.bucket	string	Required.
s3.forcePathStyle	bool	Required for most non-AWS endpoints.
s3.credentials	SecretKeysRef	Must include accessKeyId, secretAccessKey.
azure.storageAccountName	string	Azure storage account.
azure.containerName	string	Azure container.
azure.credentials	SecretKeysRef	Account credentials.
gcs.bucketName	string	GCS bucket.
gcs.projectId	string	GCP project ID.
gcs.credentials	SecretKeysRef	Service account key.

status

Field	Type	Description
ready	bool	Overall readiness.
langfuseInstanceRef	string	Name of generated LangfuseInstance.
endpoint	string	Public Langfuse URL.
callbackConfigured	bool	True when the gateway's LiteLLMInstance has been patched.
conditions	[]metav1.Condition	Standard conditions (PrerequisitesMet, GatewayReady, LangfuseReady, CallbackConfigured, Ready).

Print columns

Ready, Callback, Endpoint, Age.

Example

apiVersion: operator.palena.ai/v1alpha1
kind: PalenaObservability
metadata:
  name: traces
  namespace: palena
spec:
  gatewayRef:
    name: production
  langfuse:
    web:
      replicas: 2
    worker:
      replicas: 1
    clickhouse:
      managed:
        shards: 1
        replicas: 2
        storageSize: 100Gi
    blobStorage:
      provider: s3
      s3:
        endpoint: https://minio.internal
        region: us-east-1
        bucket: langfuse-traces
        forcePathStyle: true
        credentials:
          name: langfuse-s3
          keys:
            accessKeyId: AWS_ACCESS_KEY_ID
            secretAccessKey: AWS_SECRET_ACCESS_KEY
    auth:
      disableSignup: true
      initUser:
        email: admin@example.com
        password:
          name: langfuse-admin
          key: password
    ingress:
      enabled: true
      host: langfuse.example.com
      className: nginx

Lifecycle notes

• The controller adds a langfuse database to the gateway's existing CNPG cluster via managed.databases — it does not create a second Cluster.
• Once the LangfuseInstance becomes Ready, the controller seeds an org/project and stores the generated API keys in a Secret named <obs-name>-langfuse-apikeys.
• It then patches the gateway's LiteLLMInstance spec.callbacks.langfuse block. The deletion finalizer removes that callback block before allowing GC to proceed.