### Install Langfuse Helm Chart (Development)

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/README.md

Installs the Langfuse Helm chart using a development values file. Refer to the installation guide for minimal setup details.

```bash
helm install langfuse langfuse/langfuse \
  -f values-dev.yaml
```

--------------------------------

### Basic Helm Installation

Source: https://github.com/langfuse/langfuse-k8s/blob/main/examples/minimal-installation/README.md

Install the Langfuse Helm chart using the base `values.yaml` file for a basic setup.

```bash
helm install langfuse langfuse/langfuse -f values.yaml
```

--------------------------------

### Install Langfuse Helm Chart (Production)

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/README.md

Installs the Langfuse Helm chart using a production values file for high availability. Refer to the installation guide for production setup details.

```bash
helm install langfuse langfuse/langfuse \
  -f values-prod.yaml
```

--------------------------------

### Fallback Chain Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

Demonstrates a fallback chain for determining a value, starting from specific overrides down to chart defaults.

```yaml
# Uses: web.tag → langfuse.image.tag → Chart.AppVersion
langfuse:
  web:
    image:
      tag: null  # Falls back to parent
  image:
    tag: null    # Falls back to appVersion
```

--------------------------------

### Install Langfuse Helm Chart

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Add the Langfuse Helm repository, update it, and install the Langfuse chart with a custom values.yaml file.

```bash
helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
helm install langfuse langfuse/langfuse -f values.yaml
```

--------------------------------

### Loop Over Arrays Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Illustrates iterating over an array of hosts to define ingress configurations.

```go
{{ range .Values.langfuse.ingress.hosts }}
- host: {{ .host }}
{{ end }}
```

--------------------------------

### Helm Installation with Ingress

Source: https://github.com/langfuse/langfuse-k8s/blob/main/examples/minimal-installation/README.md

Install the Langfuse Helm chart with ingress enabled, using both base values and ingress-specific configuration files.

```bash
helm install langfuse langfuse/langfuse -f values.yaml -f with-ingress.yaml
```

--------------------------------

### Conditional Resource Creation Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Demonstrates how to conditionally include resources like HPA based on a Helm value.

```go
{{ if .Values.langfuse.web.hpa.enabled }}
// Create HPA only if enabled
{{ end }}
```

--------------------------------

### Install Helm Unittest Plugin

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Command to install the helm unittest plugin, which is required for running local tests for the Langfuse Helm chart.

```shell
helm plugin install https://github.com/helm-unittest/helm-unittest.git

```

--------------------------------

### Default Values with Fallbacks Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Shows how to provide default values for image tags, falling back to global or chart versions.

```go
{{ .Values.langfuse.web.image.tag | default .Values.langfuse.image.tag | default .Chart.AppVersion }}
// Use web tag, fallback to global tag, fallback to chart version
```

--------------------------------

### Install Langfuse Helm Chart

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Installs the Langfuse Helm chart into the 'langfuse' namespace using the specified `values.yaml` file. This command deploys Langfuse to your Kubernetes cluster.

```bash
helm install langfuse langfuse/langfuse \
  --namespace langfuse \
  --values values.yaml
```

--------------------------------

### Safe Dictionaries Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Demonstrates using `with` to safely access nested dictionary values and render them as YAML.

```go
{{ with .Values.langfuse.resources }}
resources:
  {{ . | toYaml }}
{{ end }}
```

--------------------------------

### Langfuse Helm Chart Global Schema Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

Illustrates the global configuration settings, specifically focusing on security-related options like allowing insecure images.

```yaml
global:
  security:
    allowInsecureImages: boolean  # true or false
```

--------------------------------

### Development Sizing Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Example Helm values for a single-node development deployment of Langfuse, PostgreSQL, ClickHouse, and Redis. Adjust resource requests and limits as needed.

```yaml
langfuse:
  replicas: 1
  resources:
    requests:
      cpu: 250m
      memory: 512Mi
    limits:
      cpu: 1000m
      memory: 1Gi

postgresql:
  primary:
    resources:
      requests:
        cpu: 250m
        memory: 512Mi

clickhouse:
  resourcesPreset: small

redis:
  primary:
    resources:
      requests:
        cpu: 100m
        memory: 256Mi
```

--------------------------------

### Configure SSO Provider using Secrets

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

This example demonstrates setting up Okta SSO by referencing client ID, secret, and issuer from a Kubernetes secret. This pattern is applicable to other SSO providers supported by Langfuse.

