Installing Community Edition Using Helm

Step-by-step guide to installing Lenses CE with Helm charts

Installing Community Edition Using Helm

Note: These instructions are NOT for production environments. They are intended for dev or test environment setups. Please see here for details on installing Lenses for more secure environments.

Tool Requirements

1. Kubernetes cluster and kubectl (you can use something like Minikube, K3s, or Docker Desktop in Kubernetes mode, but you will need to allocate at least 8 gigs of RAM and 6 CPUs)
2. Helm
3. A Kafka cluster (these instructions assume you already have one running)

Adding the Lenses Helm Repository

From a workstation with kubectl and Helm installed, add the Lenses Helm repository:

helm repo add lensesio https://helm.repo.lenses.io/
helm repo update

Step 1: Install and Configure Postgres

If you already have Postgres installed, skip to Step 2: Install Lenses HQ.

The following commands create the postgres-system namespace, then apply a PersistentVolumeClaim, Postgres deployment, service, and a Job that initializes the lenses_hq and lenses_agent databases.

Note: This configuration does not specify a storageClassName, so Kubernetes will use your cluster's default storage class. If your cluster does not have a default storage class configured, you may need to add storageClassName: <your-storage-class> to the PVC spec (for example, hostpath for Docker Desktop or local-path for K3s).

Warning: Using simple cleartext passwords like in the example below is NEVER recommended for anything other than a test or demo environment.

kubectl create namespace postgres-system

kubectl apply -f - <<'EOF'
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgres-data
  namespace: postgres-system
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 1Gi
---
apiVersion: v1
kind: Secret
metadata:
  name: postgres-secret
  namespace: postgres-system
type: Opaque
stringData:
  POSTGRES_USER: "postgres"
  POSTGRES_PASSWORD: "changeme"
  POSTGRES_DB: "postgres"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgres
  namespace: postgres-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
      - name: postgres
        image: postgres:14
        ports:
        - containerPort: 5432
        envFrom:
        - secretRef:
            name: postgres-secret
        volumeMounts:
        - name: postgres-data
          mountPath: /var/lib/postgresql/data
          subPath: pgdata
      volumes:
      - name: postgres-data
        persistentVolumeClaim:
          claimName: postgres-data
---
apiVersion: v1
kind: Service
metadata:
  name: postgres
  namespace: postgres-system
spec:
  selector:
    app: postgres
  ports:
  - port: 5432
    targetPort: 5432
---
apiVersion: batch/v1
kind: Job
metadata:
  name: lenses-db-init
  namespace: postgres-system
spec:
  template:
    spec:
      containers:
      - name: db-init
        image: postgres:14
        command:
        - /bin/bash
        - -c
        - |
          echo "Waiting for PostgreSQL to be ready..."
          until PGPASSWORD=changeme psql -h postgres -U postgres -d postgres -c '\l' &> /dev/null; do
            echo "PostgreSQL is unavailable - sleeping 2s"
            sleep 2
          done
          echo "PostgreSQL is up - creating databases and roles"
          PGPASSWORD=changeme psql -h postgres -U postgres -d postgres <<EOSQL
          CREATE ROLE lenses_agent WITH LOGIN PASSWORD 'changeme';
          CREATE DATABASE lenses_agent OWNER lenses_agent;
          CREATE ROLE lenses_hq WITH LOGIN PASSWORD 'changeme';
          CREATE DATABASE lenses_hq OWNER lenses_hq;
          EOSQL
          echo "Database initialization completed!"
      restartPolicy: OnFailure
  backoffLimit: 5
EOF

Wait for the Postgres deployment and the database init job to complete:

kubectl -n postgres-system wait --for=condition=available deployment/postgres --timeout=120s
kubectl -n postgres-system wait --for=condition=complete job/lenses-db-init --timeout=120s

Verify everything is running:

kubectl get pods -n postgres-system

You should see the Postgres pod running and the init job completed:

NAME                        READY   STATUS      RESTARTS   AGE
postgres-6b4f7d9c8-x2k4m   1/1     Running     0          2m
lenses-db-init-abc12        0/1     Completed   0          2m

Troubleshooting: If the Postgres pod shows Pending status with an event like pod has unbound immediate PersistentVolumeClaims, your cluster likely does not have a default storage class or the default does not support dynamic provisioning. Run kubectl get storageclass to see available options, then delete the PVC and re-apply with the correct storageClassName added to the PVC spec.

Step 2: Install Lenses HQ

Create the Lenses namespace and install HQ with the Helm chart:

kubectl create namespace lenses

helm install lenses-hq lensesio/lenses-hq \
  --namespace lenses \
  --set resources.requests.cpu=1 \
  --set resources.requests.memory=1Gi \
  --set resources.limits.cpu=2 \
  --set resources.limits.memory=4Gi \
  --set image.repository=lensesio/lenses-hq \
  --set image.pullPolicy=Always \
  --set rbacEnable=false \
  --set namespaceScope=true \
  --set restPort=8080 \
  --set servicePort=80 \
  --set servicePortName=lenses-hq \
  --set lensesHq.storage.postgres.enabled=true \
  --set lensesHq.storage.postgres.host=postgres.postgres-system.svc.cluster.local \
  --set lensesHq.storage.postgres.port=5432 \
  --set lensesHq.storage.postgres.username=lenses_hq \
  --set lensesHq.storage.postgres.database=lenses_hq \
  --set lensesHq.storage.postgres.passwordSecret.type=createNew \
  --set lensesHq.storage.postgres.passwordSecret.password=changeme \
  --set lensesHq.license.acceptEULA=true

