Container Service for Kubernetes:Best practices for migrating from a self-managed Nginx Ingress to an ALB Ingress

Install the ALB Ingress controller

1. Log on to the the ACK consoleACK console and install the ALB Ingress controller in your target cluster. For more information, see Manage the ALB Ingress controller. When prompted, set ALB Instance to None. The migration tool automatically creates the AlbConfig, IngressClass, and Ingress resources—do not pre-create an ALB instance.

   Important

   For ACK dedicated clusters, grant the ALB Ingress controller access permissions before deploying Services. See Grant an ACK dedicated cluster access to the ALB Ingress controller.

Run the migration tool

The migration tool reads your existing NGINX Ingress configuration and outputs equivalent ALB Ingress resources.

1. Create a file named ingress2albconfig.yaml with the following content:

   apiVersion: batch/v1
   kind: Job
   metadata:
     name: ingress2albconfig
     namespace: default
   spec:
     template:
       spec:
         containers:
         - name: ingress2albconfig
           image: registry.cn-hangzhou.aliyuncs.com/acs/ingress2albconfig:latest
           command: ["/bin/ingress2albconfig", "print"]
         restartPolicy: Never
         serviceAccount: ingress2albconfig
         serviceAccountName: ingress2albconfig
     backoffLimit: 4
   ---
   apiVersion: rbac.authorization.k8s.io/v1
   kind: ClusterRole
   metadata:
     name: system:ingress2albconfig
   rules:
   - apiGroups:
     - networking.k8s.io
     resources:
     - ingresses
     - ingressclasses
     verbs:
     - get
     - list
     - watch
     - update
     - create
     - patch
   ---
   apiVersion: v1
   kind: ServiceAccount
   metadata:
     name: ingress2albconfig
     namespace: default
   ---
   kind: ClusterRoleBinding
   apiVersion: rbac.authorization.k8s.io/v1
   metadata:
     name: system:ingress2albconfig
   roleRef:
     apiGroup: rbac.authorization.k8s.io
     kind: ClusterRole
     name: system:ingress2albconfig
   subjects:
     - kind: ServiceAccount
       name: ingress2albconfig
       namespace: default

2. Apply the manifest to run the Job:

   kubectl apply -f ingress2albconfig.yaml

   Expected output:

   job.batch/ingress2albconfig created
   clusterrole.rbac.authorization.k8s.io/system:ingress2albconfig created
   serviceaccount/ingress2albconfig created
   clusterrolebinding.rbac.authorization.k8s.io/system:ingress2albconfig created

3. Check that the Job's pod has completed:

   kubectl get pod -l job-name=ingress2albconfig

   Expected output:

   NAME                        READY   STATUS      RESTARTS   AGE
   ingress2albconfig-vw***     0/1     Completed   0          16m

4. View the generated ALB Ingress configurations in the pod logs:

   kubectl logs ingress2albconfig-vw***   # Replace with the pod name from the previous step.

   The output contains the converted resources. Apply them to the cluster to activate the ALB Ingress:

   apiVersion: alibabacloud.com/v1
   kind: AlbConfig
   metadata:
     creationTimestamp: null
     name: from_nginx
   spec:
     config:
       accessLogConfig: {}
       edition: Standard
       name: from_nginx
       tags:
       - key: converted/ingress2albconfig
         value: "true"
       zoneMappings:
       - vSwitchId: vsw-xxx   # Replace with the ID of your vSwitch.
       - vSwitchId: vsw-xxx   # Replace with the ID of your vSwitch.
     listeners:
     - port: 80
       protocol: HTTP
   ---
   apiVersion: networking.k8s.io/v1
   kind: IngressClass
   metadata:
     creationTimestamp: null
     name: from_nginx
   spec:
     controller: ingress.k8s.alibabacloud/alb
     parameters:
       apiGroup: alibabacloud.com
       kind: AlbConfig
       name: from_nginx
       scope: null
   ---
   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     annotations:
       alb.ingress.kubernetes.io/listen-ports: '[{"HTTP":80}]'
     creationTimestamp: null
     name: from_ingress1
     namespace: default
   spec:
     ingressClassName: from_nginx
     rules:
     - http:
         paths:
         - backend:
             service:
               name: nginx-svc-g1msr
               port:
                 number: 80
           path: /
           pathType: Prefix
   status:
     loadBalancer: {}

Automatically converted annotations

The migration tool converts the NGINX Ingress annotations in the following table to their ALB Ingress equivalents.

After Step 1, the traffic state looks like this:

Configure a temporary domain name for the CLB instance

1. Log on to the Alibaba Cloud DNS console.

2. On the Authoritative DNS Resolution page, find and click the domain name www.example.net.

3. On the DNS Settings page, click Add DNS Record. In the Add DNS Record panel, configure the following parameters and click OK.

   Parameter	Description
   Record Type	Select CNAME.
   Hostname	Enter the domain prefix. In this example, www.
   DNS Request Source	Select Default.
   Record Value	Enter the temporary domain name. In this example, web0.example.net.
   TTL	Use the default value.

4. On the DNS Settings tab, find the A record that maps www.example.net to the CLB IP address and click Modify.

5. In the Modify DNS Record panel, change Hostname to web0 and click OK. After this change, www.example.net maps to web0.example.net, which the A record resolves to the CLB instance IP address.

Add a CNAME record for the ALB instance

1. Get the ALB instance domain name:

   kubectl get albconfig

   Expected output:

   NAME         ALBID                    DNSNAME                                               PORT&PROTOCOL   CERTID   AGE
   from_nginx   alb-a8mmh2tqbmrm11****   alb-a8mmh2tqbmrm11****.cn-hangzhou.alb.aliyuncs.com                            20m

   The value in the DNSNAME column (for example, alb-a8mmh2tqbmrm11****.cn-hangzhou.alb.aliyuncs.com) is the ALB instance domain name.

2. On the DNS Settings page, click Add DNS Record. Configure the following parameters and click OK.

   Parameter	Description
   Record Type	Select CNAME.
   Hostname	Enter the domain prefix. In this example, www.
   DNS Request Source	Select Default.
   Record Value	Enter the ALB instance domain name from the previous step.
   TTL	Use the default value.

Configure weights for the CNAME records

1. On the Domain Name Resolution page, click Weight Settings in the left-side navigation pane.

2. On the Weighted Round-robin page, click EnableWeight in the Actions column and click Set Weight.

3. In the Set Weight panel, set the initial weights: CLB DNS record = 100, ALB DNS record = 0.

   

4. Gradually reduce the CLB weight and increase the ALB weight. After each adjustment, verify that your services are not affected.

5. Log on to a worker node where the Service pods are running and run the dig command multiple times to confirm traffic distribution:

6. Continue adjusting until the CLB weight reaches 0 and the ALB weight reaches 100.

If your DNS provider does not support weights for CNAME records, see the following alternative traffic-switching approach:

After Step 2, the traffic state looks like this: