feat: ork proxy — port-forward CLI for Helm-deployed Orkestra; e2e Go client migration

[iAlexeze]

Summary

• Adds ork proxy — a single command that replaces manual kubectl port-forward calls when working with a Helm-deployed Orkestra. Discovers components by the new orkestra.orkspace.io/komponent label, resolves the Runtime leader via the orkestra-konductor Lease, and keeps all forwards alive with automatic reconnection.
• Migrates three e2e kubectl subprocess calls to native Go client calls: leader Lease read, SelfSubjectAccessReview for auth checks, and SPDY portforward for kubectl.port-forward assertions.
• Fixes the kind node readiness spinner interleaving kubectl output with the spinner line.
• Adds kubectl.restart and kubectl.scale E2E DSL subcommands for rollout mutations in test sequences.

Changed files

cmd/cli/proxy.go (new)

ork proxy command. --for flag uses same vocabulary as ork generate bundle --for (runtime/run, gateway/gw, cc/controlcenter). Per-component port overrides (--runtime-port, --cc-port, --gateway-port), --context, --namespace. Global flags shadowed and hidden. Port conflict pre-check before opening any tunnel. Ctrl+C shutdown via signal.NotifyContext.

pkg/proxy/ (new)

• discover.go — FindService by orkestra.orkspace.io/komponent label; ResolvePod from Service selector; ResolveRuntimePod via orkestra-konductor Lease
• proxy.go — RunAll blocks until ctx cancelled; forwardWithReconnect reconnect loop per goroutine; forward SPDY portforward via k8s.io/client-go/tools/portforward; coloured output using pkg/utils helpers; proactive pod watch calls stop() on pod disappearance; probeReady loops on /health before marking Runtime forward live; ↺ reconnecting indicator; exits when all targets are not deployed
• ports.go — CheckPort TCP bind check
• README.md, docs/01-discovery.md, docs/02-forward.md

pkg/types/types.go

KonductorLeaseName = "orkestra-konductor" constant shared by pkg/proxy/discover.go and pkg/konductor/konduct.go.

charts/orkestra/templates/

Added orkestra.orkspace.io/komponent label to metadata (not selectors) on all six files: runtime-deployment.yaml, runtime-service.yaml, controlcenter-deployment.yaml, controlcenter-service.yaml, gateway-deployment.yaml, gateway-service.yaml.

pkg/e2e/runner.go

Runner gains cs kubernetes.Interface and cfg *rest.Config built after ensureCluster via buildClient(). Threaded through to verifyExpectation and runOnFailure. Still-waiting feedback: prints still waiting [Xs]... every 10 s while a step is polling so long waits do not look like hangs.

pkg/e2e/verify.go

• resolveLeaderHolder — CoordinationV1().Leases().Get() replaces kubectl get lease -o jsonpath; workDir param dropped
• checkKubectlAuth — SelfSubjectAccessReview when e.As == "" (matches kubectl auth can-i default behaviour); SubjectAccessReview with User set when --as is specified
• checkKubectlPortForward — SPDY portforward + net/http; readyChan eliminates the old curl-retry polling race; pod resolved via lease, service selector, or direct name
• checkKubectlRestart — kubectl rollout restart <kind>/<name> + optional rollout status; ready: true default
• checkKubectlScale — kubectl scale <kind>/<name> --replicas=N + optional rollout status; same default

pkg/e2e/validate.go

validateKubectlRestart and validateKubectlScale — kind and name required.

pkg/types/e2e.go

E2EKubectl gains Restart []E2EKubectlRestart and Scale []E2EKubectlScale. Both structs: kind, name, namespace, ready *bool.

pkg/e2e/onfailure.go

Receives cs kubernetes.Interface; resolveLeaderHolder call sites updated. restart and scale are mutations — not emitted in onFailure diagnostics.

pkg/ork/kind.go

waitForNodesReady signature gains onNodeReady func(nodeName string) callback. Output captured via os.Pipe into a goroutine — kubectl output no longer writes to the terminal. Callback updates the spinner with (N/total) progress. Success marked with final count.

pkg/health/health.go

Binds the listener synchronously before launching the goroutine. A port conflict now returns an error from Start() so ork run fails immediately instead of silently continuing with a dead health server.

documentation/reference/cli/proxy.md (new), index.md

CLI reference page for ork proxy. Added to the Tooling section of the index.

documentation/reference/schema/04-e2e/07-kubectl.md

kubectl.restart and kubectl.scale sections with field tables and examples.

examples/security/deletion-protection/e2e.yaml

Cleanup step: apply ConfigMap with deletionProtection.enabled: false + kubectl.restart gateway. The housekeeper reads enabled: false on startup and removes the ValidatingWebhookConfiguration — deleting the VWC directly does not work because the housekeeper recreates it immediately on DELETED events.

Docs + examples

Replaced all bare kubectl port-forward svc/orkestra-* calls with ork proxy across documentation and example READMEs. Gateway-specific pages use ork proxy --for gateway with curl on localhost:8443. Cross-binary example uses ork proxy -n producer-system.

Key design decisions

Label-based discovery. ork proxy finds components by orkestra.orkspace.io/komponent rather than hardcoded service names, keeping discovery decoupled from chart naming conventions. The label uses komponent (Orkestra's internal spelling) to match the rest of the codebase vocabulary.

Leader-pinned Runtime forward. A service port-forward for the Runtime routes to a random replica. ork proxy reads the orkestra-konductor Lease to resolve the leader pod, so the forwarded connection always reaches the replica with authoritative reconciler state — consistent with how ork e2e targets the leader.

SelfSubjectAccessReview not SubjectAccessReview. kubectl auth can-i without --as sends a SelfSubjectAccessReview — the API server infers the caller's identity. SubjectAccessReview with an empty User field is rejected. The migration now matches kubectl's actual behaviour.

restart/scale are mutations, not assertions. They do not appear in onFailure diagnostics. The ready: true default runs rollout status to confirm the workload settled — set ready: false to skip.

Housekeeper-aware deletion-protection cleanup. Deleting the ValidatingWebhookConfiguration directly fails because the housekeeper Watch fires immediately and recreates it. The only clean escape is to update orkestra-katalog ConfigMap with enabled: false and restart the gateway — the housekeeper then calls cleanupValidatingWebhook on startup and never re-registers.

Inspired by kubectl proxy. The command name and concept follow kubectl proxy — a dedicated proxy command for the tool's own components rather than a generic port-forward wrapper.