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 key | Value from Lens |
|---|---|
service-token | LITELLM_LENS_SERVICE_TOKEN |
gateway-secret | LENS_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