alibaba/nacos 3.3.0-RC on GitHub

Nacos 3.3.0-RC is a release candidate for the Nacos 3.3 feature iteration. It builds on 3.3.0-BETA with expanded AI Registry capabilities, DNS service discovery, and further security and compatibility improvements.

This release focuses on:

Protocol-neutral Agent management and RAD discovery, including transport negotiation and Watch/Push.
Shared AI resource search and unified MCP lifecycle management.
DNS-based service discovery and Config SDK improvements.
Authentication enabled by default, migration safeguards, and runtime stability.

The main feature updates include:

Agent registration, endpoint publication, discovery, Java SDKs, and Console management, with a migration path for historical A2A data.
Search and discovery across Agent, AgentSpec, Skill, Prompt, and MCP resources, including shared indexes and artifact retrieval.
MCP draft, review, publish, online/offline, and visibility management while retaining existing serving contracts.
Optional DNS A-record queries over UDP and TCP.

The release also retains BETA's dynamic plugin management, distributed locks, Jackson 2/3 support, and Spring Boot 4 compatibility. It includes further fixes across Config, Naming, Console, clients, AI storage, and authorization.

These notes are cumulative for 3.3.0 and include the changes documented in 3.3.0-BETA.

Detailed changes in this release:

Feature

#50 Add optional DNS service discovery with A-record queries over UDP and TCP.
#14466 Add a neutral JSON adapter with Jackson 2 and Jackson 3 runtime support.
#14804 Add protocol-neutral Agent lifecycle management, Console workflows, RAD discovery, runtime endpoints, transport negotiation, Watch/Push, and Java SDKs.
#15279 Add distributed reentrant and non-reentrant locks with watchdog renewal, FIFO waiting, gRPC notifications, Raft consistency, and a Java Lock SDK.
#15471 Support SkillSpector as an AI publish pipeline.
#15475 Add unified dynamic plugin configuration, lifecycle management, runtime updates, deterministic discovery, and Console configuration workflows.
#15476 #15604 Add plugin-owned visibility grant and revoke APIs and Console management for Skill and AgentSpec resources.
#15541 Add Agentic Resource Discovery with search, exploration, artifact retrieval, visibility filtering, persistent indexes, and hybrid keyword and vector retrieval.
#15640 Support Nacos server deployments on Linux RISC-V with RocksDB.
#15761 Add shared MCP lifecycle management with drafts, review, publish, online/offline operations, visibility, Java SDKs, and historical reconciliation while preserving existing Config/Naming serving data.

Enhancement/Refactor

#8354 Replace the mandatory Prometheus client dependency with a pluggable client metrics SPI and a no-op default.
#12064 Support configuring the gRPC port offset through individual client properties.
#12734 Add request/result-based Config SDK methods, encrypted Config CAS publishing, and conditional queries with local cache reuse.
#13690 Log the resolved client logging configuration and include namespace IDs in subscription logs.
#14804 Improve Agent detail, draft creation, version history, and legacy A2A Console workflows.
#14817 Disable selected deprecated Pipeline and MCP import APIs by default and provide a shared temporary compatibility switch.
#14932 Reduce read-path contention and improve index consistency in the legacy MCP cache.
#14980 Support deregistering persistent Naming instances from Console v3.
#15315 #15561 Improve Skill upload precheck, conflict handling, and server-side ZIP validation.
#15322 Remove obsolete Config migration compatibility code and retain only the current Config storage model.
#15346 Manage the reserved latest label for AI resources on the server.
#15357 Enable Client API authentication by default and validate standard integration scenarios with authentication enabled.
#15432 #15440 #15441 Remove reviewed unused Java code while preserving required compatibility contracts.
#15448 Improve English translations in Console UI Next.
#15486 Include the Skill owner in upload permission-denied messages.
#15606 Return a stable per-item result for every Skill batch upload candidate.
#15661 Restrict distributed embedded database query results to supported scalar types and registered row mappers.
#15678 Decouple the visibility plugin SPI from server runtime modules.
#15686 #15692 Align authorization method resolution with Spring MVC routing and expand controller-level authorization regression coverage.
#15687 Authenticate native JRaft gRPC requests with server identity and a rolling-upgrade enforcement transition.
#15695 Improve Config detail, edit, and history page layouts with larger content areas and full-screen reading.
#15720 Automatically publish the first uploaded Skill version.
#15746 Add operator-controlled outbound access policies for MCP tool imports.
#15838 Clarify that rolling back the first inserted Config history record deletes the configuration.
#15854 Remove untagged legacy Raft request parsing and preserve explicit errors for malformed log entries.

BugFix

