Upgrade Manual

1. Version Upgrade Compatibility

This document corresponds to Nacos 3.3.x. Upgrade compatibility for Nacos 3.3.x is as follows:

1.1 Client Compatibility

Compatibility between Nacos 3.x server and client versions is as follows:

Before upgrading the server, confirm that clients have valid identity credentials. Deployments using A2A must also complete the migration preparations in section 2.7.

2. Upgrade Steps

2.1. Pre-upgrade Checks

Complete these preparations before upgrading a production cluster:

1. Confirm that the source cluster version is supported and that the database schema meets the requirements of the target 3.3.x release. See section 2.2 for database checks and changes.
2. Back up the database, each node’s data, conf, and cluster.conf, and any custom plugins and configuration.
3. Rehearse the upgrade and rollback in staging with a copy of production data.
4. Inventory Client API callers and complete the auth migration in section 2.1.2. Do not wait for the first 3.3 node to start before distributing client credentials.
5. Verify every node’s Server identity as described in section 2.1.3 and review the rollback limitations in section 2.8.1.

2.1.1. Confirm the Upgrade Path from 2.x

Nacos 3.3 removes the Config compatibility migration and no longer supports a direct smooth upgrade from 2.x. Inventory two kinds of historical data before upgrading:

• Default-namespace Config data still stored with an empty tenant must be migrated to public.
• Gray Config data in legacy config_info_beta and config_info_tag tables must be migrated to the current config_info_gray model.

If either kind was used, or this cannot be confirmed, first upgrade to a 3.0.x–3.2.x release that supports the required migration. Complete it and verify default-namespace queries, gray rules, and the results received by gray clients before upgrading to 3.3.x. Skipping migration can make historical Config data unavailable or produce unexpected gray behavior. Even if the deployment already runs 3.x, confirm that any required migration actually completed; the running version alone is insufficient evidence.

This removal does not change current default namespace or beta/tag gray API semantics. Blank or omitted namespace requests still normalize to public. See Compatibility and Deprecation.

2.1.2. Prepare Client Authentication

Nacos 3.3 enables client authentication by default (nacos.core.auth.enabled=true). If clients lack valid identity credentials or permissions, Config queries, service registration, discovery, and other requests may be rejected after the upgrade, disrupting applications.

Choose an approach before upgrading:

• Clients are ready for authentication: confirm the server auth configuration and client credentials, then verify business operations such as Config queries, service registration, and discovery before upgrading.
• Clients cannot be updated yet: explicitly disable client authentication on every node to retain existing access. Enable it across the cluster after client credentials and permissions are ready.

During the temporary opt-out, restrict Nacos access to trusted networks and restore authentication after updating clients. These switches affect only client authentication; Admin and Console API authentication remains unchanged.

2.1.3. Check JRaft Authentication Between Nodes

Nacos 3.3 adds JRaft authentication between nodes. Old nodes remain compatible during the rolling upgrade. Authentication is enabled automatically once all nodes have upgraded and their support is confirmed; no manual activation is required.

Before upgrading, ensure that nacos.core.auth.server.identity.key and nacos.core.auth.server.identity.value are nonempty and identical on every node. Incorrect values can cause communication failures after the upgrade and disrupt cluster reads and writes; correct them before proceeding. These properties must remain valid even if client authentication is temporarily disabled.

See section 2.8.1 for rollback limitations after the upgrade.

2.2. Apply Database Changes

Before starting any 3.3.x node, first follow the 3.2.x Upgrade Guide to apply the database prerequisites needed to bring the current source schema up to the 3.2.x schema level; this does not require starting a 3.2.x server. Then compare the resulting actual schema with the complete matching schema in the target 3.3.x distribution and convert the remaining differences into reviewed incremental DDL. Never execute a complete initialization file containing CREATE TABLE or DROP TABLE statements directly against an existing database.

For PostgreSQL deployments upgrading directly from 3.0.x, 3.1.x, 3.2.0, or 3.2.1, or deployments that skipped the 3.2.2 schema normalization, first complete the tenant_id not-null migration documented in the 3.2.x Upgrade Guide.

The target distribution provides mysql-schema.sql, pg-schema.sql, oracle-schema.sql, and derby-schema.sql under conf. After applying the 3.2.x schema prerequisites, pay particular attention to these additional 3.3.x changes:

2.3. Migrate Configuration and Plugins

Nacos 3.3 unifies server plugin configuration. Most legacy configuration keys remain supported in 3.3, but may be removed in a future release. They do not all need to be replaced during this upgrade. Compare the current configuration with the target distribution’s conf/application.properties and migrate progressively to the new keys; avoid overwriting the target file with the source-version configuration file. See System Configurations for commonly used parameters and Plugin Migration Guide for migration guidance.

2.3.1. Default Auth Plugin

The default implementation remains nacos, but it is managed as auth:nacos in the unified plugin system. Its selector and private properties move to the canonical nacos.plugin.auth.* namespace.

nacos.core.auth.enabled, nacos.core.auth.admin.enabled, nacos.core.auth.console.enabled, and nacos.core.auth.server.identity.* remain core auth gates or server identity properties. Do not move them into a plugin-private namespace.

When a canonical property and a legacy property are both present, the canonical property wins. An empty canonical value still suppresses the legacy property. Most legacy properties remain readable in 3.3, but the target distribution may already provide defaults for their canonical replacements. When merging configuration, ensure that those defaults do not override the values in use. The startup script automatically handles only a valid legacy token secret in application.properties; other legacy keys are not rewritten automatically and can be migrated progressively by following log warnings. LDAP, OIDC, and custom auth deployments should also review the Auth Plugin page item by item.

If anonymous AI access is enabled, an explicit empty or invalid Authorization, accessToken, username, or password is rejected instead of falling back to anonymous access. Anonymous callers must omit credentials completely; authenticated callers must send valid credentials.

2.3.2. Other Plugin Configuration

Legacy properties may remain readable as aliases during the compatibility window and produce migration warnings, but a present canonical property has higher priority. Persisted implementation state also overrides static .enabled initial values. Dialect and exclusive implementation selectors, and every field marked RESTART, must be changed through static configuration followed by a restart, not through the plugin configuration API.

AI Resource Import now defaults to enabled when neither its canonical gate nor the legacy alias is configured. To keep it disabled after the upgrade, set this before rollout:

nacos.plugin.ai-resource-import.enabled=false

The legacy Importer/Source SPI, clonable Source/preset model, and configuration-based cloning of one importer to multiple endpoints have been removed. External implementations must migrate to AiResourceImportServiceBuilder. See AI Resource Import migration for the detailed mapping and built-in sources.

2.3.3. Custom and Third-party Plugins

• Record each implementation by its stable pluginType:pluginName, remove duplicate identities, and confirm that the target release discovers the intended JAR. Duplicate identities now resolve deterministically with the first implementation winning.
• Older zero-configuration plugins usually remain binary-loadable, but they appear configurable only after implementing PluginConfigSpec definitions, a current configuration snapshot, and apply callbacks.
• Older Config Change binaries remain loadable during the compatibility window but show configurable=false; migrate them to definitions and callbacks.
• AI Pipeline no longer loads PublishPipelineServiceBuilder. Recompile pipeline plugins, register PublishPipelineService directly with a public no-argument constructor, and implement the unified configuration contract.
• Third-party datasource plugins that implement or register the removed ConfigInfoBetaMapper, ConfigInfoTagMapper, or ConfigMigrateMapper SPIs must be rebuilt without those interfaces. Complete pre-3.0 data migration before upgrading.
• The legacy AI Resource Import SPI has no adapter. Recompile the plugin and update its configuration and callers together; do not mix the two models.
• Critical plugin types such as auth, datasource dialect, and AI storage can block startup when their selected implementation is missing, disabled, or fails initialization. Validate selection, state, and initialization in staging.
• On one node, verify plugin list/detail, effective sources, masking, and RESTART guidance. Do not submit runtime configuration understood only by 3.3 nodes during a rolling upgrade.

2.3.4. Migrate Deprecated AI APIs That Are Disabled by Default

The following deprecated v3 APIs are disabled by default. Migrate callers to their canonical replacements:

When disabled, they return HTTP 410 Gone with the API_DEPRECATED result code and identify the replacement API. If a migration window is required, temporarily set nacos.core.api.compatibility.enabled=true on nodes serving these endpoints, then restore the default false after migrating callers. This shared switch enables all endpoints in the table, with their existing authentication and authorization still enforced. It neither restores v1/v2 HTTP APIs nor controls the old A2A compatibility path in section 2.7.

The old nacos.ai.resource.import.legacy-mcp-api-enabled property is no longer recognized. Legacy MCP direct-URL import additionally requires explicit nacos.ai.resource.import.allow-user-url=true. Prefer managed sources and the new request model; changing only the URL while retaining all old parameters is insufficient. See AI Resource Import Migration.

2.4. Distribution Upgrade

2.4.1. Download the Target Version

2.4.2. Prepare a New Installation Directory

Extract the target distribution into a new directory:

unzip nacos-server-${target_version}.zip -d ${INSTALL_PARENT}
# or tar -xvf nacos-server-${target_version}.tar.gz -C ${INSTALL_PARENT}

The 3.3 distribution contains a coordinated server JAR, default plugins, schemas, startup scripts, and configuration templates. Do not replace only target/nacos-server.jar, and do not overwrite the new bin, conf, or complete plugins directory with files from the source version.

Migrate deployment-specific data as follows:

• Start from the new application.properties and move the properties verified in section 2.3 one by one.
• Compare and recreate cluster.conf, JVM options, log paths, certificates, and other deployment-specific files.
• Copy only custom or third-party plugin JARs that passed 3.3 compatibility verification.
• Every deployment must migrate or restore that node’s existing data/plugin so plugin-states.json and plugin-configs.json are retained. With Derby or embedded storage, migrate the complete data only after shutdown and a full backup. An external-database cluster must not blindly copy active Raft data between nodes; reuse that node’s own persistent volume or follow the rehearsed node-recovery procedure. Never let old and new processes use the same data directory concurrently.

2.4.3. Restart or Roll Through the Cluster

For a standalone deployment, stop the old instance and start with the new distribution scripts:

${OLD_NACOS_HOME}/bin/shutdown.sh
${NEW_NACOS_HOME}/bin/startup.sh -m standalone

For a cluster, upgrade one node at a time. Stop one source-version node, start it with its 3.3 configuration and the new distribution, and wait until it rejoins the cluster and core behavior is healthy before proceeding to the next node. Do not change unified plugin runtime state or configuration until all nodes run 3.3.

On Windows, use shutdown.cmd and startup.cmd from the new distribution rather than reusing the old scripts.

2.5. Docker/Kubernetes Upgrade

Container deployments must also complete the database, historical migration, and plugin checks in sections 2.1 through 2.3 before changing images. Compare the target image’s environment-variable conversion rules and the mounted application.properties; do not assume that every old environment variable maps to a canonical plugin property. See System Configurations - Startup Script and Image Variables.

services:
  nacos:
    image: nacos/nacos-server:${target_version}

docker compose pull
docker compose up -d --no-deps nacos

kubectl set image deployment/nacos-deployment \
  ${container_name}=nacos/nacos-server:${target_version}
kubectl rollout status deployment/nacos-deployment

2.6. Wait for Automatic MCP Data Migration

When upgrading a deployment with existing MCP Server data from Nacos 3.0.x–3.2.x, no manual data migration is required. Complete the server rollout and wait for background migration to finish. Existing MCP service addresses and client calling patterns remain unchanged.

2.6.1. Expected Behavior During the Upgrade

• Existing MCP management APIs remain available. New management APIs may temporarily return 409 / RESOURCE_CONFLICT; use the existing APIs while waiting for migration to finish.
• Migration completes after all nodes upgrade, historical data passes validation, and enabled search indexes are ready. Tasks retry approximately every 5 minutes by default, so several cycles may be needed.
• Normally keep nacos.ai.mcp.resource.reconciliation.enabled=true and retain the other migration defaults. See System Configurations.

