[remotego]

What type of PR is this?

• feature
• install / chart

What this PR does and why

The PD router's wait-upstreams init container ran on the router image, so whatever pd.router.imageOverride named also had to be able to run this script. We have seen an image that works properly as the router but cannot run wait-upstreams, which left a working router blocked by a container that only does DNS lookups.

This moves wait-upstreams to debian:12-slim in both sglang (0.9.31) and vllm (0.9.3). Changing the router image no longer affects it.

It also adds pd.router.waitUpstreamsImage (repository, tag), because a hard-coded image would leave mirrored and air-gapped sites with no workaround. It uses the same helper pattern as the router image, and an emptied value falls back to debian.

Rollout impact

• Router restart: the init image is part of the router's pod spec, so PD routers roll once more on their next apply. All catalog PD variants float onto these versions. On vllm + mooncake, a router can hold its listener until its bootstrap handshake with each upstream finishes, so it's best to schedule those applies, or combine them with the apply that picks up feat(sglang,vllm): run the sglang PD router on smg; move router state to /tmp #100.
• One more image to pull: sites without Docker Hub access must mirror debian:12-slim and set pd.router.waitUpstreamsImage, on vllm as well as sglang. swiss's Registry.Mirror, modelsphere's image rewrite and the offline bundle don't cover it, the same gap as the router image.

Rollback: pin the sglang chart below 0.9.31, or vllm below 0.9.3.

Known gaps

• A bad router image now fails later. wait-upstreams used to pull the router image first, so a typo showed up straight away as Init:ImagePullBackOff. Now the image is only pulled after wait-upstreams finishes, which can take as long as engine placement does.
• The router image still needs its own tools. The router container runs its own bash -lc boot script and probes, so this doesn't remove that requirement.
• wait-upstreams runs as root on sglang. It ran as uid 65532 on the smg image, and debian sets no USER. A cluster policy requiring non-root would reject it, and the chart has no setting to change this. vllm's router image already ran as root.
• 12-slim is a moving tag. The risk is low for a script this small. Today's digest is sha256:99c0b25c… if we'd rather pin it.
• hack/check-chart-images.sh can't see this image because it renders defaults, where PD is off. The router images have the same blind spot, noted in feat(sglang,vllm): run the sglang PD router on smg; move router state to /tmp #100.

Which issue(s) this PR fixes

No issue filed. Follow-up to #100.

How it was tested

Run for this PR, on both charts:

helm lint --strict                     sglang, vllm: 0 failed (CI values and PD values)
helm unittest charts/sglang            Tests: 33 passed, 33 total
helm unittest charts/vllm              Tests: 42 passed, 42 total
hack/check-chart-version.sh <base>     rc=0

• Render vs before this change, PD values (compared before the Chart.yaml bumps): in pd-ds, only the init container's image line changes on both charts. Colocate is byte-identical on both, because it has no wait-upstreams.
• New tests can fail: on each chart, I pointed the init container back at the router image and changed the helper fallback and the values default separately. The tests failed each time.
• Schema: an unknown key under waitUpstreamsImage is rejected on both charts.
• Image contents: read from the published debian:12-slim amd64 layers, not by running it: bash, getent, awk (mawk), sort, wc and sleep are all present, and the config sets no USER, so it runs as root.

Not tested on a cluster. The container hasn't resolved real cluster DNS yet. Still to do:

1. Apply to one sglang and one vllm PD release: wait-upstreams should complete and the router reach 1/1.
2. With a role under-placed, confirm the init container logs not fully placed and keeps waiting.

Checks

• Tests and linters for what changed pass locally (see the repository's README or CONTRIBUTING)
• Docs updated where behaviour, a config key or a chart value moved (the values.yaml comments and schema; neither chart has a README)
• No internal hostnames, IPs, registries or credentials

Release note

action required: the PD router's wait-upstreams init container now runs on debian:12-slim in sglang 0.9.31 and vllm 0.9.3, independent of pd.router.imageOverride. Sites without Docker Hub access must mirror it and set pd.router.waitUpstreamsImage. Router pods roll once on upgrade.

🤖 Generated with Claude Code

[remotego]

@zoboth please review.

[remotego]

Merging with an admin override of the required GitHub review, at the PR author's request, for an urgent customer test. The author reports that internal review passed; that review isn't recorded on this PR. CI is green on cb3226e. The known gaps in the description will be handled as follow-ups.

[zoboth]

I read through the full diff (Chart.yaml bumps, both _helpers.tpl additions, both pd-ds.yaml image-line changes, both values.schema.json/values.yaml additions, and all the new/changed unittest cases).

Non-blocking notes (all already called out in "Known gaps," nothing new found):

• wait-upstreams now runs as root on sglang's debian:12-slim init container (it ran as uid 65532 on the smg image before). A cluster enforcing a non-root pod security policy would reject the whole pod, and there's no waitUpstreamsImage-level securityContext to set runAsUser as a workaround today.
• A bad router image typo now surfaces only after wait-upstreams finishes instead of immediately as ImagePullBackOff — acceptable tradeoff per the description, just flagging it's a real behavior change for on-call.
• debian:12-slim is a moving tag; since you already have the digest handy (sha256:99c0b25c…), pinning it would remove that variable if reproducibility across environments becomes a concern.
• Air-gapped/mirrored sites (swiss's Registry.Mirror, modelsphere's image rewrite, the offline bundle) need a manual addition for waitUpstreamsImage — worth a fast-follow ticket before any Docker-Hub-less site takes this upgrade.

The template/schema/values changes line up with the stated behavior, and the new unit tests (default, override-leaves-init-alone, mirrored override, emptied-falls-back-to-debian) cover the paths the description claims are tested.

Verdict: approve