feat(supervisor): reserve configured source ports on run pods

The supervisor can now set the `net.ipv4.ip_local_reserved_ports` sysctl
on every run pod it creates, via the new optional
`KUBERNETES_POD_RESERVED_SOURCE_PORTS` (a comma-separated list of ports
or `low-high` ranges, validated at startup), so the kernel never picks
those ports as ephemeral source ports. Unset leaves run pods unchanged.
The sysctl is namespaced and on the Kubernetes safe sysctl list since
1.27 (kernel 3.16+), so no kubelet allowlist is needed on 1.27+
clusters.

Mono-RevId: fdd8c6b08a68c0a669c650fd51499a7a2efe24d1

Author: myftija

.server-changes/supervisor-reserved-source-ports.md

@@ -0,0 +1,6 @@
+---
+area: supervisor
+type: feature
+---
+
+Set `KUBERNETES_POD_RESERVED_SOURCE_PORTS` on the supervisor (for example `50080,50081`) to stop runs using those ports for outbound connections, which is useful to avoid port clashes.

apps/supervisor/src/env.ts

@@ -7,6 +7,7 @@ import {
   BoolEnv,
   NodeLabelValue,
   OrgPlacementOverrides,
+  ReservedPorts,
   Tolerations,
 } from "./envUtil.js";
 
@@ -280,6 +281,7 @@ export const Env = z
       .default("node-24-plus"),
     KUBERNETES_RUNNER_SECURITY_CONTEXT: z.enum(["off", "baseline", "restricted"]).default("off"),
     KUBERNETES_RUNNER_RUN_AS_USER: z.coerce.number().int().min(1).default(1000),
+    KUBERNETES_POD_RESERVED_SOURCE_PORTS: ReservedPorts,
 
     // Pod DNS config: override the cluster default ndots to `KUBERNETES_POD_DNS_NDOTS`.
     // Default k8s ndots is 5: any name with fewer than 5 dots (e.g. `api.example.com`, 2 dots) is first walked

apps/supervisor/src/envUtil.test.ts

@@ -4,6 +4,7 @@ import {
   AdditionalEnvVars,
   NodeLabelValue,
   OrgPlacementOverrides,
+  ReservedPorts,
   Tolerations,
 } from "./envUtil.js";
 
@@ -113,6 +114,27 @@ describe("NodeLabelValue", () => {
   });
 });
 