#11122 Accept healthCheckEnabled as a health-check switch entry while retaining the legacy check alias.
#11890 Avoid removing metadata for instances that still exist after restart.
#12557 Retry Config dump write-lock acquisition to prevent stale MD5 cache data.
#14008 Fix native-image metadata required to establish gRPC client connections.
#14804 Keep AI search available with partial results while indexes are being backfilled.
#14981 #15468 Fix concurrent Config publish duplicate-key handling through the datasource dialect SPI, including PostgreSQL unique_violation.
#15410 Fix trailing separators when joining collections containing null elements.
#15415 Prevent malformed config-plugin property names from discarding valid plugin configuration.
#15420 Fix Skill ZIP uploads with invalid or unavailable version candidates.
#15425 Prevent out-of-range batch indexes from causing IndexOutOfBoundsException.
#15446 Fix page count calculation for empty and exactly divisible result sets.
#15447 Prevent NamingUtils.getServiceName from failing on a trailing service separator.
#15466 Correct @Since annotations for Skill upload APIs.
#15470 Prevent Naming connection cleanup from waiting for unrelated distributed-lock Raft writes.
#15475 Fix standalone Console auth plugin initialization and forward the caller identity to downstream Server requests.
#15476 Enforce Prompt visibility on list, detail, version, download, and Client read APIs.
#15477 Wait for persistent service metadata before starting health checks.
#15490 Fix Chinese text corruption in Skill Scanner pipeline reports on Windows.
#15494 Restore complete MCP tool advanced-template support in Console UI Next.
#15510 Reject explicitly supplied invalid Bearer tokens instead of falling back to anonymous access.
#15534 Generate deterministic, ASCII-safe physical Config keys for AI resources.
#15543 Restore case-sensitive collation for newly initialized MySQL Config schemas.
#15557 Fix startup failures when plugin state snapshots are restored before unified plugin discovery.
#15560 Preserve MCP tool passthrough authentication when editing and publishing runtime templates.
#15603 Fix visibility query conversion when explicitly authorized resources are present.
#15618 Try lower-priority explicit Skill upload versions before generating a version.
#15620 Allow AI resource versions to be resubmitted after completed or stale review results.
#15625 Fix gray Config cache null access and cross-thread visibility in Config disk services and client connections.
#15634 Fix API authorization metadata, custom resource parser precedence, AgentSpec authorization, and Prometheus security path matching.
#15642 Make AI resource deletion cleanup-first and retryable across all stored versions.
#15658 Keep AI resource reads, updates, and deletion bound to the persisted storage provider.
#15660 Fix standalone Console startup when the Config clone source-permission checker is unavailable.
#15663 Preserve case-sensitive AI resource identities in MySQL search and task tables.
#15675 Preserve nullable MCP tool output schemas during editing, display, and OpenAPI import.
#15682 Prevent login responses from disclosing whether a username exists.
#15689 Preserve string serialization of Config storage IDs with Jackson 3 to avoid numeric precision loss.
#15701 Fix Config history next-record queries on Derby and preserve gray-version filtering.
#15703 Migrate the legacy skills.sh importer state key without overriding canonical configuration.
#15705 Clean removed Skill and AgentSpec draft files while retaining retry metadata after storage failures.
#15710 Declare the required SQL LIKE escape clause for Derby, Oracle, and other affected dialects.
#15712 #15827 Reject unsafe instance addresses, HTTP targets, headers, and MySQL connection options in active health checks.
#15714 Handle encoded context paths consistently in the legacy controller-method resolver.
#15718 Escape all LIKE predicates when searching embedded roles with username filters.
#15724 Forward the namespace when querying Config listeners by IP across cluster members.
#15744 Align bootstrap and distribution configuration defaults.
#15763 Reject invalid IPv6 mixed addresses with too many explicit address blocks.
#15803 Reject unsafe AgentSpec and Skill ZIP layouts and enforce entry-count and decompression limits.
#15804 Reject unsafe filesystem paths before Config, archive, and local rule-storage operations.
#15821 Increase the embedded Derby connection timeout to prevent initialization failures on slow storage.
#15844 Use the correct default gRPC protocol negotiator type.
#15847 Restore public defaults for newly created Agent and MCP resources and preserve existing visibility scopes.
#15850 #15851 Select the default JDBC driver from the datasource dialect and clarify non-MySQL configuration examples.
#15853 Return schema metadata in current, historical, and previous-version Config details.
#15864 Resolve HEAD requests through their GET mapping in the legacy controller-method cache.
#15866 Remove server-list event subscriptions on client shutdown and prevent callbacks from accessing a closed server-list provider.

Dependencies

#14944 Upgrade Spring Boot from 3.5.14 to 4.0.6.
#15470 Upgrade SOFA JRaft to 1.4.1 while preserving callback cache behavior and JRaft authentication.
#15584 Upgrade Maven Compiler Plugin from 3.5.1 to 3.15.0 for JDK 25 build compatibility.
#15645 #15834 Upgrade compatible legacy and next Console dependencies, patch the sanitizer bundled with Monaco, and refresh packaged frontend assets.
#15707 Upgrade Log4j API from 2.25.4 to 2.25.5.
#15767 Upgrade gRPC to 1.81.0 to address CVE-2026-33871.

