Skip to content

docs(network): Document compute-node port allocation ranges #205

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
fslongjin merged 1 commit into from
May 15, 2026
+20 −0
Merged

docs(network): Document compute-node port allocation ranges #205

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions docs/architecture/network.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,16 @@ This path does not create entries in the session tables, which keeps the maps le

The Go API provides `AddPortMapping()`, `DelPortMapping()`, `ListPortMapping()`, and `GetPortMapping()` for managing mappings at runtime.

### 6.4 Compute-Node Port Allocation

To prevent collisions between subsystems, the host's usable port space is partitioned into three ranges:

| Port range | Purpose | Allocator |
|------------|---------|-----------|
| `10000`--`19999` | `ip_local_port_range` (host ephemeral ports) | Set by network-agent at startup |
Comment on lines +277 to +279
Copy link
Copy Markdown

@github-actions github-actions Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit: Consider adding a brief cross-reference to §6.3 here. The AddPortMapping() API from §6.3 allocates host ports from the 20000–29999 range documented in this row. A small note like "see §6.3 Management for the API" would help readers connect the allocation range to the API that consumes it.

| `20000`--`29999` | Ports CubeProxy uses to reach sandboxes | Allocated by network-agent when a sandbox is created |
| `30000`--`65535` | Source ports used by host SNAT for sandbox-originated traffic | Allocated by CubeVS during SNAT |

---

## 7. TAP Device Lifecycle
Expand Down
10 changes: 10 additions & 0 deletions docs/zh/architecture/network.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,6 +270,16 @@ CubeVS 完全在内核态执行逐沙箱的出站网络策略，使用 LPM（最

Go API 提供了 `AddPortMapping()`、`DelPortMapping()`、`ListPortMapping()` 和 `GetPortMapping()`，用于在运行时管理映射关系。

### 6.4 计算节点端口分配

为避免不同子系统之间的端口冲突，计算节点上的可用端口被划分为三段：

| 端口范围 | 用途 | 分配者 |
|----------|------|--------|
| `10000`--`19999` | `ip_local_port_range`（宿主机临时端口） | 由 network-agent 启动时修改 |
| `20000`--`29999` | CubeProxy 访问沙箱所用的端口范围 | 由 network-agent 在创建沙箱时分配 |
Comment on lines +277 to +280
Copy link
Copy Markdown

@github-actions github-actions Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

与英文版建议一致：可考虑在此处添加对 §6.3 管理的交叉引用，说明 AddPortMapping() 所分配的宿主端口即来自 20000–29999 这一范围。

| `30000`--`65535` | 沙箱出站报文经主机 NAT 时使用的端口范围 | 由 CubeVS 在 SNAT 时分配 |

---

## 7. TAP 设备生命周期
Expand Down