Alibaba Cloud Elasticsearch supports three management architectures: Basic Management (v1), Basic Management (v2), and Cloud-native Management (v3). The v3 architecture delivers improvements to feature iteration, system stability, and security. This guide walks you through upgrading a v1 or v2 instance to v3 using the online migration tool.
For an automated alternative, see Automatic upgrade.
Two stages of the migration process — master node migration and primary shard migration — cannot be rolled back once started. Before you begin, understand which operations can be rolled back and plan your maintenance window accordingly.
Prerequisites
Before you begin, make sure you have:
-
A v1 or v2 Elasticsearch instance running a supported version
-
Access to the online migration tool (contact technical support to request access)
-
Completed all business preparations — all instance change operations are blocked during the upgrade
Limitations
Version requirements
| Source version | Upgrade support | Target version | Additional requirements |
|---|---|---|---|
| 6.7, 6.8, 7.10, or 7.16 | Supported | Same as source | For 6.7 and 6.8: no indexes can be in the closed state |
| 6.3, 7.4, or 7.7 | Supported | 7.4 or 7.7 → 7.10; 6.3 → 6.8 | Indexes must have replicas; contact technical support to add the instance to a whitelist |
| 5.5 or 5.6 | Not supported | — | — |
Specification limits
The following instance specifications cannot be upgraded: 1-core 2 GB, 2-core 2 GB, 4-core 4 GB, 8-core 8 GB, 12-core 12 GB, or 16-core 16 GB.
Region limits
The v1 or v2 instance and the target v3 instance must be in the same region.
Feature limits
The upgrade is not supported if the source instance has any of the following features enabled:
-
Core features: Cross-cluster replication (CCR), inter-instance network connection, high availability (HA), application performance management (APM), or Logstash
-
Extended features: Scalability (such as auto-scaling) or Nginx reverse proxy
-
Storage: OpenStore (Advanced Edition) enabled, or local disks in use
-
X-Pack: Disabled
-
Zone: The primary zone is not supported by the v3 architecture
How the upgrade works
The upgrade uses a blue-green deployment during a scheduled period:
-
The system creates a destination v3 cluster alongside the source cluster.
-
Data is migrated in stages — replicas first, then the master node, then primary shards.
-
Network isolation cuts the source cluster off, and the destination cluster takes over.
Duration: Proportional to data volume; typically several hours. When upgrading from v1 to v3, the cluster restarts twice during the network isolation phase, which extends the total duration.
Downtime: The operations and maintenance (O&M) window you set causes a service interruption of approximately 1 to 2 seconds. No extra fees are incurred.
Node count during upgrade: The cluster topology temporarily shows double the number of nodes.
Rollback boundaries
The four data migration operations fall into two safety zones:
| Phase | Operations | Rollback |
|---|---|---|
| Safe zone | Cluster merge, replica migration | Supported — after a rollback, create a new upgrade task to retry |
| Point of no return | Master node migration, primary shard migration | Not supported under any circumstances |
Once master node migration starts, you cannot roll back — not for any reason. The same applies to primary shard migration. Confirm you are ready before allowing the process to advance past replica migration.
Upgrade your instance
Step 1: Create an upgrade task
-
Log on to the Alibaba Cloud Elasticsearch console.
-
In the left navigation pane, choose Elastic Stack Cloud Native PaaS > Online Migration Tool.
-
Click Create and configure the following parameters:
Parameter Description Type Select Architecture Upgrade for Alibaba Cloud Elasticsearch Cluster. Cluster Select the v1 or v2 instance to upgrade. -
Click OK.
Step 2: Run the upgrade
Feasibility check and cluster configuration
On the Configure Source and Destination Clusters tab:
Data migration
On the Migrate Data
| Operation | What happens | Rollback |
|---|---|---|
| Cluster merge | Source and destination clusters merge into one. Total nodes = source nodes + destination nodes. Kibana for the destination cluster is temporarily shut down; use the source cluster's Kibana until the service switch is complete. | Supported |
| Replica migration | Index replica shards move from source nodes to destination nodes. | Supported — after a rollback, create a new upgrade task to retry |
| Master node migration | The master node transfers from the source cluster to the destination cluster. For v7.x and later, the switch is automatic. For v5.x and v6.x, a new master is elected after network isolation. | Not supported — cannot be rolled back |
| Primary shard migration | Primary shards (raw data) move from source nodes to destination nodes. | Not supported — cannot be rolled back |
Network isolation
On the Service Switch tab, request network isolation. This action prevents source cluster nodes from rejoining the merged cluster. The source cluster stops serving traffic, and the destination v3 cluster takes over.
Step 3: Validate the migration
After network isolation completes, click Go to Instance List to view your new v3 instance.
Access the destination cluster from the Kibana console and run queries or write operations to confirm the cluster is working as expected.
The private Kibana endpoint is disabled after the upgrade. Enable it if needed.
Contact the Alibaba Cloud Elasticsearch support team if you encounter any issues during validation.
Automatic upgrade
The v3 architecture can also be upgraded automatically through the management platform — no action required on your part. This method supports upgrades from v1 or v2 to v3. Contact technical support to arrange the automatic upgrade.
Troubleshooting
If the feasibility check fails or the upgrade is blocked, use the following table to identify and resolve the issue:
| Issue | Cause | Resolution |
|---|---|---|
| Feasibility check fails | Source cluster is unhealthy or cluster usage is too high | Resolve cluster health issues and reduce usage before retrying |
| Upgrade not supported | X-Pack is disabled | Enable X-Pack on the source instance |
| Upgrade not supported | Instance specification is in the excluded list (1-core 2 GB, 2-core 2 GB, 4-core 4 GB, 8-core 8 GB, 12-core 12 GB, 16-core 16 GB) |
This upgrade path is not available for this specification |
| Upgrade not supported | A blocked feature is enabled (CCR, HA, APM, Logstash, Scalability/auto-scaling, Nginx, OpenStore, local disk) | Disable the feature before starting the upgrade |
| Upgrade not supported | Source version is 5.5 or 5.6 | These versions are not eligible for upgrade |
| Upgrade not supported | Primary zone is not supported by v3 | Contact technical support for guidance |
| Upgrade not supported | Instance and target are in different regions | Upgrades are only supported within the same region |
| Indexes in closed state | Source version is 6.7 or 6.8 | Open all closed indexes before starting the upgrade |
| Missing replicas | Source version is 6.3, 7.4, or 7.7 | Add replicas to all indexes before starting the upgrade |
What's next
-
View instance details to confirm your v3 instance is running correctly
-
Enable the private Kibana endpoint if your workflow depends on it