docs: add bilingual cross-node Pause/Resume/Snapshot guide - #1506
Conversation
Document S3 backend, remote_status=ready, origin-first scheduling, and host-fact matching so operators can restore pause packages and snapshots on another node. Assisted-by: Cursor:Composer Signed-off-by: ls-ggg <335814617@qq.com> Co-authored-by: Cursor <cursoragent@cursor.com>
![cubesandboxbot[bot]](https://avatars.githubusercontent.com/in/3653584?s=60&v=4){kind=small}
|
|
||
| The target node's kernel and CPU identity must match the origin. Memory state (including CPU registers and feature bits) cannot restore correctly otherwise. | ||
|
|
||
| > **Current match policy:** cross-node compatibility currently requires **equality on `cpuid_hash` and `host_kernel_release` only**. Other fields (`cpu_vendor`, `host_kernel_fingerprint`, `kvm_api_version`) are collected and shown but **are not equality gates**. A target with a non-empty `kvm_module_taint` (forced / out-of-tree / unsigned `kvm.ko`) is rejected. Later releases may tighten this; follow the version you run. |
There was a problem hiding this comment.
The kvm_module_taint claim here doesn't match the cross-node scheduling path. In the code, the taint gate is enforced only by the diagnostic restore-compat endpoints (EvaluateSnapshotRestoreCompat / ListCompatibleNodesForSnapshot / ListCompatibleNodesForFactors in CubeMaster/pkg/templatecenter/restore_compat.go, kvmModuleTaintDimension). The actual cross-node scheduler — restoreplace.Decide (CubeMaster/pkg/restoreplace/placement.go:274) → nodemeta.QueryHostFactCandidates → filterHostFactCandidates (CubeMaster/pkg/nodemeta/service.go:190) — filters candidates only on cpuid_hash + host_kernel_release equality and never consults kvm_module_taint. Both Resume (resumePlacement) and FromSnap (fromSnapshotPlacement) route through restoreplace.Decide. So a cross-node restore can land on a node with a tainted kvm.ko provided the two equality keys match. Consider scoping this to the compatible-nodes check, or (if the code comment's "hard restore blocker" intent is to hold) filing the scheduler gap separately. Same applies to the ZH page.
| cubemastercli cubebox list --all | ||
| ``` | ||
|
|
||
| Non-paused rows sort by create time descending; paused rows come last and include `pause_snap`. After a successful Resume those columns return to `-`. |
There was a problem hiding this comment.
Minor: "those columns return to -" only holds for remote and pause_snap. The backend column is filled from the sandbox's persisted spec (enrichSandboxListBackends, CubeMaster/pkg/service/sandbox/sandbox_list.go:249), so an S3-backed sandbox keeps showing s3 after a successful Resume — it does not return to -. Consider rewording to "the remote and pause_snap columns return to -".
| > **当前匹配范围**：跨机兼容性判定**目前仅以 `cpuid_hash` 与 `host_kernel_release` 两个维度做相等匹配**。 | ||
| > 其余字段（`cpu_vendor`、`host_kernel_fingerprint`、`kvm_api_version`）目前只是采集并展示、 | ||
| > **尚未纳入相等匹配门禁**。目标节点若带非空的 `kvm_module_taint`（强制 / 树外 / 未签名的 `kvm.ko`）， | ||
| > 会被拒绝作为跨机目标。后续版本可能收紧匹配维度，请以实际版本为准。 |
There was a problem hiding this comment.
与英文版同一处：跨机调度路径（restoreplace.Decide → nodemeta.QueryHostFactCandidates/filterHostFactCandidates）只按 cpuid_hash 与 host_kernel_release 相等匹配，并不读取 kvm_module_taint。taint 门禁只在兼容性诊断接口（restore_compat.go 的 EvaluateSnapshotRestoreCompat / ListCompatibleNodesForSnapshot / ListCompatibleNodesForFactors）中生效。建议将该表述限定到「兼容性检查」范围，或另行修复调度器。
Review: docs: add bilingual cross-node Pause/Resume/Snapshot guideScope: Docs-only PR (586 additions, 2 deletions). Adds EN/ZH Overall: Technically accurate. I verified the substantive claims against the base tree ( Findings1. HIGH — Benchmark tables presented as measured data, while the PR description calls them placeholdersThe PR body explicitly states "Benchmark tables are placeholders," but the new docs present concrete numbers (e.g. cold-start s3 p95 2. MEDIUM —
|
Record 2026-08-25 per-instance avg/p95, template spec, and host SKU. Rounds stay "start N then kill all" so later re-runs keep the same tables. Assisted-by: Cursor:Composer Signed-off-by: ls-ggg <335814617@qq.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Assisted-by: Cursor:Composer Signed-off-by: ls-ggg <335814617@qq.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Assisted-by: Cursor:Composer Signed-off-by: ls-ggg <335814617@qq.com> Co-authored-by: Cursor <cursoragent@cursor.com>
Assisted-by: Cursor:Composer Signed-off-by: ls-ggg <335814617@qq.com> Co-authored-by: Cursor <cursoragent@cursor.com>
|
|
||
| Times are **milliseconds**. **avg** / **p95** are **per-sandbox** create latency (when that sandbox became `running`), not batch wall time divided by concurrency. | ||
|
|
||
| Figures below were measured on 2026-08-25. Numbers depend on hardware, image, and dirty-page load; treat them as a same-cluster xfs vs s3 comparison, not a SLA. |
There was a problem hiding this comment.
The PR description says "Benchmark tables are placeholders", but this section presents concrete numbers as measured on 2026-08-25 with a detailed environment/method. This is contradictory as written. If the tables are placeholders, mark them clearly as illustrative/placeholder (or drop them) before merge; if they are real measurements, update the PR description instead. As-is, readers will treat these numbers as measured results.
|
|
||
| The target node's kernel and CPU identity must match the origin. Memory state (including CPU registers and feature bits) cannot restore correctly otherwise. | ||
|
|
||
| > **Current match policy:** cross-node compatibility currently requires **equality on `cpuid_hash` and `host_kernel_release` only**. Other fields (`cpu_vendor`, `host_kernel_fingerprint`, `kvm_api_version`) are collected and shown but **are not equality gates**. A target with a non-empty `kvm_module_taint` (forced / out-of-tree / unsigned `kvm.ko`) is rejected. Later releases may tighten this; follow the version you run. |
There was a problem hiding this comment.
This states a target with non-empty kvm_module_taint is "rejected" for cross-node restore, but the current scheduler path does not enforce that. restoreplace.Decide → defaultListCompatible → nodemeta.QueryHostFactCandidates gates on equality of cpuid_hash and host_kernel_release only; the kvm_module_taint gate exists solely in the diagnostic restore-compat evaluation (CubeMaster/pkg/templatecenter/restore_compat.go, kvmModuleTaintDimension), which is not what the scheduler consults. Consider clarifying that the taint rejection is currently only reported by the diagnostic check, not enforced by placement — or note it as a planned gate.
|
|
||
| ## Configuring the S3 backend | ||
|
|
||
| The S3 path in CubeSandbox is **on by default**. You need a ready **S3lvol** service; there is no extra feature flag. |
There was a problem hiding this comment.
"No extra feature flag" is imprecise for one-click installs: deploy/one-click/env.example exposes ONE_CLICK_ENABLE_S3LVOL (default 0, see deploy/one-click/install.sh:1555), which turns the cube-sandbox-s3lvol systemd unit on. So S3lvol is not on by default when using the one-click installer — operators must set that flag. The "on by default" claim may be true of the CubeMaster/Cubelet code path once the service is up, but the sentence as written will mislead installer users. Suggest mentioning the flag.
|
|
||
| 单位 **ms**。表中 **avg** / **p95** 是**单实例**从发起到进入 `running` 的耗时，不是整批 wall 再除以并发。 | ||
|
|
||
| 下列数字测于 2026-08-25。结果随硬件、镜像和脏页负载变化，只适合作为同集群上 xfs 与 s3 的对照，不是 SLA。 |
There was a problem hiding this comment.
PR 描述里写的是 "Benchmark tables are placeholders"，但本节以「测于 2026-08-25」的形式给出了具体数字和详细的测试方法，两者矛盾。若这些表格是占位数据，请在合入前明确标注为示例/占位（或删除）；若确为实测数据，请同步更新 PR 描述。否则读者会把这些数字当作实测结果。
1 participant
Summary
docs/guide/cross-node-snapshot.md,docs/zh/guide/cross-node-snapshot.md).CanCrossNode(backend=s3andremote_status=ready), host-fact matching (cpuid_hash+host_kernel_release), CLI columns, and current limitations.CLI examples match current master:
cubemastercli tpl create-from-image --backend s3andcubeopscli node list --jsonfor HostFacts. Benchmark tables are placeholders.Test plan
cubemastercli tpl create-from-image --helpandcubeopscli node list --help.Assisted-by: Cursor:Composer
Signed-off-by: ls-ggg 335814617@qq.com