```yaml
langfuse:
  additionalEnv:
    - name: AUTH_OKTA_CLIENT_ID
      valueFrom:
        secretKeyRef:
          name: okta-secrets
          key: AUTH_OKTA_CLIENT_ID
    - name: AUTH_OKTA_CLIENT_SECRET
      valueFrom:
        secretKeyRef:
          name: okta-secrets
          key: AUTH_OKTA_CLIENT_SECRET
    - name: AUTH_OKTA_ISSUER
      valueFrom:
        secretKeyRef:
          name: okta-secrets
          key: AUTH_OKTA_ISSUER

```

```yaml
apiVersion: v1
kind: Secret
metadata:
  name: okta-secrets
type: Opaque
stringData:
  AUTH_OKTA_CLIENT_ID: "your-okta-client-id"
  AUTH_OKTA_CLIENT_SECRET: "your-okta-client-secret"
  AUTH_OKTA_ISSUER: "https://your-domain.okta.com"

```

--------------------------------

### Minimal values.yaml for Langfuse Installation

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Defines the essential configuration parameters for a basic Langfuse Helm chart installation. This includes generating unique salts, secrets, and passwords for various services.

```yaml
# Minimal required configuration
langfuse:
  salt:
    value: $(openssl rand -base64 32)  # Generate unique salt
  nextauth:
    secret:
      value: $(openssl rand -hex 32)   # Generate unique secret
  nextauth:
    url: https://langfuse.example.com  # Set to your public URL

postgresql:
  auth:
    password: $(openssl rand -base64 32)  # Generate secure password

clickhouse:
  auth:
    password: $(openssl rand -base64 32)  # Generate secure password

redis:
  auth:
    password: $(openssl rand -base64 32)  # Generate secure password

s3:
  auth:
    rootPassword: $(openssl rand -base64 32)  # Generate MinIO password
```

--------------------------------

### Create PostgreSQL Password Secret

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Example of creating a Kubernetes secret to securely store sensitive information like database passwords.

```bash
kubectl create secret generic pg-auth \
  --from-literal=password=secure_password
```

--------------------------------

### Direct Value Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

Provides a value directly within the Helm chart configuration.

```yaml
langfuse:
  salt:
    value: "salt123"
```

--------------------------------

### Production Sizing Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Example Helm values for a 3-node production deployment of Langfuse, PostgreSQL, ClickHouse, and Redis. This configuration increases replica counts and resource allocations for higher availability and performance.

```yaml
langfuse:
  web:
    replicas: 3
    resources:
      requests:
        cpu: 1000m
        memory: 1Gi
      limits:
        cpu: 2000m
        memory: 2Gi

  worker:
    replicas: 2
    resources:
      requests:
        cpu: 500m
        memory: 512Mi

postgresql:
  primary:
    resources:
      requests:
        cpu: 1000m
        memory: 1Gi

clickhouse:
  replicaCount: 3
  resourcesPreset: 2xlarge

redis:
  primary:
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
```

--------------------------------

### Default Value Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

Illustrates using a chart-defined default value when a configuration is not explicitly provided.

```yaml
langfuse:
  nodeEnv: production  # Default if not specified
```

--------------------------------

### Apply Topology Spread Constraints for High Availability

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

These examples show how to configure topology spread constraints to distribute Langfuse pods evenly across zones and hostnames, enhancing high availability. Constraints can be applied globally or per component (web, worker).

```yaml
langfuse:
  # Global topology spread constraints applied to all langfuse pods
  pod:
    topologySpreadConstraints:
      - maxSkew: 1
        topologyKey: topology.kubernetes.io/zone
        whenUnsatisfiable: ScheduleAnyway
        labelSelector:
          matchLabels:
            app.kubernetes.io/instance: langfuse
  
  # Component-specific topology spread constraints
  web:
    pod:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: web
  
  worker:
    pod:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: kubernetes.io/hostname
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app: worker

```

--------------------------------

### Render Helm Chart Templates

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Render Helm chart templates for the langfuse release without installing them. The output is saved to manifests.yaml.

```bash
helm template langfuse langfuse/langfuse \
  --namespace langfuse \
  --values values.yaml > manifests.yaml
```

--------------------------------

### Secret Reference Example

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

References a value from an existing Kubernetes secret.

