Kubernetes

Use Helm to deploy Lens with LiteLLM. For an installed LiteLLM chart, go to Add Lens to an existing deployment.

New deployment

This example uses the componentized litellm chart, with one HTTPS hostname for LiteLLM and traces. It creates Lens and a single ClickHouse instance with a 20 GiB persistent volume. Use external ClickHouse if you need database replication or high availability.

Before you start, you need:

• A Kubernetes cluster, kubectl, Helm, and a default storage class.
• PostgreSQL with a database named litellm and a user that can create and alter its schema. This example uses TLS with a certificate trusted by the container's system CA bundle.
• A Redis endpoint reachable from the cluster.
• An NGINX ingress controller, a hostname pointing to it, and the hostname's TLS certificate and private key.

1. Create the secrets

The examples use namespace litellm. Create it and a file for your private configuration:

kubectl create namespace litellm
umask 077
cat > litellm.env <<EOF_ENV
LITELLM_MASTER_KEY=sk-$(openssl rand -hex 32)
LITELLM_SALT_KEY=sk-$(openssl rand -hex 32)
STORE_MODEL_IN_DB=True
EOF_ENV

Add your Redis URL to litellm.env. Use rediss:// for TLS and URL-encode special characters in the password:

REDIS_URL=rediss://default:URL_ENCODED_PASSWORD@redis.example.com:6379

Create the application secret:

kubectl create secret generic litellm-env --namespace litellm \
  --from-env-file=litellm.env

Create postgres.env with your PostgreSQL credentials, then import it:

postgres.env

username=litellm
password=YOUR_POSTGRES_PASSWORD

chmod 600 postgres.env
kubectl create secret generic litellm-db --namespace litellm \
  --from-env-file=postgres.env

Keep these files out of Git and store the credentials in your secret manager. Preserve the master and encryption keys with your database backups. Lens's service token and ClickHouse password are generated by the chart.

Import the certificate, replacing the two file paths:

kubectl create secret tls litellm-tls --namespace litellm \
  --cert=/path/to/fullchain.pem --key=/path/to/privkey.pem

2. Save the values file

Save this as values.yaml. Replace postgres.example.com and both occurrences of llm.example.com with your database host and public hostname:

values.yaml

masterKey:
  secretName: litellm-env
  secretKey: LITELLM_MASTER_KEY

database:
  writer:
    host: postgres.example.com
    port: 5432
    dbname: litellm
    sslMode: verify-full
    sslRootCert: /etc/ssl/certs/ca-certificates.crt
    passwordSecret:
      name: litellm-db
      usernameKey: username
      passwordKey: password

gateway:
  envSecrets: [litellm-env]
  config:
    proxy_config:
      general_settings:
        coordination_redis:
          url: os.environ/REDIS_URL
backend:
  envSecrets: [litellm-env]

ingress:
  enabled: true
  className: nginx
  controller: nginx
  host: llm.example.com
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
  tls:
    - secretName: litellm-tls
      hosts: [llm.example.com]

lensWorker:
  enabled: true

The chart routes /lens-ingest to Lens and supplies the public tracing URL to the dashboard. No separate Lens hostname or connection settings are needed. To choose another storage class, add lensWorker.clickhouse.storageClassName.

3. Install

Select a published chart with Lens. Replace RELEASE_VERSION with its version, without the v prefix, then install:

export CHART_VERSION="RELEASE_VERSION"
helm upgrade --install litellm \
  oci://ghcr.io/berriai/litellm/chart/litellm \
  --version "$CHART_VERSION" \
  --namespace litellm -f values.yaml --wait

The chart runs PostgreSQL migrations and deploys LiteLLM, Lens, and ClickHouse. Check the installation before connecting your agents.

Add Lens to an existing deployment

Keep your chart, release name, namespace, model configuration, and database. Select a matching chart release with Lens support. Update any gateway or backend image overrides to that release too.

1. Enable Lens

Add this to your existing values file:

lensWorker:
  enabled: true

The chart creates the service token and ClickHouse with a 20 GiB persistent volume. Your cluster needs a default storage class. For external ClickHouse, managed secrets, or GitOps, follow Storage and secrets before installing.

With one HTTPS hostname in the chart's main ingress, /lens-ingest is routed to Lens and the dashboard receives its public URL. If you use a separate trace hostname, add the dedicated ingress settings to the same values file.

2. Deploy

Use your existing release name, namespace, values file, and chart reference. This example uses litellm for the release and namespace:

export CHART_VERSION="RELEASE_VERSION"
helm upgrade litellm oci://ghcr.io/berriai/litellm/chart/litellm \
  --version "$CHART_VERSION" \
  --namespace litellm -f values.yaml --wait

For the single-container chart, use oci://ghcr.io/berriai/litellm-helm instead. Do not switch chart types to enable Lens. Published charts include their Lens image digest; source charts need it supplied explicitly.

Check the installation

Check the pods and ingress in your namespace:

kubectl get pods,ingress --namespace litellm

For the new deployment example, open https://llm.example.com/ui/. Sign in as admin with the LITELLM_MASTER_KEY from litellm.env. For an existing deployment, use your usual administrator login.

1. Open Lens > Set up Lens, or Traces > Set up tracing if you already have traces.
2. Check that Traces endpoint is https://llm.example.com/lens-ingest/v1/traces, using your hostname.
3. Click Generate tracing key, then Send a test trace.
4. Click View trace, then connect your agent.

If a service is unavailable, use Troubleshooting. Before relying on this installation for production data, configure backups for PostgreSQL, ClickHouse, and secrets. The production checklist covers capacity and availability settings.