Migrate self-managed NGINX Ingress to Cloud-native API Gateway

Prerequisites

An NGINX Ingress Controller is deployed in your ACK cluster.
A Cloud-native API Gateway instance is created. If not, Create a gateway instance.

Usage notes

Cloud-native API Gateway does not copy Ingress configurations. It parses changes to your existing Ingress resources in real time.
During migration, Ingress configuration changes are reflected in both the NGINX Ingress Controller and Cloud-native API Gateway.
Do not delete production Ingress configurations after migration. Cloud-native API Gateway continues to parse both existing and future Ingress configurations.
Existing and future Ingress configurations must remain associated with the IngressClass that Cloud-native API Gateway monitors. For example, if ingressClassName was nginx/higress/apig, keep it unchanged after migration.

Migration procedure

The Migrate to Cloud tool guides you through route migration and traffic switching.

Note

An official AI Skill (alibabacloud-nginx-ingress-to-api-gateway) can batch-check Ingress compatibility, generate Wasm plugins and new Ingress route configurations for incompatible annotations, and produce a complete migration runbook.

Step 1: Migrate routing rules

Log on to the API Gateway console.
In the navigation pane on the left, choose Cloud Migration.
On the Cloud Migration page, click Create a task.

In the Create Migration Configuration panel, configure the parameters.

Cloud-native API Gateway monitors all Ingress resources associated with the source IngressClass in the selected cluster and applies their domain and route configurations.

Important

If the target gateway is already associated with this cluster but uses a different IngressClass, the migration fails. The IngressClass you specify must match the one configured for the associated cluster.

Parameter	Description
Instance	The destination gateway instance.
Source Cluster	The container cluster hosting the NGINX Ingress to migrate. Must be in the same VPC as Cloud-native API Gateway.
API Name	The HTTP API that receives the imported NGINX Ingress routes.
resource	The destination resource group.
Namespace	The namespace of the Ingress resources to migrate.
IngressClass	The IngressClass of the Ingress resources to migrate. Note Only a single IngressClass can be specified. If empty, the gateway monitors all Ingress resources regardless of IngressClass.

Click Next.
Cloud-native API Gateway monitors all Ingress resources associated with the source IngressClass and applies the domain and route configurations to the new API.
1. For example, assume you have an Ingress resource named nginx-route in your source container cluster.
2. On the Cloud-native API Gateway console, you can see that the gateway has automatically synchronized the Ingress from the source cluster and created corresponding domain name and route configurations.

Step 2: Validate routes

Validate Ingress resource compatibility:

If no incompatible Ingress annotations are found, proceed to the next step.
If incompatible Ingress annotations exist, use AI tools like HiClaw, CoPaw, or QoderWork with the official migration Skill alibabacloud-nginx-ingress-to-api-gateway to analyze configurations, generate Wasm plugins for incompatible annotations, and create a runbook. If issues remain, submit a ticket.
Important
- You can ignore nginx.ingress.kubernetes.io/service-weight if its value is an empty string (""). This annotation was added by default in older ACK console versions and has no functional effect.
- Do not delete incompatible annotations during migration. The NGINX Ingress Controller still uses them for production traffic.

Step 3: Choose a traffic switching method

Test before switching traffic

Before switching live traffic, test locally. Point your service domain to the Cloud-native API Gateway SLB IP in your local hosts file, then verify routing with curl or Postman.

Select a traffic switching method

Reuse the original SLB

This method adds Cloud-native API Gateway nodes to the backend vServer group of the original SLB instance. The SLB distributes traffic by weight during migration, then forwards all traffic to Cloud-native API Gateway after completion.

Configure the following parameters:

Parameter	Description
ACK Cluster Namespace	The namespace of the Kubernetes Service associated with the NGINX Ingress SLB.
ACK Cluster SLB Service	The Kubernetes Service associated with the NGINX Ingress SLB.
SLB ID	Confirm the queried SLB is the migration target.
Ports and Backend Servers	The listener port and protocol (HTTP/HTTPS) of the original SLB. The target vServer group is displayed automatically. Note Ensure you select the correct port and protocol to avoid traffic loss.

Switch traffic via DNS

In your DNS provider's console, add records pointing migrated domain names to the Cloud-native API Gateway SLB address. Use weighted DNS records for gradual traffic switching.

Step 4: Switch traffic

Reuse the original SLB

Step 1: Click Change SLB

Clicking Change SLB detaches the SLB from container service management and sets the listener scheduling to Weighted Round Robin.

Important

This step detaches the SLB from container service management. After detachment, the SLB cannot detect Pod IP changes in the NGINX Ingress Controller. Proceed to the next step immediately to modify annotations and re-associate the Kubernetes Service with the SLB.

Step 2: Overwrite service annotations

After Step 1, go to the ACK console. Delete all current annotations from the Kubernetes Service selected in the Reuse the original SLB step. Copy the annotations generated on the Traffic Switching page and add them to the target Service. This reconfigures the Service to reuse the SLB. Click Pre-check to verify before proceeding.

Step 3: Switch traffic by weight

Set the Cloud-native API Gateway traffic weight (1-100). Start with a value between 1 and 10.

This value is the total weight of all Cloud-native API Gateway nodes. The SLB distributes traffic based on the weight ratio between gateway nodes and NGINX Ingress nodes (default total weight: 100). Setting the gateway weight to 100 gives it half the traffic; setting it to 50 gives it one-third.
Monitor gateway health and business metrics using Cloud-native API Gateway dashboards.
- If metrics are healthy, increase the weight gradually. Wait at least 3 minutes between changes (configuration applies asynchronously).
- If metrics degrade, set the weight to 0 to stop migration.
You can also increase the gateway weight indirectly by lowering the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight annotation on the Kubernetes Service selected in Reuse the original SLB. Setting this annotation to 0 directs all traffic to Cloud-native API Gateway.
SLB operates at Layer 4 (connection level), so weight values do not precisely control request-level distribution.
If success rate drops, set weight to 0 for a quick rollback.

Note

To retain the ability to adjust traffic weights between NGINX Ingress and Cloud-native API Gateway, stay at this step. When traffic is verified and rollback capability is no longer needed, click Complete Traffic Verification to proceed.

Important

After you click Complete Traffic Verification, you can no longer modify the weight.

Step 4: Switch all traffic

On the ACK console, set the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight annotation to 0 for the Kubernetes Service selected in Step 3: Choose a traffic switching method, or delete the Service resource. The system removes the NGINX Ingress Controller nodes from the SLB, switching all traffic to Cloud-native API Gateway. Click Complete Migration to finish.

Switch traffic via DNS

In your DNS provider's console, add records pointing migrated domain names to the Cloud-native API Gateway SLB address. Use weighted DNS records for gradual traffic switching.

Quick rollback

If routing issues occur during migration, roll back traffic to the NGINX Ingress Controller:

If using the 'Reuse the original SLB' method, set the weight to 0.
If using DNS switching, remove the DNS records pointing your domain names to the Cloud-native API Gateway SLB address.

Step 5: Complete the migration

Reuse the original SLB

If you have other SLBs not yet fully switched, complete their traffic switching. Once all SLB traffic is switched, delete the Kubernetes Service and NGINX Ingress Controller if no longer needed.

Switch traffic via DNS

Once all domain names resolve to the Cloud-native API Gateway SLB, delete the Kubernetes Service and NGINX Ingress Controller if no longer needed.