Breaking Change Notice

Nacos 3.3.0-RC changes authentication defaults, disables selected deprecated APIs, and introduces migration and compatibility boundaries that require attention before upgrading.

Affected users:

Applications that connect without credentials and rely on the previous Client API authentication default.
Integrations using deprecated Pipeline or Console MCP import endpoints.
Deployments with legacy Config data, unsafe historical AI Config keys, or untagged Raft logs.
Clusters migrating historical A2A or MCP resources, or planning a downgrade after migration or JRaft authentication enforcement.
Applications relying on built-in Prometheus client metrics, private-network MCP tool imports, or implicit Agent/MCP visibility defaults.

Recommended upgrade path:

Prepare Client API credentials. An absent nacos.core.auth.enabled now means true. Existing explicit false settings remain effective. If credentials are not ready, explicitly retain false during migration, provision identities and permissions, verify client access, and then enable authentication consistently on every member. Admin and Console authentication defaults are unchanged.
Migrate deprecated AI API calls. The deprecated Pipeline base-path list and path-variable detail endpoints, and the old Console MCP import endpoints, return HTTP 410 with API_DEPRECATED by default. Use Pipeline /list and /detail endpoints and the unified /v3/console/ai/import/validate and /execute endpoints. nacos.core.api.compatibility.enabled=true temporarily reopens the selected endpoints; the old nacos.ai.resource.import.legacy-mcp-api-enabled property is no longer recognized.
Complete legacy Config migrations. Upgrade pre-3.0 deployments through an earlier Nacos 3.x version. Migrate default-namespace data from the empty tenant to public, and legacy beta/tag data from config_info_beta and config_info_tag to config_info_gray. For the nacos_config AI storage provider, explicitly migrate affected historical non-ASCII or overlength Config coordinates to the deterministic ASCII-safe mapping.
Check persisted Raft logs. Nacos 3.3 no longer replays untagged entries, including entries originally written by Nacos 2.0.x and retained across intermediate upgrades. Complete recovery and snapshot/log migration with a version that can read those entries before upgrading. Changing the running version alone does not convert persisted logs.
Plan historical A2A migration explicitly. The default nacos.ai.a2a.compatibility.mode=CANONICAL does not scan historical data. For historical 3.0–3.2 A2A data, follow the migration runbook and configure new members with AUTO and a consistent migration policy. Early 3.3 AUTO deployments require the runbook's separate preflight. After permanent canonical cutover, a legacy-only server must not rejoin. MCP reconciliation also has a one-way managed-lifecycle transition; preserve its migration state and existing Config/Naming serving data.
Keep cluster server identities consistent. Native JRaft authentication becomes enforced once all members advertise support, and enforcement persists across restarts. A rolling downgrade to members without JRaft credential support is not guaranteed to remain available.
Install a client metrics provider when needed. The mandatory Prometheus dependency has been removed from nacos-client. Without an implementation of NacosClientMetricsProvider, client metrics recording is a no-op, even when enableClientMetrics is enabled.
Review MCP import access policy. Public MCP import targets remain available by default. Private or local targets must be explicitly allowed with nacos.console.ai.mcp.import.allowed-private-addresses; HTTP redirects are not followed.
Set private resource scopes explicitly. The built-in visibility plugin defaults new Agent and MCP resources to PUBLIC. Existing stored scopes and Prompt/Skill defaults are unchanged. Set the intended private scope for resources that should not be discoverable by other users.
Back up and rehearse the upgrade. Back up the database and relevant persisted data, then verify authentication, historical resource migration, discovery, and client behavior in staging before upgrading to Nacos 3.3.0-RC.

Deployments without the affected historical data do not require the data migrations above; the new authentication defaults and applicable API changes still need review.

Java Version Requirements

Module	Java Required
Nacos-Server / Nacos-Console	Java 17
Nacos-Client	Java 8
Nacos-Maintainer-Client	Java 8

New Contributors

@Ayanami-Shinji made their first contribution in #15286
@Zhengcy05 made their first contribution in #15318
@a981008 made their first contribution in #15280
@thegoldenflow made their first contribution in #15348
@hutiefang76 made their first contribution in #15413
@vasiliy-mikhailov made their first contribution in #15415
@Funzhou000 made their first contribution in #15448
@cl421866707 made their first contribution in #15491
@sweat123 made their first contribution in #15502
@fudianchn made their first contribution in #15646
@cyforkk made their first contribution in #15631
@GerardGao made their first contribution in #15764
@lavyoung made their first contribution in #15771
@neoLsH made their first contribution in #15792
@TianHengZhuang made their first contribution in #15822
@ABin-Huang made their first contribution in #15817
@Ashfaqbs made their first contribution in #15849

Full Changelog: 3.2.2...3.3.0-RC