← Docs

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.

Clusters are registered and browsed in the console at app.subnomic.com.

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
kubectl exec, attach and port-forward are not supported yet (they need a separate streaming channel). Standard get/describe/apply/delete/logs work.

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.
  • exec / attach / port-forward fail — not supported yet (they need a separate streaming channel).

Permissions

kube.read kube.proxy kube.manage