Skip to content

[ISSUE #14804] Add historical A2A rolling-upgrade migration - #15814

Merged
KomachiSion merged 12 commits into
alibaba:developfrom
KomachiSion:codex/rad-a2a-upgrade-migration
Sep 3, 2026
Merged

KomachiSion merged 12 commits into
alibaba:developfrom
KomachiSion:codex/rad-a2a-upgrade-migration

Conversation

@KomachiSion

Copy link
Copy Markdown
Collaborator

What is the purpose of the change

For #14804.

Provide a one-way and recoverable upgrade path from the historical Nacos 3.0-3.2 A2A Config/Naming layout to canonical RAD Agent Resource/Version/Runtime state without disrupting old A2A SDKs during a rolling upgrade. AUTO keeps legacy definitions authoritative until all current members and projections pass the cutover gates, and then permanently switches the cluster to CANONICAL.

Brief changelog

  • Add the internal Config-backed migration Marker, Lease, Progress, member capability/policy negotiation, reconciliation, write-after hints, QUIESCING fences, and permanent CANONICAL cutover.
  • Convert historical A2A definitions into canonical Agent Resource/Version/Storage with strict conflict detection, idempotent repair, safe orphan handling, and per-entry failure isolation.
  • Dual-materialize exact-version Runtime Endpoints during migration and support a frozen optional legacy Naming shadow after cutover, with stable publisher ownership, retries, disconnect/redo handling, and capacity accounting.
  • Gate cutover on definition, storage, Search, Runtime, member ACK, and retry-queue readiness; incomplete or unsafe state remains in or returns to SYNCING.
  • Isolate migration control state in _nacos_internal_, freeze the storage provider and shadow policy in the Marker, and add bounded diagnostics, metrics, runbook guidance, and a 4.0 removal inventory.
  • Add bilingual specifications, focused unit tests, OpenAPI/Java SDK integration-test scenarios, and dedicated rolling-upgrade workflow fixtures.

Verifying this change

  • Ran mvn -pl ai,test/java-sdk-test,test/openapi-test spotless:apply and the matching spotless:check successfully.
  • Ran the focused migration suite (A2a*Migration*Test, A2aHistoricalDefinition*Test, and A2aRuntimeSnapshotComparatorTest): 180 tests, 0 failures.
  • Verified the modified migration scanner/readiness/reconciliation production classes at 100% JaCoCo line coverage.
  • Compiled OpenAPI and Java SDK integration tests with their 46-module dependency reactor successfully.
  • Ran scoped RAT, Checkstyle, SpotBugs, and Spotless checks successfully, and built the complete release distribution successfully.
  • Performed a real single-node upgrade from Nacos 3.2.3 to the current server with a long-lived Nacos 3.2.3 SDK client. Definition migration, reads/writes during migration, subscriptions, endpoint heartbeat/redo, restart, permanent cutover, and post-cutover reads/writes passed.
  • Performed a real two-node rolling upgrade backed by MySQL. Mixed-version SYNCING, old-node writes and reconciliation, SDK failover/endpoint redo, readiness convergence, CANONICAL cutover, node restart, subscriptions, RAD Discover/Search, the legacy A2A facade, and the optional Naming shadow passed.
  • Confirmed all temporary Nacos servers, migration clients, and MySQL processes used by the directed tests were stopped.

Follow this checklist to help us incorporate your contribution quickly and easily:

  • Make sure there is a Github issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a Github issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue.
  • Format the pull request title like [ISSUE #123] Fix UnknownException when host config not exist. Each commit in the pull request should have a meaningful subject line and body.
  • Write a pull request description that is detailed enough to understand what the pull request does, how, and why.
  • Write necessary unit-test to verify your logic correction, more mock a little better when cross module dependency exist. If the new feature or significant change is committed, please remember to add integration-test in test module.
  • Run mvn spotless:apply to format your code. Run mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check spotless:check -DskipTests to make sure basic checks pass. Run mvn clean install to make sure unit-test pass. Run mvn clean test-compile failsafe:integration-test to make sure integration-test pass.

Introduce the temporary 3.0-3.2 A2A migration state, Config-backed marker/lease/progress control objects, member capability metadata, conservative AUTO authority routing, and the 4.0 removal inventory.

Assisted-by: Claude Code
Move migration coordination records into the internal AI namespace, freeze the Agent storage provider in the migration plan, and avoid Config history growth for transient control updates.

Assisted-by: Claude Code
@github-actions

github-actions Bot commented Sep 3, 2026

Copy link
Copy Markdown

Thanks for your this PR. 🙏
Please check again for your PR changes whether contains any usage/api/configuration change such as Add new API , Add new configuration, Change default value of configuration.
If so, please add or update documents(markdown type) in docs/next/ for repository nacos-group/nacos-group.github.io


感谢您提交的PR。 🙏
请再次查看您的PR内容,确认是否包含任何使用方式/API/配置参数的变更,如:新增API、新增配置参数、修改默认配置等操作。
如果是,请确保在提交之前,在仓库nacos-group/nacos-group.github.io中的docs/next/目录下添加或更新文档(markdown格式)。

Run the SYNCING migration cases only in the dedicated AUTO restart phase so the default CANONICAL OpenAPI matrix does not execute incompatible migration assertions.

Assisted-by: Claude Code
Run dual-layout Runtime assertions only in the dedicated AUTO/SYNCING server phase so the default CANONICAL Java SDK matrix remains transport-neutral.

Assisted-by: Claude Code
@KomachiSion
KomachiSion merged commit 05e789e into alibaba:develop Sep 3, 2026
7 checks passed
@KomachiSion KomachiSion added this to the 3.3.0 milestone Sep 3, 2026
@KomachiSion
KomachiSion deleted the codex/rad-a2a-upgrade-migration branch September 3, 2026 08:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants