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:

2. Upgrade Steps

2.1. Pre-upgrade Checks

Complete these preparations before upgrading a production cluster:

1. Confirm that the source cluster runs a supported 3.0.x, 3.1.x, or 3.2.x release, and record the exact patch version, deployment mode, and database type. If the source version predates 3.2.x or its actual schema does not contain every 3.2.x change, list the database operations that must be applied from the 3.2.x upgrade guide.
2. Back up the database and each node’s data, conf, cluster.conf, custom plugins, and their configuration. Every deployment must retain plugin state and runtime configuration under data/plugin. With Derby or another embedded store, data also contains the primary database and must be preserved in full.
3. Inventory plugin JARs, implementation names, states, selection properties, and private configuration. Distinguish built-in plugins from custom and third-party plugins.
4. Rehearse database changes, authentication, plugin loading, rolling upgrade, and rollback in staging with a production-like data copy.
5. Avoid plugin runtime configuration changes during the upgrade. Submit configuration that depends on 3.3 plugin definitions only after every node has been upgraded.

2.1.1. Verify Historical Config Migration Is Complete

Nacos 3.3 removes the pre-3.0 Config storage migration compatibility. It no longer migrates or double-writes between the legacy empty tenant (tenant_id = '') and the default namespace public, and it no longer migrates rows from config_info_beta or config_info_tag to config_info_gray.

Before stopping the last source-version node:

1. Check for default-namespace configuration rows with tenant_id = ''. If any exist, verify that they have been migrated to tenant_id = 'public', resolving rows with the same data_id and group_id first.
2. Check whether business data still depends on config_info_beta or config_info_tag. If so, complete its migration to config_info_gray and the current GrayRule model before upgrading to 3.3.x.
3. Verify default-namespace reads, formal publishing, beta/tag gray queries, and stopping gray releases.

No corresponding data migration is needed if the deployment never used the default namespace or beta/tag gray release. If the migration format is uncertain, keep the source cluster available while completing and verifying the migration; do not expect 3.3 startup to perform it.

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.

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.

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 identity, state, implementation selection, and private configuration. Use the target distribution’s conf/application.properties as the migration template instead of overwriting it with the source-version file. See System Configurations for commonly used parameters and Plugin Migration Guide for migration semantics. The target distribution template remains the final parameter baseline for that release.

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 alias are both present, the canonical property wins. An empty canonical value still suppresses the alias. The target template already contains nacos.plugin.auth.type=nacos and canonical defaults for auth:nacos. Explicitly copy retained values to canonical properties instead of keeping old and new properties side by side. The startup script specially migrates only a valid legacy token secret in application.properties; migrate all other auth values explicitly. 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.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. Post-upgrade Verification and Rollback Preparation

At minimum, verify the following after the upgrade:

1. Node versions, cluster membership, and health are correct, with no schema, plugin-loading, or configuration-alias errors in the logs.
2. Config publish/query, service register/discover, Console login, Client API, and Admin API authentication match the pre-upgrade settings.
3. Deployments that used the default namespace or gray release recheck the paths listed in section 2.1.1.
4. Plugin management reports the expected plugin IDs, states, configuration sources, and restart-required fields, with no implementation enabled unexpectedly.
5. When ARD is enabled, all three relational tables exist and index tasks converge. When the PostgreSQL vector plugin is enabled, also verify the pgvector schema and datasource connectivity.

Keep the old distribution, configuration, plugin JARs, and database backup until the observation period ends. Before rollback, remove runtime plugin overrides understood only by 3.3. Roll back AI Resource Import plugin JARs, configuration, and callers together. Do not reverse new tables or widened columns during an emergency rollback; use the database rollback procedure validated before rollout.