Microservices Engine (MSE) provides a console-based migration tool that moves traffic from a self-managed NGINX Ingress gateway to an MSE Ingress gateway. The migration reuses your existing Ingress configurations rather than copying them -- the MSE cloud-native gateway listens to your Ingress resources in real time and parses them automatically.
This migration is designed to:
Enable incremental traffic shifting -- gradually move traffic by weight, with instant rollback
Allow parallel operation -- both NGINX Ingress Controller and the MSE gateway process Ingress changes simultaneously during migration
Require no configuration conversion -- existing Ingress resources continue to reference the NGINX Ingress class (for example,
ingressClassName: nginx)
Two traffic switching methods are available: reusing your existing Server Load Balancer (SLB) instance, or switching at the DNS level.
Prerequisites
Before you begin, make sure that you have:
A Container Service for Kubernetes (ACK) cluster, ACK Serverless cluster, or Container Compute Service (ACS) cluster with NGINX Ingress Controller deployed
An MSE cloud-native gateway (version 1.2.22 or later). If you do not have one, see Create a cloud-native gateway
The MSE cloud-native gateway and the cluster in the same Virtual Private Cloud (VPC)
How it works
During migration, both NGINX Ingress Controller and the MSE Ingress gateway process changes to your Ingress resources simultaneously. The MSE gateway does not replace your Ingress configurations -- it reads and applies the same ones. After migration, your Ingress resources must still reference the NGINX Ingress class (for example, ingressClassName: nginx).
Do not delete any NGINX Ingress configurations that are in use after migration completes. The MSE Ingress gateway depends on these existing configurations.
Show Details
Choose a traffic switching method
Two methods are available. The SLB reuse method is faster and simpler for most use cases:
| Method | Timeliness | Switching level | Weight-based switching | Complexity |
|---|---|---|---|---|
| Reuse original cluster SLB | Fast | SLB level | Supported | Easy |
| DNS resolution to SLB | Slow | Domain name level | Depends on DNS provider | Proportional to the number of domain names |
Reuse original cluster SLB
The MSE Ingress gateway joins the vServer group of the SLB instance associated with the NGINX Ingress Controller service. The SLB distributes traffic between NGINX Ingress and MSE based on weight. The original SLB instance stays unchanged throughout -- no DNS changes required.
DNS resolution to SLB
Add the IP address of the SLB instance associated with the MSE Ingress gateway to the DNS records for all affected domain names. Use weight-based DNS routing (if your DNS provider supports it) to gradually shift traffic.
Migration process
The MSE console guides you through five steps. The traffic switching method you chose in the previous section affects Steps 3 through 5.
Migrate routing rules -- The MSE gateway starts listening to your Ingress resources
Check routes -- Verify annotation compatibility
Select a traffic switching method -- Choose SLB reuse or DNS resolution
Switch traffic -- Gradually shift traffic from NGINX Ingress to MSE Ingress
Complete the migration -- Finalize and clean up
Step 1: Migrate routing rules
Log on to the MSE console. In the top navigation bar, select a region.
In the left-side navigation pane, choose Cloud-native Gateway > Migration to Cloud.
On the Migration to Cloud page, click Add Task.
In the Create Migration Configuration panel, configure the following parameters:
ImportantIf the destination gateway is already associated with the cluster and uses a different Ingress class, migration is blocked. The Ingress class configured here must match the one configured for the associated cluster.
Parameter Description Cloud-native Gateway The destination MSE cloud-native gateway. The gateway version must be 1.2.22 or later. ACK/ASK/ACS Cluster The cluster where NGINX Ingress Controller is deployed. The gateway and cluster must be in the same VPC. Source Ingress Class The Ingress class associated with the Ingress resources to migrate. Only one Ingress class is supported per task. If left blank, the gateway listens to all Ingress resources in the cluster. 
Click Next. The MSE cloud-native gateway automatically starts listening to all Ingress resources associated with the specified Ingress class. Domain names and routes from these Ingress resources are synchronized to the gateway.
Verify synchronization
Deploy an Ingress resource (for example, one named
httpbin) in the cluster.
In the MSE console, confirm that the Ingress resource is automatically synchronized and that the corresponding domain names and routes appear on the gateway.
Step 2: Check routes
Check whether all Ingress annotations are compatible with the MSE cloud-native gateway.
If all annotations are compatible, proceed to Step 3.
If any annotation is incompatible, submit a ticket for assistance.
The annotation
nginx.ingress.kubernetes.io/service-weightwith an empty value ("") can be safely ignored. The old ACK console adds this annotation by default, and it has no effect.Do not delete incompatible annotations that are currently in use. NGINX Ingress Controller still parses them and they affect your live traffic. Instead, add MSE extended annotations to achieve the same functionality on the MSE gateway. After all traffic has moved to MSE, remove the incompatible annotations.
Step 3: Select a traffic switching method
Test before switching
Before switching production traffic, verify traffic distribution locally:
Add the IP address of the SLB instance associated with the MSE cloud-native gateway to your local hosts file.
Use
curlor Postman to confirm that traffic distribution works as expected.
Configure the switching method
Reuse original cluster SLB
Configure the following parameters:
| Parameter | Description |
|---|---|
| ACK Cluster Namespace | The namespace of the Kubernetes service corresponding to the SLB instance associated with NGINX Ingress Controller |
| ACK Cluster SLB Service | The name of that Kubernetes service |
| SLB ID | The ID of the SLB instance to migrate |
| Ports and Backend Servers | The listener port and protocol (HTTP or HTTPS). The vServer group is displayed automatically after selection. |
Select the correct port and protocol. An incorrect selection can cause traffic loss.
DNS resolution to SLB
Add DNS records that map all domain names involved in the migration to the IP address of the SLB instance associated with the MSE cloud-native gateway. Use weight-based DNS routing to gradually shift traffic.
Step 4: Switch traffic
Reuse original cluster SLB
4a. Detach the SLB from cluster management
Click Change SLB. This detaches the SLB instance from cluster management and changes the listener scheduling algorithm to weighted round-robin.
After this step, the SLB instance no longer detects pod IP changes for NGINX Ingress Controller. Complete step 4b as soon as possible to re-associate the Kubernetes service with the SLB instance.
4b. Update service annotations
Log on to the ACK console.
Find the Kubernetes service you specified in the Reuse Original Cluster SLB configuration.
Delete all existing annotations from that service.
Copy the annotations generated on the Switch Traffic tab in the MSE console and add them to the service.
Click Pre-check. After the check passes, proceed to the next step.
If application pods in the same cluster access the NGINX Ingress gateway, add the following annotation to the Kubernetes service: Before adding this annotation, confirm that IP address-based access control is not enabled on the SLB instance. This annotation forces in-cluster pods to route through the SLB instance instead of bypassing it through kube-proxy.
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-hostname: mse-ingress-migration4c. Shift traffic by weight
Set the weight for the MSE cloud-native gateway. The weight determines how the SLB instance distributes traffic between MSE and NGINX Ingress nodes in the vServer group.
How weight works:
The weight value represents the total weight of all MSE gateway nodes
The default total weight of all NGINX Ingress gateway nodes is 100
Setting the MSE weight to 100 routes half of all traffic to MSE
Setting the MSE weight to 50 routes one-third of all traffic to MSE
Traffic shifting process:
Start with a weight between 1 and 10. The valid range is 1 to 100.
Monitor the MSE cloud-native gateway dashboard in the MSE console to verify that business metrics are healthy.
If metrics are as expected, increase the weight gradually. Wait at least 3 minutes between weight changes, because configuration takes effect asynchronously.
If metrics are not as expected, set the weight to 0 to roll back immediately.
You can also increase the MSE traffic share by decreasing the value of the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight on the Kubernetes service. Setting this annotation to 0 routes all SLB traffic to the MSE gateway.SLB is a Layer 4 load balancer that uses connection-level scheduling. The weight cannot precisely control request-level distribution.
After you click Complete Traffic Verification, the weights are locked and cannot be modified. Stay on this step until you are confident that traffic distribution is correct and rollback is not needed.
4d. Route all traffic to MSE
In the ACK console, set the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight annotation on the Kubernetes service to 0. Alternatively, delete the Kubernetes service entirely. Either action removes NGINX Ingress Controller from the SLB instance and routes all traffic to the MSE cloud-native gateway.
Click Complete Migration to finalize the migration task.
DNS resolution to SLB
Add DNS records that map all migrated domain names to the IP address of the SLB instance associated with the MSE cloud-native gateway. Use weight-based DNS routing to gradually shift traffic.
Rollback
If traffic distribution is not as expected, roll back immediately:
Reuse original cluster SLB: Set the MSE gateway weight to 0.
DNS resolution to SLB: Remove the DNS records that point to the MSE cloud-native gateway's SLB instance.
Step 5: Complete the migration
Reuse original cluster SLB
After all SLB traffic flows through the MSE cloud-native gateway, delete the NGINX Ingress Controller Kubernetes service and uninstall NGINX Ingress Controller based on your requirements.
DNS resolution to SLB
After all domain names resolve to the SLB instance associated with the MSE cloud-native gateway, delete the NGINX Ingress Controller Kubernetes service and uninstall NGINX Ingress Controller based on your requirements.
FAQ
What does the error mse.backend.gw.MIGRATE_INGRESS_CLASS_CONFLICT mean?
The MSE cloud-native gateway is already associated with the cluster and has Ingress listening enabled, but the Ingress class configured on the gateway differs from the source Ingress class you specified.
To resolve this:
If you use an MseIngressConfig resource to manage MSE Ingresses, follow the instructions in Use MSE Ingress gateways to access services in ACK clusters and ACS clusters.
If you do not use MseIngressConfig, update the Ingress listening settings for the cluster in the MSE console.
What does the error mse.backend.gw.MIGRATE_SERVICE_ANNOTATION_NOT_MATCH mean?
The annotations on the Kubernetes service do not match the expected values. Go back to step 4b and verify that you copied the correct annotations from the Switch Traffic tab.
What does the error mse.backend.gw.MIGRATE_SERVICE_NOT_MATCH mean?
The annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight on the Kubernetes service is not set to 0, or the Kubernetes service has not been deleted. In the ACK console, set this annotation to 0 or delete the Kubernetes service.