All Products
Search
Document Center

:Migrate Nginx Ingress to ASM gateway

Last Updated:Jun 13, 2025

This topic describes how to migrate from Nginx Ingress to ASM gateway.

Prerequisites

Solution

ASM

Procedure

Step 1: Configure the Classic Load Balancer (CLB) instance of Nginx Ingress to reusable

1) Run the following command to obtain the CLB instance ID of Nginx Ingress:

$ kubectl -n kube-system get svc nginx-ingress-lb -o yaml|grep service.k8s.alibaba/loadbalancer-id
service.k8s.alibaba/loadbalancer-id: lb-bp1gts52ced2vgaw1ni78

2) Open the Server Load Balancer console. Then perform the following operations on the CLB instance:

  • Disable configuration read-only mode.

  • Delete the following tags from the CLB instance: kubernetes.do.not.delete and ack.aliyun.com.

  • Change the name of the vServer group. For those start with k8s/, change them to shared and "-" and port number. For example, change k8s/80/nginx-ingress-lb/kube-system/c553a74e6ad13423aa839c8e5******** to shared-80.

3) Modify the service of Nginx Ingress. Add the following annotations:

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: ${CLB instance ID}

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: "false"

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port: If you have multiple port and vServer group combinations, separate them with commas (,). For example, "${YOUR_VGROUP_ID_1}:80, ${YOUR_VGROUP_ID_2}:443". Note that you need to provide the vServer group ID, not the previously named name such as shared-80.

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight: "100"

Step 2: Create an ASM gateway

You need to create an ASM gateway using YAML. However, you can still use the ASM gateway to create a page for visual configuration. Click the preview button at the bottom of the page to directly obtain a basic YAML file. After obtaining the file, you need to edit the serviceAnnotations in the YAML and add the following service annotations to reuse the CLB instance of Nginx Ingress.

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: ${CLB instance ID}

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: "false"

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port: If you have multiple port and vServer group combinations, separate them with commas (,). For example, "${YOUR_VGROUP_ID_1}:80, ${YOUR_VGROUP_ID_2}:443". Note that you need to provide the vServer group ID, not the previously named name such as shared-80.

service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight: "0"

Example of ServiceAnnotations:

 serviceAnnotations:
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: "lb-xxxxx"  // Replace lb-xxxxx with the ID of the CLB instance that you created in the CLB console.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: 'false'  // This must be explicitly set to false because Istio gateway overrides listeners by default.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port: "${YOUR_VGROUP_ID}:80"   // Replace ${YOUR_VGROUP_ID} with the virtual server.
    service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight: "0"   // Set the service traffic weight. Initially set to 0 so the ASM gateway does not receive traffic.

Step 3: Manually transform ingress to VS, DR, and other Istio configurations

Transform Ingress into the corresponding VirtualService configuration for Istio. You can refer to the following Ingress configuration.

apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: helloworld
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
spec:
  rules:
    - http:
        paths:
          - backend:
              serviceName: helloworld
              servicePort: 80
            path: /helloworld(/|$)(.*)
      host: example.com

Expected output:

apiVersion: networking.istio.io/v1beta1
kind: VirtualService
metadata:
  name: example-vs
spec:
  gateways:
  - istio-system/ingressgateway  ## your gateway name
  hosts:
  - example.com
  http:
  - name: route-helloworld
    match:
    - uri:
        prefix: /helloworld/
    - uri:
        prefix: /helloworld
    rewrite:
      uri: /
    route:
    - destination:
        host: helloworld
        port:
          number: 80

VirtualService and DestinationRule can be placed in the same namespace, with the service Deployment. If they are not in the same namespace, the destination.host field needs to be filled in FQDN format.

Step 4: Verify traffic

After Ingress configuration to VirtualService, you need to perform verification tests to confirm whether the configuration is effective. Referring to the Solution, you can manually create a new CLB instance and send test traffic requests to this CLB for testing. Also you can request the ASM ingress gateway service directly within the cluster to determine if the configuration is correct based on the test results.

Step 5: Adjust the weights of backend instances under the CLB corresponding to Ingress for traffic migration to the ASM gateway

We recommend you to set the weight of the ASM gateway instance to a small value (such as 1%) to observe whether the online requests meet expectations, You can gradually increase it after until all traffic is switched to the ASM gateway.

The weight adjustment methods are as follows:

  • The weight of the ASM gateway instance can be adjusted through ServiceAnnotations under IstioGateway, corresponding to service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight: "60".

  • The weight of the Nginx instance can be adjusted through Annotation under the related Service: service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight. If the Service does not have weight-related Annotations configured, the distribution weight of the Nginx Ingress instance can be directly configured through the CLB console.