```yaml
langfuse:
  salt:
    secretKeyRef:
      name: my-secrets
      key: salt
```

--------------------------------

### Extra Manifests Template

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Allows deploying custom Kubernetes resources defined in `extraManifests`. Includes an example configuration for a ConfigMap.

```yaml
{{ range .Values.extraManifests }}
---
{{ . }}
{{ end }}
```

```yaml
extraManifests:
  - apiVersion: v1
    kind: ConfigMap
    metadata:
      name: custom-config
    data:
      key: value
```

--------------------------------

### Ingress with Custom Backend for Redirect

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Configure ingress with a custom backend, specifically for setting up redirects using annotations like the AWS Load Balancer Controller. This example sets up a redirect to a different host and status code.

```yaml
langfuse:
  ingress:
    enabled: true
    className: "alb"
    annotations:
      alb.ingress.kubernetes.io/scheme: internet-facing
      alb.ingress.kubernetes.io/target-type: ip
      alb.ingress.kubernetes.io/actions.redirect-to-langfuse: |
        {
          "type": "redirect",
          "redirectConfig": {
            "protocol": "HTTPS",
            "port": "443",
            "host": "langfuse.example.com",
            "statusCode": "HTTP_301"
          }
        }
    hosts:
      - host: langfuse.example.com
        paths:
        - path: /
          pathType: Prefix
      - host: langfuse-v3.example.com
        paths:
        - path: /
          pathType: Prefix
          backend:
            service:
              name: redirect-to-langfuse
              port:
                name: use-annotation
```

--------------------------------

### Check Pod Status and Describe Pods

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Get the status of all pods in the Langfuse namespace and describe a specific pod to view its events and status.

```bash
# Get pod status
kubectl get pods -n langfuse

# Describe a pod for events
kubectl describe pod <pod-name> -n langfuse
```

--------------------------------

### Redis/Valkey Cluster Mode Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Configuration for deploying Redis or Valkey in cluster mode for high availability and horizontal scaling. Requires 'deploy: false' to indicate an external setup.

```yaml
redis:
  deploy: false
  cluster:
    enabled: true
    nodes:
      - "redis-1:6379"
      - "redis-2:6379"
      - "redis-3:6379"
  auth:
    password: cluster_password
```

--------------------------------

### Verify Langfuse Installation Status

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Checks the status of Langfuse pods, waits for deployments to become ready, and displays recent logs for the web and worker components to confirm a successful installation.

```bash
# Check pod status
kubectl get pods -n langfuse

# Wait for pods to be ready (usually 2-3 minutes)
kubectl rollout status deployment/langfuse-web -n langfuse

# Check logs
kubectl logs -n langfuse -l app=web --tail=50
kubectl logs -n langfuse -l app=worker --tail=50
```

--------------------------------

### Follow Pod Logs in Real-time

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Follow logs in real-time for pods with the label app=web in the langfuse namespace.

```bash
kubectl logs -n langfuse -l app=web -f
```

--------------------------------

### List PostgreSQL Databases

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

List all available databases in the PostgreSQL instance. This command assumes a local connection to PostgreSQL via port forwarding.

```bash
psql -h localhost -U postgres -l
```

--------------------------------

### Check Ingress Status

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

View the status of Kubernetes Ingress resources and get detailed information about a specific Ingress.

```bash
kubectl get ingress -n langfuse
kubectl describe ingress langfuse -n langfuse
```

--------------------------------

### Hostname Helpers for Services

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

These Go template functions construct connection strings for various backend services like databases and caches.

```go-template
{{ include "langfuse.postgresql.hostname" . }}
// Returns: release-postgresql (if deploy=true) or configured host
```

```go-template
{{ include "langfuse.redis.hostname" . }}
// Returns: release-redis-primary (if deploy=true) or configured host
```

```go-template
{{ include "langfuse.clickhouse.hostname" . }}
// Returns: release-clickhouse (if deploy=true) or configured host
```

```go-template
{{ include "langfuse.s3.endpoint" . }}
// Returns: http://release-s3:9000 (if deploy=true) or configured endpoint
```

--------------------------------

### Enable Ingress with Host and Path

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Enable ingress for Langfuse and configure a primary host and path. This allows external access to your Langfuse instance.

```yaml
langfuse:
  ingress:
    enabled: true
    hosts:
    - host: langfuse.your-host.com
      paths:
      - path: /
        pathType: Prefix
    annotations: []
```

