Edit

Share via

Migrate from HTTP application routing to the application routing add-on

Important

The Kubernetes SIG Network and the Security Response Committee announced the upcoming retirement of the Ingress NGINX project, with maintenance ending in March 2026. There's no immediate action required today for AKS clusters using the Application Routing add-on with NGINX. Microsoft will provide official support for critical security patches for Application Routing add-on NGINX Ingress resources through November 2026.

AKS is aligning with upstream Kubernetes by moving to Gateway API as the long-term standard for ingress and L7 traffic management. We recommend you start planning your migration path based on your current setup:

  • Application Routing add-on users: Production workloads remain fully supported through November 2026. AKS will continue evolving the Application Routing add-on with Gateway API alignment. You don't need to move to a different ingress product.
  • OSS NGINX users have several options:
  • Service mesh users: If you plan to adopt a service mesh, consider the Istio-based service mesh add-on. Use Istio Ingress today, and plan to migrate to Istio Gateway API support when it becomes GA.

In this article, you learn how to migrate your Azure Kubernetes Service (AKS) cluster from HTTP application routing feature to the application routing add-on. The HTTP application routing add-on has been retired and doesn't work on any cluster Kubernetes version currently in support. We recommend migrating as soon as possible to maintain a supported configuration.

Prerequisites

  • Azure CLI version 2.54.0 or later installed and configured. Run az --version to find the version. If you need to install or upgrade, see Install Azure CLI.
  • aks-preview Azure CLI extension of version 0.5.171 or later installed

Note

These steps detail migrating from an unsupported configuration. As such, AKS cannot offer support for issues that arise during the migration process.

Update your cluster's add-ons, Ingresses, and IP usage

  1. Enable the application routing add-on.

    az aks approuting enable --resource-group <ResourceGroupName> --name <ClusterName>

  2. Update your Ingresses, setting ingressClassName to webapprouting.kubernetes.azure.com. Remove the kubernetes.io/ingress.class annotation. You also need to update the host to one that you own, as the application routing add-on doesn't have a managed cluster DNS zone. If you don't have a DNS zone, follow instructions to create and configure one.

    Initially, your ingress configuration will look something like this:

    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  annotations:
    kubernetes.io/ingress.class: addon-http-application-routing  # Remove the ingress class annotation
spec:
  rules:
  - host: aks-helloworld.<CLUSTER_SPECIFIC_DNS_ZONE>
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: aks-helloworld
            port:
              number: 80

    After you've properly updated, the same configuration looks like the following:

    apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
spec:
  ingressClassName: webapprouting.kubernetes.azure.com # Set the ingress class property to refer to the application routing add-on ingress class
  rules:
  - host: aks-helloworld.<CLUSTER_SPECIFIC_DNS_ZONE> # Replace with your own hostname
    http: 
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: aks-helloworld
            port:
              number: 80

  3. Update the Ingress controller's IP (such as in DNS records) with the new IP address. You can find the new IP by using kubectl get. For example:

    kubectl get svc nginx --namespace app-routing-system -o jsonpath='{.status.loadBalancer.ingress[0].ip}'

  4. Disable the HTTP application routing add-on.

    az aks disable-addons --resource-group <ResourceGroupName> --name <ClusterName> --addons http_application_routing

Remove and delete all HTTP application routing resources

  1. After the HTTP application routing add-on is disabled, some related Kubernetes resources might remain in your cluster. These resources include configmaps and secrets that are created in the kube-system namespace. To maintain a clean cluster, you can remove these resources. Look for addon-http-application-routing resources using the following kubectl get commands:

    kubectl get deployments --namespace kube-system
kubectl get services --namespace kube-system
kubectl get configmaps --namespace kube-system
kubectl get secrets --namespace kube-system

    The following example output shows configmaps that should be deleted:

    NAMESPACE     NAME                                                       DATA   AGE
kube-system   addon-http-application-routing-nginx-configuration         0      9m7s
kube-system   addon-http-application-routing-tcp-services                0      9m7s
kube-system   addon-http-application-routing-udp-services                0      9m7s

  2. Delete remaining resources using the kubectl delete command. Make sure to specify the resource type, resource name, and namespace. The following example deletes one of the previous configmaps:

    kubectl delete configmaps addon-http-application-routing-nginx-configuration --namespace kube-system

  3. Repeat the previous kubectl delete step for all addon-http-application-routing resources remaining in your cluster.

Next steps

After migrating to the application routing add-on, learn how to monitor Ingress controller metrics with Prometheus and Grafana.

  • Last updated on