<fix>[storage]: ZSTAC-87684 prepare zbs hosts on attach

[zstack-robot-2]

Summary

Backport zstack !9991 from 5.5.22 to 5.4.12 for ZSTAC-87684.

Fix external/ZBS primary storage attach so connected, non-maintenance KVM hosts in the target cluster are prepared before attach succeeds.

Changes

• Cherry-pick source commit 9022e987c21cb8e5edc5b5689570a1deb8004d85.
• Prepare usable cluster hosts through ExternalPrimaryStorage.attachHook(...).
• Fail attach on deploy-client or heartbeat activation failure without changing primary storage status.
• Keep the original integration coverage; adapt heartbeat assertions to the single logical pool supported by 5.4.12.

Testing

• git diff --check upstream/5.4.12..HEAD
• Remote x86 module build
• ZbsPrimaryStorageCase.testPrepareHostsWhenAttachPrimaryStorageToCluster
• CI pipeline

Original issue: ZSTAC-85462

Resolves: ZSTAC-87684

sync from gitlab !10741

[coderabbitai]

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your current included review allowance is based on your included PR review attempts over the past 7 days.

Next review available in: 22 minutes

Limit details: You’ve used the included review currently available. Your 95 included PR review attempts over the past 7 days set your current allowance at 1 review per hour.

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits within each organization.

For paid Pro and Pro+ reviews, CodeRabbit uses a developer's included PR review attempts over the past 7 days to set the current hourly allowance. At typical activity levels, the full plan allowance applies. Higher sustained activity can lower the allowance until earlier attempts leave the 7-day window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 5eff5a2b-604a-4489-95a6-9cd886ca416d

📥 Commits

Reviewing files that changed from the base of the PR and between e418c48 and 906be64.

📒 Files selected for processing (1)

• storage/src/main/java/org/zstack/storage/addon/primary/ExternalPrimaryStorage.java

Warning

.coderabbit.yaml has a parsing error

The CodeRabbit configuration file in this repository has a parsing error and default settings were used instead. Please fix the error(s) in the configuration file. You can initialize chat with CodeRabbit to get help with the configuration file.

💥 Parsing errors (1)

Could not fetch remote config from http://open.zstack.ai:20001/code-reviews/zstack-cloud.yaml: TimeoutError: The operation was aborted due to timeout

⚙️ Configuration instructions

• Please see the configuration documentation for more information.
• You can also validate your configuration using the online YAML validator.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: e2143285-8c5b-4f61-aea3-95b5fa996978

📥 Commits

Reviewing files that changed from the base of the PR and between 393371f and e418c48.

📒 Files selected for processing (2)

• storage/src/main/java/org/zstack/storage/addon/primary/ExternalPrimaryStorage.java
• test/src/test/groovy/org/zstack/test/integration/storage/primary/addon/zbs/ZbsPrimaryStorageCase.groovy

Included review availability: 1 review is currently available. Based on recent review activity, included reviews refill at 2 per hour.

---

Walkthrough

新增 ExternalPrimaryStorage.attachHook。该钩子筛选可用主机，部署客户端，并激活心跳卷。ZBS 集成测试覆盖成功挂载、维护主机跳过、客户端部署失败和心跳卷激活失败。

Changes

ZBS 主存储挂载

Layer / File(s)	Summary
主存储挂载钩子 storage/src/main/java/org/zstack/storage/addon/primary/ExternalPrimaryStorage.java	新增 attachHook。方法筛选已连接且非维护状态的主机，部署客户端，并在部署成功后激活心跳卷。
挂载流程集成验证 test/src/test/integration/storage/primary/addon/zbs/ZbsPrimaryStorageCase.groovy	新增成功挂载、维护主机跳过、客户端部署失败和心跳卷激活失败测试，并清理模拟器处理器。

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: ⚪ Minimal · up to e418c

The change prepares eligible ZBS hosts before attach completes and fails attach on preparation errors; no actionable merge-blocking risk remains at the current head, so it is merge-ready after normal checks and review.

Sequence Diagram(s)

sequenceDiagram
  participant 主存储挂载
  participant 集群主机查询
  participant 客户端部署
  participant 心跳卷
  主存储挂载->>集群主机查询: 查询可用主机
  主存储挂载->>客户端部署: 部署客户端
  客户端部署-->>主存储挂载: 返回部署结果
  主存储挂载->>心跳卷: 激活心跳卷
  心跳卷-->>主存储挂载: 返回激活结果

Loading

Poem

我是小兔，蹦过主机行，
维护节点安静旁观。
客户端部署齐步走，
心跳卷亮起月光。
失败即刻回报，挂载稳稳收场。

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题准确概括了在挂载时准备 ZBS 主机的主要变更。
Description check	✅ Passed	描述说明了回移目的、代码变更、失败行为和测试状态，与变更内容相关。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sync/haidong.pang/fix/ZSTAC-87684

---

_{Comment @coderabbitai help to get the list of available commands.}

[zstack-robot-2]

Comment from gitlab:

自上次添加REVIEWED标签(2026-08-18 18:30:55.000Z)后, 有新的COMMIT更新(2026-08-19 11:06:00.927Z), 所以移除了REVIEWED标签