# PJ2026-01060309 Cross Node Proxy K3s Build Benchmark

## Scope

This SPEC replaces the earlier HWLAB full-CI dependency for pikasTech/unidesk#1032. The benchmark target is now a generic k3s build workload that can run on any platform-infra target with an enabled egress proxy. It must not require HWLAB runtime namespaces, Tekton Pipelines, Argo CD, git-mirror, or HWLAB source repositories.

The first profile is `no-mirror-600m` in `config/platform-infra/egress-proxy-benchmarks.yaml`. It runs a fresh k3s Job per node, uses an emptyDir workspace, forbids benchmark reuse, keeps registry/source mirror settings out of the workload, and produces at least 600 MiB of build output. The profile also downloads an explicit no-mirror dependency payload so proxyserver traffic can be observed during the run.

The benchmark separates bootstrap image availability from the measured workload. A profile may define target-scoped `targetOverrides.<target>.image` and `imagePullPolicy` when a node cannot pull the default bootstrap image directly before pod proxy variables exist. These overrides must be generic platform-infra images, not HWLAB application images, and the measured workload must still use the same no-mirror download and 500MiB+ output rules.

## Architecture

`platform-infra egress-proxy k3s-build-benchmark` is the coordinator. It reads platform-infra targets from `config/platform-infra/sub2api.yaml`, reads workload profiles from `config/platform-infra/egress-proxy-benchmarks.yaml`, renders one Kubernetes Job per target, and uses `trans <target.route> sh -- ...` as the short control path.

The workload Job runs in the target platform-infra namespace and receives proxy environment variables that point at the YAML-declared `sub2api-egress-proxy` service. The existing `platform-infra egress-proxy traffic` sampler remains the proxyserver-side observability source. Benchmark status may include a bounded traffic sample, but raw proxy credentials and Secret values are never printed.

The portable workload path uses Python from the bootstrap image to download the declared dependency payload and generate the build artifact. It does not rewrite apt, apk, npm, pip, or registry sources. Debian/apt bootstrap images remain supported for future profiles, but apt is not required for the default cross-node benchmark.

## Data Model

Stable benchmark records contain:

- `target`: platform-infra target id such as `D601` or `D518`.
- `profile`: benchmark profile id, initially `no-mirror-600m`.
- `runId` and `jobName`: k3s Job identity.
- `image`, `payloadMiB`, `dependencyDownload.expectedMiB`, `noMirror`: profile facts from YAML.
- `targetOverrides`: optional target-specific bootstrap image facts; these are not measured dependency mirrors.
- `state`: `pending`, `running`, `succeeded`, `failed`, or `missing`.
- `startedAt`, `completedAt`, `durationSeconds`: Job timing.
- `outputMiB`, `downloadMiB`: workload evidence parsed from Job logs.
- `proxy`: service, port, source fingerprint, and values-redacted marker.
- `traffic`: optional proxyserver sample with window bytes, rate, cumulative bytes, top client, and top destination.
- `failureFamily`: `none`, `job-missing`, `image-pull`, `apt-download`, `dependency-download`, `payload-too-small`, `timeout`, `proxy-unavailable`, or `unknown`.

## CLI Sequence

1. `--dry-run` resolves all requested targets and profiles, then prints a bounded table of target, route, namespace, proxy service, payload size, expected dependency download, and no-mirror policy.
2. `--confirm` creates one unique k3s Job per target and returns immediately with run id, Job name, status command, logs command, and traffic command.
3. `status` reads the newest matching Job per target, parses the bounded Job log result marker, and prints a cross-node table.
4. `status --traffic-sample-seconds N` additionally samples the target proxyserver loopback Clash API for N seconds per node and includes rate/window/cumulative traffic columns.
5. `logs` prints bounded Job log tails for drill-down.

## Boundaries

This benchmark is not a HWLAB application CI result and must not be reported as PipelineRun timing. It measures a generic k3s build workload under the node-local platform-infra egress proxy. It is valid for cross-node proxy path and build egress performance comparison because every target runs the same YAML profile and the same Job template.

The workload must stay no-mirror: do not rewrite apt/apk sources to regional mirrors, do not use npm mirror registries, do not configure Docker registry mirrors, and do not reuse a previous Job, PVC, or dependency cache. The configured profile must keep output payload at or above 500 MiB.

## Acceptance

- `bun scripts/cli.ts platform-infra egress-proxy k3s-build-benchmark --targets D601,D518 --profile no-mirror-600m --dry-run` prints two target plans or structured blockers.
- `--confirm` starts D601 and D518 Jobs without waiting for completion.
- `status --traffic-sample-seconds 15` prints cross-node build status plus proxyserver traffic evidence.
- Final issue closeout includes a table with target, profile, job, state, duration, output MiB, dependency download MiB, traffic window/rate/cumulative, top client, top destination, and failure family.