--------------------------------

### Retrieve Initial Admin Credentials from Pod Logs

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Find the initial admin credentials by searching the logs of the Langfuse web pods for relevant information.

```bash
# Check pod logs for initial setup info
kubectl logs -n langfuse -l app=web --all-containers=true | grep -i admin
```

--------------------------------

### Get External IP of LoadBalancer Service

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Retrieve the external IP address assigned to a Kubernetes Service of type LoadBalancer.

```bash
kubectl get service -n langfuse langfuse -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
```

--------------------------------

### Recommended Resource Requests and Limits for Production

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Define recommended resource requests and limits for production environments for web, worker, PostgreSQL, Redis, and ClickHouse components.

```yaml
langfuse:
  web:
    resources:
      requests:
        cpu: 1000m
        memory: 1Gi
      limits:
        cpu: 2000m
        memory: 2Gi

  worker:
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
      limits:
        cpu: 1000m
        memory: 1Gi

postgresql:
  primary:
    resources:
      requests:
        cpu: 1000m
        memory: 1Gi

redis:
  primary:
    resources:
      requests:
        cpu: 500m
        memory: 512Mi

clickhouse:
  resourcesPreset: 2xlarge
```

--------------------------------

### Image Configuration Changes

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Illustrates the restructuring of image configuration, allowing per-component overrides.

```yaml
# Old
image:
  repository: langfuse/langfuse
  pullPolicy: Always
  tag: 3

# New
langfuse:
  image:
    tag: 3
    pullPolicy: Always
    pullSecrets: []
  
  web:
    image:
      repository: langfuse/langfuse
      tag: null  # Inherits from langfuse.image.tag if not set
      pullPolicy: null  # Inherits from langfuse.image.pullPolicy if not set
  
  worker:
    image:
      repository: langfuse/langfuse-worker
      tag: null  # Inherits from langfuse.image.tag if not set
      pullPolicy: null  # Inherits from langfuse.image.pullPolicy if not set
```

--------------------------------

### Upgrade Langfuse to Latest Version

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Upgrade an existing Langfuse installation to the latest version using Helm. Ensure your values.yaml is correctly configured.

```bash
helm upgrade langfuse langfuse/langfuse \
  --namespace langfuse \
  --values values.yaml
```

--------------------------------

### Add Langfuse Helm Repository

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Adds the Langfuse Helm chart repository to your local Helm configuration. Ensure Helm 3.x is installed.

```bash
helm repo add langfuse https://langfuse.github.io/langfuse-k8s
helm repo update
```

--------------------------------

### View Helm Chart Differences

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Use `helm diff upgrade` to compare the current release with a potential upgrade, showing configuration changes.

```bash
helm diff upgrade langfuse langfuse/langfuse \
  --namespace langfuse \
  --values values.yaml
```

--------------------------------

### External Database Configuration (PostgreSQL, ClickHouse, Redis)

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Configure connection details for external PostgreSQL, ClickHouse, and Redis instances. Ensure 'deploy' is set to false for external services.

```yaml
postgresql:
  deploy: false
  host: mydb.postgres.database.azure.com
  port: 5432
  auth:
    username: langfuse_user
    password: secure_password
    database: langfuse_prod
  directUrl: postgresql://langfuse_user:password@mydb.postgres.database.azure.com/langfuse_prod
  shadowDatabaseUrl: postgresql://langfuse_user:password@mydb.postgres.database.azure.com/shadow_db

clickhouse:
  deploy: false
  host: mycluster.clickhouse.com
  httpPort: 8123
  nativePort: 9000
  database: default
  auth:
    username: default
    password: secure_password

redis:
  deploy: false
  host: my-redis.cache.amazonaws.com
  port: 6379
  auth:
    password: secure_password
```

--------------------------------

### Verify Langfuse Helm Repository

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Lists all configured Helm repositories and searches for the Langfuse chart to confirm successful addition.

```bash
helm repo list
helm search repo langfuse
```

--------------------------------

### Generate Secure Values for Langfuse Installation

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Generates random, secure values for salt, NextAuth secret, and database/storage passwords using openssl. These are used in the `values.yaml` file.

```bash
# Generate salt for API key hashing
SALT=$(openssl rand -base64 32)

# Generate NextAuth secret
NEXTAUTH_SECRET=$(openssl rand -hex 32)

# Generate database passwords
PG_PASSWORD=$(openssl rand -base64 32)
CH_PASSWORD=$(openssl rand -base64 32)
REDIS_PASSWORD=$(openssl rand -base64 32)
MINIO_PASSWORD=$(openssl rand -base64 32)
```

--------------------------------

### Langfuse Encryption Key Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Demonstrates the transition from using an environment variable for encryption keys to a structured configuration, supporting direct values or existing secrets.

```yaml
# Old
langfuse:
  additionalEnv:
    - name: "ENCRYPTION_KEY"
      value: "<encryption-key>"

# New
langfuse:
  encryptionKey:
    value: "<encryption-key>"
```

```yaml
langfuse:
  encryptionKey:
    existingSecret: <secret-name>
    existingSecretKey: <secret-key>
```

--------------------------------

### Create PostgreSQL Backup

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Create a backup of the postgres_langfuse database using pg_dump. This command assumes a local connection to PostgreSQL via port forwarding.

```bash
pg_dump -h localhost -U postgres -d postgres_langfuse > langfuse_backup.sql
```

--------------------------------

### Minimal Production Values

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

Configuration for a minimal production deployment, generating necessary secrets and setting up essential services.

```yaml
langfuse:
  salt:
    value: "$(openssl rand -base64 32)"
  nextauth:
    url: https://langfuse.example.com
    secret:
      value: "$(openssl rand -hex 32)"

postgresql:
  auth:
    password: "$(openssl rand -base64 32)"

clickhouse:
  auth:
    password: "$(openssl rand -base64 32)"

redis:
  auth:
    password: "$(openssl rand -base64 32)"

s3:
  auth:
    rootPassword: "$(openssl rand -base64 32)"
```

--------------------------------

### Convert to YAML with Helm

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Use `toYaml` to convert a dictionary or object into a YAML formatted string. This is helpful for generating configuration files.

```helm
{{ dict | toYaml }}
```

--------------------------------

### ClickHouse Configuration Migration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Explains the migration of ClickHouse configuration from environment variables to a structured format, including host, ports, authentication, and migration URLs. Note that the new structure and `additionalEnv` are mutually exclusive.

```yaml
# Old Clickhouse Configuration (in additionalEnv)
langfuse:
  additionalEnv:
    - name: "CLICKHOUSE_MIGRATION_URL"
      value: "clickhouse://<host>:<native-port>"
    - name: "CLICKHOUSE_URL"
      value: "http://<host>:<http-port>"
    - name: "CLICKHOUSE_USER"
      value: "<username>"
    - name: "CLICKHOUSE_PASSWORD"
      value: "<password>"

# New Clickhouse Configuration
clickhouse:
  host: <host>
  httpPort: <http-port>
  nativePort: <native-port>
  auth:
    username: "<username>"
    password: "<password>"
  migration:
    url: "clickhouse://<host>:<native-port>"
```

```yaml
clickhouse:
  auth:
    existingSecret: <secret-name>
    existingSecretPasswordKey: <password-key>
```

--------------------------------

### Per-Upload Type S3/MinIO Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Shows how to configure S3/MinIO buckets and endpoints for specific upload types.

```yaml
s3:
  nameOverride: minio
  eventUpload:
    bucket: <bucket>
    [...]
  batchExport:
    bucket: <bucket>
    [...]
  mediaUpload:
    bucket: <bucket>
    [...]
```

--------------------------------

### Redis Configuration Migration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Details the renaming of the `valkey` section to `redis` and the integration of environment variables into structured parameters for connection details and authentication.

```yaml
# Old Redis Configuration
langfuse:
  additionalEnv:
    - name: "REDIS_CONNECTION_STRING"
      value: "redis://<username>:<password>@<host>:<port>/<database>"

# New Redis Configuration
redis:
  nameOverride: valkey
  host: <host>
  port: <port>
  auth:
    username: <username>
    password: <password>
    database: <database>
```

```yaml
redis:
  auth:
    existingSecret: <secret-name>
    existingSecretPasswordKey: <password-key>
```

--------------------------------

### Run Helm Unittests Locally

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Command to execute the Helm unittests for the Langfuse chart locally. The --color flag enables colored output.

```shell
helm unittest charts/langfuse --color

```

--------------------------------

### Test PostgreSQL Connection

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Test PostgreSQL connection from a pod using the postgres:15 image. This command runs interactively and will be removed upon completion.

