Kubernetes Access (pc kube)

Proxima Console gives operators audited, short-lived, identity-aware kubectl access to monitored Kubernetes clusters — the Teleport tsh kube experience, built on the same rails as Terminal Access. The real apiserver is never exposed: the in-cluster Proxima agent dials out, and every request is authorized per-user and surfaced in the cluster's own audit log.

v1 scope

• Two capability tiers: read (kubernetes:read) and exec (kubernetes:execute) — see the read/execute model.
• A cluster is reachable only when it runs the Proxima cluster-agent agent with kube access enabled.
• v1 assumes one cluster = one Proxima client (see Security → tenancy).

How it works

The kubeconfig points at the Proxima backend, never at the apiserver. The backend is a per-request L7 proxy; the agent is the only component that talks to the apiserver, authenticating with its own ServiceAccount and impersonating your identity. Because k8s RBAC evaluates the impersonated groups, the apiserver — not Proxima — is the final authority on what you can do, and the cluster's audit log shows your email, not the agent.

This reuses the existing platform primitives: the SSH-relay byte transport (kube.in/out NATS subjects), the SSH-CA short-lived-credential pattern (the kube token), and the terminal RBAC/tenant-scoping model.

Using it

1. List reachable clusters

pc kube ls

Lists the clusters you can access (those running the collector with kube access enabled, scoped to your permitted clients).

2. Log in

pc kube login <cluster>

Like tsh kube login, this merges a context into your standard kubeconfig ($KUBECONFIG, or ~/.kube/config) and switches to it — so kubectl works immediately with no export KUBECONFIG. It prints:

Logged into Kubernetes cluster "<cluster>". Try 'kubectl version' to test the connection.

Each login adds another context (existing contexts are preserved); switch between clusters with kubectl config use-context or another pc kube login. More:

pc kube login --all                   # add every cluster you can access
pc kube login prod --kubeconfig ./kc  # update a specific file
pc kube login prod --print            # print to stdout, touch no file
pc kube logout prod                   # remove a context (--all removes every Proxima context)

The merged context points at the backend, with an exec-credential plugin that mints/refreshes a short-lived token automatically:

clusters:
- name: proxima-<cluster>
  cluster:
    server: https://api-console.prxm.uz/api/v1/kube/<cluster-id>   # the proxy
users:
- name: proxima-<cluster>
  user:
    exec:
      apiVersion: client.authentication.k8s.io/v1
      command: pc
      args: ["kube", "credentials", "--cluster", "<cluster-id>"]
contexts:
- {name: proxima-<cluster>, context: {cluster: proxima-<cluster>, user: proxima-<cluster>}}
current-context: proxima-<cluster>

3. Use native tooling

kubectl get pods -A
kubectl logs -f deploy/api          # long-lived streams work (no 30s cut-off)
kubectl exec -it pod/web -- sh      # requires kubernetes:execute; recorded

kubectl, k9s, helm, lens, etc. all work unchanged — they only ever talk to Proxima, and pc refreshes the credential on demand. There is no cluster CA to distribute (kubectl validates the backend's public TLS cert).

Read/execute model

Permission	k8s group impersonated	What it allows
kubernetes:read	proxima:kube-readonly (+ system:authenticated)	get/list/describe/logs across resources — excludes secrets
kubernetes:execute	additionally proxima:kube-exec	kubectl exec/attach into pods

The two tiers are separate permissions backed by separate k8s groups, so the read/exec split is enforced by real k8s RBAC: the backend only asserts the proxima:kube-exec group for a caller who actually holds kubernetes:execute, and the read-only group's ClusterRole cannot exec. A read-only user physically cannot kubectl exec — the apiserver returns 403.

Both permissions are granted by default to the same roles that hold terminal:write (Super Admin, Admin, Engineer, Team Lead). Exec is the higher-privilege grant — see Security → exec is not read-only.

Enabling a cluster

Kube access is off by default. Enable it on the agent Helm release for a cluster (see Deployment → Helm chart for the full values):

kubeAccess:
  enabled: true
  apiServerURL: "https://kubernetes.default.svc"
  verifyTLS: true   # verify the apiserver cert against the in-cluster CA

Enabling it installs three RBAC objects (the two tier ClusterRoles and a resourceNames-restricted impersonate ClusterRole bound to the collector ServiceAccount) and turns on the collector's kube reverse-proxy. With it off, none of those objects render and the collector behaves exactly as before.

One cluster, one client

Only enable kube access on a cluster dedicated to a single Proxima client. The read-only ClusterRole is cluster-wide, so on a cluster shared by multiple clients a user of one client could read another's namespaces. See Security → tenancy.

See Security model for the full threat model and the hardening guarantees (impersonation, identity isolation, revocation, audit).