+describe("ReservedPorts", () => {
+  it("is unset when empty", () => {
+    for (const value of [undefined, "", "  "]) {
+      expect(ReservedPorts.parse(value)).toBeUndefined();
+    }
+  });
+
+  it("accepts ports and ranges, stripping whitespace the kernel would reject", () => {
+    expect(ReservedPorts.parse("50080,50081")).toBe("50080,50081");
+    expect(ReservedPorts.parse(" 50080 , 50000-50100 ")).toBe("50080,50000-50100");
+    expect(ReservedPorts.parse("0,65535,8080-8080")).toBe("0,65535,8080-8080");
+  });
+
+  it.each(["50080,", ",50080", "50080 50081", "65536", "50100-50000", "08080", "0x50", "-1", "a"])(
+    "refuses %j, so a bad value stops the supervisor from starting",
+    (value) => {
+      expect(ReservedPorts.safeParse(value).success).toBe(false);
+    }
+  );
+});
+
 describe("Tolerations", () => {
   it("should parse key=value entries as Equal", () => {
     expect(Tolerations.parse("dedicated=runs:NoSchedule")).toEqual([

apps/supervisor/src/envUtil.ts

@@ -146,6 +146,36 @@ export const Tolerations = z.string().transform((val, ctx) => {
     });
 });
 
+// The kernel rejects whitespace between entries and reads a leading zero as octal.
+const PORT_OR_RANGE = /^(0|[1-9]\d{0,4})(?:-(0|[1-9]\d{0,4}))?$/;
+
+export const ReservedPorts = z
+  .string()
+  .optional()
+  .transform((val, ctx) => {
+    if (val === undefined || val.trim() === "") {
+      return undefined;
+    }
+
+    const entries = val.split(",").map((entry) => entry.trim());
+
+    for (const entry of entries) {
+      const match = PORT_OR_RANGE.exec(entry);
+      const low = Number(match?.[1]);
+      const high = Number(match?.[2] ?? match?.[1]);
+
+      if (!match || high > 65535 || low > high) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Invalid reserved port "${entry}". Must be a port or an ascending low-high range, within 0-65535.`,
+        });
+        return z.NEVER;
+      }
+    }
+
+    return entries.join(",");
+  });
+
 /**
  * Scalar values are coerced: YAML/JSON easily produce `true` or `3` where a label
  * value is meant, and Kubernetes label values are always strings. An empty value

apps/supervisor/src/workloadManager/kubernetes.test.ts

@@ -3,6 +3,7 @@ import {
   nodetypeNodeSelector,
   runPodTolerations,
   runnerSecurityContext,
+  withReservedSourcePorts,
   withRunnerSeccompProfile,
   withNodeSelector,
 } from "./kubernetesPodSpec.js";
@@ -155,6 +156,51 @@ describe("withRunnerSeccompProfile", () => {
   });
 });
 
+describe("withReservedSourcePorts", () => {
+  const reserved = { name: "net.ipv4.ip_local_reserved_ports", value: "50080,50081" };
+
+  it("leaves the spec untouched when unset", () => {
+    for (const ports of [undefined, ""]) {
+      expect(withReservedSourcePorts(basePodSpec, ports)).toBe(basePodSpec);
+    }
+  });
+
+  it("adds the sysctl and keeps the rest of the security context", () => {
+    expect(withReservedSourcePorts(basePodSpec, "50080,50081")).toEqual({
+      ...basePodSpec,
+      securityContext: { ...basePodSpec.securityContext, sysctls: [reserved] },
+    });
+  });
+
+  it("adds a security context when the spec has none", () => {
+    expect(withReservedSourcePorts({ restartPolicy: "Never" }, "50080,50081")).toEqual({
+      restartPolicy: "Never",
+      securityContext: { sysctls: [reserved] },
+    });
+  });
+
+  it("preserves existing sysctls", () => {
+    const existing = { name: "net.ipv4.ip_local_port_range", value: "32768 60999" };
+    const podSpec = { ...basePodSpec, securityContext: { sysctls: [existing] } };
+
+    expect(withReservedSourcePorts(podSpec, "50080,50081").securityContext?.sysctls).toEqual([
+      existing,
+      reserved,
+    ]);
+  });
+
+  it("replaces an existing value rather than duplicating the name", () => {
+    const podSpec = {
+      ...basePodSpec,
+      securityContext: { sysctls: [{ ...reserved, value: "40000" }] },
+    };
+
+    expect(withReservedSourcePorts(podSpec, "50080,50081").securityContext?.sysctls).toEqual([
+      reserved,
+    ]);
+  });
+});
+
 describe("runnerSecurityContext", () => {
   it("sets nothing when off", () => {
     expect(runnerSecurityContext("off", 1000, "node-24")).toBeUndefined();

apps/supervisor/src/workloadManager/kubernetes.ts

@@ -18,6 +18,7 @@ import {
   nodetypeNodeSelector,
   runPodTolerations,
   runnerSecurityContext,
+  withReservedSourcePorts,
   withRunnerSeccompProfile,
   withNodeSelector,
 } from "./kubernetesPodSpec.js";
@@ -137,12 +138,15 @@ export class KubernetesWorkloadManager implements WorkloadManager {
           );
         }
       }
-      const podSpec = withRunnerSeccompProfile(basePodSpec, {
-        profilePath: env.KUBERNETES_RUNNER_SECCOMP_PROFILE_PATH,
-        runtimes: env.KUBERNETES_RUNNER_SECCOMP_PROFILE_RUNTIMES,
-        runtime: opts.runtime,
-        checkpointsEnabled: this.opts.checkpointsEnabled,
-      });
+      const podSpec = withReservedSourcePorts(
+        withRunnerSeccompProfile(basePodSpec, {
+          profilePath: env.KUBERNETES_RUNNER_SECCOMP_PROFILE_PATH,
+          runtimes: env.KUBERNETES_RUNNER_SECCOMP_PROFILE_RUNTIMES,
+          runtime: opts.runtime,
+          checkpointsEnabled: this.opts.checkpointsEnabled,
+        }),
+        env.KUBERNETES_POD_RESERVED_SOURCE_PORTS
+      );
 
       await this.k8s.core.createNamespacedPod({
         namespace: this.namespace,

apps/supervisor/src/workloadManager/kubernetesPodSpec.ts

@@ -97,6 +97,30 @@ export function withRunnerSeccompProfile(
   };
 }
 
+const RESERVED_PORTS_SYSCTL = "net.ipv4.ip_local_reserved_ports";
+
+export function withReservedSourcePorts(
+  podSpec: Omit<k8s.V1PodSpec, "containers">,
+  ports: string | undefined
+): Omit<k8s.V1PodSpec, "containers"> {
+  if (!ports) {
+    return podSpec;
+  }
+
+  return {
+    ...podSpec,
+    securityContext: {
+      ...podSpec.securityContext,
+      sysctls: [
+        ...(podSpec.securityContext?.sysctls ?? []).filter(
+          (sysctl) => sysctl.name !== RESERVED_PORTS_SYSCTL
+        ),
+        { name: RESERVED_PORTS_SYSCTL, value: ports },
+      ],
+    },
+  };
+}
+
 const BUN_RUN_AS_USER = 1001;
 
 /**