feat: expose the SSH port-forward shadow (#546)

[matbun]

Closes interlink-hq/interLink#546. Chart side of interlink-hq/interLink#550. Part of interlink-hq/interLink#545.

Surfaces the virtual kubelet's SSH port-forward shadow through values, so an air-gapped HPC site can be reached without hand-writing a shadow template. Needs a virtual kubelet with interlink-hq/interLink#550 in it — before that, shadowMode is a knob that renders config the VK ignores.

Usage

virtualNode:
  network:
    enableTunnel: true
    shadowMode: ssh
    ssh:
      loginHost: login.hpc.example.org
      user: alice
      keySecret: hpc-ssh-key       # or auth: kerberos + keytabSecret + principal

enableTunnel turns on shadow pods for offloaded pods with exposed ports; shadowMode picks which shadow is rendered. Both are needed.

Full deployment in interlink/examples/ssh_tunnel.yaml.

What's in it

network.shadowMode — "" (default, wstunnel) or "ssh". Only emitted into the VK config when set, so the default render is untouched.

network.ssh.* — loginHost, user, port, image, auth, keySecret/keySecretKey, keytabSecret/keytabSecretKey, principal, krb5ConfigMap, knownHostsConfigMap, replicateCredentials, nodeWaitTimeout, extraOptions.

loginHost and user use required and fail rendering when shadowMode: ssh:

Error: execution error at (interlink/templates/virtual-kubelet-config.yaml:89:19):
virtualNode.network.ssh.user is required when shadowMode is ssh

Everything else is only emitted when set, so defaults live in the VK rather than being pinned in two places that can drift.

The wstunnel template ConfigMap is no longer rendered or mounted in ssh mode. This is the part worth reviewing. The chart sets WstunnelTemplatePath and mounts an nginx/traefik wstunnel template whenever enableTunnel is on — and the VK prefers a template file over its built-in ones. In ssh mode that silently produces an nginx wstunnel Deployment instead of the SSH shadow, which is the kind of failure that costs an afternoon. New helper interlink.useWstunnelTemplateFile gates the ConfigMap, the volume, the mount, and WstunnelTemplatePath on one condition. An explicit customTemplate still wins in either mode.

RBAC. Secrets gain create/update/patch, but only when shadowMode: ssh and ssh.replicateCredentials is on, since that grant is cluster-wide.

network.ssh.forwardMode — portforward (default, ssh -L) or exec, for login nodes that set AllowTcpForwarding no and answer every channel with administratively prohibited. execConnectCommand (default nc) is the relay command run on the login node in that mode. Both omitted when unset.

Security note

ssh.replicateCredentials defaults to true, matching the VK default. It copies the SSH key or keytab Secret into each shadow's namespace, which makes it readable by anyone who can read Secrets there. It defaults on because shadows follow the offloaded pod into per-user namespaces (interlink.eu/shadow-same-ns) and multi-tenant setups are unusable otherwise — but it is a real tradeoff. Set it to false and provision the Secret yourself if that isn't acceptable, and the cluster-wide Secret write grant goes away with it.

Compatibility

helm template with both existing test values files produces output byte-identical to main:

$ diff <(git stash; helm template t ./interlink -f test_values.yaml) \
       <(git stash pop; helm template t ./interlink -f test_values.yaml)
$ diff ... test_values-wstunnel-wireguard.yaml

helm lint clean.