Migrate traffic from a self-managed Istio ingress gateway to an ASM ingress gateway - Alibaba Cloud Service Mesh

When you move from a self-managed Istio deployment to Service Mesh (ASM), you need to migrate ingress traffic. This guide walks through a weight-based traffic shifting approach: both the existing Istio ingress gateway and a new ASM ingress gateway share the same Classic Load Balancer (CLB) instance, and you control the traffic split by adjusting vServer group weights.

Prerequisites

An ASM instance is created and the target Kubernetes cluster is added to the mesh
Administrator access to the Kubernetes cluster where the self-managed Istio ingress gateway runs
Access to the CLB console to manage load balancer labels and vServer groups
The self-managed Istio ingress gateway is running and handling traffic normally

Choose a traffic shifting strategy

You have two options for redirecting traffic to the ASM ingress gateway:

Strategy	When to use	How it works
DNS-based switching	You can modify DNS records directly	Update the Domain Name System (DNS) record of your domain to point to the ASM ingress gateway IP address
Weight-based shifting	You cannot modify DNS records, or you need gradual, controlled migration	Both gateways share a CLB instance; adjust vServer group weights to shift traffic incrementally

This guide focuses on weight-based shifting. If you use DNS-based switching, skip the CLB reuse configuration and update your DNS records after creating the ASM ingress gateway.

Create the ASM ingress gateway

Create an ASM ingress gateway in the same Kubernetes cluster as your self-managed Istio ingress gateway. For detailed instructions, see Create an ingress gateway.

When you create the gateway:

Use a distinct name. The ASM ingress gateway name must differ from the existing Istio ingress gateway name. Append -asm to distinguish it -- for example, ingressgateway-asm.
Deploy to the same cluster. In Step 3 of the Create an ingress gateway topic, set the Cluster parameter to the Kubernetes cluster where the source Istio ingress gateway resides.

Reuse the existing CLB instance

To share the CLB instance between both gateways, add the following service annotations in the ASM ingress gateway YAML:

Annotation	Purpose	Value
`service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id`	Specifies the CLB instance to reuse	The ID of the CLB instance associated with your source Istio ingress gateway
`service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners`	Controls whether existing listeners are overwritten	`false` (preserves existing listeners)
`service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port`	Maps vServer groups to ports	vServer group IDs and ports, comma-separated (for example, `"${YOUR_VGROUP_ID_1}:80, ${YOUR_VGROUP_ID_2}:443"`)
`service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight`	Sets the traffic weight for the ASM ingress gateway	Adjust based on your business requirements. Set to `0` when no routing rule is configured or exceptions occur

Sample serviceAnnotations configuration:

serviceAnnotations:
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: "lb-xxxxx"  # Replace with your CLB instance ID
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: 'false'  # Preserve existing listeners
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port: "${YOUR_VGROUP_ID}:80"  # Replace with your vServer group ID
  service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight: "60"  # Set to 0 when no routing rule is configured or exceptions occur

Note

For more information about reusing CLB instances created by using the LoadBalancer service type, see the FAQ at the end of this topic.

Verify the gateway

After creating the ASM ingress gateway, confirm the gateway pods are running:

kubectl get pods -n istio-system -l istio=ingressgateway-asm

Expected output (pod name and age will differ):

NAME                                    READY   STATUS    RESTARTS   AGE
ingressgateway-asm-5d8f7b9c4f-xxxxx    1/1     Running   0          1m

Migrate Istio configurations

Migrate Istio routing configurations to the ASM ingress gateway. Follow the make-before-break order below to prevent 503 errors caused by eventually consistent configuration propagation.

1. Apply DestinationRule resources first

Apply the DestinationRule configurations that the ASM ingress gateway needs. Wait a few seconds for the configuration to propagate to Envoy sidecars before proceeding.

2. Update the Gateway selector

In the Istio Gateway YAML, update selector.istio to match your ASM ingress gateway name:

spec:
  selector:
    istio: ingressgateway-asm

3. Apply VirtualService configurations

After the Gateway selector update and DestinationRule configurations have propagated, apply the VirtualService configurations that reference the ASM ingress gateway.

Important

Always apply DestinationRule before VirtualService when adding new routing rules. If a VirtualService references a subset that does not yet exist in a DestinationRule, traffic to that subset returns 503 errors until the DestinationRule propagates.

Verify configurations

Confirm that the ASM ingress gateway has received the expected routing configuration:

kubectl get gateway,virtualservice,destinationrule -n istio-system

Check that all Gateway, VirtualService, and DestinationRule resources are listed and reference the correct gateway name.

Shift traffic gradually

With configurations in place, shift traffic from the self-managed Istio ingress gateway to the ASM ingress gateway by adjusting CLB weights.

Set the ASM ingress gateway weight to a small value, such as 10, to route a fraction of traffic to it. Edit the service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight annotation on the ASM ingress gateway Service.
Verify traffic flows correctly through the ASM ingress gateway. Check application logs, response codes, and latency:
```
   kubectl logs -n istio-system -l istio=ingressgateway-asm --tail=50
```
Gradually increase the ASM ingress gateway weight (for example, 10 -> 30 -> 60 -> 100) while reducing the source Istio ingress gateway weight accordingly.
After all traffic routes through the ASM ingress gateway, set the source Istio ingress gateway weight to 0.

How to adjust weights

Gateway	Action
Source Istio ingress gateway	Edit the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight` annotation on its Kubernetes Service
ASM ingress gateway	Edit the `service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight` annotation on the ASM ingress gateway Service

Rollback

If the ASM ingress gateway does not work as expected at any point during the migration:

Set the ASM ingress gateway weight to 0 to stop sending traffic to it.
Set the source Istio ingress gateway weight back to 100.
Revert Gateway, VirtualService, and DestinationRule configurations to point to the original Istio ingress gateway. When removing subsets, update VirtualService first, wait a few seconds, then update DestinationRule.

FAQ: Reuse a CLB instance auto-created by the Istio ingress gateway Service

If a CLB instance was automatically created when a Service was created for the self-managed Istio ingress gateway, take these steps before reusing it for the ASM ingress gateway:

Open the CLB console and find the CLB instance.
Delete the following two labels from the CLB instance:
- kubernetes.do.not.delete
- ack.aliyun.com

Add the following annotations to the Service of the self-managed Istio ingress gateway: Replace the following placeholders with your actual values:

Placeholder	Description	Example
`<your-clb-instance-id>`	ID of the CLB instance	lb-bp1abc2defg
`<your-vserver-group-id>`	ID of the vServer group	rsp-bp1abc3defg
`<port>`	Listener port number	80

   service.beta.kubernetes.io/alibaba-cloud-loadbalancer-force-override-listeners: "false"
   service.beta.kubernetes.io/alibaba-cloud-loadbalancer-id: <your-clb-instance-id>
   service.beta.kubernetes.io/alibaba-cloud-loadbalancer-vgroup-port: <your-vserver-group-id>:<port>
   service.beta.kubernetes.io/alibaba-cloud-loadbalancer-weight: "100"