```bash
kubectl run -it --rm psql-test \
  --image=postgres:15 \
  --restart=Never \
  -n langfuse \
  -- psql -h langfuse-postgresql -U postgres -c "SELECT 1"
```

--------------------------------

### Test PostgreSQL Restore

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Test restoring a backup to a newly created test database. This command assumes a local connection to PostgreSQL via port forwarding.

```bash
psql -h localhost -U postgres -c "CREATE DATABASE test_langfuse"
psql -h localhost -U postgres -d test_langfuse < langfuse_backup.sql
```

--------------------------------

### S3/MinIO Configuration Structure

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Defines the environment variables and the new global S3/MinIO configuration structure for uploads.

```yaml
- name: "LANGFUSE_S3_EVENT_UPLOAD_BUCKET"
  value: "<bucket>"
- name: "LANGFUSE_S3_EVENT_UPLOAD_REGION"
  value: "<region>"
- name: "LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID"
  value: "<access-key-id>"
- name: "LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY"
  value: "<secret-access-key>"
- name: "LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT"
  value: "<endpoint>"
- name: "LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE"
  value: "true"

# New S3/MinIO Configuration - global settings
s3:
  nameOverride: minio
  bucket: <bucket>
  region: <region>
  endpoint: <endpoint>
  forcePathStyle: true
  accessKeyId:
    value: "<access-key-id>"
  secretAccessKey:
    value: "<secret-access-key>"
  eventUpload:
    prefix: "events/"
  batchExport:
    prefix: "exports/"
  mediaUpload:
    prefix: "media/"
```

--------------------------------

### Minimum Resource Requests and Limits

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Specify minimum resource requests and limits for CPU and memory for development or testing environments.

```yaml
langfuse:
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi
```

--------------------------------

### Chart and Metadata Helpers

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

These Go template functions are used to generate common Kubernetes resource names and labels.

```go-template
{{ include "langfuse.name" . }}
// Expands to: langfuse (or nameOverride if set)
```

```go-template
{{ include "langfuse.fullname" . }}
// Expands to: release-langfuse (or fullnameOverride if set)
```

```go-template
{{ include "langfuse.chart" . }}
// Expands to: langfuse-1.5.32
```

```go-template
{{ include "langfuse.labels" . }}
// Common Kubernetes labels for all resources
```

```go-template
{{ include "langfuse.selectorLabels" . }}
// Labels used for pod selectors
```

--------------------------------

### Test ClickHouse Connection

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Test ClickHouse connection from a pod using the clickhouse/clickhouse-client image. This command runs interactively and will be removed upon completion.

```bash
kubectl run -it --rm ch-test \
  --image=clickhouse/clickhouse-client \
  --restart=Never \
  -n langfuse \
  -- clickhouse-client -h langfuse-clickhouse -u default
```

--------------------------------

### Logging Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Introduces the new logging configuration section for setting log level and format.

```yaml
langfuse:
  logging:
    level: info  # trace, debug, info, warn, error, fatal
    format: text # text or json
```

--------------------------------

### Custom Storage Class Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Define custom storage classes for different components like PostgreSQL and ClickHouse to manage persistent volume provisioning.

```yaml
global:
  defaultStorageClass: "fast-ssd"

postgresql:
  primary:
    persistence:
      storageClass: "postgres-ssd"

clickhouse:
  persistence:
    storageClass: "clickhouse-ssd"
```

--------------------------------

### Pod Disruption Budget (PDB) Template

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Ensures application availability during voluntary disruptions by setting minimum available pods. Only created if `langfuse.web.pdb.create` is true.

```yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: {{ include "langfuse.fullname" . }}-web
spec:
  {{ if .Values.langfuse.web.pdb.minAvailable }}
  minAvailable: {{ .Values.langfuse.web.pdb.minAvailable }}
  {{ else if .Values.langfuse.web.pdb.maxUnavailable }}
  maxUnavailable: {{ .Values.langfuse.web.pdb.maxUnavailable }}
  {{ else }}
  maxUnavailable: 1
  {{ end }}
  selector:
    matchLabels:
      {{ include "langfuse.selectorLabels" . | nindent 6 }}
      app: web
```

--------------------------------

### Minimal Langfuse Configuration for Development

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

A minimal `values.yaml` configuration suitable for development and testing environments. It sets basic parameters and resource requests/limits.

