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. Distribution Upgrade

2.1.1 Verify Database Schema

Compare the schema file of your currently deployed Nacos version with the schema file for the target version and target database.

If there are schema changes, apply the database alterations first. MySQL example:

-- When upgrading from 2.0.X, execute all SQL statements below. When upgrading from versions later than 2.1.X, execute only the last three lines.
ALTER TABLE `config_info` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT 'secret key';
ALTER TABLE `config_info_gray` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT 'secret key';
ALTER TABLE `his_config_info` ADD COLUMN `encrypted_data_key` varchar(1024) NOT NULL DEFAULT '' COMMENT 'secret key';
ALTER TABLE `his_config_info` ADD COLUMN `publish_type` varchar(50)  DEFAULT 'formal' COMMENT 'publish type gray or formal';
ALTER TABLE `his_config_info` ADD COLUMN `gray_name` varchar(50)  DEFAULT NULL COMMENT 'gray name';
ALTER TABLE `his_config_info` ADD COLUMN `ext_info`  longtext DEFAULT NULL COMMENT 'ext info';

Version 3.2.0 introduces new AI-related tables. The following tables must be created when upgrading to 3.3.X from any previous version:

CREATE TABLE IF NOT EXISTS `pipeline_execution` (
    `execution_id`  varchar(64)  NOT NULL COMMENT 'execution ID',
    `resource_type` varchar(32)  NOT NULL COMMENT 'resource type',
    `resource_name` varchar(256) NOT NULL COMMENT 'resource name',
    `namespace_id`  varchar(128) DEFAULT NULL COMMENT 'namespace ID',
    `version`       varchar(64)  DEFAULT NULL COMMENT 'version',
    `status`        varchar(32)  NOT NULL COMMENT 'execution status',
    `pipeline`      longtext     NOT NULL COMMENT 'pipeline node result JSON',
    `create_time`   bigint(20)   NOT NULL COMMENT 'creation time',
    `update_time`   bigint(20)   NOT NULL COMMENT 'update time',
    PRIMARY KEY (`execution_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI resource publish review pipeline execution record';

CREATE TABLE IF NOT EXISTS `ai_resource` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id',
    `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'creation time',
    `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'modification time',
    `name` varchar(256) NOT NULL COMMENT 'resource name',
    `type` varchar(32) NOT NULL COMMENT 'resource type',
    `c_desc` varchar(2048) DEFAULT NULL COMMENT 'resource description',
    `status` varchar(32) DEFAULT NULL COMMENT 'resource status',
    `namespace_id` varchar(128) NOT NULL DEFAULT '' COMMENT 'namespace ID',
    `biz_tags` varchar(1024) DEFAULT NULL COMMENT 'business tags',
    `ext` longtext DEFAULT NULL COMMENT 'extension information (JSON)',
    `c_from` varchar(256) NOT NULL DEFAULT 'local' COMMENT 'source identifier (import/sync source)',
    `version_info` longtext DEFAULT NULL COMMENT 'version information (JSON)',
    `meta_version` bigint(20) NOT NULL DEFAULT 1 COMMENT 'metadata version (optimistic lock)',
    `scope` varchar(16) NOT NULL DEFAULT 'PRIVATE' COMMENT 'visibility: PUBLIC/PRIVATE',
    `owner` varchar(128) NOT NULL DEFAULT '' COMMENT 'creator username',
    `download_count` bigint(20) NOT NULL DEFAULT 0 COMMENT 'download count',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_ai_resource_ns_name_type` (`namespace_id`,`name`,`type`,`c_from`),
    KEY `idx_ai_resource_name` (`name`),
    KEY `idx_ai_resource_type` (`type`),
    KEY `idx_ai_resource_gmt_modified` (`gmt_modified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI resource metadata table';

CREATE TABLE IF NOT EXISTS `ai_resource_version` (
    `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT 'id',
    `gmt_create` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'creation time',
    `gmt_modified` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT 'modification time',
    `type` varchar(32) NOT NULL COMMENT 'resource type',
    `author` varchar(128) DEFAULT NULL COMMENT 'author',
    `name` varchar(256) NOT NULL COMMENT 'resource name',
    `c_desc` varchar(2048) DEFAULT NULL COMMENT 'version description',
    `status` varchar(32) NOT NULL COMMENT 'version status',
    `version` varchar(64) NOT NULL COMMENT 'version number',
    `namespace_id` varchar(128) NOT NULL DEFAULT '' COMMENT 'namespace ID',
    `storage` longtext DEFAULT NULL COMMENT 'storage information (JSON)',
    `publish_pipeline_info` longtext DEFAULT NULL COMMENT 'publish pipeline information (JSON)',
    `download_count` bigint(20) NOT NULL DEFAULT 0 COMMENT 'download count',
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_ai_resource_ver_ns_name_type_ver` (`namespace_id`,`name`,`type`,`version`),
    KEY `idx_ai_resource_ver_name` (`name`),
    KEY `idx_ai_resource_ver_status` (`status`),
    KEY `idx_ai_resource_ver_gmt_modified` (`gmt_modified`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='AI resource version table';

If you use PostgreSQL and upgrade from 3.2.1 or earlier to 3.2.2, check whether tenant_id in the config-related tables is already NOT NULL DEFAULT '' before the upgrade. Nacos 3.2.2 validates the PostgreSQL schema during startup. If older tables still allow tenant_id to be null, the server may fail to start. See alibaba/nacos#15275 for the related discussion.

Before running the migration, check whether config_info contains duplicate logical config rows. If multiple rows with the same data_id and group_id have tenant_id IS NULL, clean the conflict first, then run the migration SQL.

SELECT data_id, group_id, COUNT(*)
FROM config_info
WHERE tenant_id IS NULL
GROUP BY data_id, group_id
HAVING COUNT(*) > 1;

After confirming there is no conflict, run pg-upgrade-null-tenant-id.sql from the target Nacos source. The SQL is:

ALTER TABLE config_info ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE config_info SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE config_info ALTER COLUMN tenant_id SET NOT NULL;

ALTER TABLE config_info_gray ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE config_info_gray SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE config_info_gray ALTER COLUMN tenant_id SET NOT NULL;

ALTER TABLE config_tags_relation ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE config_tags_relation SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE config_tags_relation ALTER COLUMN tenant_id SET NOT NULL;

ALTER TABLE his_config_info ALTER COLUMN tenant_id SET DEFAULT '';
UPDATE his_config_info SET tenant_id = '' WHERE tenant_id IS NULL;
ALTER TABLE his_config_info ALTER COLUMN tenant_id SET NOT NULL;

2.1.2. Download the New Version

2.1.3. Replace the Binary JAR

Extract the newly downloaded distribution package:

  unzip nacos-server-$version.zip
  # or tar -xvf nacos-server-$version.tar.gz

Then locate nacos/target/nacos-server.jar and replace the JAR in the old distribution. For example:

cp nacos/target/nacos-server.jar ${old.nacos.home}/target/

2.1.4. Update Configuration Files

Nacos 3.0.X has significant configuration changes compared to Nacos 2.X, including many new server and console related settings, as well as parameter reordering. Please carefully compare the configuration files between the new and old versions and reconfigure accordingly.

Key parameter changes:

server.port —> nacos.server.main.port

server.servlet.contextPath —> nacos.server.contextPath

2.1.5. Update Startup Parameters (Optional)

Compare the startup scripts (bin/startup.sh or bin/startup.cmd) between the old and new versions to check for new or modified parameters, and apply them to the old startup scripts. For example:

diff nacos/bin/startup.sh ${old.nacos.home}/bin/startup.sh

2.1.6. Restart Nacos Server

After all replacements are complete, restart Nacos Server:

# Cluster mode example
## Linux
${nacos.home}/bin/shutdown.sh
${nacos.home}/bin/startup.sh

## Windows
${nacos.home}/bin/shutdown.cmd
${nacos.home}/bin/startup.cmd

2.1.7. Config Compatibility Migration Removal (Nacos 3.3.0+)

This removal only affects historical storage migration compatibility. It does not change current Config semantics:

• Blank or omitted namespace requests are still normalized to the default namespace. The current default namespace ID is public.
• Current beta/tag gray release APIs remain available and are backed by the config_info_gray and GrayRule model.

When upgrading from versions before 3.0 to 3.3.x, if the old deployment did not use the default namespace and did not use beta gray release, this compatibility removal does not affect smooth upgrade for this compatibility area. If the old deployment used the default namespace or beta gray release, a fully smooth upgrade is no longer guaranteed. Operators must migrate and verify the affected data before upgrading to 3.3.x.

Affected deployments must complete at least these actions:

1. Check whether the old database has default-namespace config data with tenant_id = ''.
2. Before upgrading to 3.3.x, migrate default-namespace data from the empty tenant to tenant_id = 'public'. If rows with the same data_id and group_id exist under both the empty tenant and public, decide which business data to keep before migrating to avoid conflicts.
3. Check whether the old database has gray data in config_info_beta or config_info_tag.
4. Before upgrading to 3.3.x, migrate legacy beta/tag gray data into the current config_info_gray model and store the corresponding grayName and GrayRule metadata according to the current gray rule model.
5. After migration, use current clients or APIs to verify default-namespace config reads, formal publish, beta gray query, tag gray query, and stopping gray release.

If you cannot directly confirm the migration format in your own tooling, you can first upgrade to a 3.0.x-3.2.x version that still contains this compatibility migration capability, complete the migration, run stably, verify the data, and then upgrade to 3.3.x.

2.1.8. Migrate MCP Services (Optional)

If you are upgrading from version 3.0.0 and your cluster has MCP services, note that due to changes in the official MCP Registry API standard, the MCP Server metadata structure has changed. This incompatibility means that after upgrading from 3.0.0 to 3.0.1 or later, the console will be unable to read legacy MCP Server data. You need to use the MCP Migration Tool to migrate the existing MCP service data from version 3.0.0.

# java -jar ./mcp-migration-tool.jar ${nacos-server-host}:${nacos-server-port} ${username} ${password}
# Example
java -jar ./mcp-migration-tool.jar localhost:8848 nacos ${your_password}

2.2. Docker/Kubernetes Upgrade

2.2.1 Verify Database Schema

Please refer to 2.1.1 Verify Database Schema to compare and apply database schema changes.

2.2.2. Verify Environment Variables

Compare the environment variables of your current deployment with System Parameters - Image Environment Variables to check for changes. If there are any, update the Docker environment variable file or Kubernetes configmap/secret accordingly.

For example, add the following environment variables:

NACOS_AUTH_TOKEN=${Base64-encoded token from a custom string of 32+ characters}
NACOS_AUTH_IDENTITY_KEY=${any string}
NACOS_AUTH_IDENTITY_VALUE=${any string}

2.2.3. Update Image Version

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

docker-compose pull
docker-compose up -d --remove-orphans

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

3. Legacy HTTP API Removal (Nacos 3.2.0+)

3.1 API Removal Notice

The old v1 and v2 HTTP APIs are no longer included in the default Nacos server distribution. These APIs have been migrated to a separate legacy adapter module.

Affected APIs:

• All v1 REST APIs (e.g., /nacos/v1/ns/instance, /nacos/v1/cs/configs)
• All v2 REST APIs

3.2 Migration Options

You have two options:

Option 1: Migrate to New APIs and Clients (Recommended)

• Use the new v3 APIs
  • v3 Admin API Documentation
  • v3 Console API Documentation
• Upgrade to the latest Nacos client SDK
  • Nacos Client Documentation

Option 2: Use Legacy API Adapter (Temporary Solution)

If you need time to migrate, you can temporarily restore the old APIs using the legacy adapter.

3.3 Installing the Legacy API Adapter

Step 1: Build or Download the Adapter

Option A: Download from Release

# Download from GitHub releases
wget https://github.com/nacos-group/nacos-api-legacy-adapter/releases/download/v${version}/nacos-api-legacy-adapter-${version}.jar

Option B: Build from Source

git clone https://github.com/nacos-group/nacos-api-legacy-adapter.git
cd nacos-api-legacy-adapter
mvn clean install
# Output: target/nacos-api-legacy-adapter-${version}.jar

Requirements:

• JDK 17+
• Maven 3.6+
• The nacos.version in pom.xml must match the target Nacos server version

Step 2: Install the Adapter

For Nacos Server Deployment:

1. Place the JAR file in the Nacos plugins directory:

cp nacos-api-legacy-adapter-${version}.jar ${NACOS_HOME}/plugins/

2. Restart Nacos server:

sh ${NACOS_HOME}/bin/shutdown.sh
sh ${NACOS_HOME}/bin/startup.sh -m standalone  # Standalone mode
# or
sh ${NACOS_HOME}/bin/startup.sh                # Cluster mode

3. The adapter will automatically load when the JAR is in the classpath.

For Embedded/Custom Applications:

Add the Maven dependency:

<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-api-legacy-adapter</artifactId>
    <version>${nacos.version}</version>
</dependency>

Step 3: Verify Installation

Check Nacos server logs for confirmation:

tail -f ${NACOS_HOME}/logs/nacos.log

Look for log messages indicating the legacy adapter has loaded.

Step 4: Test Legacy APIs

Test that your old v1/v2 API calls work again:

curl -X GET "http://localhost:8848/nacos/v1/ns/instance/list?serviceName=test"

3.4 Version Compatibility

Important: The adapter version must match your Nacos server version.

3.5 Planning Your Migration

While using the legacy adapter, plan your migration:

1. Audit your API usage - Identify all v1/v2 API calls
2. Review new v3 APIs - Understand the new API structure
3. Update clients - Upgrade to latest Nacos client SDKs
4. Test thoroughly - Test in staging environment
5. Migrate gradually - Use feature flags or canary deployments
6. Remove adapter - Once migration is complete, remove the adapter JAR

3.6 Getting Help

• Legacy Adapter Repository: https://github.com/nacos-group/nacos-api-legacy-adapter
• Nacos Main Repository: https://github.com/alibaba/nacos
• Community Support: Nacos Community