docs(sidecar): scope P2P rank derivation to per-pod DP groups

vLLM binds the tier at p2p-connector-port plus the global
data_parallel_index (tiering/p2p/manager.py), while the endpoint-port
offset yields the pod-local rank. The two agree only when each pod is its
own DP group, so state that boundary: multi-pod DP groups (LWS wide-EP)
need the source's global index supplied per request, and this derivation
is the per-pod fallback.

Signed-off-by: nilig <nili.ifergan@gmail.com>

Author: nilig

docs/disaggregation.md

@@ -559,7 +559,7 @@ Both prefill and decode pods require the following `--kv-transfer-config`:
 
 `host` must be the pod's own IP at runtime (use the Kubernetes downward API env var `status.podIP`). `port` must match `--p2p-connector-port` (default `7777`). `cpu_bytes_to_use` controls the CPU KV offload buffer size; size it to hold the KV for the expected concurrent in-flight transfers. `OffloadingConnector` is available in vLLM nightly builds from 2026-06-30 onward (commit `bec232a`, [PR #42285](https://github.com/vllm-project/vllm/pull/42285)).
 
-**Data parallelism:** with `--data-parallel-size` N > 1, DP rank `r`'s P2P tier listens on `<p2p-connector-port>+r` and its shared-memory offload region is per-replica, so ranks in one pod do not collide. The sidecar derives the target rank from the routed endpoint's port (rank `r` is served on `<port>+r`) and injects `remote_port` = `--p2p-connector-port` + `r`; a port outside the rank range falls back to rank 0. This assumes every pod in the pool shares the sidecar's port layout and DP size. Requires vLLM with per-DP-rank P2P ports and per-replica offload regions ([PR #47636](https://github.com/vllm-project/vllm/pull/47636), [PR #47987](https://github.com/vllm-project/vllm/pull/47987)); on older engines every rank binds the same `POD_IP:<p2p-connector-port>` and DP > 1 fails at engine startup. Size `/dev/shm` for N regions: pod shm must exceed N x `cpu_bytes_to_use`.
+**Data parallelism:** with `--data-parallel-size` N > 1, vLLM binds DP replica `i`'s P2P tier on `<p2p-connector-port>+i`, where `i` is the **global** `data_parallel_index`, and gives each replica a distinct shared-memory offload region, so ranks in one pod do not collide. The sidecar derives the target's pod-local rank from the routed endpoint's port (rank `r` is served on `<port>+r`) and injects `remote_port` = `--p2p-connector-port` + `r`; a port outside the rank range falls back to rank 0. Local rank equals the global index only when each pod is its own DP group, so this derivation covers per-pod DP deployments; in multi-pod DP groups (e.g. LWS wide-EP, where pod k's replicas hold global indices k*N..k*N+N-1 behind the same serving ports) the source's global index must be supplied per request and is not derivable from the endpoint port. Requires vLLM with per-DP-rank P2P ports and per-replica offload regions ([PR #47636](https://github.com/vllm-project/vllm/pull/47636), [PR #47987](https://github.com/vllm-project/vllm/pull/47987)); on older engines every rank binds the same `POD_IP:<p2p-connector-port>` and DP > 1 fails at engine startup. Size `/dev/shm` for N regions: pod shm must exceed N x `cpu_bytes_to_use`.
 
 ### General Sidecar Flags
 

pkg/sidecar/proxy/connector_p2p.go

@@ -251,13 +251,15 @@ func (s *Server) p2pSourceParams(sourceHostPort string) map[string]any {
 	}
 }
 
-// p2pPortFor resolves the P2P tier control port on the target endpoint. With
-// data parallelism the sidecar serves rank r on <base port>+r
-// (data_parallel.go) and vLLM binds rank r's P2P tier on
-// <p2p-connector-port>+r, so the rank encoded in the routed endpoint's port
-// selects the matching P2P port. All pods in the pool are assumed to share
-// the sidecar's port layout and DP size. A port outside the rank range (or
-// unparsable) falls back to the base P2P port, which is rank 0's tier.
+// p2pPortFor resolves the P2P tier control port on the target endpoint. The
+// sidecar serves rank r on <base port>+r (data_parallel.go), so the routed
+// endpoint's port encodes the pod-local rank. vLLM binds the tier at
+// <p2p-connector-port> + the global data_parallel_index, so the mapping is
+// correct when each pod is its own DP group (local rank == global index).
+// Multi-pod DP groups (e.g. LWS wide-EP) need the source's global rank
+// supplied per request instead; this derivation is the per-pod fallback. A
+// port outside the rank range (or unparsable) falls back to the base P2P
+// port, which is rank 0's tier.
 func (s *Server) p2pPortFor(targetHostPort string) int {
 	base := s.config.P2PConnectorPort
 	if s.config.DataParallelSize <= 1 || s.dpBasePort == 0 {