2.6.2. Post-upgrade Checks

Confirm that all nodes are healthy and Server logs report migration completion. Verify MCP list/detail queries and the new management APIs.

2.6.3. Troubleshoot an Incomplete Migration

2.6.4. Rollback Considerations

After MCP migration completes, downgrading does not automatically reverse the new management data. Deployments using MCP must verify that the target version can handle that data before rollback.

2.7. Automatic Historical A2A Data Migration

This section applies to upgrades from Nacos 3.1.x–3.2.x that already use A2A Agent management or service registration through an old A2A SDK. Before upgrading, configure every target-version node as follows:

nacos.ai.a2a.compatibility.mode=AUTO
nacos.ai.a2a.migration.legacy-naming-shadow-enabled=false

The default CANONICAL mode does not migrate historical A2A data. Existing A2A deployments must explicitly use AUTO. Keep Agent Storage and migration configuration consistent across nodes, and do not change these settings after migration starts.

Ordinary A2A API/SDK callers can keep legacy-naming-shadow-enabled=false. Only applications that read old <legacyEncodedAgentName>::<exactVersion> service names directly through the Naming Gateway need to set it to true before migration; otherwise, discovery through those names may stop working after migration. Normally retain other migration defaults. See System Configurations.

2.7.1. Expected Behavior During the Upgrade

Until historical migration completes, external RAD search, discovery, publish, Endpoint registration, and subscription requests return 409 / AGENT_MIGRATION_IN_PROGRESS (50105); gRPC returns the same business error code. Retry requests or subscriptions after migration completes. Heartbeats for existing valid Endpoints, complete deregistration, and local subscription cancellation remain available.

Complete the server rollout and migration before upgrading clients that depend on RAD. A new SDK may use RAD even when calling A2A methods, so the same restrictions apply without automatic fallback to the old protocol.

2.7.2. Post-upgrade Checks

Confirm that every node is upgraded and healthy and that Server logs report migration completion. Check existing Agent names, versions, content, and service addresses, and verify both old A2A calls and RAD discovery.

2.7.3. Troubleshoot an Incomplete Migration

2.7.4. Rollback Considerations

Before migration completes, you can stop automatic migration by setting every node to LEGACY on the current version and performing a rolling restart. This does not roll back the server version.

After migration completes, returning to a version that understands only old A2A data is unsupported. If rollback is required, verify target-version compatibility and also follow the limitations in section 2.8.1.

2.8. Post-upgrade Verification and Rollback Preparation

Verify at least the following after upgrading:

1. Every node is upgraded and healthy, with no persistent communication, authentication, database, or plugin-loading errors in the logs.
2. Config publish/query, service registration/discovery, and Console login work. Clients with authentication enabled can access their resources. If authentication is temporarily disabled, confirm when it will be enabled.
3. Deployments upgraded from 2.x have working default-namespace Config data and existing gray rules.
4. Custom plugins load correctly, with the expected configuration and enabled state.
5. If AI resource search or vector search is used, indexes finish initializing and queries work.
6. If MCP or A2A is used, follow sections 2.6 and 2.7 to confirm migration completion, existing business calls, and new management features. Applications using old Naming Gateway service names must also verify discovery.
7. Callers of the old AI APIs in section 2.3.4 have migrated, or the temporary compatibility switch is configured.

Retain the pre-upgrade distribution, configuration, plugins, and data backups until the observation period ends.

2.8.1. Rollback Considerations

If a problem occurs during the upgrade, pause the remaining node upgrades and check node identity, database changes, and plugin configuration. Prefer correcting configuration and verifying recovery when that resolves the problem.

Once the upgrade completes and JRaft authentication activates, do not directly perform a rolling downgrade to an older version without that authentication support. Doing so can break communication between nodes and make the cluster unavailable. Disabling client authentication does not remove this limitation.

If rollback may be needed, verify the target version’s compatibility and rehearse it before upgrading. For an unverified rollback, preserve the current state and logs and contact maintainers to confirm the recovery approach.