---
title: "Kubernetes"
url: "/docs/proxy/lens/deployment/kubernetes"
canonical_url: "https://docs.litellm.ai/docs/proxy/lens/deployment/kubernetes"
type: "docs"
last_updated: "2026-10-08"
summary: "Install LiteLLM and Lens with Helm, or add Lens to an existing Helm release."
related:
  - "/docs/proxy/lens/deployment/local"
  - "/docs/proxy/lens/deployment/server"
---
# Kubernetes

> Index of all LiteLLM docs: https://docs.litellm.ai/llms.txt


Use Helm to deploy Lens with LiteLLM. For an installed LiteLLM chart, go to [Add Lens to an existing deployment](#existing-deployment).

## New 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](./storage.md#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:

```bash
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:

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

Create the application secret:

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

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

```dotenv title="postgres.env"
username=litellm
password=YOUR_POSTGRES_PASSWORD
```

```bash
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:

```bash
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:

```yaml title="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](./releases.md#helm-charts). Replace `RELEASE_VERSION` with its version, without the `v` prefix, then install:

```bash
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](#check-the-installation) before connecting your agents.

## Add Lens to an existing deployment {#existing-deployment}

Keep your chart, release name, namespace, model configuration, and database. Select a [matching chart release](./releases.md#helm-charts) with Lens support. Update any gateway or backend image overrides to that release too.

### 1. Enable Lens

Add this to your existing values file:

```yaml
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](./storage.md) 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](./configuration.md#dedicated-ingress) 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:

```bash
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](./releases.md#source-charts).

## Check the installation

Check the pods and ingress in your namespace:

```bash
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](../first-trace.md).

If a service is unavailable, use [Troubleshooting](./configuration.md#troubleshooting). Before relying on this installation for production data, configure backups for PostgreSQL, ClickHouse, and secrets. The [production checklist](../../prod.md) covers capacity and availability settings.

## Related pages

- [Local quickstart](https://docs.litellm.ai/docs/proxy/lens/deployment/local.md)
- [Docker Compose on a server](https://docs.litellm.ai/docs/proxy/lens/deployment/server.md)