This topic describes how to use a UI-based migration tool that is provided by Cloud-native API Gateway to migrate traffic from a self-managed NGINX Ingress gateway to a Cloud-native API Gateway instance.
Prerequisites
A Container Service for Kubernetes (ACK) cluster, ACK Serverless cluster, or ACS cluster is created, and NGINX Ingress Controller is deployed in the cluster.
A Cloud-native API Gateway instance is created. For more information, see Create a gateway instance.
Usage notes
In this topic, a Cloud-native API Gateway instance reuses Ingress configurations during the migration. Ingress configurations are not copied. The instance listens to the changes of existing Ingress configurations in real time and parses the listened configuration.
During the migration, both NGINX Ingress Controller and the Cloud-native API Gateway instance can perceive changes of Ingress configurations.
After the migration is complete, do not delete online NGINX Ingress configurations that are in use. The migration aims to allow the Cloud-native API Gateway instance to listen to and parse existing and new Ingress configurations.
After the migration is complete, the existing and new Ingress configurations still must be associated with the Ingress class of the NGINX Ingress gateway. For example, if the value of ingressClassName in spec for the NGINX Ingress gateway is nginx, this setting remains unchanged for both existing and new Ingress configurations after the migration.
Procedure
Cloud-native API Gateway provides a migration tool for you to migrate route configurations and traffic as prompted.
Step 1: Migrate routing rules
Log on to the Cloud-native API Gateway console.
In the left-side navigation pane, click Migrate to Cloud.
On the Migrate to Cloud page, click Create Task.
In the Create Migration Configuration panel, configure the parameters.
Cloud-native API Gateway automatically listens to the changes of all Ingress resources that are associated with the source Ingress class in the cluster, and makes the configurations of the domain names and routes of the Ingress resources take effect.
ImportantIf the destination Cloud-native API Gateway instance is associated with the cluster and the existing Ingress class of the cluster is not the same as the Ingress class that is configured in this step, migration is not allowed. You must make sure that the Ingress class configured in this step is the same as the Ingress class configured for the associated cluster.
Parameter
Description
Instance
The instance to which you want to migrate the NGINX Ingress gateway.
Source Cluster
The cluster to which the NGINX Ingress gateway belongs. You must make sure that the Cloud-native API Gateway instance and the cluster are in the same virtual private cloud (VPC).
API Name
The name of the HTTP API to which the NGINX Ingress gateway is imported.
Resource Group
The resource group to which you want to migrate the NGINX Ingress gateway.
Namespace
The namespace with which the Ingress resources to be migrated are associated.
IngressClass
The Ingress class with which the Ingress resources to be migrated are associated.
NoteOnly one Ingress class is supported.
If you do not specify this parameter, the Cloud-native API Gateway instance listens to all the Ingress resources in the cluster.
Click Next.
The Cloud-native API Gateway instance automatically listens to the changes of all Ingress resources that are associated with the source Ingress class in the cluster, and makes the configurations of the domain names and routes of the Ingress resources take effect.
In this example, an Ingress named nginx-route is deployed in the cluster.
In the Cloud-native API Gateway console, you can find that the Ingress of the cluster is automatically synchronized to the Cloud-native API Gateway instance, and the domain names and routes of the Ingress are generated.
Step 2: Check routes
Check the compatibility of the Ingress resources to which the Cloud-native API Gateway instance listens.
If all Ingress annotations are compatible with the Cloud-native API Gateway instance, proceed to the next step.
If any Ingress annotation is incompatible with the Cloud-native API Gateway instance, submit a ticket.
ImportantThe annotation
nginx.ingress.kubernetes.io/service-weightwith the value of double quotation marks ("") can be ignored. This annotation is added by default in the old ACK console and does not make sense.During the migration, do not delete incompatible annotations that are in use. These incompatible annotations are still parsed by NGINX Ingress Controller and take effect on your business traffic.
Step 3: Select a traffic switching method
Test traffic distribution before traffic switching
We recommend that you perform a local test by performing the following operations before you switch traffic: Modify the local hosts file, add the mappings of IP addresses of Server Load Balancer (SLB) instances associated with the Cloud-native API Gateway instance for DNS services, and then use tools such as curl or Postman to check whether traffic distribution meets your expectations.
Select a traffic switching method
Reuse the original SLB
In this method, you need to add the Cloud-native API Gateway instance to the backend vServer group of the SLB instance that is associated with the NGINX Ingress gateway. During the migration, the SLB instance distributes business traffic to the Cloud-native API Gateway instance based on the configured weight. After the migration is complete, all business traffic on the SLB instance is switched to the Cloud-native API Gateway instance.
The following table describes the parameters when this method is selected.
Parameter | Description |
ACK Cluster Namespace | The namespace of the Kubernetes service that corresponds to the SLB instance associated with the NGINX Ingress gateway. |
ACK Cluster SLB Service | The name of the Kubernetes service that corresponds to the SLB instance associated with the NGINX Ingress gateway. |
SLB ID | The ID of the SLB instance on which the traffic you want to switch. |
Ports and Backend Servers | The listener port of the SLB instance in the cluster and the gateway protocol (HTTP or HTTPS). After you select the port and protocol, the vServer group is automatically displayed. Note Make sure that the port and protocol that you select are valid. Otherwise, traffic loss may occur. |
DNS resolution to SLB
For the DNS service provided by the DNS vendor, add the mappings between all domain names involved in route migration and the IP address of the SLB instance that is associated with the Cloud-native API Gateway instance. We recommend that you use DNS records to gradually switch traffic based on configured weight values.
Step 4: Switch traffic
Reuse the original SLB
Step 1: Click Change SLB
After you click Change SLB, the SLB instance is no longer managed by the cluster and the listener scheduling algorithm is changed to weighted round-robin.
After the change, the SLB instance cannot detect the changes in the pod IP address of NGINX Ingress Controller. Complete the next step at the earliest opportunity to re-associate the Kubernetes service with the SLB instance.
Step 2: Overwrite service annotations
After Step 1 is complete, log on to the ACK console to manually delete all the annotations of the Kubernetes service that you specify when you select Reuse Original Cluster SLB, and copy the annotations that are automatically generated on the Switch Traffic tab to the annotations of the Kubernetes service. This step enables the Kubernetes service to reuse the SLB instance. After the operation is complete, click Pre-check. After the check is passed, go to the next step.
Step 3: Switch traffic based on the configured weight
Specify the weight based on which traffic is switched to the Cloud-native API Gateway instance. You can set the weight to a value ranging from 1 to 100 based on your business requirements. We recommend that you set the weight to a value ranging from 1 to 10 for the first time.
The value is the sum of weights of all nodes in the Cloud-native API Gateway instance. The SLB instance distributes traffic based on the weight of each node in the Cloud-native API Gateway instance and the weight of each node in the NGINX Ingress gateway in the vServer group. The default total weight of all nodes in the NGINX Ingress gateway is 100. If you set the weight of the Cloud-native API Gateway instance to 100, half of the traffic is routed to the Cloud-native API Gateway instance. In the same way, if you set the weight of the Cloud-native API Gateway instance to 50, 1/3 of the traffic is routed to the Cloud-native API Gateway instance.
During the migration, you can view the metrics of the Cloud-native API Gateway instance on the dashboard in the Cloud-native API Gateway console. You can monitor the health status of the instance and check whether the business metrics are as expected.
If business metrics are as expected, you can gradually increase the weight of the Cloud-native API Gateway instance. The weight configuration takes effect asynchronously in the background. Therefore, you must change the weight at an interval of more than 3 minutes.
If business metrics are not as expected, set the weight to 0 to terminate the migration.
To increase the weight of the Cloud-native API Gateway instance, you can also decrease the value of the annotation
service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weightfor the Kubernetes service that you specify when you select Reuse Original Cluster SLB. If you set the annotation to 0, all traffic on the SLB instance is routed to the Cloud-native API Gateway instance.SLB serves as a Layer-4 load balancer that uses connection-level throttling. The weight cannot accurately control the request distribution proportion.
If the success rate decreases after traffic switching, you can set the weight to 0 to perform quick traffic rollback.
If you want to maintain the migrating state and be able to adjust the weights of the NGINX Ingress gateway and Cloud-native API Gateway Ingress gateway at any time, we recommend that you stay in this step for a long period of time. After you verify that the traffic is as expected and traffic rollback is not required, click Complete Traffic Verification to go to the next step.
After you click Complete Traffic Verification, you cannot modify the weights.
Step 4: Switch all traffic to the Cloud-native API Gateway instance
In the ACK console, set the value of the annotation service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight for the Kubernetes service that you specify in Step 3: Select a traffic switch method to 0. You can also directly delete the Kubernetes service resources. NGINX Ingress Controller is automatically removed from the SLB instance. All traffic on the SLB instance is switched to the Cloud-native API Gateway instance. Click Complete Migration to complete the migration task.
DNS resolution to SLB
For the DNS service provided by the DNS vendor, add the mappings between all domain names involved in route migration and the IP address of the SLB instance that is associated with the Cloud-native API Gateway instance. We recommend that you use DNS records to gradually switch traffic based on configured weight values.
Quick traffic rollback
If the traffic distribution is not as expected, you can use one of the following methods to immediately roll back the traffic to NGINX Ingress Controller.
Reuse Original Cluster SLB: Set the weight to 0 to terminate the migration.
DNS Resolution to SLB: For the DNS service provided by the DNS provider, delete the mappings between the business domain names and the IP address of the SLB instance that is associated with the Cloud-native API Gateway instance.
Step 5: Complete the migration
Reuse the original SLB
If you select this method, make sure that all traffic on the SLB instance is distributed to the Cloud-native API Gateway instance. Then, you can delete the Kubernetes service and NGINX Ingress Controller based on your business requirements.
DNS resolution to SLB
If you select this method, make sure that all domain names are parsed as the IP address of the SLB instance that is associated with the Cloud-native API Gateway instance. Then, you can delete the Kubernetes service and NGINX Ingress Controller based on your business requirements.