Managed NGINX ingress with the application routing add-on

One way to route Hypertext Transfer Protocol (HTTP) and secure (HTTPS) traffic to applications running on an Azure Kubernetes Service (AKS) cluster is to use the Kubernetes Ingress object. When you create an Ingress object that uses the application routing add-on NGINX Ingress classes, the add-on creates, configures, and manages one or more Ingress controllers in your AKS cluster.

This article shows you how to deploy and configure a basic Ingress controller in your AKS cluster.

Application routing add-on with NGINX features

The application routing add-on with NGINX delivers the following:

  • Easy configuration of managed NGINX Ingress controllers based on Kubernetes NGINX Ingress controller.
  • Integration with Azure DNS for public and private zone management
  • SSL termination with certificates stored in Azure Key Vault.

For other configurations, see:

With the retirement of Open Service Mesh (OSM) by the Cloud Native Computing Foundation (CNCF), using the application routing add-on with OSM is not recommended.

Prerequisites

  • An Azure subscription. If you don't have an Azure subscription, you can create a free account.
  • 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.

Limitations

  • The application routing add-on supports up to five Azure DNS zones.
  • The application routing add-on can only be enabled on AKS clusters with managed identity.
  • All global Azure DNS zones integrated with the add-on have to be in the same resource group.
  • All private Azure DNS zones integrated with the add-on have to be in the same resource group.
  • Editing the ingress-nginx ConfigMap in the app-routing-system namespace isn't supported.
  • The following snippet annotations are blocked and will prevent an Ingress from being configured: load_module, lua_package, _by_lua, location, root, proxy_pass, serviceaccount, {, }, '.

Enable application routing using Azure CLI

Enable on a new cluster

To enable application routing on a new cluster, use the az aks create command, specifying the --enable-app-routing flag.

az aks create \
    --resource-group <ResourceGroupName> \
    --name <ClusterName> \
    --location <Location> \
    --enable-app-routing \
    --generate-ssh-keys

Enable on an existing cluster

To enable application routing on an existing cluster, use the az aks approuting enable command.

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

Connect to your AKS cluster

To connect to the Kubernetes cluster from your local computer, you use kubectl, the Kubernetes command-line client. You can install it locally using the az aks install-cli command. If you use the Azure Cloud Shell, kubectl is already installed.

Configure kubectl to connect to your Kubernetes cluster using the az aks get-credentials command.

az aks get-credentials --resource-group <ResourceGroupName> --name <ClusterName>

Deploy an application

The application routing add-on uses annotations on Kubernetes Ingress objects to create the appropriate resources.

  1. Create the application namespace called aks-store to run the example pods using the kubectl create namespace command.

    kubectl create namespace aks-store
    
  2. Deploy the AKS store application using the following YAML manifest file:

    kubectl apply -f https://raw.githubusercontent.com/Azure-Samples/aks-store-demo/main/sample-manifests/docs/app-routing/aks-store-deployments-and-services.yaml -n aks-store
    

This manifest will create the necessary deployments and services for the AKS store application.

Create the Ingress object

The application routing add-on creates an Ingress class on the cluster named webapprouting.kubernetes.azure.com. When you create an Ingress object with this class, it activates the add-on.

  1. Copy the following YAML manifest into a new file named ingress.yaml and save the file to your local computer.

    apiVersion: networking.k8s.io/v1
    kind: Ingress
    metadata:
      name: store-front
      namespace: aks-store
    spec:
      ingressClassName: webapprouting.kubernetes.azure.com
      rules:
      - http:
          paths:
          - backend:
              service:
                name: store-front
                port:
                  number: 80
            path: /
            pathType: Prefix
    
  2. Create the ingress resource using the kubectl apply command.

    kubectl apply -f ingress.yaml -n aks-store
    

    The following example output shows the created resource:

    ingress.networking.k8s.io/store-front created
    

Verify the managed Ingress was created

You can verify the managed Ingress was created using the kubectl get ingress command.

kubectl get ingress -n aks-store

The following example output shows the created managed Ingress:

NAME          CLASS                                HOSTS   ADDRESS       PORTS   AGE
store-front   webapprouting.kubernetes.azure.com   *       51.8.10.109   80      110s

You can verify that the AKS store works pointing your browser to the public IP address of the Ingress controller. Find the IP address with kubectl:

kubectl get service -n app-routing-system nginx -o jsonpath="{.status.loadBalancer.ingress[0].ip}"

Remove the application routing add-on

To remove the associated namespace, use the kubectl delete namespace command.

kubectl delete namespace aks-store

To remove the application routing add-on from your cluster, use the az aks approuting disable command.

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

Note

To avoid potential disruption of traffic into the cluster when the application routing add-on is disabled, some Kubernetes resources, including configMaps, secrets, and the deployment that runs the controller, will remain on the cluster. These resources are in the app-routing-system namespace. You can remove these resources if they're no longer needed by deleting the namespace with kubectl delete ns app-routing-system.

Next steps