Verify that Lenses HQ is running:

kubectl get pods -n lenses

You should see something similar to this:

NAME                          READY   STATUS    RESTARTS   AGE
lenses-hq-5f4744c664-nhwhm   1/1     Running   0          2m

Accessing Lenses HQ

For quick local access, use port-forwarding:

kubectl port-forward -n lenses svc/lenses-hq 8080:80

Then open your browser to http://localhost:8080.

For a more permanent setup, choose one of the ingress options below.

Option A: Traefik (Recommended)

Traefik is the modern, actively maintained replacement for Nginx Ingress and is the default ingress controller in K3s — so if you are running K3s, you already have it installed and can skip straight to applying the Ingress resource below.

Traefik handles WebSocket connections out of the box, which is important for the Lenses Agent communication channel on port 10000.

If Traefik is not already installed, add it via Helm:

helm repo add traefik https://traefik.github.io/charts
helm repo update

helm install traefik traefik/traefik \
  --namespace traefik \
  --create-namespace \
  --set ports.web.port=80 \
  --set ports.websecure.port=443

Wait for Traefik to be ready:

kubectl rollout status deployment/traefik -n traefik --timeout=120s

Apply the Lenses HQ Ingress resource:

# lenses-hq-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: lenses-hq-ingress
  namespace: lenses
  annotations:
    traefik.ingress.kubernetes.io/router.entrypoints: web
spec:
  ingressClassName: traefik
  rules:
  - host: lenses-hq.local  # Change this to your desired hostname
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: lenses-hq
            port:
              number: 80
      - path: /agents
        pathType: Prefix
        backend:
          service:
            name: lenses-hq
            port:
              number: 10000

kubectl apply -f lenses-hq-ingress.yaml

---

Option B: Kubernetes Gateway API (Envoy Gateway)

The Kubernetes Gateway API is now GA and is the official successor to the Ingress spec. This is the forward-looking choice if you want to align with where the ecosystem is heading. Envoy Gateway is the CNCF-backed implementation.

Install the Gateway API CRDs and Envoy Gateway:

# Install Gateway API CRDs
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/latest/download/standard-install.yaml

# Install Envoy Gateway
helm install eg oci://docker.io/envoyproxy/gateway-helm \
  --version v1.3.0 \
  --namespace envoy-gateway-system \
  --create-namespace

Wait for Envoy Gateway to be ready:

kubectl rollout status deployment/envoy-gateway -n envoy-gateway-system --timeout=120s

Create a GatewayClass and Gateway:

# lenses-gateway.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: envoy
spec:
  controllerName: gateway.envoyproxy.io/gatewayclass-controller
---
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: lenses-gateway
  namespace: lenses
spec:
  gatewayClassName: envoy
  listeners:
  - name: http
    protocol: HTTP
    port: 80

kubectl apply -f lenses-gateway.yaml

Create HTTPRoute resources for HQ and the Agent channel:

# lenses-httproutes.yaml
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: lenses-hq-route
  namespace: lenses
spec:
  parentRefs:
  - name: lenses-gateway
  hostnames:
  - "lenses-hq.local"  # Change this to your desired hostname
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /agents
    backendRefs:
    - name: lenses-hq
      port: 10000
  - matches:
    - path:
        type: PathPrefix
        value: /
    backendRefs:
    - name: lenses-hq
      port: 80

kubectl apply -f lenses-httproutes.yaml

---

Installing Lenses Agent

1. Once you have successfully logged on to Lenses HQ you can start to set up your agent. See the Community Edition walk through for login details.
2. Click on the Add New Environment button in the Environments screen. Follow the in-product instructions to setup your new environment.
3. Be sure to save your Agent Key from the screen that follows. It can only be displayed once.
4. Install the Lenses Agent with the following command, replacing YOUR_AGENT_KEY_HERE with your actual Agent Key:

helm install lenses-agent lensesio/lenses-agent \
  --namespace lenses \
  --set image.repository=lensesio/lenses-agent \
  --set image.tag=6.1.0 \
  --set image.pullPolicy=IfNotPresent \
  --set lensesAgent.storage.postgres.enabled=true \
  --set lensesAgent.storage.postgres.host=postgres.postgres-system.svc.cluster.local \
  --set lensesAgent.storage.postgres.port=5432 \
  --set lensesAgent.storage.postgres.username=lenses_agent \
  --set lensesAgent.storage.postgres.database=lenses_agent \
  --set lensesAgent.storage.postgres.passwordSecret.type=createNew \
  --set lensesAgent.storage.postgres.passwordSecret.password=changeme \
  --set lensesAgent.hq.agentKey.secret.type=createNew \
  --set lensesAgent.hq.agentKey.secret.name=agentKey \
  --set lensesAgent.hq.agentKey.secret.value=YOUR_AGENT_KEY_HERE

Give Kubernetes time to install the Lenses Agent, then go back to the Lenses HQ UI and verify your Kafka cluster is connected. You can now use Lenses on your own cluster!