Azure Kubernetes Service (AKS) Ingress Controller

This document provides a comprehensive guide to understanding and configuring Ingress controllers within Azure Kubernetes Service (AKS). Ingress controllers are crucial for managing external access to services within your Kubernetes cluster, enabling features like load balancing, SSL termination, and name-based virtual hosting.

What is an Ingress Controller?

In Kubernetes, an Ingress resource is an API object that manages external access to services in a cluster, typically HTTP. Ingress may provide load balancing, SSL termination, and name-based virtual hosting. An Ingress controller is a piece of software that fulfills the Ingress resource configuration. It watches the Kubernetes API for Ingress resources and configures a load balancer (often an Azure Load Balancer or a third-party solution) to route traffic accordingly.

Common Ingress Controllers for AKS

AKS supports several popular Ingress controllers, each with its own strengths and configuration nuances. The most common ones include:

Kubernetes NGINX Ingress Controller: A widely adopted and feature-rich controller.
Traefik: Known for its ease of use, dynamic configuration, and integration with service discovery.
Application Gateway Ingress Controller (AGIC): Leverages Azure Application Gateway for robust ingress capabilities, including WAF integration.

Deploying the NGINX Ingress Controller

One of the most straightforward ways to get started is by deploying the official Kubernetes NGINX Ingress Controller. You can typically deploy it using Helm:


# Add the ingress-nginx repository
helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx
helm repo update

# Install the ingress-nginx chart
helm install ingress-nginx ingress-nginx/ingress-nginx \
  --namespace ingress-nginx \
  --create-namespace

After installation, an Azure Load Balancer will be provisioned to expose the Ingress controller. You can find its external IP address using:


kubectl get service -n ingress-nginx ingress-nginx-controller

Configuring Ingress Resources

Once your Ingress controller is running, you define your routing rules using Ingress resources. Here's an example of an Ingress resource that routes traffic to two different services based on the hostname and path:


apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-app-ingress
  namespace: default
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /  # Example annotation for NGINX
spec:
  ingressClassName: nginx # Ensure this matches your controller's class
  rules:
  - host: myapp.example.com
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: frontend-service
            port:
              number: 80
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-api-service
            port:
              number: 8080
  tls:
  - hosts:
    - myapp.example.com
    secretName: myapp-tls-secret # Kubernetes secret containing your TLS certificate

Key Components of an Ingress Resource:

metadata.name: A unique name for your Ingress resource.
namespace: The namespace where the Ingress resource and the target services reside.
ingressClassName: Specifies which Ingress controller should handle this Ingress resource.
rules: Defines the routing logic.
- host: The domain name for which these rules apply.
- http.paths: A list of path-based rules.
  - path: The URL path to match.
  - pathType: How to match the path (e.g., Prefix, Exact).
  - backend.service: The Kubernetes service to forward traffic to.
tls: Configures TLS termination.
- hosts: The hosts for which TLS should be enabled.
- secretName: A Kubernetes secret containing the TLS certificate and key.

Advanced Configurations

Ingress controllers offer a rich set of features for advanced routing and security:

SSL/TLS Termination: Secure your applications by offloading TLS encryption to the Ingress controller.
Path-Based Routing: Route different URL paths to different backend services.
Host-Based Routing: Host multiple applications on the same IP address using different hostnames.
Load Balancing: Distribute traffic across multiple pods of a service.
Annotations: Ingress controllers often use annotations to provide specific configurations, such as rewrite rules, authentication, rate limiting, and more.

Important: The specific annotations and configurations can vary significantly between different Ingress controller implementations. Always refer to the official documentation for the Ingress controller you are using.

Troubleshooting Common Issues

Ingress Controller Not Running: Check the logs of your Ingress controller pods for errors.
External IP Not Appearing: Ensure the Ingress controller service is of type LoadBalancer and that Azure has successfully provisioned an external IP.
Traffic Not Routing Correctly: Verify your Ingress resource configuration, including hostnames, paths, and service backend definitions. Check the Ingress controller logs for routing-related errors.
SSL Certificate Issues: Ensure the TLS secret exists in the correct namespace and contains a valid certificate and private key.

Next Steps

Explore the specific documentation for your chosen Ingress controller to leverage its full capabilities: