Skip to content

Docs

Pro and up

Kubernetes

Get full kubectl access to a cluster through Zero Trust — RBAC-scoped and recorded. The agent talks to the API server with its own in-cluster ServiceAccount, so no kubeconfig secret ever leaves the cluster.

Before you start (admin)

A kubernetes-mode agent must be running in the cluster (it uses the mounted ServiceAccount). Then register the cluster: Kubernetes → New cluster → name + the kubernetes agent.

Use kubectl (recommended)

  1. Go to Kubernetes → your cluster → kubeconfig (downloads a file).
  2. Point kubectl at it and use it normally:
export KUBECONFIG=~/Downloads/prod-cluster.kubeconfig
kubectl get pods -A
kubectl describe deployment/api -n default
kubectl apply -f manifest.yaml
The downloaded kubeconfig embeds a freshly-minted API key scoped to kube.proxy. kubectl talks to Subnomic (not directly to your cluster); Subnomic forwards each request to the API server through the agent. Treat the kubeconfig like a secret.

Browser API console

For quick read-only checks without kubectl: Kubernetes → cluster → API console. Enter an API path and Run (GET):

/api/v1/namespaces
/api/v1/namespaces/default/pods
/apis/apps/v1/deployments
/version
attach and port-forward are not supported through the API console (they need a separate streaming channel). Standard get/describe/apply/delete/logs work. For an interactive shell, use the pod terminal below rather than the console.

Pod terminal

Open a Pod and press Terminal to get an interactive shell inside one of its containers — the equivalent of kubectl exec -it. Pick the container and the shell (auto tries sh then bash). Every keystroke and every byte of output is recorded like an SSH session, and the recording appears under the cluster server's Sessions tab with playback and an on-demand summary.

A shell is available once an administrator grants the kube.exec permission — it is in no default role, because a shell inside a container can read that pod's mounted secrets. An existing cluster also needs its agent permissions refreshed once: re-apply agent.yaml so the agent may exec into pods. Updating the agent image alone does not do it.

Require approval (optional)

Tick Require approval to connect on the cluster (New cluster form) to gate it behind just-in-time access. The API console and kubectl then return "approval required" until the user holds an active grant. For kubectl the grant binds to whoever downloaded the kubeconfig. See Access requests.

Troubleshooting

  • kubectl / Lens gets 401 (the server has asked for credentials) — the kubeconfig server URL must be https://. Kubernetes clients only send the token over TLS, so a plaintext http:// URL drops it. Re-download the kubeconfig from an https endpoint.
  • "agent is offline" (503) — the kubernetes agent isn't connected. Check the pod is running and reached the backend.
  • "approval required" (403) — the cluster is gated; request access (or break-glass). For kubectl the grant binds to whoever downloaded the kubeconfig.
  • 403 from the API server itself — the kubernetes agent's ServiceAccount lacks RBAC for that resource.
  • "this cluster's agent does not serve terminals yet" — the cluster is running an agent binary from before the terminal existed. Update the agent, then re-apply agent.yaml for its permissions. Both steps are needed; neither implies the other.
  • the pod terminal says the agent may not exec into pods — the cluster is running agent permissions from before the terminal existed. Re-apply agent.yaml; an image update alone never changes them.
  • no Terminal button on a Pod — the kube.exec permission is in no default role; an administrator has to grant it.
  • "no usable shell in this container" — the image ships neither /bin/sh nor /bin/bash (distroless). Nothing can be done from here; the container has no shell to enter.
  • attach / port-forward fail — still not supported (they need a separate streaming channel).

Permissions

kube.read kube.proxy kube.manage kube.exec