Skip to main content

Kubernetes

The Lens Helm chart deploys the complete Lens UI, Rust API and background processing with ClickHouse and Keeper. This source installation uses the public Lens repository and requires a Kubernetes cluster, Helm, kubectl and a storage class for the persistent volume. Standalone Lens does not require a gateway or PostgreSQL

For help from your coding agent, use Set it up for me and specify Helm

New deployment​

Until an independent release is published, build the source image and push it to a registry your cluster can read. Use a native builder matching the cluster nodes' Linux architecture. From a fresh clone of BerriAI/lens, replace the example registry and team:

LENS_IMAGE_REPOSITORY=registry.example.com/your-team/lens
LENS_IMAGE_TAG=$(git rev-parse HEAD)
docker build --build-arg LENS_VERSION="$LENS_IMAGE_TAG" -f deploy/runtime/Dockerfile \
-t "$LENS_IMAGE_REPOSITORY:$LENS_IMAGE_TAG" .
docker push "$LENS_IMAGE_REPOSITORY:$LENS_IMAGE_TAG"
helm upgrade --install lens ./helm/lens --namespace lens --create-namespace \
--set image.repository="$LENS_IMAGE_REPOSITORY" --set image.tag="$LENS_IMAGE_TAG"
kubectl --namespace lens port-forward service/lens 4318:4318

Configure image-pull credentials if your registry is private. Open http://localhost:4318/ui/. Obtain the generated login credential locally:

kubectl --namespace lens get secret lens-admin \
-o jsonpath='{.data.admin-token}' | base64 --decode

Keep that credential private. Helm reuses generated credentials on upgrades, and uninstall retains credentials and the ClickHouse volume. Before exposing Lens to agents, configure publicUrl, HTTPS ingress and a reachable ingestion address using the Helm guide

For external ClickHouse, provide a stable endpoint reaching one server with KeeperMap. Multiple Lens replicas may share that server. Multi-server load balancing and automatic failover to a different ClickHouse server are outside the supported topology

Connect an existing LiteLLM deployment​

Connect the LiteLLM chart to Lens running in its own release or on a platform such as Render. This connects the gateway to Lens without deploying another Lens or ClickHouse instance.

First complete steps 1–3 of Add Lens to LiteLLM. The gateway must have the adapter and UI described in that guide. Keep your release name, namespace, and model configuration. These values target the current LiteLLM chart. Migrate older chart values before upgrading.

1. Store the connection secrets​

Use your Kubernetes secret manager to create lens-connection in the gateway namespace with these keys:

Secret keyValue from Lens
service-tokenLITELLM_LENS_SERVICE_TOKEN
gateway-secretLENS_GATEWAY_SECRET

For a manual setup, save each value in a separate private file named service-token and gateway-secret. Do not include a trailing newline. Set your namespace and create the Secret:

export GATEWAY_NAMESPACE="YOUR_GATEWAY_NAMESPACE"
kubectl --namespace "$GATEWAY_NAMESPACE" create secret generic lens-connection \
--from-file=service-token=./service-token \
--from-file=gateway-secret=./gateway-secret

If this Secret already exists, reuse it after confirming the values match Lens. Keep the files out of Git. For GitOps, declare the Secret through your existing secret-management controller.

2. Add the Lens values​

Save this as lens-connection.yaml, using the address of your existing Lens service:

lens:
enabled: true
url: https://lens.example.com
publicUrl: https://lens.example.com
serviceTokenSecret:
name: lens-connection
key: service-token
gatewaySecret:
name: lens-connection
key: gateway-secret

The gateway must be able to reach url. Agent exporters must be able to reach publicUrl. Neither address includes /ui/ or /v1/traces.

Add the tracing store setting in the same file:

gateway:
config:
proxy_config:
general_settings:
tracing:
store:
type: lens

If your deployment supplies config.yaml from an external ConfigMap instead, add general_settings.tracing.store.type: lens to that file through its existing owner.

3. Apply and check​

Set GATEWAY_RELEASE to your existing Helm release name. Set GATEWAY_CHART to your OCI chart. Replace YOUR_ORG with your registry namespace. Set GATEWAY_CHART_VERSION to the chart version you use. You can inspect the installed release with:

helm list --namespace "$GATEWAY_NAMESPACE"

Merge these settings with your complete values file. Then apply both:

export GATEWAY_RELEASE="YOUR_GATEWAY_RELEASE"
export GATEWAY_CHART="oci://ghcr.io/YOUR_ORG/charts/litellm"
export GATEWAY_CHART_VERSION="1.0.0"
helm upgrade "$GATEWAY_RELEASE" "$GATEWAY_CHART" \
--version "$GATEWAY_CHART_VERSION" \
--namespace "$GATEWAY_NAMESPACE" \
-f gateway-values.yaml -f lens-connection.yaml --wait

This rolls the gateway pods to load the connection settings. For GitOps, commit the values and Secret references through your normal review and sync process instead.

Sign in to LiteLLM, select Lens, and complete the connection check. Then send your first trace.

If an older gateway Helm release owns Lens, transfer ownership before you upgrade. The current chart does not deploy Lens or ClickHouse. Use the ownership-transfer guide to preserve its resources and storage first.

Check the installation​

For the standalone example:

kubectl get pods,services,pvc --namespace lens
kubectl logs --namespace lens deployment/lens --tail=100

Complete the first-trace flow in standalone Lens or the embedded gateway page, using an endpoint reachable by the agent. Open a stored trace after restarting Lens and verify a bounded investigation when analysis is configured

Keep ClickHouse data and Keeper state in the same recovery plan. The backup guide describes the required recovery boundary; its Compose helper does not manage Kubernetes backups. Use your cluster's snapshot and restore procedure and verify records after a restore

LiteLLM Enterprise
SSO/SAML, audit logs, spend tracking, multi-team management, and guardrails, built for production.
Learn more →