Architecture¶
portfwd is a single Bash script. No daemon, no database — just processes and a
state directory.
Overview¶
portfwd up reads the profile, then for each forward spawns a background
supervisor that runs kubectl port-forward and restarts it whenever it
exits, until asked to stop.
Components¶
parse_profile— awk reads the YAML profile and emits onename|namespace|target|ports|context|protectedrow per forward. All config parsing lives here, including the optionalcontexts:section, which is folded into each row'sprotectedfield before it is emitted.supervise— per-forward loop: runkubectl port-forward, and on drop waitPORTFWD_RECONNECT_DELAYand retry while the.wantmarker exists.- State dir (
PORTFWD_STATE_DIR, default$XDG_RUNTIME_DIR/portfwd-$USER) — holds<name>.pid,<name>.want,<name>.ports, and<name>.logper forward, plus<name>.sessionwhile a protected forward is open. audit_open/audit_close— the protected-session record.upwrites the pending half (context, namespace, target, start, reason) to<name>.session;downreads it back, appends the finished row to$PORTFWD_AUDIT_LOG, and removes the marker.
Data flow¶
portfwd.yaml ──parse_profile──▶ name|ns|target|ports|ctx|protected
│ │
│ └─▶ portfwd env ──▶ NAME_HOST / NAME_PORT
supervise & ──▶ kubectl port-forward (retry loop)
│
state dir: .pid/.want/.ports/.log/.session
│
protected session ──▶ $PORTFWD_AUDIT_LOG (append)
portfwd status checks each local port with nc; portfwd down removes .want
markers, kills the supervisors and their children, and closes out any protected
session they held.
Decisions¶
- No YAML library — awk parsing keeps the dependency set to bash + kubectl.
- File-based state — survives shell exit and lets
status/downwork from any terminal. uprefuses whole, not in part — one protected forward without a--reasonfails the run rather than starting the unprotected ones, so a guarded profile cannot be half-opened by habit.- The audit log is a file — appended locally, mode 600, no network and no privileged helper. A record that needed a server would be one nobody runs; ship the file with whatever already ships your logs.
- The session is closed on
down, not by a trap — the supervisor is a background job that may be killed several ways, so the record is written by the command that ends the session. A marker left behind by a machine that died is closed out withinterruptedon the nextup.