```yaml
langfuse:
  salt:
    value: secure_salt_value
  nextauth:
    secret:
      value: secure_nextauth_secret
    url: http://localhost:3000

langfuse:
  replicas: 1
  resources:
    requests:
      cpu: 100m
      memory: 256Mi
    limits:
      cpu: 500m
      memory: 512Mi

postgresql:
  auth:
    password: postgres_password

clickhouse:
  auth:
    password: clickhouse_password

redis:
  auth:
    password: redis_password

s3:
  auth:
    rootPassword: minio_password
```

--------------------------------

### View Pod Logs

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

View logs for a specific pod in the langfuse namespace. Replace <pod-name> with the actual pod name.

```bash
kubectl logs -n langfuse <pod-name> -c langfuse
```

--------------------------------

### Langfuse Helm Chart Configuration for Web Service

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Configure the Langfuse web service, including image repository, replicas, service type, and autoscaling options.

```yaml
langfuse:
  web:
    image.repository: langfuse/langfuse
    replicas: 1
    service:
      type: ClusterIP
      port: 3000
    hpa.enabled: false
    keda.enabled: false
    vpa.enabled: false
```

--------------------------------

### Configure External Postgres with Client Certificates

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

This configuration mounts client certificates from a secret and uses them in the DATABASE_URL for secure connection to an external PostgreSQL server. It also sets NextAuth and Salt secrets.

```yaml
langfuse:
  salt: null
  nextauth: 
    secret: null
  extraVolumes:
    - name: db-keystore   # referencing an existing secret to mount server/client certs for postgres
      secret:
        secretName: langfuse-postgres  # contain the following files (server-ca.pem, sslidentity.pk12)
  extraVolumeMounts:
    - name: db-keystore
      mountPath: /secrets/db-keystore  # mounting the db-keystore store certs in the pod under the given path
      readOnly: true
  additionalEnv:
    - name: DATABASE_URL  # Using the certs in the url eg. postgresql://the-db-user:the-password@postgres-host:5432/langfuse?ssl=true&sslmode=require&sslcert=/secrets/db-keystore/server-ca.pem&sslidentity=/secrets/db-keystore/sslidentity.pk12&sslpassword=the-ssl-identity-pw
      valueFrom:
        secretKeyRef:
          name: langfuse-postgres  # referencing an existing secret
          key: database-url
    - name: NEXTAUTH_SECRET
      valueFrom:
        secretKeyRef:
          name: langfuse-general # referencing an existing secret
          key: nextauth-secret
    - name: SALT
      valueFrom:
        secretKeyRef:
          name: langfuse-general
          key: salt
service: 
  [...]
ingress: 
  [...]
postgresql:
  deploy: false
  auth:
    password: null
    username: null

```

--------------------------------

### Basic Langfuse Configuration with Secrets

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Set essential configuration parameters for Langfuse, including salt, NextAuth secret, and database/cache credentials.

```yaml
# Optional, but highly recommended. Generate via `openssl rand -hex 32`.
#  langfuse:
#    encryptionKey:
#      value: ""
langfuse: 
  salt:
    value: secureSalt
  nextauth:
    secret:
      value: ""

postgresql:
  auth:
    # If you want to use `postgres` as the username, you need to provide postgresPassword instead of password.
    username: langfuse
    password: ""

clickhouse:
  auth:
    password: ""

redis:
  auth:
    password: ""

s3:
  auth:
    rootPassword: ""
```

--------------------------------

### Include Template Output with Helm

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Use the `include` function to render and output the content of another template. This is useful for reusing template logic across your Helm chart.

```helm
{{ include "langfuse.labels" . }}
```

--------------------------------

### Langfuse Helm Chart Configuration for External PostgreSQL

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Configure connection details for an external PostgreSQL database when 'deploy' is set to false in the chart.

```yaml
postgresql:
  deploy: false
  host: my-postgres.example.com
  auth:
    username: langfuse_user
    password: secure_password
  directUrl: "postgres://langfuse_user:password@my-postgres.example.com/langfuse_db"
```

--------------------------------

### Provide Default Value with Helm

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

The `default` function provides a fallback value if the specified value is empty or not set. This helps in creating more resilient configurations.

```helm
{{ .Value | default "fallback" }}
```

--------------------------------

### Ingress with Mixed Backends for Paths

Source: https://github.com/langfuse/langfuse-k8s/blob/main/README.md

