<feature>[zns]: ZNS SDN controller integration - Wave 1-6 (ZCF-2133)

[zstack-robot-1]

ZNS SDN Controller integration - schema, error codes, status, ping tracker

Resolves: ZCF-2133

sync from gitlab !9764

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

Walkthrough

新增 ZNS 数据模型（ZnsTenantVO、ZnsTenantRouterVO），为 ZnsTransportZoneVO 添加 znsResourceUuid 与复合唯一约束；扩展 SdnControllerStatus（Syncing、Ready）；Ping 跟踪器在 Syncing/Ready 或找不到记录时跳过处理；新增 10 个 ZNS 相关错误码常量。

Changes

Cohort / File(s)	Summary
数据库架构变更 conf/db/upgrade/V5.5.18__schema.sql	添加表 ZnsTenantVO（PK uuid、sdnControllerUuid FK -> SdnControllerVO(uuid) ON DELETE CASCADE、znsResourceUuid、复合唯一约束 (sdnControllerUuid,znsResourceUuid) 等）和 ZnsTenantRouterVO（PK uuid、sdnControllerUuid、可空 tenantUuid FK -> ZnsTenantVO(uuid) ON DELETE CASCADE、state 字段、idx_zns_tr_tenant 索引、复合唯一约束 (sdnControllerUuid,znsResourceUuid)）；为 ZnsTransportZoneVO 添加非空列 znsResourceUuid 并增加复合唯一约束 uk_zns_tz_resource (znsSdnControllerUuid,znsResourceUuid)。
枚举扩展 header/src/main/java/org/zstack/header/network/sdncontroller/SdnControllerStatus.java	向 SdnControllerStatus 增加枚举常量 Syncing 与 Ready，用于表示 ZNS 向导初始化同步中及完成状态。
心跳追踪器逻辑 plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerPingTracker.java	getPingMessage 在找不到控制器记录时返回 null 并记录；当控制器状态为 Syncing 或 Ready 时不生成/发送 ping；handleReply 在 Syncing/Ready 状态下提前返回，避免自动变更控制器状态。
错误代码常量 utils/src/main/java/org/zstack/utils/clouderrorcode/CloudOperationsErrorCode.java	新增 10 个 ZNS Wave4 相关错误码常量 ORG_ZSTACK_NETWORK_ZNS_10025 至 ORG_ZSTACK_NETWORK_ZNS_10034，覆盖段/路由器操作、DHCP/MTU 补丁、重复 IP 版本、删除受限、缺少系统 tag、HTTP 409 等场景。
L3 网络初始化 network/src/main/java/org/zstack/network/l3/L3NetworkManagerImpl.java	在创建 L3 网络时显式设置 L3NetworkVO.type，使用 msg.getType() 或回退到 L3_BASIC_NETWORK_TYPE。

Sequence Diagram(s)

sequenceDiagram
    participant PingTracker as PingTracker
    participant DB as Database
    participant Controller as SdnController (VO)
    participant Network as NetworkService

    PingTracker->>DB: 查找 controller by uuid
    alt record not found
        DB-->>PingTracker: null
        PingTracker-->>Network: 不发送 ping（返回 null）
    else record found
        DB-->>PingTracker: controller (status)
        alt status is Syncing/Ready
            PingTracker-->>Network: 跳过发送 ping（受管状态）
        else other statuses
            PingTracker->>Network: 生成并发送 ping 消息
            Network-->>PingTracker: ping reply
            PingTracker->>DB: 根据 reply 更新 controller 状态
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 分钟

Poem

🐇 新表跳出地洞跑，租户路由排成队，
心跳遇见两新态，缺人时静悄悄，
错码十枚齐列好，数据库稳又在。 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The pull request title follows the required [scope]: format and is 68 characters, meeting all specified requirements.
Description check	✅ Passed	The pull request description is directly related to the changeset, describing ZNS SDN controller integration components including schema, error codes, and status changes.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch sync/shixin.ruan/shixin-ZCF-2133@@2

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@conf/db/upgrade/V5.5.18__schema.sql`:
- Line 40: The migration currently defines the column `description` as
VARCHAR(2048); change its type to TEXT to avoid truncation from unbounded
external ZNS data: replace `description VARCHAR(2048) DEFAULT NULL` with
`description TEXT DEFAULT NULL` in the migration and any other SQL statements in
the same migration that create or alter this `description` column, ensuring
indexes/constraints remain valid after the type change.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: http://open.zstack.ai:20001/code-reviews/zstack-cloud.yaml (via .coderabbit.yaml)

Review profile: CHILL

Plan: Pro

Run ID: 3f1853d2-762d-4d68-8037-add5989f5954

📥 Commits

Reviewing files that changed from the base of the PR and between edd0a38 and fe2aab5.

📒 Files selected for processing (4)

• conf/db/upgrade/V5.5.18__schema.sql
• header/src/main/java/org/zstack/header/network/sdncontroller/SdnControllerStatus.java
• plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerPingTracker.java
• utils/src/main/java/org/zstack/utils/clouderrorcode/CloudOperationsErrorCode.java

[coderabbitai]

🧹 Nitpick comments (1)

plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerPingTracker.java (1)

56-59: 建议在资源缺失时主动 untrack，避免重复告警

Line 56-59 当前仅返回 null，若跟踪集中仍有该 UUID，会持续触发无效查询与 warn 日志。建议这里直接 untrack(resUuid) 做自愈。

建议修改

 if (vo == null) {
     logger.warn(String.format("SDN controller[uuid:%s] has been deleted, skip ping sending", resUuid));
+    untrack(resUuid);
     return null;
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerPingTracker.java`
around lines 56 - 59, In SdnControllerPingTracker inside the method containing
the vo null-check, when vo == null currently you only return null; instead call
the tracker’s untrack(resUuid) before returning to remove the UUID from the
tracking set and prevent repeated warn logs and pointless lookups—i.e., invoke
untrack(resUuid) (or the class method used to stop tracking) then log if needed
and return null.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In
`@plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerPingTracker.java`:
- Around line 56-59: In SdnControllerPingTracker inside the method containing
the vo null-check, when vo == null currently you only return null; instead call
the tracker’s untrack(resUuid) before returning to remove the UUID from the
tracking set and prevent repeated warn logs and pointless lookups—i.e., invoke
untrack(resUuid) (or the class method used to stop tracking) then log if needed
and return null.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: http://open.zstack.ai:20001/code-reviews/zstack-cloud.yaml (via .coderabbit.yaml)

Review profile: CHILL

Plan: Pro

Run ID: 69260cbe-bdad-4417-9e0d-7a9d138eb84c

📥 Commits

Reviewing files that changed from the base of the PR and between fe2aab5 and 7f7b000.

📒 Files selected for processing (4)

• conf/db/upgrade/V5.5.18__schema.sql
• header/src/main/java/org/zstack/header/network/sdncontroller/SdnControllerStatus.java
• plugin/sdnController/src/main/java/org/zstack/sdnController/SdnControllerPingTracker.java
• utils/src/main/java/org/zstack/utils/clouderrorcode/CloudOperationsErrorCode.java

✅ Files skipped from review due to trivial changes (1)

• utils/src/main/java/org/zstack/utils/clouderrorcode/CloudOperationsErrorCode.java

🚧 Files skipped from review as they are similar to previous changes (1)

• conf/db/upgrade/V5.5.18__schema.sql

[zstack-robot-1]

Comment from shixin.ruan:

已修复：在 getPingMessage() 的 vo == null 分支中添加 untrack(resUuid)，自愈避免重复 warn 日志，commit 476676b。