podbench

A development seat — editor, gdb, a Python inner loop — inside a Kubernetes pod, reached over nothing but your kubeconfig.

podbench launches a debug container into a running pod (or into a sacrificial clone of one), tunnels ssh through kubectl exec, and hands you the config stanza that VS Code Remote-SSH needs. There is no port-forward to babysit, no pod IP to reach, no file sync and no traffic interception: the editor is already inside the cluster.

              laptop
     VS Code · Remote-SSH · kubectl
                 |
                 |  ssh over kubectl exec (API server only)
                 |
  +--------------+--------------------------------------+
  |  pod                                                 |
  |                                                      |
  |  +----------------------+  +----------------------+  |
  |  | app container        |  | podbench             |  |
  |  |                      |  |                      |  |
  |  | workload process     |  | sshd · vscode-server |  |
  |  |   (maybe distroless) |  | gdb · git · uv       |  |
  |  | fs visible at        |  |                      |  |
  |  |   /proc/<pid>/root   |  |                      |  |
  |  +----------------------+  +----------------------+  |
  |                                                      |
  |  shared: PID namespace (via the target)              |
  |          network namespace (always)                  |
  +------------------------------------------------------+

Two artefacts: a debug container image (ghcr.io/gilesknap/podbench) and a launcher you never have to install — uvx podbench runs it straight from PyPI, uses your kubeconfig, and shells out to kubectl for everything it does to a cluster.

Try it

$ uvx podbench doctor
$ uvx podbench attach pod/web-7d9f8c5b4-x2k9p -n demo

doctor checks the prerequisites, the cluster-side RBAC and the one-time ssh Include line — the only thing podbench leaves behind — and names whatever is missing; --fix adds the Include. attach then walks a capability ladder, lands the best seat the cluster will admit, and runs its probe inside the container it just created, so the report is measured rather than inferred from the spec it asked for:

rung        full - root plus CAP_SYS_PTRACE
supports
  [x] live attach (gdb -p <pid>)
  [x] read-only inspect (/proc/<pid>/root, maps, environ)
      root, maps and environ readable
  [x] debug launched processes (podbench dbg --launch ./prog)
  [ ] iterate (edit, relaunch, verify through the Service)
  [x] ssh seat (Remote-SSH: editor, shell, git, sftp)
measured
  verdict     live attach available
  blocker     none

ssh config written to ~/.podbench/config.d/demo-web-7d9f8c5b4-x2k9p.conf
then:  ssh podbench-demo-web-7d9f8c5b4-x2k9p

Connect that alias with Remote-SSH: Connect to Host…, or let attach --open do it for you.

The other two modes are a table row away. For the inner loop, podbench dev authors the dev pod and podbench run relaunches the app inside it: measured end to end, 1.18 s per edit → relaunch → verified-through-the-Service cycle. When the fix has to survive the pod, podbench hotfix moves the venv onto a claim so a restart no longer restores the image's code, and records where the change came from.

The PyPI name is not published yet, so uvx podbench will not resolve until the first release. Until then, run every command as uvx --from git+https://github.com/gilesknap/podbench podbench <verb>.

Read this before you attach to a live pod

Not fine print — each of these has bitten a spike on a real cluster.

• podbench can get your workload OOM-killed. An ephemeral container may not declare resources at all, so on a live pod the seat shares the workload's memory and ephemeral-storage limits and cannot reserve its own — and a VS Code session is a 1.1–1.3 GB working set. Exceed memory and the kernel OOM-kills something in the pod cgroup; exceed ephemeral storage and the kubelet evicts the whole pod. Anything heavier than looking belongs in a dev pod, which is immune. attach --resize buys headroom in place, opt-in.
• Being refused SYS_PTRACE is normal, not an error. It is outside both the baseline and the restricted Pod Security Standards, so podbench walks a ladder with two valid rungs and lands the better one the cluster admits. Four unrelated subsystems deny attach with the same EPERM, so it probes and names the blocker instead of leaving you an errno.
• Ephemeral containers are permanent. They cannot be removed, restarted or edited, and a name once used is burnt for the life of the pod. So attach reconnects by default, nothing may live only in the writable layer, and --new is for when you mean it.
• A dev pod never joins a Service by accident. podbench dev drops the origin's selector labels unless you pass --take-traffic, and --cutover records the original selector for an exact restore.

The docs carry the reasoning and the measurements behind all four, and What is proven, and what is not is candid about the gaps — no real VS Code GUI client has connected yet, and Hotfix mode has never been run against a cluster.

Documentation

See https://gilesknap.github.io/podbench for the full documentation.

• Tutorials — setup, your first session
• How-to — attach to a pod, debug with gdb, iterate on Python, VS Code Remote-SSH, the container image
• Reference — CLI, glossary
• Explanations — architecture, security, what is proven, and what is not, design brief, Phase 0 report