Skip to content

Kubernetes#

Connect Kubernetes clusters to Lens Agents. Agents get full kubectl access with their own identity, governed by policy, with short-lived credentials and complete audit attribution.

How It Works#

Agents access Kubernetes clusters through a relay that proxies K8s API requests. The agent's identity is mapped to a Kubernetes principal using API impersonation:

Agent → Lens Agents → K8s Relay → K8s API Server
  • Agent identity: agent:<name> with groups <org>/<team>
  • Credentials: short-lived JWT tokens (60-second lifetime, automatically rotated)
  • Access scope: determined by Kubernetes RBAC applied to the impersonated identity

The cluster sees the agent as its own principal. Standard Kubernetes RBAC controls what the agent can do.

Connection modes#

Tunnel mode#

A relay runs inside the cluster and initiates an outbound WebSocket connection to Lens Agents. No inbound ports, no public endpoint, no VPN required.

Best for: clusters behind firewalls, private networks, environments where inbound access is restricted.

How it works: 1. Deploy the relay agent inside the cluster 2. The relay connects outbound to Lens Agents via WebSocket 3. Agent requests are forwarded through the tunnel to the K8s API server 4. Keepalive: ping every 30 seconds, auto-reconnect with exponential backoff (5s to 60s)

Direct relay mode#

The relay is exposed at a public HTTPS URL. Requests are authenticated via JWT and forwarded to the K8s API server with impersonation headers.

Best for: clusters with public endpoints, environments where direct access is acceptable.

What Agents Can Do#

Agents have full kubectl capabilities within their RBAC scope:

  • List and inspect resources (pods, deployments, services, configmaps, secrets, etc.)
  • View logs
  • Exec into pods
  • Port-forward
  • Attach to running containers
  • Apply and delete resources (if RBAC allows)

All operations go through the K8s API with the agent's impersonated identity — standard Kubernetes RBAC controls what's allowed.

Credential handling#

Kubernetes credentials are never stored in the agent's environment:

  1. Agent requests access to a cluster
  2. Lens Agents generates a short-lived JWT token (60-second lifetime)
  3. The K8s relay validates the JWT and proxies the request using impersonation headers
  4. The cluster sees the request as coming from the agent's identity
  5. Token is automatically rotated — no long-lived credentials

This means even a compromised agent cannot extract Kubernetes credentials. Access depends on the platform, not on secrets in the sandbox.

Audit#

Every Kubernetes API call is recorded in the audit trail:

  • K8s API path and method
  • Agent identity
  • Cluster name
  • Result (success/failure)
  • Timestamp