Configure ingress for a single host but with different backends for different paths. This allows routing to the main application or a specific service like a webhook handler.

```yaml
langfuse:
  ingress:
    enabled: true
    hosts:
    - host: langfuse.example.com
      paths:
      - path: /
        pathType: Prefix
      - path: /api/webhook
        pathType: Prefix
        backend:
          service:
            name: webhook-service
            port:
              number: 8080
```

--------------------------------

### Redis/Valkey Embedded Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/deployment-architecture.md

Default configuration for deploying Redis or Valkey as an embedded cache and job queue. Set 'deploy' to false to use an external service.

```yaml
redis:
  deploy: true  # Set to false for external Redis
  host: ""  # Auto-discovered if deploy=true
  port: 6379
  auth:
    username: default
    password: ""
  cluster:
    enabled: false
    nodes: []
  sentinel:
    enabled: false
```

--------------------------------

### Port Forward to PostgreSQL

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/installation-guide.md

Establish a port forward connection to the langfuse-postgresql service in the langfuse namespace to access the PostgreSQL database locally.

```bash
kubectl port-forward -n langfuse svc/langfuse-postgresql 5432:5432
```

--------------------------------

### Add and Update Helm Repository

Source: https://github.com/langfuse/langfuse-k8s/blob/main/examples/minimal-installation/README.md

Add the Langfuse Helm repository and update your local Helm repository cache.

```bash
helm repo add langfuse https://cbeneke.github.io/langfuse-k8s
helm repo update
```

--------------------------------

### Langfuse Helm Chart Root Level Keys

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/values-schema.md

Defines the main configuration sections available at the root level of the values.yaml file. These include global settings, database configurations (PostgreSQL, Redis, ClickHouse), and object storage.

```yaml
global:                    # Global settings for all components
nameOverride:             # Override chart name
fullnameOverride:         # Override full resource name
langfuse:                 # Core Langfuse application settings
postgresql:              # PostgreSQL database configuration
redis:                   # Redis/Valkey cache configuration
clickhouse:              # ClickHouse analytics database configuration
s3:                      # S3/Object storage configuration
extraManifests:          # Additional Kubernetes manifests
```

--------------------------------

### Apply Secret Configuration

Source: https://github.com/langfuse/langfuse-k8s/blob/main/examples/minimal-installation/README.md

Apply the Kubernetes secret configuration. Ensure you edit `secret.yaml` to set secure values before applying.

```bash
kubectl apply -f secret.yaml
```

--------------------------------

### Vertical Pod Autoscaler (VPA) Template

Source: https://github.com/langfuse/langfuse-k8s/blob/main/_autodocs/templates-reference.md

Manages resource optimization for pods by automatically adjusting CPU and memory requests. Only created if `langfuse.web.vpa.enabled` is true.

```yaml
apiVersion: autoscaling.k8s.io/v1
kind: VerticalPodAutoscaler
metadata:
  name: {{ include "langfuse.fullname" . }}-web
spec:
  targetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {{ include "langfuse.fullname" . }}-web
  updatePolicy:
    updateMode: {{ .Values.langfuse.web.vpa.updatePolicy.updateMode }}
  resourcePolicy:
    containerPolicies:
      - containerName: "*"
        {{ if .Values.langfuse.web.vpa.minAllowed }}
        minAllowed:
          {{ .Values.langfuse.web.vpa.minAllowed | toYaml | nindent 10 }}
        {{ end }}
        {{ if .Values.langfuse.web.vpa.maxAllowed }}
        maxAllowed:
          {{ .Values.langfuse.web.vpa.maxAllowed | toYaml | nindent 10 }}
        {{ end }}
        {{ if .Values.langfuse.web.vpa.controlledResources }}
        controlledResources:
          {{ .Values.langfuse.web.vpa.controlledResources | toYaml | nindent 10 }}
        {{ end }}
```

--------------------------------

### S3/MinIO Configuration Renaming

Source: https://github.com/langfuse/langfuse-k8s/blob/main/UPGRADE.md

Details the renaming of the `minio` section to `s3` and the integration of environment variables into structured parameters for enabling event uploads.

```yaml
# Old S3/MinIO Configuration (in additionalEnv)
langfuse:
  additionalEnv:
    - name: "LANGFUSE_S3_EVENT_UPLOAD_ENABLED"
      value: "true"
```