Replace ack-ingress-nginx with ack-ingress-nginx-v1 - Container Service for Kubernetes

The Ingress API v1beta1 is deprecated in Kubernetes 1.24. If your cluster uses ack-ingress-nginx, the bundled NGINX Ingress Controller 0.44.0 relies on this deprecated API and stops working after a Kubernetes 1.24 upgrade. This topic walks you through replacing ack-ingress-nginx with ack-ingress-nginx-v1, which ships NGINX Ingress Controller 1.1.0 and later and uses the stable networking.k8s.io/v1 API.

Note

This topic applies only to clusters where ack-ingress-nginx was installed from the Marketplace page in the ACK console. If your NGINX Ingress Controller was installed from the Add-ons page, see Update the NGINX Ingress controller.

Prerequisites

Before you begin, ensure that you have:

An ACK cluster running Kubernetes 1.20 or later
ack-ingress-nginx installed from the Marketplace page in the ACK console

Note

Chart version 4.0.17 or later (ack-ingress-nginx-v1 1.8.0-aliyun.1 or later) requires Kubernetes 1.22 or later. If your cluster runs Kubernetes 1.20, select chart version 4.0.16 (ack-ingress-nginx-v1 1.2.1-aliyun.1).

Step 1: Install ack-ingress-nginx-v1

Install one ack-ingress-nginx-v1 instance for each NGINX Ingress Controller deployed by ack-ingress-nginx. For instructions, see Deploy multiple Ingress controllers in a cluster.

Important

Do not set controller.ingressClassResource.name in ack-ingress-nginx-v1 to the same value as controller.ingressClass in ack-ingress-nginx. Duplicate ingress class names cause routing conflicts between the two controllers.

(Optional) Migrate SLB configuration

If you customized the Server Load Balancer (SLB) specification or parameters in ack-ingress-nginx, migrate those settings to ack-ingress-nginx-v1 using Service annotations:

Internet-facing SLB instances: configure the controller.service annotation
Internal-facing SLB instances: configure the controller.service.internal annotation

For the full list of supported annotations, see Use annotations to configure CLB instances and Use annotations to configure NLB instances.

Step 2: Test traffic routing with a new Ingress

Create a new Ingress based on the original configuration and point it at the ack-ingress-nginx-v1 ingress class. This lets you verify routing without touching existing traffic.

The following example shows the original Ingress:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx-intranet
spec:
  rules:
  - host: test-ingress.com
    http:
      paths:
      - path: /foo
        backend:
          service:
            name: web1-service
            port:
              number: 8080
        pathType: ImplementationSpecific
      - path: /bar
        backend:
          service:
            name: web1-service
            port:
              number: 8080
        pathType: ImplementationSpecific

Create a new Ingress that targets ack-ingress-nginx-v1. The steps differ depending on how the ingress class is specified in the original Ingress.

If the ingress class is specified using the `kubernetes.io/ingress.class` annotation, change the annotation value to the ingress class name used by ack-ingress-nginx-v1. Keep all other annotations unchanged.

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: test-ingress-v1
  namespace: default
  annotations:
    kubernetes.io/ingress.class: nginx-intranet-v1  # Change to the ingress class name of ack-ingress-nginx-v1
spec:
  rules:
  - host: test-ingress.com
    http:
      paths:
      - path: /foo
        backend:
          service:
            name: web1-service
            port:
              number: 8080
        pathType: ImplementationSpecific
      - path: /bar
        backend:
          service:
            name: web1-service
            port:
              number: 8080
        pathType: ImplementationSpecific

If the ingress class is specified using `spec.ingressClassName`, create a new Ingress and change the spec.ingressClassName value to the ingress class name used by ack-ingress-nginx-v1.

After creating the new Ingress, update your local hosts file to map the domain name to the IP address of the new Classic Load Balancer (CLB) instance, then verify that ack-ingress-nginx-v1 routes traffic correctly.

Step 3: Switch traffic to ack-ingress-nginx-v1

After confirming that ack-ingress-nginx-v1 routes traffic correctly, update DNS to send live traffic to the new controller.

Log in to the Alibaba Cloud DNS console (or the DNS management console for your domain) and map the domain name to the IP address of the new CLB instance. DNS changes propagate over time — monitor your application using container logs and metrics during the switchover.

What's next

After traffic is fully switched and your application is accessible, uninstall ack-ingress-nginx:

Log in to the ACK console.
Go to the cluster details page and choose Applications > Helm in the left-side navigation pane.
Find the Helm release named ack-ingress-nginx and click Delete in the Actions column.